Codex 如何配置 API Base URL

大家好，我是 Codex 中文网的站长宇哥。

先说结论

Codex 的配置核心是 config.toml。OpenAI 官方配置文档说明，用户级配置默认在 ~/.codex/config.toml，项目里也可以放 .codex/config.toml 作为项目级覆盖，但项目级配置只会在你信任该项目时加载。

配置 API Base URL 时，最重要的是分清楚两类地址：

• openai_base_url：模型请求走的 OpenAI 兼容接口地址。
• chatgpt_base_url：ChatGPT 登录流程使用的地址，普通 API 中转通常不要改它。

如果你只是想配置 OpenAI API 或兼容 OpenAI 协议的服务，通常关注模型 provider、API key 环境变量和 openai_base_url。

Codex 配置文件在哪里

用户级配置位置：

~/.codex/config.toml

项目级配置位置：

.codex/config.toml

官方 Config basics 里说明，CLI 和 IDE 扩展共享同一套配置层。也就是说，你在 ~/.codex/config.toml 配好的默认模型、审批策略、MCP servers，在 CLI 和 IDE 扩展里都能复用。

项目级 .codex/config.toml 更适合放“这个仓库特有”的配置，例如项目规则、沙箱、某些 repo 内工作流。涉及 provider、认证、base URL 这类机器本地或账号相关信息，更适合放在用户级配置中。

配置优先级怎么理解

官方文档给出的配置优先级是：命令行 flags 和 --config 覆盖最高，其次是项目配置、profile 配置、用户配置、系统配置，最后才是内置默认值。

实际使用时可以这样理解：

• 临时测试某个参数：用 CLI flags 或 -c key=value。
• 某个仓库固定规则：放 .codex/config.toml。
• 个人长期默认设置：放 ~/.codex/config.toml。
• 公司统一限制：可能由系统配置或 requirements.toml 管理。

例如临时覆盖模型可以使用命令行参数，长期默认模型则写入配置文件。

一个常见的 API 配置思路

不同版本和 provider 的配置项可能会随 Codex 更新而变化，因此这里给一个排查思路，而不是鼓励你照抄未知中转站配置。

你需要确认：

• 当前 Codex 使用哪个 model_provider。
• 这个 provider 从哪个环境变量读取 API key。
• 这个 provider 的 base URL 是不是 OpenAI 兼容接口。
• 模型名称是否被该 provider 支持。

常见环境变量写法如下：

export OPENAI_API_KEY="sk-..."

如果你接入的是 OpenAI 兼容中转服务，还要确认服务商给你的 Base URL 是否包含 /v1。很多 OpenAI 兼容接口要求类似：

https://example.com/v1

但也有中转服务会在网关层处理路径，所以不要盲目补 /v1，最终以你接入的服务文档为准。

修改配置前先做备份

很多 Codex 配置问题不是写错一个字段，而是多层配置互相覆盖。修改前建议先备份：

cp ~/.codex/config.toml ~/.codex/config.toml.bak

再打开配置文件编辑：

mkdir -p ~/.codex
code ~/.codex/config.toml

如果你不用 VS Code，可以换成自己的编辑器。

如何确认配置是否生效

配置完成后，不要直接让 Codex 做复杂任务。先做一个最小请求：

codex "只回复一句：Codex 配置测试成功。不要读取文件，不要修改文件。"

如果这个请求成功，再进入真实项目目录，让 Codex 做只读分析：

codex "总结这个仓库的技术栈和入口文件，不要修改文件。"

这样可以把问题拆开：第一步验证模型请求，第二步验证项目目录访问。

常见错误排查

401 Unauthorized

优先检查 API key 是否为空、是否复制错、是否被 shell 配置覆盖。可以先打印变量长度，不要直接把完整 key 打到终端历史里：

echo ${#OPENAI_API_KEY}

如果长度为 0，说明当前 shell 没有读到 API key。把变量写入 .zshrc、.bashrc 或你的 secret 管理工具后，需要重新打开终端或重新 source 配置文件。

404 model not found

这通常不是网络问题，而是模型名与 provider 不匹配。确认当前 provider 支持你配置的模型。不要把“ChatGPT 里能选某个模型”等同于“当前 API provider 一定支持同名模型”。

429 Too Many Requests

429 多数和频率、额度、并发或服务商限制有关。先降低并发、等待一段时间，再查服务商控制台的额度和速率限制。自动发文、批量重构、循环调用时尤其容易撞到 429。

网络连接失败

分层排查：

• 本机能否访问目标 Base URL。
• 终端代理是否生效。
• 公司网络是否拦截。
• DNS 是否能解析目标域名。
• provider 是否要求特定区域或额外鉴权。

可以先用：

curl -I https://example.com/v1

只要这里都访问不了，Codex 里也大概率访问不了。

不建议怎么做

不要把 API key 写到项目仓库里，尤其不要提交 .codex/config.toml 里包含密钥的版本。项目级配置适合团队共享规则，不适合共享个人密钥。

不要一口气同时改模型、provider、base URL、代理、审批策略。一次只改一个变量，失败时更容易定位。

不要直接复制陌生中转站配置到生产环境。先用测试 key 和小额度验证，再决定是否长期使用。

官方资料

• OpenAI Codex Config basics
• OpenAI Codex Configuration Reference
• OpenAI Codex CLI command line options

FAQ

Codex 配置文件必须放在项目里吗？

不必须。个人默认配置放 ~/.codex/config.toml 更常见。只有项目特有规则才建议放 .codex/config.toml。

Base URL 配错会出现什么现象？

可能是网络连接失败、404、401，也可能是 provider 返回格式不兼容。先用最小请求验证，再进入项目任务。

API key 和 ChatGPT 登录能混用吗？

可以根据使用入口和配置选择，但不要在排错时混在一起判断。先确认当前会话到底使用的是 ChatGPT 登录还是 API key。

总结

Codex API 配置的关键不是记住某个中转站模板，而是理解配置层级、provider、API key、base URL、模型名之间的关系。按“备份配置、一次改一个变量、最小请求验证、再跑项目任务”的顺序操作，排错会稳很多。