进阶教程 · 接入

Codex 第三方 API / 中转接入指南

如何配置 API Key、第三方中转与常见限制说明，帮你安全完成第一次接入。

声明：本文是 CodexNav 的中文实践说明，非 OpenAI 官方文档。第三方中转/聚合服务仅作配置思路说明，不构成推荐或背书。密钥安全、账单、合规与数据风险需自行承担。字段名与行为可能随 Codex 版本变化，以官方 config / CLI 文档为准。

更新核验：2026.09

先说结论

  1. 入门不必接第三方 API。优先用官方 ChatGPT 登录把 国内安装 和 第一次任务 跑通。
  2. 第三方接入适合：已理解 config.toml、Base URL、模型名；或必须走兼容网关/自建入口。
  3. 只选一种鉴权方式：ChatGPT 登录 或 API Key，不要混用。
  4. Key 放环境变量或本机鉴权文件，不要写进仓库、截图、公开文档。
Codex 第三方 API / 中转接入指南的入口、目标与准备条件操作示意图
图 1 · 进入任务前先确认目标、范围和准备条件

你在改什么

常见本机文件：

路径作用
~/.codex/config.toml模型、provider、Base URL、行为开关
~/.codex/auth.json登录态 / API Key 相关鉴权信息

改之前先备份：

cp ~/.codex/config.toml ~/.codex/config.toml.backup
cp ~/.codex/auth.json ~/.codex/auth.json.backup 2>/dev/null || true

配置分层与常见键，见：config.toml 速查。

方案怎么选

方案适合谁注意
官方登录绝大多数用户最稳；先走这条
手动改 config.toml想看清底层配置、方便排障字段写错就不生效
第三方图形管理 / 网关工具要多供应商切换、协议转换第三方维护风险；Codex 更新可能要跟进

下面只讲手动配置的最小可验证路径。图形工具与网关属于进阶，自行评估信任与维护成本。

手动配置：最小示例

目标：新增一个 provider，把请求指到兼容的 Responses API 入口。

  1. 在 shell 里注入 Key（示例名，按你的服务商文档调整）：
export OPENAI_API_KEY="你的密钥"
# 确认没有首尾空格或换行
printenv OPENAI_API_KEY | od -c | head
  1. 在 ~/.codex/config.toml 增加类似结构（示例值请替换）：
model = "你的模型名"
model_provider = "my-api-provider"

[model_providers.my-api-provider]
name = "My API Provider"
base_url = "https://example.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
requires_openai_auth = false

容易写错的点

  • model_provider 必须和 [model_providers.xxx] 的 xxx 完全一致
  • base_url 通常写到 /v1，不要再拼一遍完整 /v1/responses 路径
  • 上游若只支持 Chat Completions、不支持 Responses，往往不能只靠改 toml，需要协议转换网关
  • 改完后完全退出再启动 Codex / 新开终端再跑 codex
Codex 第三方 API / 中转接入指南的三步关键操作与请求骨架示意图
图 2 · 把关键操作拆成三步，并给每一步留下可观察结果

接入后怎么验收

用只读任务验证，不要一上来改生产代码：

请只读说明：当前工作区路径、你准备使用的模型、当前鉴权方式。不要修改任何文件。

通过标准：

  1. 能正常返回，且模型名符合预期
  2. 没有 401 / 鉴权类报错
  3. 需要回滚时，能一键恢复 .backup 文件

失败时先看：401 / 429 / 超时排错。

Codex 第三方 API / 中转接入指南的结果验收与交付证据清单示意图
图 3 · 用结果、检查与交付证据确认任务真的完成

风险清单

  • Key 泄露 → 账单与数据风险
  • 不可信中转 → 请求/代码上下文可能被记录
  • 模型名映射错误 →「看起来连上了」但能力降级
  • 混用登录态 → 间歇性 401、重连异常
  • 把真实 Key 贴进聊天或 Issue → 立即轮换 Key

和站内其它页的关系

参考资料