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

OpenAI Codex 默认把请求打到官方端点，但在很多实际场景里——国内网络不稳定、想用多模型聚合服务、需要企业内部审计流量——你会希望把请求改道到自定义网关。Codex 原生支持这件事，配置入口在 ~/.codex/config.toml 里，也可以用环境变量临时覆盖。本文梳理三种方法，按「最快上手 → 最推荐 → 最灵活」的顺序排列，每种方法附完整可复制的配置。

为什么要接自定义网关

Codex 的默认行为是把 API 请求发给 api.openai.com，这在以下场景会遇到问题：

1. 国内网络：api.openai.com 在大陆无法直接访问，需要通过国内可访问的第三方 API 端点
2. 多模型切换：想在 Codex 里用非 OpenAI 的模型（DeepSeek、Claude、Kimi 等），需要一个兼容 OpenAI 协议的聚合入口
3. 企业审计：需要把 LLM 流量过一遍内部网关，记录 token 消耗或做内容审查
4. 成本控制：不同网关对不同模型的定价不同，切换网关是降本的直接手段

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 爬虫"

注意点：

1. _API_KEY 和 _BASE_URL 里的 必须一致（都大写，下划线分隔）
2. 这种方式只对当前终端会话生效，关掉终端后失效
3. 如果只想替换 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。

完整字段说明

实战示例：接入专为 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 "重构这个函数，消除重复代码"

同样的结构可以套用到任何 OpenAI 兼容的端点——改 base_url 和 env_key 就行，其余格式不变。

保留 ID 限制

以下 ID 是 Codex 内置保留的，不能用作自定义 provider 的键名：

1. openai
2. ollama
3. 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。

常见坑与排错

坑 1：base_url 末尾加不加 /v1

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

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

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

坑 2：model 字段写错

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

坑 3：环境变量没生效

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

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

坑 4：wire_api 冲突

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

常见问题

Q：Codex Desktop 和 Codex CLI 的自定义网关配置一样吗？

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

Q：能同时定义多个自定义 provider 吗？

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

Q：自定义网关支持 streaming 吗？

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

Q：企业内网网关需要额外配置吗？

如果网关需要特定请求头（如内部 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 就能接上。

本文配置语法基于 Codex CLI 2026 年官方文档（~/.codex/config.toml 格式），建议搭配官方 config.md 查看最新字段说明。