Codex 使用教程：如何接入第三方大模型 API

Codex 默认可以使用 OpenAI 提供的模型和 ChatGPT 计划能力。如果你希望在 Codex 里测试其他厂商的模型、自建推理服务或兼容 OpenAI API 的网关，可以通过 provider 配置把请求发到自定义 API 地址。

这类接入适合开发者做模型比较、成本测试、局域网服务调用和供应商切换。配置前要确认三件事：第三方服务是否兼容 Codex 需要的 API 形式，模型 ID 是否真实可用，API Key 是否只保存在本机或密钥管理系统中。

先理解 Codex 的接入结构

Codex 的一个 provider 通常包含四类信息：

配置项	作用
provider ID	在 Codex 中识别这套服务的名称
base_url	API 服务的根地址，通常包含 /v1
env_key	指定从哪个环境变量读取 API Key
wire_api	指定请求使用的 API 形态，例如 Responses

第三方平台的“兼容 OpenAI”并不代表能直接接入 Codex。当前官方配置参考中，wire_api 只支持 responses。仅提供 Chat Completions 的服务需要通过支持 Responses 的网关或适配层接入；还要检查工具调用和流式输出是否兼容。参见 Codex 配置参考。

Codex 配置文件放在哪里

个人默认配置通常放在：

~/.codex/config.toml

Codex CLI 和 IDE 扩展共用配置层。项目里的 .codex/config.toml 适合放项目级设置，但 provider、认证和主机地址属于机器本地配置，建议写在用户级 ~/.codex/config.toml。当前官方配置参考还特别说明，项目级配置不会接受 model_provider 和 model_providers 等机器本地 provider 字段。

如果只想临时测试一次，也可以使用 CLI 的 -c 参数覆盖配置；长期使用则把配置写入用户级文件，并用环境变量提供密钥。

第一步：准备第三方 API

你需要从第三方服务获取以下信息：

• API 根地址，例如 https://api.example.com/v1。
• API Key 对应的环境变量名。
• 服务方提供的准确模型 ID。
• 服务支持的 API 形态：Responses、Chat Completions 或其他协议。
• 是否支持流式输出、工具调用、文件和图像输入。

不要根据模型名称猜测接口地址，也不要把 API Key 直接写进 config.toml、Git 仓库或文章。若服务商没有明确说明兼容协议，先用它提供的 curl 示例验证请求格式。

第二步：配置一个自定义 provider

下面是一个使用 Responses API 的通用示例。示例中的域名、模型 ID 和环境变量名都是占位符，使用前替换成你的服务商实际值：

model = "third-party-model"
model_provider = "third_party"

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

然后在当前终端设置 API Key：

export THIRD_PARTY_API_KEY="your-api-key"

在 macOS 或 Linux 中，想让每次打开终端都能使用，可以把环境变量写入 shell 的用户配置文件；在团队或生产环境里，优先使用操作系统密钥链、CI Secret 或专门的 Secret Manager。不要把真实 Key 写进项目文件。

第三步：确认 wire_api

服务支持 Responses API

如果第三方服务明确支持 /v1/responses，可以使用：

wire_api = "responses"

这种方式更接近当前 OpenAI 代理工作流，但具体还要检查工具调用、流式事件和输入格式是否都兼容。

服务只支持 Chat Completions

如果服务只提供 /v1/chat/completions，当前 Codex 无法通过把 wire_api 改成 chat 来直接接入。需要服务方提供 Responses 兼容接口，或使用能转换请求、工具调用和流式事件的适配层。仅修改 URL 路径不会完成协议转换。

最稳妥的做法是先用一个最小文本请求测试，再逐步测试流式输出、工具调用、文件输入和长对话。不要把“能返回一句话”当作完整兼容。

第四步：选择模型并启动 Codex

配置完成后，使用配置文件里的模型启动 Codex：

codex

也可以在一次运行中覆盖模型或 provider：

codex --model third-party-model -c 'model_provider="third_party"'

如果 Codex 启动后仍使用默认模型，按下面顺序检查：

1. model_provider 的 ID 是否与 [model_providers.<id>] 完全一致。
2. model 是否是服务商实际支持的模型 ID。
3. THIRD_PARTY_API_KEY 是否存在于启动 Codex 的同一个终端环境。
4. base_url 是否包含正确的 API 前缀，例如 /v1。
5. 远程地址是否使用 HTTPS。

第五步：用最小任务验证连接

不要一开始就让 Codex 修改整个代码库。先用三个低风险任务检查链路：

文本任务

让 Codex 解释一段短代码，确认模型能返回完整文本，并观察终端是否报告鉴权或协议错误。

文件任务

让 Codex 读取一个不含秘密的本地文件并提取三条信息。如果文本请求成功、文件请求失败，说明第三方接口可能没有实现 Codex 所需的输入格式。

工具任务

让 Codex 执行一个只读命令，例如列出当前目录文件。工具调用需要服务端和客户端都支持对应协议；如果模型只会返回文字而不会调用工具，检查 provider 的 wire API 和服务方文档。

验证时建议记录模型名、请求时间、错误信息和是否产生费用。不要在调试日志中公开 Authorization、API Key 或完整的敏感请求体。

常见报错与处理方法

401 Unauthorized

通常是 API Key 缺失、变量名写错、Key 已过期或网关要求另一种认证头。检查环境变量是否在 Codex 进程中可见，并确认服务方的认证方式。

404 Model not found

模型 ID 不一定等于网页上显示的昵称。到第三方 API 文档或模型列表确认准确 ID，注意大小写、版本后缀和区域名称。

404 endpoint not found

常见原因是 base_url 多了一层或少了一层路径。例如服务要求 /v1，配置却写成了域名根目录；也可能是服务只支持 Chat Completions，而 Codex 正在请求 Responses。

400 invalid request

说明请求已到达服务，但字段不符合它的协议。先用最简单的文本请求排查，再逐项加入系统提示词、工具、图片和结构化输出。

能聊天，但无法执行工具

这通常表示文本接口基本可用，工具调用协议没有完整兼容。确认服务方是否支持工具调用、流式事件和 Codex 使用的请求字段；必要时把第三方模型用于文本任务，把工具型编程任务切回官方支持的 provider。

用 profile 管理多个模型服务

如果你经常在 OpenAI、第三方网关和本地模型之间切换，可以为不同 provider 建立 profile。比如用户配置目录里可以保存：

~/.codex/config.toml
~/.codex/third-party.config.toml
~/.codex/local.config.toml

当前官方文档使用单独文件保存 profile；Codex 0.134.0 及之后的版本不再读取旧的 [profiles.<name>] 表。可将上面的 provider 示例写入 ~/.codex/third-party.config.toml，使用顶层配置键，然后运行：

codex --profile third-party

profile 会覆盖基础用户配置中的对应项。避免把 API Key 写进 profile 文件，详见 高级配置的 Profiles 说明。

安全边界

第三方模型 API 会把提示词、代码片段和文件内容发送给对应服务商。接入前应确认：

• 数据是否用于训练或日志保存。
• 是否支持删除请求记录。
• 服务商是否提供企业隔离和访问审计。
• API Key 是否可以设置额度、来源 IP 和最小权限。
• 网关是否会把请求转发给其他模型供应商。

在 Codex 中使用第三方 provider 时，先关闭或避免发送敏感文件，再逐步扩大任务范围。API Key 只放在环境变量或密钥管理系统里，定期轮换；发现泄露后立即撤销，不要只修改本地配置。

Codex 接入第三方 API 的推荐流程

1. 阅读第三方服务的 API 兼容说明，确认提供 Responses 接口。
2. 创建一个权限有限、额度有限的 API Key。
3. 在 ~/.codex/config.toml 中配置 provider、模型和 HTTPS 地址。
4. 用环境变量注入 Key，启动 Codex 做最小文本测试。
5. 依次测试文件读取、多轮对话和工具调用。
6. 记录费用、错误和输出质量，再决定是否用于日常开发。

常见问题

Codex 能接入任意大模型 API 吗？

不能直接保证。第三方服务至少需要提供与 Codex 当前 provider 配置相匹配的 API 协议、认证方式和模型 ID。协议不完整时，可能只能完成简单文本请求。

API Key 可以写在项目的 .codex/config.toml 里吗？

不建议。项目文件可能进入 Git、备份或共享目录。使用 env_key 让 Codex 从环境变量读取 Key，并对环境变量和密钥文件设置访问权限。

为什么项目级配置没有生效？

Codex 只在信任项目时加载项目级 .codex/ 配置，而且 provider、认证和主机地址属于用户级机器配置。把 provider 定义放到 ~/.codex/config.toml，再用项目配置覆盖适合项目的普通设置。

能否把第三方 API 用在团队仓库里？

先确认组织的数据政策、第三方服务条款和项目的代码保密要求。团队仓库不应共享个人 API Key，也不应默认把内部代码发送给未经批准的模型供应商。

总结

Codex 接入第三方大模型 API 的关键是三件事：provider 配置要放在正确的位置，base_url、模型 ID 和 API 协议要对应，密钥和数据边界要单独管理。先用最小任务验证文本、文件和工具链路，再决定是否把第三方模型用于日常开发。

官方参考：

• Codex 配置基础
• Codex 配置参考
• Codex 高级配置与自定义 Provider

更新时间：2026-10-21