配合 Codex CLI 使用

配合 Codex CLI 使用

Codex CLI 支持自定义 model provider。把 base_url 指向万川即可，其余工作流不变。

这里的 base_url 需要带 /v1，即 https://chuanapi.com/v1。Codex CLI 会在其后拼接 /responses。

前置条件

已在控制台创建 API Key 并写入环境变量 WANCHUAN_API_KEY。
本机已安装 Codex CLI，且存在 ~/.codex 目录。

配置步骤

编辑 ~/.codex/config.toml，新增一个指向万川的 provider，并把默认 provider 切过去：

# ~/.codex/config.toml
model = "MODEL_ID"
model_provider = "wanchuan"

[model_providers.wanchuan]
name = "WanChuan"
base_url = "https://chuanapi.com/v1"
env_key = "WANCHUAN_API_KEY"
wire_api = "responses"

把 MODEL_ID 换成模型目录里的真实 id。env_key 填的是环境变量名而不是密钥本身，密钥不会落到配置文件里。

使用 Responses 协议

当前 Codex 官方配置参考将自定义 provider 的 wire_api 固定为 responses。协议差异见协议兼容。

验证连通

改完配置先别急着启动 codex，单独打一次接口更容易定位问题：

curl https://chuanapi.com/v1/responses \
  -H "Authorization: Bearer $WANCHUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","input":"你好"}'

常见问题

404：base_url 漏了 /v1，或 model id 不在目录里。
401：env_key 指向的环境变量在启动 codex 的那个 shell 里没有值。注意 GUI 终端与登录 shell 的环境可能不同。
403：账号分组不含该模型，换一个目录中可用的 id。
工具调用不生效：确认模型目录标注了 Tools 能力，并保持 wire_api = "responses"。
配置没被读取：确认改的是 ~/.codex/config.toml而不是项目内的同名文件，且 TOML 语法正确（表头拼写错误会被静默忽略）。

相关文档

协议兼容—— Chat Completions 与 Responses 的边界。
错误码—— 状态码含义与重试策略。

本页基于 2026-09-15 的 Codex CLI 配置格式校订。该 CLI 的配置字段随版本变动较快，如与官方文档不一致，以官方为准。