Codex接入自定义API网关的三种方法全解

先说几个核心判断：Codex 默认把 API 请求打到官方端点，这本身没问题。但国内网络环境不稳定、想接入多模型聚合服务、或者企业内部需要审计流量——这些场景下，你就得把请求改道到自定义网关。好消息是，Codex 原生支持这件事，配置入口在 ~/.codex/config.toml 里，也可以用环境变量临时覆盖。下面梳理三种方法，按「最快上手 → 最推荐 → 最灵活」的顺序排列，每种方法都附上完整可复制的配置。

为什么要接自定义网关

正常情况下，Codex 会把 API 请求一股脑丢给 api.openai.com。但以下几个场景，这个默认行为就会卡住脖子：

• 国内网络
  ：坦白说，api.openai.com 在大陆无法直接访问，你得找国内可访问的第三方 API 端点来绕一下。

• 多模型切换
  ：想在 Codex 里用 DeepSeek、Claude、Kimi 这些非 OpenAI 的模型？那就需要一个兼容 OpenAI 协议的聚合入口，统一接进来。

• 企业审计
  ：内部要求 LLM 流量必须经过网关，记录 token 消耗或做内容审查。这时候不改道不行。

• 成本控制
  ：不同网关对不同模型的定价天差地别，切换网关是降本最直接的手段之一。

核心原理其实很简单：Codex 支持所有兼容 OpenAI Chat Completions 或 Responses API 的第三方端点。你只需要把 base_url 指向你的网关地址，再把 API Key 换成对应服务商的 Key，就搞定了。

方法一：环境变量（临时/CI 场景首选）

最快的方式，不需要改任何配置文件，适合临时测试或者 CI/CD 环境里跑一跑。

# 自定义 provider 名称（大写），任意字符串
export MYGATEWAY_API_KEY="your-api-key-here"
export MYGATEWAY_BASE_URL="https://your-gateway-api-base-url/v1"
# 调用时用 --provider 指向这个名称
codex --provider MYGATEWAY "帮我写一个 Python 爬虫"

：

• _API_KEY 和 _BASE_URL 里的 必须一致（都大写，下划线分隔）。
• 这种方式只对当前终端会话生效，关掉终端后自动失效。
• 如果只是想替换 Key、不换地址，单独 export OPENAI_API_KEY="xxx" 即可覆盖官方 Key。

方法二：config.toml 自定义 provider（推荐，持久生效）

这是最推荐的方式。配置写进 ~/.codex/config.toml，所有项目共享，重启终端后依然有效，省心。

配置文件位置

~/.codex/config.toml

如果文件不存在，直接新建一个即可。Codex 首次运行时也会自动创建这个文件。

基础结构

# 顶层：指定默认使用哪个 provider 和模型
model = "gpt-4.1"
model_provider = "mygateway"   # 对应下面 [model_providers.xxx] 的键名

# 定义自定义 provider
[model_providers.mygateway]
name = "My API Gateway"
base_url = "https://your-gateway-api-base-url/v1"
env_key = "MYGATEWAY_API_KEY"   # 从这个环境变量读 Key

然后设置 Key：

export MYGATEWAY_API_KEY="your-api-key-here"

之后直接运行 codex "任务描述" 即可，不需要每次加 --provider。

完整字段说明

字段	是否必填	说明
name	否	显示名称，日志里用
base_url	是	网关的 API 根地址
env_key	是（二选一）	从环境变量读 API Key
wire_api	否	协议类型，填 "responses" 时走 Responses API，默认走 Chat Completions
http_headers	否	静态请求头，字典格式
env_http_headers	否	从环境变量读取的请求头
query_params	否	附加 query 参数（如 Azure 的 api-version）

实战示例：接入专为 AI 编程设计的聚合网关

市场上有些聚合网关专门针对 Codex、Claude Code、Cline 这类工具做了适配，开箱即用地打通多模型切换。以 Fenno（api.fenno.ai）为例，它支持 GPT、Claude、GLM、DeepSeek 等主流编程模型，接入方式与标准 OpenAI 格式完全一致：

model = "claude-sonnet-4-5"
model_provider = "fenno"

[model_providers.fenno]
name = "Fenno AI Gateway"
base_url = "https://api.fenno.ai/v1"
env_key = "FENNO_API_KEY"

export FENNO_API_KEY="your-fenno-key"
codex "重构这个函数，消除重复代码"

——改 base_url 和 env_key 就行，其余格式纹丝不动。

保留 ID 限制

以下 ID 是 Codex 内置保留的，

用作自定义 provider 的键名：

• openai
• ollama
• lmstudio

其他名称都可以自由命名，这很灵活。

方法三：命令行 --provider（调试首选）

不想改配置文件、也不想改环境变量，可以每次运行时临时指定，调试时最方便：

# 内置 provider 直接用名字
codex --provider openrouter --model "anthropic/claude-opus-5" "任务"

# 内置支持的 provider 列表（截至 2026 年）：
# openai / openrouter / azure / gemini / ollama
# mistral / deepseek / xai / groq / arceeai

对于自定义 provider，需要先在 config.toml 里定义好，然后用 --provider 在运行时覆盖全局设置：

codex --provider fenno --model "gpt-4.1-mini" "生成单元测试"

这在「平时用默认配置，偶尔切换到另一个网关测试」的场景下很实用，不用来回改 config.toml 顶层的 model_provider。

常见坑与排错

不同网关的规范不一样。有的网关要求完整路径 https://gateway.example.com/v1，有的只需要根地址 https://gateway.example.com。如果返回 404，先检查这里。最简单的验证方法是直接 curl：

curl https://your-gateway/v1/models 
  -H "Authorization: Bearer $YOUR_API_KEY"

能返回模型列表，说明地址正确。

自定义网关有自己的模型 ID 命名规范，不一定和 OpenAI 官方一致。比如有些网关把 Claude 命名为 claude-opus-5，有些是 anthropic/claude-opus-5。建议先查网关文档里的模型 ID 列表，别想当然。

Codex 读的是当前 shell 的环境变量。如果在 .zshrc/.bashrc 里加了 export，需要重新 source 或新开终端：

source ~/.zshrc
# 或者直接确认变量存在
echo $FENNO_API_KEY

如果网关只支持 Chat Completions 协议（/v1/chat/completions），不要设置 wire_api = "responses"，否则 Codex 会发 Responses API 格式的请求，网关会报格式错误。不填 wire_api 时，Codex 默认走 Chat Completions，安全。

常见问题

配置文件路径相同（~/.codex/config.toml），但 Codex Desktop 在处理本地自定义 provider 时有已知的 API Key 混用问题（GitHub issue #24457），如果遇到认证失败，优先用 CLI 验证一下。

可以。在 config.toml 里定义多个 [model_providers.] 块，通过顶层 model_provider 切换全局默认，或运行时用 --provider 临时切换。

Codex 默认开启流式输出。只要网关的端点支持 SSE 格式的流式响应，就可以正常工作。大部分 OpenAI 兼容网关都支持，可以在 curl 里加 "stream": true 手动验证。

如果网关需要特定请求头（如内部 token 或 tenant ID），用 http_headers 字段写死静态值，或用 env_http_headers 从环境变量读：

[model_providers.internal]
base_url = "https://llm.internal.company.com/v1"
env_key = "INTERNAL_LLM_KEY"
http_headers = { "X-Tenant-ID" = "your-tenant" }

小结

Codex 接自定义网关，核心就三步，简单直接：

1. 在 ~/.codex/config.toml 里加一个 [model_providers.] 块。
2. 填好 base_url（网关地址）和 env_key（Key 的环境变量名）。
3. 顶层设 model_provider = "" 激活，设 model 指定默认模型。

临时场景用环境变量 + --provider，生产环境推荐写进 config.toml 持久化。协议层面，只要网关兼容 OpenAI Chat Completions API，Codex 就能无缝接上。