- Codex 接入外置模型的核心不是只改 model,而是同时声明模型 ID、provider ID、API 地址与认证来源。
- provider 配置应放在用户级 ~/.codex/config.toml 或独立 Profile 中;项目级 .codex/config.toml 会忽略 model_provider 和 model_providers。
- 当前 Codex 自定义 provider 的 wire_api 只支持 responses,只兼容 Chat Completions 的服务不能直接视为可用。
- API Key 应通过 env_key 指向环境变量,不要把真实密钥写进 TOML、仓库或教程截图。
- 是否接入成功要用一次真实的 codex exec 请求验证;配置文件能被保存,不等于鉴权、模型 ID、流式响应和工具调用都正常。
很多所谓“Codex 外置模型教程”只给出一段 config.toml,却跳过了最容易失败的地方:第三方服务究竟兼容的是 Responses API,还是较旧的 Chat Completions API。前者是当前 Codex 自定义 provider 的协议要求,后者即使也使用 /v1 路径,也不代表能直接接入。
Codex 外置模型实际由哪 4 个字段决定?
一套最小配置由 model、model_provider、base_url 和 env_key 共同决定。model 是第三方服务实际接受的模型 ID;model_provider 是 Codex 内部选择的 provider 名称;base_url 决定请求发往哪里;env_key 则告诉 Codex 从哪个环境变量读取 API Key。
这四项像一张快递单:模型 ID 是收件人,provider ID 是你在 Codex 中给这条线路起的名字,API 地址是目的地,环境变量是通行凭证。少一项,或者把模型 ID 写成网站展示名而非接口 ID,请求都可能在真正生成代码之前失败。
OpenAI 的配置参考还规定,自定义 provider 不能占用 openai、ollama 和 lmstudio 这三个内置 ID。换句话说,你可以把 provider 命名为 external、company_proxy 或服务商名称,但不要试图用自定义表覆盖内置 provider。 如何使用 4 个字段完成第三方 API 最小配置?
建议先创建独立 Profile,而不是直接改掉日常使用的默认模型。新建 ~/.codex/external.config.toml,填入以下模板,再把占位内容替换为服务商文档给出的真实值:
wire_api = "responses" 即使省略也会使用当前默认值,但显式写出更利于排查。这里不能改成 chat 或 chat_completions:官方高级配置文档与配置参考均显示,responses 是当前唯一支持的自定义 provider 协议。 base_url 是否应包含 /v1,要看服务商文档。不要机械复制示例,因为有的网关把版本路径包含在基础地址中,有的会由客户端拼接。判断标准不是 URL 看起来像不像 OpenAI,而是它最终能否接受 Codex 发出的 Responses 请求。
如何使用环境变量配置 API Key?
先在当前终端临时设置环境变量,验证成功后再决定是否写入安全的 shell 配置或密钥管理工具:
随后用同一个终端启动 Codex。env_key = "EXTERNAL_API_KEY" 保存的只是环境变量名称,不是密钥本身。OpenAI 配置参考明确不鼓励把 bearer token 直接写进配置;如果企业网关使用短期令牌,也可以改用命令式认证,让 Codex 在需要时调用凭据助手取得 token。
如果你从桌面图标或 IDE 启动 Codex,终端里的临时 export 不一定会进入该进程。这时最典型的现象是:终端测试成功,IDE 却报 401。应先确认启动方式和环境变量继承关系,而不是反复修改 base_url。
如何使用 Profile 验证 Codex 已接入外置模型?
保存配置后,在设置过 API Key 的同一终端执行一次最小请求:
如果返回预期文本,至少可以确认 Profile 被读取、环境变量存在、基础地址可达、鉴权通过、模型 ID 被服务端接受,并且基础流式响应能够完成。独立 Profile 的价值在于不破坏默认配置:日常仍可直接运行 codex,需要外置模型时再加 --profile external。
进一步验收时,不要停在“一句话能回复”。再让模型读取一个测试目录、调用一个无副作用工具并生成小型 diff。Codex 是编码代理,不是普通聊天框;有些中转服务可以转发纯文本,却不能完整处理 Responses 事件、工具调用或推理字段。
为什么配置正确仍然连接失败?
第一类是配置作用域错误。Codex 的 CLI 与 IDE 扩展共享配置层,但 provider 与认证属于机器本地设置。官方文档明确说明,项目级 .codex/config.toml 中的 model_provider、model_providers 和 openai_base_url 会被忽略;应把它们放进用户级配置或 $CODEX_HOME 下的 Profile 文件。
第二类是协议不兼容。若服务商只文档化 /v1/chat/completions,没有 Responses API 或等价的协议转换层,不应宣称它“支持 Codex”。常见表现包括 404、请求字段不被识别、连接开始后流式中断,以及文本回复正常但工具调用失败。
第三类是地址、模型名或认证头不匹配。先用服务商自己的文档确认模型 API ID 和基础地址,再检查环境变量是否进入 Codex 进程。需要自定义请求头时,可以使用 http_headers;需要从环境变量取请求头时,使用 env_http_headers。不要为了通过鉴权,把真实 token 直接写进仓库里的配置。
第四类是能力被高估。自定义 provider 的独立网页搜索能力默认关闭;即使设置 supports_standalone_web_search = true,也只是在声明能力,服务端、所选模型和运行时仍必须真的支持兼容端点。对于第三方模型,最稳妥的验收顺序是纯文本、流式输出、工具调用、长上下文,最后才是搜索等附加能力。
Codex 外置模型配置的 5 条行动清单
- 先确认第三方服务支持 Responses API,不能只看“OpenAI 兼容”四个字。
- 用独立 external.config.toml Profile 试跑,避免覆盖可用的默认模型配置。
- 通过 env_key 读取 API Key,不在 TOML、Git、日志或截图中留下真实密钥。
- 用 codex exec --profile external 发起真实请求,并继续验证工具调用,而不是只检查文件语法。
- 失败时按“配置作用域 → 环境变量 → URL → 模型 ID → Responses 事件”的顺序排查,避免同时改动多项配置。
Codex 能否接入外置模型,最终取决于协议兼容性,而不是模型品牌。配置文件解决的是“请求发到哪里”,真实验收还要回答“返回的事件能否让编码代理继续工作”。只要守住这一区别,第三方云 API、企业代理和本地兼容服务都可以用同一套思路判断,而不必为每家服务商背一份互相矛盾的配置模板。