Codex CLI 接入
在 ~/.codex/config.toml 里加一个指向 JuCode 的 model provider。
先说两个容易踩的点。
wire_api 现在只接受 "responses"。 "chat" 已经被移除,写上去 Codex 读配置时
会直接报错:wire_api = "chat" is no longer supported。也就是说 Codex 一定走 JuCode
的 /v1/responses,而这个端点恒为流式——好在 Codex 本来就只用流式,不受影响。
base_url 要带 /v1。 Codex 在它后面直接拼 /responses,内置 openai provider
的默认值就是 https://api.openai.com/v1。少写 /v1 会打到不存在的路径上。
安装
npm install -g @openai/codexmacOS 也可以用 brew install --cask codex。
配置
写 ~/.codex/config.toml
model = "gpt-5.4"
model_provider = "jucode"
model_reasoning_effort = "medium"
[model_providers.jucode]
name = "JuCode"
base_url = "https://api.jucode.cn/v1"
env_key = "JUCODE_API_KEY"
wire_api = "responses"[model_providers.jucode] 里的 jucode 是你自己起的 id,顶层 model_provider 用
同一个字符串选中它。wire_api 的默认值本来就是 "responses",这里写出来只是为了明确。
name 是显示名,可以省略。
导出 API Key
env_key 给的是环境变量的名字,不是 Key 本身。Codex 启动时读这个变量,把值放进
Authorization: Bearer。
export JUCODE_API_KEY="sk-juc-..."变量为空时 Codex 直接失败
它不会退回去用 ChatGPT 登录。自定义 provider 的 requires_openai_auth 默认是 false,
登录流程会被跳过,所以少了这个变量就是硬错误。
告诉 Codex 上下文窗口(建议)
Codex 不认识 JuCode 的模型名,拿不到窗口大小,自动压缩的触发时机会不准。顶层加一行:
model_context_window = 1050000值从 GET https://api.jucode.cn/v1/models 返回的 context_window 字段取。
推理档位
顶层 model_reasoning_effort 控制推理强度。两边接受的取值不完全一样:
| 取值 | |
|---|---|
| Codex 客户端接受 | none minimal low medium high xhigh max ultra |
| JuCode 网关接受 | none low medium high xhigh |
取交集,也就是 none / low / medium / high / xhigh。写 Codex 认识但网关
不认的值(比如 ultra),错误会在请求时才暴露,而不是在读配置时。
另外 gpt-5.3-codex 不接受 none——它无法关闭推理。每个模型实际支持哪几档,看
/v1/models 里的 reasoning_efforts 字段,详见模型与能力。
验证
配置写完后,不进 TUI 直接跑一发:
codex exec "用一句话解释什么是幂等性"或者进 TUI 后用 /status,它会显示当前会话的配置(模型、provider、推理档位)和
token 用量。/model 可以临时切模型和推理档位。
不想改配置文件的话,可以在命令行上覆盖任意配置项:
codex -c model_provider=jucode -c model=gpt-5.4-c 的值按 TOML 解析,解析失败就当字符串字面量。
排查
老教程里普遍写 wire_api = "chat",现在这个值已被移除。改成 "responses",或者
干脆删掉这一行——默认值就是它。
先确认 env_key 里的名字和你 export 的变量名完全一致,大小写敏感。Codex 读不到
非空值就直接失败,不会静默降级。
变量有了还是 401,就绕开 Codex 直接验一次:
curl https://api.jucode.cn/v1/models \
-H "Authorization: Bearer $JUCODE_API_KEY"返回 invalid_api_key 说明 Key 本身有问题——常见的是复制时带了尾部换行,或者 Key 已
被吊销。完整的 401 分支见认证。
model 写的名字在你这把 Key 下不可用。列一下能调的:
curl https://api.jucode.cn/v1/models \
-H "Authorization: Bearer $JUCODE_API_KEY"不同 Key 看到的列表可能不同,Key 上可以配模型组白名单。
如果返回的是 endpoint_unsupported_by_providers(503 而非 400),那不是模型名错了,
而是这个模型背后没有支持 Responses 端点的上游。换一个模型。
说明请求没走你新加的 provider。按顺序查:
- 顶层
model_provider是否设成了你的 provider id。只写[model_providers.jucode]而不设model_provider,Codex 仍然用内置的openaiprovider 打api.openai.com。 - 进 TUI 跑
/status,确认显示的 provider 和模型就是你配的那套。 /debug-config会列出配置的各个来源层,可以看出是不是被别的层覆盖了。-m/--model和-c命令行覆盖只对当次运行生效,别拿它当持久配置。
确认 JuCode 这边的额度:
curl https://api.jucode.cn/v1/open/balance \
-H "Authorization: Bearer $JUCODE_API_KEY"详见开放 API。
/v1/responses 是长连接流式响应。provider 表里可以单独调重试和空闲超时:
[model_providers.jucode]
# ...
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000上表三个是 Codex 的默认值。注意网关把上游 429 映射成了 503(/anthropic/v1/messages
除外),所以持续 503 更可能是上游限流而不是服务真的挂了,见错误码。