Codex 如何配置第三方 API（2026 年 7 月最新版）：ChatGPT 合并后接入指南

最后更新时间：2026-07-23

AIMirror GPT 中文站

现在配置 Codex 第三方 API，先要改掉一个旧印象：Codex 的桌面入口正在合并进新的 ChatGPT 桌面 App，但本地 CLI、IDE 扩展和 ~/.codex/config.toml 仍是独立的工程配置面。ChatGPT 登录适合使用账号套餐内的 Codex 能力；第三方 API 则是让本地 Codex 向你指定的兼容服务发请求，两者不是同一份凭证，也不能互相替代。¹² 截至 2026 年 7 月，官方配置参考明确规定：自定义 provider 使用 Responses API，wire_api 只有 responses 一种受支持的值，省略时也默认走它。³

先给结论：什么能配，什么不该配

只要服务商明确支持 OpenAI Responses API，并向你提供可用的基础地址、API key 和模型 ID，就可以通过 model_provider 接入 Codex。最小配置由五部分组成：model 指向实际模型 ID，model_provider 选中你的 provider，base_url 指向服务地址，env_key 写环境变量名称，wire_api 固定为 responses。名称可以自定义，模型 ID 却不能猜，必须以服务商控制台或模型列表为准。

最重要的边界是配置位置。provider、base_url、认证字段只能写在用户级 ~/.codex/config.toml，不能写进仓库的 .codex/config.toml。官方说明，项目级配置即使出现 model_provider、model_providers 或 openai_base_url，Codex 也会忽略并在启动时提示警告。² 这项限制很有价值：它防止你拉取一个仓库后，被仓库配置悄悄改到陌生网关或窃取凭证。

第 1 步：先确认你不是在给 ChatGPT 登录“换 API”

合并后的产品体验容易造成混淆。ChatGPT 桌面 App 里的 Codex 模式、Codex CLI 和 IDE 扩展可以共享任务体验，但 API 路由仍按本地配置决定。你若只想使用 ChatGPT 账号内的能力，运行 codex login 并保持默认 openai provider 即可；你若希望统一账单、经过企业网关，或试用自建的兼容服务，才需要配置第三方 API。

这一步要先做选择，而不是把两种认证叠在一起。个人日常开发且不需要特殊路由，ChatGPT 登录操作最少；脚本、CI 或明确指定服务商的项目，API key 更容易审计和轮换。无论选哪一种，生产源码、客户数据、访问令牌和 .env 文件都不应为了“让模型看得更全”直接发送到不受你数据协议约束的服务。先使用脱敏副本跑通，再根据组织的合规要求扩大范围。

第 2 步：把密钥放进环境变量，不要写进 TOML

以下示例使用通用占位名称 THIRD_PARTY_API_KEY，不绑定某个服务商。先在当前 shell 注入密钥：

export THIRD_PARTY_API_KEY="替换为服务商控制台生成的密钥"

它适合第一次连通性测试，因为关掉终端后变量会失效，泄露面较小。需要长期使用时，把变量保存到操作系统提供的密钥管理或团队批准的秘密管理器；不要把真实 key 写入 config.toml、AGENTS.md、shell 脚本、共享 dotfiles 或 Git 仓库。CI 则应把同名变量作为受保护的 Secret 注入，并限制它只在需要的部署环境可读。

验证也不要打印完整密钥。macOS/Linux 可以先执行 test -n "$THIRD_PARTY_API_KEY" && echo "key loaded"；Windows PowerShell 可用 if ($env:THIRD_PARTY_API_KEY) { "key loaded" }。看到 key loaded 即可进入下一步。若没有输出，先处理环境变量作用域，不要急着改 Codex 配置。

第 3 步：写入用户级 config.toml

打开 ~/.codex/config.toml。没有这个文件时可以新建；已有默认模型、审批或沙箱设置时，只增加下面的字段，不要覆盖原有配置。将 https://api.example.com/v1 和模型 ID 替换成服务商公开文档或控制台显示的真实值：

model = "provider-console-model-id"
model_provider = "third-party"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.third-party]
name = "Third-party Responses API"
base_url = "https://api.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"

这段配置里，third-party 只是本机标签，保持前后一致即可。base_url 是否包含 /v1 取决于服务商给出的完整 API 基址，不能凭常识补删；错误时通常会得到 404。官方当前也保留 openai、ollama、lmstudio 等内置 provider ID，因此不要把自定义 provider 命名成这些保留值。² approval_policy = "on-request" 与 sandbox_mode = "workspace-write" 是较适合初次接入的保守组合：Codex 能在工作区改文件，涉及需要确认的操作仍会暂停询问。

有些旧教程会让你把 wire_api 写成 Chat Completions 或用一个“兼容模式”蒙混过去。不要这样做。最新版参考页列明 Responses 是唯一支持的 protocol；若服务商只提供 Chat Completions，而不提供 Responses 兼容层，它目前不适合作为 Codex 的 custom provider。³ 先在服务商文档中确认接口能力，能省掉大量看似网络错误、实为协议不匹配的排查时间。

第 4 步：按顺序做三次验证

保存后重新打开一个终端和新的 Codex 会话，让新环境读取变量与配置。第一次请求不要让它修改项目，先选一个无敏感信息的小目录，执行一项只读任务：

codex "只读取当前目录的 README，列出项目用途和可能缺失的安装步骤；不要修改文件，也不要运行网络命令。"

第一关是启动：没有 provider 解析错误、环境变量缺失提示或保留 ID 冲突。第二关是路由：能得到正常回答，说明地址、密钥和模型 ID 至少已连通。第三关才是能力：新建一个临时仓库或可回滚分支，让 Codex 增加一处文档说明，再用 git diff 审核改动并跑项目已有检查。三关都通过，才可以把它用于真实开发。

若你使用 IDE 扩展，也不要只在图形界面里点一次就认定成功。CLI 与 IDE 都读取用户配置，但 IDE 可能保留旧会话；重启扩展并开新线程，再完成同一条只读任务，才能确认路由一致。对团队而言，建议记录服务地址、模型别名、测试日期和负责人，不记录密钥本身。

常见报错怎么定位

401 或 403 通常先查 key：变量名是否与 env_key 完全一致、密钥是否已过期、当前账号是否有该模型权限。404 多半是 base_url 或模型 ID 错误，尤其要检查服务商给的是根域名、/v1 还是更深一层项目路径。遇到 400、流式中断或“不支持 Responses”一类报错，优先检查 provider 是否真支持 Responses API，而不要反复调高重试次数。

另一类问题是“我明明写了配置却不生效”。先执行 pwd，确认你改的是当前系统用户的 ~/.codex/config.toml；再检查是否误写到了项目的 .codex/config.toml。官方的加载顺序允许项目层覆盖许多工程设置，但特意禁止项目层改 provider 和认证。² 因此，第三方路由不生效时，回到用户级配置才是正确修复方向。

最后别把模型能力问题误判为配置问题。请求成功但工具调用、长上下文或推理质量差，可能是服务商模型本身没有完整实现 Codex 所需的 Responses 行为。此时用一个官方或已验证模型做同样的只读测试，比较请求 ID、错误信息和输出；若只有第三方失败，应向服务商提供最小复现，而不是降低沙箱或把更多仓库权限交出去。

进阶：默认官方路由与第三方路由怎样共存

需要在官方 OpenAI 路由和第三方 API 之间切换时，最清晰的办法是使用不同 profile，而不是反复手改同一个文件。官方高级配置说明，codex --profile profile-name 会先加载 ~/.codex/config.toml，再叠加 ~/.codex/profile-name.config.toml。² 基础配置保留你的通用沙箱和审批策略，把第三方的 model、model_provider 与 [model_providers.*] 放到单独 profile 中；需要时再显式切换。

这种做法的好处是可审计：你一眼能知道当前会话走哪条路，也能让 CI 只加载必要的配置。备用方案是保留一份无第三方 provider 的默认用户配置，在需要时临时导出变量并使用 profile。无论哪种方式，复核标准都一样：切换后先跑只读任务，确认模型和服务端日志正确，再允许写入工作区。

FAQ

Codex 和 ChatGPT 合并后，CLI 还能接第三方 API 吗？

可以。合并影响的是桌面产品入口与工作流，CLI、IDE 扩展及用户级 config.toml 的 provider 配置仍然存在。不要把 ChatGPT 登录态当成第三方 key，也不要把第三方 key 当成 ChatGPT 订阅凭证。

能否把 API key 写进项目的 .codex/config.toml，方便团队共享？

不能，也不应这样做。项目层的 provider 与认证字段会被 Codex 忽略，而且密钥进入仓库会带来泄露与轮换成本。团队应共享无密钥的工程规则，凭证则由每位成员的密钥管理器或 CI Secret 提供。

为什么按旧教程配置 Chat Completions 后无法工作？

因为官方 2026 年 7 月配置参考已将 custom provider 的 wire_api 限定为 Responses。服务商若不提供 Responses 兼容能力，就应选另一个网关、使用其原生客户端，或等待其更新兼容层。

行动建议

配置 Codex 第三方 API 时，先以用户级 config.toml、环境变量和 Responses 兼容性跑通一个只读任务，再考虑写入、自动化与团队推广。低风险的中文问答、资料梳理和提示词打磨，可先在 AIMirror GPT 中文站 完成；真实仓库改动则应保留本地 diff、测试与人工 review。这样既能利用 ChatGPT 与 Codex 合并后的统一工作流，也不会把路由、密钥和工程权限混成一团。