Codex CLI
~/.codex/config.toml注册自定义服务商 hzapi 并启用原生 responses 协议，通过环境变量 HZAPI_API_KEY 完成鉴权。
请确保模型 ID 在当前令牌分组内可用 · OpenAI 配置规范 ↗
DEVELOPER DOCUMENTATION · 开发者接入指南
标准协议接入，五分钟连通生产环境
无论您使用命令行研发工具（Codex CLI、Claude Code）还是桌面交互终端（Cherry Studio、Chatbox），均可通过标准 REST 接口与官方兼容协议无缝接入 HZAPI 网关。
ONBOARDING WORKFLOW
接入流程
标准三步接入流程
01
API KEY · SCOPED QUOTA
签发 API 访问令牌
登录控制台进入「令牌管理」，创建专属 API Key，并根据业务场景绑定对应的模型分组权限与配额上限。
02
/v1/responses · /v1/messages
匹配网关协议与端点
根据工具规范配置协议：Codex 采用 OpenAI Responses 协议，Claude Code 采用 Anthropic Messages 原生协议，通用客户端采用 Chat Completions 协议。
03
200 OK · STREAM AUDIT
连通性验证与调用审计
在客户端发起测试请求，确认流式响应正常返回后，可在控制台「使用日志」中实时核查本次调用的延迟、Token 消耗与计费明细。
CLIENT CONFIGURATION
工具与客户端
主流研发工具与客户端配置指南
选择您正在使用的研发终端或桌面客户端，右侧工作台将同步生成对应的标准网关地址（Base URL）、上游协议类型与推荐模型标识符。
CC Switch · Codex · 服务商参数配置
GATEWAY INSPECTOR
标准接入参数
配置面板
HZAPI
Responses（原生）
https://hzapi.vip/v1
sk-hzapi-••••••••••••••••
填入控制台签发的令牌
gpt-6.1-sol
保存配置并在客户端中激活该服务商
→
✓
进入控制台核对 →
连通性与调用审计验证
ENDPOINT SPECIFICATION
端点规范
各协议网关地址（Base URL）配置规范
不同客户端对 REST 路径后缀的自动拼接逻辑有所差异。请参照下方标准规范填写网关地址，确保最终发起的 HTTP 请求路径准确无误。
01
OpenAI Responses 协议
https://hzapi.vip/v1
02
Anthropic Messages 协议
https://hzapi.vip
03
Cherry Studio 客户端
https://hzapi.vip
04
Chatbox 客户端
https://hzapi.vip
CLI & SDK INTEGRATION
工程化接入
命令行工具与配置文件接入示例
适用于终端研发工作流与服务端集成。将以下标准配置片段合入对应工具的配置文件，并通过系统环境变量安全注入 API 密钥。
Claude Code
settings.json在用户配置中声明 ANTHROPIC_BASE_URL 与访问密钥，无缝接入 Claude 系列编程与推理模型。
终端内可执行
/status 校验网关状态 · Claude Code 文档 ↗
REST API 标准调用
POST /v1/responses使用标准 HTTP Bearer 令牌发起请求，快速验证生产环境网络连通性与模型响应。
Python / JS SDK 示例请见 首页快速接入工作台 →
DIAGNOSTICS & BILLING
状态码诊断与计费规范
常见状态码排查与多模态计费准则
当接口返回非 200 状态码时，建议结合响应体中的错误信息与控制台「使用日志」进行快速诊断。
Q返回 401 / 403 鉴权与权限异常如何排查？
请核查 API Key 是否完整复制（无首尾多余空格）、令牌是否处于启用状态且未超出配额上限，并确认当前请求的模型标识符属于该令牌所绑定的模型分组。
Q提示模型不存在（Model Not Found）如何处理？
第三方客户端预设的模型列表可能与网关实时路由表不一致。请前往「模型广场」复制对应分组下的完整模型 ID（若模型包含 -hz-g87 等分组路由后缀，请完整保留）。
QCodex CLI 连接异常或返回 400 Bad Request？
请确认三项配置：上游协议是否设为 Responses、base_url 是否精确配置至 /v1 层级，以及所选令牌分组是否支持原生 Responses 协议。更新配置后请重启终端会话。
Q遇到 429 速率限制或 5xx 上游超时如何应对？
429 表示当前并发或 RPM/TPM 触发流控阈值，建议在客户端引入指数退避重试或平滑请求速率；502 / 503 多为上游渠道瞬时异常，请结合控制台「使用日志」检查所选模型分组状态或发起重试。
Q为什么客户端本地估算金额与平台账单存在差异？
第三方客户端内置的静态费率表无法实时同步平台的分组倍率与阶梯定价。所有调用费用均以「模型广场」实时公示费率及控制台「使用日志」中的结算记录为准。