Codex
Codex CLI 接自定义 OpenAI 兼容服务商:十行配置和六个“假 bug”报错
Codex CLI 默认连 OpenAI,但任何支持 OpenAI Responses API 的服务商都能接入,配置只需十行 TOML。作者整理了接入后最常见的六种报错——401、404、503、402 等——它们看起来像 Codex 的 bug,实际几乎都是配置问题,并给出逐一排查的方法。
今天就能做
- 接入自定义服务商前,先确认它支持 /v1/responses 接口,base_url 以 /v1 结尾
- 遇到报错先跑一遍清单:echo 密钥变量、从 /v1/models 复制模型 ID、检查推理档位设置
- 预付费网关用户保持余额略高于单次请求的预估冻结额,避免莫名 402
基础配置:三处容易踩坑的细节
- 在 ~/.codex/config.toml 里加一个 [model_providers.xxx] 块,包含 name、base_url、env_key 和 wire_api 四项,不影响原有 OpenAI 配置
- env_key 填的是环境变量的名字,不是密钥本身,Codex 启动时从该变量读取密钥
- wire_api = "responses" 让 Codex 调用 /v1/responses;只支持 /v1/chat/completions 的服务商跑不好工具和推理功能
- base_url 必须以 /v1 结尾,Codex 会在后面自动拼接 /responses
- 想设为默认,把 model_provider 和 model 两行写到 config.toml 顶部即可
401 invalid_api_key:密钥没错但读不到
- 最常见原因:启动 Codex 的那个 shell 里根本没有这个变量——在另一个终端 tab 里 export 的,或写进了 .zshrc 但没开新 shell
- 用 echo ${MODEL_SALE_API_KEY:0:12} 验证,输出为空说明 Codex 也读不到
- 解决办法:把 export 写进 shell 配置文件,或用 MODEL_SALE_API_KEY=... codex ... 的方式内联启动
404 model_not_found:模型 ID 别靠记忆
- 同一个模型在 OpenAI、路由器、网关三处的 ID 是三个不同的字符串
- 用 curl 请求服务商的 /v1/models 接口,配合 jq 列出所有可用 ID,原样复制,包括点和横杠
- 例如 gpt-6.1-sol 和 gpt-6-sol 是两个不同的模型
密钥名不选模型;503 不是你的问题
- 多数网关的密钥能调所有模型,密钥名只是给你自己看的标签,模型由 -m 参数或 config.toml 里的 model 决定
- 想限制某个密钥只能调一个模型,去服务商后台找 per-key 模型白名单功能
- 503 model_unavailable 表示模型在目录里但当前没有健康路由,换一个模型(会话内 /model 或重启换 -m)并看服务商状态页,死循环重试没用
400 推理档位报错与 402 余额陷阱
- model_reasoning_effort 的合法值因模型而异,有用户设了 ultra 导致所有请求失败
- 不确定就删掉这个设置,让模型用默认值;GPT-6.1 Sol 支持的是 low、medium、high、xhigh、max
- 预付费服务商会在请求前冻结一笔预估金额(含完整 max_output_tokens 和上下文大小),结束后释放未用部分
- 余额为正却报 402,说明冻结额度不够:多充一点或调低输出上限;并非所有服务商都像作者家这样改成只冻结剩余额度
快速排查清单
- 在运行 Codex 的那个 shell 里 echo 密钥变量
- 模型 ID 一律从 /v1/models 复制
- 确认 wire_api = "responses" 且 base_url 以 /v1 结尾
- 推理档位用模型支持的值,或干脆不设
- 503 = 换模型,402 = 预留余额比单次请求成本略高
原文:Codex CLI with a custom OpenAI-compatible provider: the config, and six errors that look like bugs
来源:DEV Community · 2026-11-17
查看原文本文由 AI 阅读原文后整理,未经人工逐字核对,内容以原文为准。
登录后可以点赞、查看和发表评论