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

2026-08-03 16:40:30 vibecoding77

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

为什么要接自定义网关

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

国内网络：api.openai.com 在大陆无法直接访问，需要通过国内可访问的第三方 API 端点
多模型切换：想在 Codex 里用非 OpenAI 的模型（DeepSeek、Claude、Kimi 等），需要一个兼容 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 爬虫"

注意点：

<PROVIDER>_API_KEY 和 <PROVIDER>_BASE_URL 里的 <PROVIDER> 必须一致（都大写，下划线分隔）
这种方式只对当前终端会话生效，关掉终端后失效
如果只想替换 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 "重构这个函数，消除重复代码"

同样的结构可以套用到任何 OpenAI 兼容的端点——改 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 <id> 在运行时覆盖全局设置：

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.<id>] 块，通过顶层 model_provider 切换全局默认，或运行时用 --provider <id> 临时切换。

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 接自定义网关的核心就三步：

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

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

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

以上就是Codex接入自定义API网关的三种方法全解的详细内容，更多关于Codex接入自定义API网关的资料请关注脚本之家其它相关文章！