Codex API 手动配置指南
如果你现在主要在 VS Code / Cursor 插件里使用 Codex，建议先看这篇更完整的入口文档：
当自动安装、扩展登录态或 ccswitch 导入不可用时，再手动配置 Codex。Codex 的常见难点不是“文件在哪”，而是：到底该用 openai_base_url，还是该新建 [model_providers.<id>]；到底要不要改 wire_api；用户级和项目级配置谁覆盖谁。
不要把 API Key 写进公开项目。Key 只放在你自己的用户目录，不能提交到 GitHub、README、截图或聊天记录。
适合谁看
- Codex 配了第三方 API 后仍然走默认配置。
- 想检查
~/.codex/config.toml和项目内.codex/config.toml到底谁生效。 - 不确定该用
openai_base_url还是自定义model_providers。 - 想判断
wire_api = "responses"还是"chat"更合适。
你需要准备
| 信息 | 从哪里拿 | 示例 |
|---|---|---|
| API Key | 控制台或账户页面 | sk-xxxxxxxxxxxxxxxx |
| Base URL | 业务侧确认后的兼容入口 | https://YOUR_API_DOMAIN/v1 |
| 模型名 | 控制台模型列表 | 控制台显示的 OpenAI compatible model id |
| Provider ID | 自定义命名 | custom |
本文继续使用 YOUR_API_DOMAIN 占位，不写真实线路域名。
找到 Codex 配置目录
Windows
%USERPROFILE%\.codex\config.tomlmacOS / Linux
~/.codex/config.toml如果目录不存在，可以先启动一次 Codex，或者手动创建。
先看字段决策树
1) 只是把内置 OpenAI provider 指向代理或兼容网关
优先用：openai_base_url
model = "控制台显示的 OpenAI compatible model id"
openai_base_url = "https://YOUR_API_DOMAIN/v1"适合场景：
- 你仍然走 OpenAI compatible 语义；
- 只是把请求改到代理、路由器或数据驻留入口；
- 不想额外维护自定义 provider 名称。
2) 你要新增第三方 provider，而不是复用内置 OpenAI provider
优先用：[model_providers.<id>]
model_provider = "custom"
model = "控制台显示的 OpenAI compatible model id"
[model_providers.custom]
name = "custom"
base_url = "https://YOUR_API_DOMAIN/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"适合场景：
- 想显式区分多个 provider；
- 需要不同环境或线路分别切换；
- 后续要配多个 profile 或 provider。
3) 你需要临时切换 provider
优先检查：
model_provider = "..."- profile 覆盖
--provider启动参数
如果 CLI 参数指定了 provider，它可能覆盖你在 config.toml 里的默认设置。
4) 不确定 wire_api 该写什么
先按兼容能力判断：
| 场景 | 建议 |
|---|---|
兼容 /v1/responses | wire_api = "responses" |
| 只兼容 Chat Completions 风格 | wire_api = "chat" |
| 不确定 | 先看服务方文档或最小请求结果，不要瞎猜 |
/v1 不等于一定支持所有 OpenAI 风格端点，wire_api 选错时常见报错是 404、请求体字段不匹配或响应结构异常。
最小 TOML 示例
方案 A：只改内置 OpenAI provider
model = "控制台显示的 OpenAI compatible model id"
openai_base_url = "https://YOUR_API_DOMAIN/v1"方案 B：新增自定义 provider
model_provider = "custom"
model = "控制台显示的 OpenAI compatible model id"
[model_providers.custom]
name = "custom"
base_url = "https://YOUR_API_DOMAIN/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"用户级、项目级和 trusted project
Codex 常见冲突不是语法问题，而是“你改了 A 文件，实际运行读的是 B 文件”。
| 位置 | 作用 | 常见问题 |
|---|---|---|
~/.codex/config.toml | 用户级默认配置 | 大多数情况下先从这里开始 |
.codex/config.toml | 项目级配置 | 通常只在 trusted project 下生效 |
| profile | 同一 provider 的多套策略 | 容易覆盖默认 model/provider |
| CLI 参数 | 本次运行临时覆盖 | 关闭当前会话后失效 |
如果你在项目里也放了 .codex/config.toml，记得确认当前项目是否已 trusted，否则你会以为项目级配置没生效，其实是根本没被读取。
验证步骤
- 确认
config.toml已保存。 - 确认 API Key 已按当前 provider 方式提供。
- 完全关闭 Codex 和当前终端。
- 重新打开终端。
- 启动 Codex，先看当前 provider / model 是否符合预期。
- 发送一个短 prompt，只验证配置是否生效，不要一上来就跑长任务。
常见冲突排查
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 仍然走默认配置 | 实际读的不是你改的那个文件 | 先确认是用户级还是项目级配置生效 |
| 401 / invalid key | Key 错、过期或 provider 使用的 env_key 不匹配 | 重新检查 Key 来源与字段名 |
| 404 / model not found | 模型名不对、provider 不对，或 /v1 路径错误 | 先换成控制台展示模型，再看 provider 和路径 |
| 404 / endpoint not found | wire_api 选错 | 在 responses 与 chat 间按兼容能力重查 |
| 改完没反应 | 旧终端、旧 profile 或 --provider 覆盖 | 清理临时覆盖项后再测 |
| TOML 报错 | 引号、表头、缩进或重复字段问题 | 用 TOML 校验器检查 |
如果报 model not found，继续看：Model Not Found 排查。如果是 429 或额度问题，看：429 Rate Limit 与余额排查。