Codex 接入第三方大模型 API 完全教程（2026 最新版）

caorui.

1364人浏览 · 2026-07-08 22:58:40

caorui. · 2026-07-08 22:58:40 发布

Codex 接入第三方模型API

适用 Codex CLI ≥ 0.110 / Codex IDE 扩展 / Codex Desktop App · 2026-07-09

Codex 之所以能跑 OpenAI 官方之外的模型，关键不是装什么插件、改什么源码，而是 ~/.codex/config.toml 里那张 [model_providers.<id>] 表：填 5 个字段（base_url / env_key / wire_api 加两个可选 header），Codex 就把请求按 OpenAI Responses 协议发到那个 endpoint。

所以接 DeepSeek、GLM、Qwen、本地 Ollama、Bedrock，以及各类 OpenAI 兼容聚合服务，走的是同一套机制。下面以一个 OpenAI 兼容聚合服务为例（文中以 EasyAPI 作为示例平台），把 5 字段配法跑通一次。

其它 OpenAI 兼容聚合平台、官方 Azure OpenAI、阿里云百炼、AWS Bedrock 等都按这个套路：只换 base_url 和 env_key 两个字段。

一、5 字段最小配置

~/.codex/config.toml：

model = "gpt-4o"
model_provider = "easyapi"

[model_providers.easyapi]
name = "EasyAPI 聚合"
base_url = "https://token.easyapi.com/v1"
env_key = "EASYAPI_KEY"
wire_api = "responses"
# 建议带上这俩 header，多数聚合服务用来排权和统计
http_headers = { "HTTP-Referer" = "https://localhost", "X-Title" = "Codex CLI" }

5 个字段拆开看：

字段	必填	说明
`model`	是	你要用的模型名（按聚合服务实际提供的模型 ID 填）
`model_provider`	是	自定义 provider id，跟下面 `[model_providers.xxx]` 段名一致
`base_url`	是	聚合服务入口，末尾必须有 `/v1`
`env_key`	推荐	从哪个环境变量读 API Key，不要硬编码
`wire_api`	是	写死 `"responses"`（`"chat"` 已被 Codex 0.80+ 移除）

二、API Key 放在哪

把 Key 单独放 ~/.codex/auth.json，方便加权限保护（chmod 600）：

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
}

auth.json 的字段名统一叫 OPENAI_API_KEY，Codex 不关心这个 Key 实际属于谁，只把值塞到请求的 Authorization: Bearer 头里（除非你在 config.toml 里用 env_key 走环境变量）。

三、启动验证

codex "用一句话介绍你自己"
# 看到回复就通了

codex exec "说明当前项目主要作用"  # 非交互式

报 provider not found / model_not_found：99% 是 model_provider 和 [model_providers.<id>] 段名没对齐（区分大小写）。报 404：一般是 base_url 末尾少了或多写了 /v1。

四、实战配置（含两张实际截图）

下面是跑在自己机器上的真实配置，仅供格式参考。

~/.codex/config.toml

personality = "pragmatic"
model = "gpt-4o"
model_provider = "easyapi"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

[model_providers.easyapi]
name = "EasyAPI 聚合"
base_url = "https://token.easyapi.com/v1"
env_key = "EASYAPI_KEY"
wire_api = "responses"

在这里插入图片描述

~/.codex/auth.json

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
}

在这里插入图片描述

几个关键点：

model_provider = "easyapi" 这个 id 是自定义的，叫什么都行，关键是跟 [model_providers.easyapi] 段名完全一致。
base_url 指向 OpenAI 兼容聚合服务的 endpoint（这里是占位符，你换成自己服务方提供的地址）。
requires_openai_auth 默认 false，接非 OpenAI 官方 endpoint 时保持默认即可。
sandbox_mode = "workspace-write"：只允许写工作区，生产环境推荐档位；高权限档位慎用。
personality / model_reasoning_effort 是 Codex 全局参数，跟具体 provider 无关。

五、其它平台同理操作

只要一个平台对外暴露 OpenAI 兼容接口（/v1/chat/completions 或 /v1/responses），接 Codex 就只有两件事：

改 base_url：把 https://your-endpoint.example.com/v1 换成该平台提供的 endpoint。
改 env_key：把 EASYAPI_KEY 换成对应的环境变量名（或者直接复用 OPENAI_API_KEY 字段放进 auth.json）。

按这个套路接过的常见平台（用过的都说稳定）：

官方 Azure OpenAI：base_url = "https://<resource>.openai.azure.com/openai/v1"，env_key = "AZURE_OPENAI_API_KEY"
阿里云百炼 DashScope：base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"，env_key = "DASHSCOPE_API_KEY"
OpenRouter：base_url = "https://openrouter.ai/api/v1"，env_key = "OPENROUTER_API_KEY"
AWS Bedrock（Codex 0.140+ 原生支持）：用 [model_providers.xxx.aws] 段配置 profile + region，无需 API Key
本地 Ollama：base_url = "http://localhost:11434/v1"，Key 随便填（Ollama 不校验）

重点就一句话：5 字段配置，只动 base_url 和 env_key 两个，其它字段照抄。

六、安全提醒

收紧权限：chmod 600 ~/.codex/auth.json，grep -r "sk-" ~/.codex/config.toml 确认无明文 Key。
不要通过非官方端点转发：生产环境的数据库连接信息、私钥证书、用户隐私数据、商业源码，别走聚合服务。
分项目用独立 Key：便于分别看消耗、单独吊销。