# Codex 接第三方模型 API：先确认 Responses 兼容，再写 provider

> 用用户级 config.toml 或独立 profile 为 Codex 配置第三方模型提供方，安全传入 API Key，并按认证、模型、协议、流式响应和限流逐层验证。

- Source: https://www.aifreeapi.com/zh/posts/codex-third-party-api
- Language: zh
- Published: 2026-08-25
- Updated: 2026-08-25
- Publisher: AI Free API (https://www.aifreeapi.com)

把 Codex 的模型请求切到第三方服务，真正的门槛不是“有一个 API Key”，而是服务商是否实现了 Codex 当前使用的 **Responses API 协议**。不少平台写着“OpenAI-compatible”，实际只兼容 `/v1/chat/completions`；这样的地址即使能被普通 SDK 调用，也不一定能处理 Codex 的流式输出、工具调用和推理元数据。

一个可用的接入至少要同时满足四个条件：服务商明确提供 Responses 端点；模型 ID 在该端点真实存在；认证头符合服务商约定；流式响应能持续返回并正常结束。确认这些条件后，再改配置，能避免把协议不兼容误判成密钥或网络问题。

这里讨论的是 **Codex 调用哪个模型提供方**。MCP 是给 Codex 增加数据库、浏览器或业务系统等外部工具；两者都可能被叫作“外部 API 接入”，但配置位置、认证和失败表现完全不同。

![Codex 第三方模型 API 从兼容性确认、provider 配置到路由验证与回滚的路线图](https://www.aifreeapi.com/posts/zh/codex-third-party-api/img/provider-validation-troubleshooting.webp)

## 最稳妥的试法是单独建一个 profile

OpenAI 当前的 [Codex 高级配置文档](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers) 把 provider 定义为 base URL、wire API、认证和可选 HTTP headers 的组合。`model_provider` 与 `model_providers` 属于机器本地配置，项目里的 `.codex/config.toml` 会忽略这些键；它们应放在 `~/.codex/config.toml`，或放进同目录的独立 profile 文件。

如果你还要保留 ChatGPT 或 OpenAI 官方路线，独立 profile 比直接覆盖主配置更容易回退。新建 `~/.codex/third-party.config.toml`，先写最小配置：

```toml
model = "provider-model-id"
model_provider = "acme"

[model_providers.acme]
name = "Acme Model API"
base_url = "https://api.example.com/v1"
env_key = "ACME_API_KEY"
wire_api = "responses"
```

这里的 `acme` 只是你自定义的 provider ID，必须与 `[model_providers.acme]` 对上；`provider-model-id` 和 `base_url` 则必须逐字使用服务商文档给出的值，不要照抄示例。不要复用 `openai`、`ollama` 或 `lmstudio` 作为自定义 ID，它们是保留名称。

OpenAI 的 [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference#configtoml) 目前只支持 `wire_api = "responses"`。如果服务商只给出 Chat Completions 地址，停止在这里，先向服务商确认 Responses 兼容端点；随意把路径改成 `/responses` 不能补出缺失的协议实现。

## 密钥放环境变量，不放 TOML 和仓库

`env_key = "ACME_API_KEY"` 的意思是：Codex 从名为 `ACME_API_KEY` 的环境变量读取凭据。它不是密钥本身。macOS、Linux 或 WSL 可在启动 Codex 的同一个 shell 中临时设置：

```bash
export ACME_API_KEY="你的真实密钥"
codex --profile third-party
```

PowerShell 可以在当前会话中设置：

```powershell
$env:ACME_API_KEY = "你的真实密钥"
codex --profile third-party
```

不要把真实值提交到 dotfiles 仓库、项目 `.env` 示例、截图或故障日志。官方参考虽保留 `experimental_bearer_token` 字段，但明确建议改用 `env_key`。有些服务商文档为了缩短示例，会把 token 直接写进配置；这只能说明那家服务商的演示方式，不会改变本地明文泄露风险。

桌面端还有一个容易忽略的边界：从 Dock、开始菜单或 IDE 启动的进程，未必继承你在某个终端窗口里临时 `export` 的变量。若 CLI 能用而桌面端报未找到密钥，先检查启动进程能否看到该环境变量，不要立即重写 `base_url`。服务商如果要求 `api-key`、租户 ID 或版本号等特殊 header/query 参数，应只按其第一方文档使用 `env_http_headers`、`http_headers` 或 `query_params`；不要猜字段。

## 一次验证要同时证明“模型”和“路由”

启动时显示了自定义模型，只能证明配置被读取，不能证明请求真的到达预期服务商。一次低风险验证最好包含三份证据：

1. Codex 当前会话显示的模型 ID 与 profile 相符；
2. 一条不读文件、不改代码的短请求得到完整响应，流没有中途断开；
3. 服务商控制台或网关日志在对应时间出现同一模型的请求、状态码和用量。

可以在一个不含敏感文件的空目录中启动：

```bash
mkdir codex-provider-check
cd codex-provider-check
codex --profile third-party
```

然后让模型只返回一个固定短句。若服务商提供 request ID，把时间、provider、模型 ID、HTTP 状态和 request ID 记下来，但不要记录密钥或完整提示内容。只有客户端与服务商两边证据一致，才能排除“界面显示自定义模型，但流量仍走另一条路”的疑问。

像 DeepSeek 这类服务商会提供自己的 Codex 接入说明。其当前[官方 Codex 文档](https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/codex/)明确写出 Responses 支持和专属模型配置，这可以证明 DeepSeek 路线；它不能证明另一家“OpenAI-compatible”网关也支持同样字段或功能。

## 失败时从最早的异常边界开始查

不要同时更换密钥、模型和 URL。保留最小配置，每次只修一层：

![Codex 第三方 API 的六层诊断矩阵，列出配置、环境变量、认证、路由、协议和限流的检查动作](https://www.aifreeapi.com/posts/zh/codex-third-party-api/img/layered-diagnostic-matrix.webp)

| 现象 | 最可能的归属 | 先做什么 |
|---|---|---|
| 启动即提示未知配置键 | Codex 版本或 TOML 语法 | 运行 `codex --version`，对照当前配置参考，检查表名和引号 |
| 提示环境变量不存在 | 启动进程没有拿到密钥 | 在同一 shell 设置变量再启动；桌面端另查其环境来源 |
| 401 / 403 | 密钥、认证头、项目权限或服务商账户 | 在服务商控制台核对 key 状态与所需 header，不要改模型名碰运气 |
| 404 / model not found | base URL 路径或 provider 模型 ID | 对照服务商的 Responses 文档与模型列表 |
| 请求建立后立刻解析失败 | 返回体不是 Responses 格式 | 停止使用 Chat Completions-only 路线，向服务商确认兼容性 |
| 输出一半卡住或反复重连 | SSE 流、代理超时或上游中断 | 记录 request ID 和断开时间，再查网关与服务商日志 |
| 429 | 第三方账户、网关或模型限额 | 按实际响应来源查余额和速率；ChatGPT 仍有额度不能证明第三方有容量 |

如果只有 429，可继续使用本站的 [Codex 限流归属排查](/zh/posts/codex-rate-limits)；如果表现为长时间无输出，转到 [Codex 超时分层诊断](/zh/posts/codex-timeout)。权限、项目配置与用户配置互相覆盖的问题，则看 [Codex config.toml 配置边界](/zh/posts/codex-config-toml)。

## 能回答问题，不等于功能完全等价

自定义 provider 成功返回文本后，仍要逐项验证你真正依赖的能力。OpenAI 当前文档指出，自定义 provider 的 standalone web search 默认关闭；即使设置支持标记，也需要服务商端点、模型、Codex 运行时和管理策略同时支持。图片输入、工具调用、推理摘要、WebSocket、插件或云端任务同样不能从一次文本成功自动推出。

计费和数据边界也随路由改变。ChatGPT 登录与 OpenAI API key 本来就是不同合同；第三方 provider 又有自己的余额、限流、日志、保留政策和支持责任。使用第三方模型时，应以该服务商的控制台和条款判断成本与数据处理，不要把 ChatGPT 套餐权益当作第三方用量包。

完成验证后，如果希望把第三方路线设为长期默认，再把已验证的最小块移入用户主配置。若只是偶尔使用，保留 profile 更清楚。回滚时退出当前会话并不再传 `--profile third-party` 即可；如果曾修改主配置，只删除你新增的 `model`、`model_provider` 与对应 provider 表，保留其他认证、MCP、规则和历史状态，不要删除整个 `~/.codex`。