Codex 接入第三方大模型 API 教程：配置、验证与排错（2026）

Codex 接入第三方大模型 API，关键不在于把一个 API 地址粘贴进配置文件，而在于先确认服务商是否提供 Codex 所需的 Responses 兼容能力，再把密钥、provider 和模型 ID 分开管理。本文面向 Codex CLI、桌面端和 IDE 用户，给出一套可以逐步验证的配置流程。示例只使用占位地址和变量名，请以你实际购买的服务商文档为准。

需要先比较中文回答、代码解释或提示词效果时，可以打开 AIMirror GPT 中文站 或 AICNBox 多模型入口 做网页端体验。两者是独立第三方服务，不会替你提供 Codex 的 API Key，也不改变本文的本地 provider 配置。

先确认三件事

第一，第三方服务要明确支持 OpenAI Responses API。Codex 自定义 provider 的 wire_api 支持 responses，不能把只提供 Chat Completions 的接口直接当成 Codex provider。第二，服务商要提供完整的 API 基地址、API Key 和可用模型 ID。第三，确认服务商允许把代码和文件发送到其服务器，并了解日志、留存、计费和删除规则。OpenAI 的 Responses API 本身支持文本、图像、文件和工具调用，但第三方网关未必完整实现这些能力。¹²

本教程中的三个占位符含义如下：https://api.example.com/v1 是服务商给出的基础地址，THIRD_PARTY_API_KEY 是本地环境变量名，provider-console-model-id 是控制台实际显示的模型 ID。不要把示例值原样复制到生产配置，也不要根据模型宣传名猜 ID。

配置前的兼容性清单

下单或开通服务前，先向服务商确认四个问题：是否支持 Responses API；是否支持流式事件；是否接受 Codex 会发送的工具调用字段；是否允许代码类请求并说明数据留存周期。只写着“兼容 OpenAI”的宣传语不够，最好取得接口文档、示例请求和错误码说明。若服务商只给出 Chat Completions 示例，应把它视为另一种协议，不能直接套用本文的 wire_api = "responses"。

同时记录服务商名称、接口基础地址、模型 ID、价格单位、限流规则和客服联系方式。记录时只保存不含密钥的配置摘要，并注明核验日期。模型名称可能随套餐或地区变化，出现 404 时可以先回到这份摘要逐项对照，而不是连续重试导致额外费用。

ChatGPT 登录和第三方 API 不是一回事

Codex 使用 ChatGPT 账号登录时，走的是 OpenAI 账号和套餐内的 Codex 能力；使用第三方 API 时，Codex 会把请求发给你指定的 provider，费用、权限、日志和服务协议由第三方负责。这两种方式可以共存，但不共享凭证。不要把 ChatGPT 密码当成 API Key，也不要把第三方 Key 填进官方登录窗口。

个人开发者若只想使用默认 OpenAI 路由，保持官方登录即可。需要统一企业网关、使用另一个模型、按第三方账单计费，或测试自建兼容服务时，再配置 custom provider。第一次接入建议使用没有敏感数据的临时项目，等只读任务验证通过后再处理真实仓库。

第一步：把 API Key 放进环境变量

macOS 或 Linux 终端可以先临时设置变量：

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

Windows PowerShell 可以使用：

$env:THIRD_PARTY_API_KEY = "替换为服务商生成的密钥"

先验证变量是否存在，不要打印完整 Key：

test -n "$THIRD_PARTY_API_KEY" && echo "key loaded"

需要长期使用时，把变量放进操作系统的密钥管理器、受保护的 CI Secret 或你所在团队批准的凭证系统。不要把真实 Key 写入 config.toml、AGENTS.md、脚本、截图或 Git 仓库。测试结束后可以撤销旧 Key，再生成一枚权限更小的新 Key。

第二步：配置用户级 config.toml

打开 ~/.codex/config.toml。没有文件可以新建；已有审批、沙箱、默认模型等设置时，只增加 provider 配置，不要覆盖原内容。下面是最小示例：

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 只是本机标签，model_provider 必须与它完全一致。base_url 要按服务商文档填写：有的服务商要求根路径，有的要求带 /v1，不要凭经验增删路径。env_key 只写变量名，不要在 TOML 中写真实密钥。wire_api 保持为 responses，服务商若只有 Chat Completions 接口，应先确认是否有 Responses 兼容层。

provider 和认证配置应放在用户级文件。项目内的 .codex/config.toml 可以保存团队共享的沙箱、审批和项目规则，但不要把 API Key 或第三方路由写入仓库。这样做既能避免密钥泄露，也能防止你克隆一个不熟悉的仓库后被项目配置悄悄切换到陌生网关。³

第三步：启动后做只读验证

保存配置后，在刚才设置环境变量的同一终端启动新的 Codex 会话。临时 export 不会自动传到新开的终端或从桌面图标启动的应用；换终端时需要重新设置变量。第一次任务不要修改文件，也不要上传未脱敏资料：

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

验证分三层。启动层不能出现 provider 解析、变量缺失或 TOML 语法错误；请求层要能返回正常回答，说明地址、Key 和模型 ID 至少已经连通；能力层再用一个临时目录做小改动，检查 git diff 并执行项目已有测试。第三层通过后，才适合让 Codex 操作真实仓库。

如果你同时使用 IDE 扩展，重启扩展并新建会话。旧会话可能仍保留默认路由，不能只看界面上出现了模型名称就判断接入成功。团队可以记录服务商、基础地址、模型 ID、验证日期和负责人，但不要记录密钥。

验证结果怎么记录

建议为每个 provider 保留一份简短的验证记录：日期、客户端版本、模型 ID、是否能完成纯文本请求、是否能读取项目说明、是否能在审批后修改临时文件，以及服务商后台是否出现对应调用。验证记录不要包含用户内容、完整响应或 API Key。这样在模型升级、网关迁移或费用异常时，可以快速判断是配置变化还是模型能力变化。

验证顺序应保持从低风险到高风险。先做不含代码和个人资料的短问答，再读取一个公开 README，之后在临时目录创建一个无关紧要的小文件，最后才考虑真实仓库。每一步都检查终端输出、git diff 和服务商用量页面。任何一步出现权限、协议或数据处理疑问，都先暂停，不要用“多试几次”替代排查。

常见报错定位

401 或 403 通常先检查环境变量名、Key 是否过期，以及账号是否拥有该模型权限。404 多半是 base_url、路径或模型 ID 不正确；尤其要核对服务商要求的是根域名、/v1 还是更深的项目路径。400、流式中断或“不支持 Responses”时，先检查协议兼容性，不要盲目增加重试次数。

“我写了配置但没有生效”时，先检查是否设置了 CODEX_HOME；没有自定义时，用户配置通常位于 ~/.codex/config.toml。再核对是否误写到项目 .codex/config.toml，或被启动参数、profile 覆盖。若只读请求成功、代码任务失败，问题可能在工具调用、流式事件、图片输入或模型推理能力，而不一定是 Key 错误。用同一个公开小任务分别测试官方 provider 和第三方 provider，保留最小报错信息，再向服务商反馈。

失败后的回滚方案

第三方网关出现故障时，先停止正在运行的写入任务，保存终端报错和工作区差异。把 model_provider 切回原来的官方 provider，或使用已经核验过的备用 profile，再重新执行只读检查。不要在故障期间同时修改 URL、模型 ID 和权限设置，否则很难判断到底是哪一项修复了问题。

确认恢复后，撤销可能已经暴露的 Key，检查服务商调用日志和余额，再决定是否继续使用原网关。若项目涉及客户代码或生产配置，还应通知项目负责人复核数据是否被发送到第三方。回滚的目标是恢复可控状态，而不是保证所有未完成任务自动续跑。

一份可复用的接入检查表

完成配置后，可以按下面顺序复核：第一，终端变量存在且没有出现在日志；第二，config.toml 的 provider 标签和 model_provider 完全一致；第三，基础地址没有重复路径；第四，模型 ID 来自服务商控制台；第五，纯文本只读任务成功；第六，服务商后台有对应调用；第七，写入权限仍由审批策略控制。任何一项无法确认，都不要把这次接入标记为“已完成”。

这份检查表适合交给团队中的同事复核，也适合在更换模型后重新执行。尤其是第三方网关更新协议、调整模型名称或迁移区域时，旧配置可能仍能启动，却在工具调用或长文本任务中失败。把验证拆成独立步骤，能减少误判和重复扣费。

对个人用户而言，最重要的是保留回退能力；对团队而言，还要把配置摘要、预算和责任人写进交接记录。这样即使原服务商临时限流，也能在不暴露密钥的前提下切换到已核验的路线。

用 profile 切换官方与第三方路由

经常切换时，不建议反复改主配置。Codex 支持按 profile 保存一组模型和 provider 设置；在默认 CODEX_HOME 目录下，可为 profile 建立对应的配置文件，例如 ~/.codex/third-party.config.toml，其中放入前文的 model、model_provider 和 provider 段，再用 codex --profile third-party 启动。实际文件名和命令参数以当前版本配置参考为准，先用 codex --help 核对。每次切换后都先跑一条只读任务，确认当前模型和服务端日志符合预期，再允许写入工作区。profile 方便审计，也便于在服务商故障时回到官方路由。³

上述 profile 文件使用顶层配置键，不要再套一层 [profiles.third-party]。这是本文核验日期的官方配置方式，旧版本客户端可能不同；升级前先备份不含密钥的配置。IDE 与桌面端是否采用相同选择方式，应以对应版本设置为准，不能把 CLI 参数直接粘贴进图形界面。³

安全和费用边界

Codex 可能读取代码、文档、终端输出和你主动提供的文件。接入第三方前，先脱敏客户数据、令牌、私钥、生产配置和内部文档；把工作目录限制在必要范围，保留审批确认，不要为了“让模型更聪明”关闭沙箱。第三方模型产生的 Token 费用由服务商计收，建议设置预算、用量提醒和 Key 轮换周期。

FAQ

只支持 Chat Completions 的网关能接 Codex 吗？

不能直接下结论。需要服务商提供明确的 Responses 兼容层，并说明基础地址、事件格式和工具调用支持。没有兼容说明时，优先使用原生客户端或选择已验证的 provider。

API Key 可以放进项目配置方便团队共享吗？

不可以。密钥应由个人密钥管理器或 CI Secret 注入，项目仓库只保存不含凭证的工程规则。共享配置时也要避免把完整网关地址和内部项目标识暴露给无关人员。

能否一边登录 ChatGPT，一边使用第三方模型？

可以，但两者是不同路由。通过 profile 或明确的 provider 切换更容易审计；每次切换后先完成只读验证，不要把不同服务商的 Key 混用。

总结

Codex 接入第三方大模型 API 的稳妥顺序是：确认 Responses 兼容性，准备真实模型 ID，把 Key 放入环境变量，在用户级 config.toml 配置 provider，先用只读任务验证，再逐步开放写入权限。真实项目接入时，仍应以服务商文档、用量页面和数据协议为准。