Codex API Key 怎么配置？先分清 Key、Base URL、Provider 和模型
从官方登录、自定义 Provider 到 AI Code With 的完整配置与 401/404 排错
很多 Codex API Key 教程一上来就让你复制 Key、粘贴、保存。然后你运行 Codex，报 401；换一个 Key，又开始报 404；再去改 Base URL，最后连自己到底走的是 ChatGPT 登录、OpenAI API，还是第三方 Provider 都说不清。
问题通常不是“Key 粘错了”，而是把认证、Provider、Endpoint 和模型这几层混在了一起。
所以 Codex API Key 配置的第一步，不是粘贴 Key，而是先选路。
这篇不只告诉你“填什么”，还会把每一层到底负责什么、怎么验证成功、401/404/429 分别该查哪里，以及通过 AI Code With 接 Codex 时哪些参数不能混用，一次讲清楚。
一、先决定：你到底要 ChatGPT 登录，还是 API Key？
Codex 本地客户端支持不同认证路线。对普通用户来说，最先需要分清的是：你是用 ChatGPT 账号登录，还是用 API Key 登录。两条路都能让 Codex 工作，但认证来源、计费方式和后续排错思路并不一样。
路线 A：ChatGPT 登录
如果你只是想正常使用 Codex，又没有第三方 Provider 或自动化需求，先走官方登录通常最省事。CLI 中直接运行：
codex login
然后按照浏览器流程完成登录。
这条路线的重点是“账号会话”，不是你手工往配置文件里塞 API Key。
路线 B：OpenAI API Key 登录
如果你希望使用 OpenAI Platform API Key，或者要在脚本、CI/CD 等程序化场景里使用 Codex，当前官方 CLI 推荐把 Key 通过标准输入交给登录命令：
printenv OPENAI_API_KEY | codex login --with-api-key
这样至少不会把完整 Key 直接写进一条会长期留在 shell history 里的命令。前提是 OPENAI_API_KEY 本身已经通过安全方式进入环境。
API Key 登录按 OpenAI Platform 的标准 API 计费，而不是消耗 ChatGPT 套餐里包含的使用额度。
改任何配置前，先看自己现在在哪条路上
codex login status
这一步经常比重新复制 Key 有用。你先确认当前认证方式，再决定下一步是改 Provider、重新登录，还是清理旧凭证。
如果确实需要清除当前已保存的认证，可以使用：
codex logout
不要一上来就删除整个 ~/.codex 目录。那个目录里除了认证信息，还可能有 config.toml、其他 Provider、MCP 等配置。
二、Key 只是四块拼图中的一块
一旦你开始接第三方模型、代理或中转服务，通常就会同时看到四个东西：Key、Provider、Base URL、Model ID。它们看起来都像“API 配置”，但职责完全不同。
| 配置项 | 它回答的问题 | 常见错误 |
| API Key | 谁有权限调用 | Key 无效、Key 属于另一个账号或服务 |
| Provider | Codex 把请求交给谁 | Provider ID 与配置段不一致 |
| Base URL / Endpoint | 请求实际发到哪里 | 把普通 API 地址和 CLI 专用地址混用 |
| Model ID | 最终调用哪个模型 | 把展示名称当成调用 ID，或 Provider 根本不提供该模型 |
最危险的配置方式，是把 A 服务的 Key、B 服务的 Base URL、C 服务的 Model ID 拼成一套，然后看到报错就继续换 Key。Key 就算完全正确，其他三层不匹配一样会失败。
排错顺序应该是：先确认认证路线，再确认 Provider，再核对 Endpoint，最后核对模型。
三、如果只是改内置 OpenAI Provider 的地址
Codex 当前配置参考里提供了 openai_base_url，用来覆盖内置 openai Provider 的 Base URL。概念上类似：
openai_base_url = "https://<VERIFIED_BASE_URL>/v1"
这里有一个很容易忽略的规则：Provider、认证相关配置属于机器本地配置。当前 Codex 会忽略项目级 .codex/config.toml 中的 openai_base_url、model_provider、model_providers 等字段，所以这类配置应该写到用户级 ~/.codex/config.toml。
也就是说，如果你在项目目录里改了 .codex/config.toml，却发现 Provider 完全没变化，不一定是 TOML 写错了，可能是这个层级本来就不允许覆盖。
四、自定义 Provider 应该怎么理解？
如果不是简单覆盖内置 OpenAI 地址，而是要增加一个真正独立的 Provider，Codex 当前 schema 支持自定义 model_providers。一个通用示意可以写成：
model = "<VERIFIED_MODEL_ID>"
model_provider = "custom"
[model_providers.custom]
name = "My Provider"
base_url = "https://<VERIFIED_BASE_URL>/v1"
env_key = "PROVIDER_API_KEY"
wire_api = "responses"
这里有四个细节值得注意。
• model_provider 的值要和 [model_providers.<id>] 里的 <id> 对上。
• base_url 必须来自服务方当前文档，不要凭经验猜。
• env_key 写的是“环境变量名”，不是 API Key 本身。
• 当前 Codex 自定义 Provider 的 wire_api 只支持 responses。
如果你采用 requires_openai_auth = true，则不要再同时把 env_key 当成另一套独立认证机制混进去；官方配置参考明确把这些认证方式区分开了。
五、如果你准备通过 AI Code With 接 Codex
这时候 AI Code With 才是文章里最自然的出现位置：你已经明确需要一个第三方 Provider，需要 Key、专用 Endpoint、模型和调用记录，而不是为了广告突然插进来。
AI Code With 当前 Codex CLI / Desktop 文档给出的 Codex 专用 Base URL 是：
https://api.aicodewith.ai/chatgpt/v1
同时走 Responses 协议。这里最重要的不是背地址，而是理解：这个地址是 Codex 场景的专用入口，不应该和其他普通 OpenAI 风格 API 客户端常见的 /v1 地址混用。AI Code With 自己的文档也专门区分了 CLI 端点和标准 API 端点。
AI Code With 当前文档里的最小配置思路
当前 AI Code With 的 Codex 文档使用 auth.json 保存 OPENAI_API_KEY，并在用户级 config.toml 定义一个使用 requires_openai_auth = true 的 Provider。结构可以理解为：
~/.codex/auth.json
{
"OPENAI_API_KEY": "你的_AI_CODE_WITH_KEY"
}
~/.codex/config.toml
model_provider = "codex"
model = "<CURRENT_MODEL_ID>"
[model_providers.codex]
name = "codex"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
这里的 <CURRENT_MODEL_ID> 不建议永久写死在教程里。模型上下线和调用 ID 都可能变化，最稳的方式是在配置当天从 AI Code With 当前模型页或 Codex 接入文档复制。
另外，auth.json 里是真实凭证，不要截图完整内容、不要提交 Git，也不要为了让别人“帮你看看”直接发到群里。
为什么我更建议给 Codex 单独建一个 Key？
如果一个 Key 同时给 Codex、Claude Code、测试脚本和其他工具使用，短期确实方便，但任何一次泄露、异常费用或调用暴增都会变得难排。
更实用的做法是给 Codex 单独创建一个用途明确的 Key，例如 codex-macbook 或 codex-daily。AI Code With 当前 Key 管理文档也建议按不同用途创建独立密钥。这样以后需要轮换时只动 Codex，不会牵连其他工具。
六、配置成功不能只看“Codex 能回复”
一条完整的验证链至少应该有三步。
1. 先确认认证状态
codex login status
至少知道自己当前走的是哪种认证。
2. 发一个最小、无副作用的请求
不要一配置完就让 Codex 改几十个文件。先让它做一个不会修改项目的简单任务，例如解释当前目录里的 README 或回答一句测试问题。
这样失败时，你能确定问题发生在模型调用链，而不是复杂任务、权限或文件系统。
3. 核对请求到底落到哪里
如果走 OpenAI 官方 API，就看对应 OpenAI Platform 用量；如果走 AI Code With，就去后台 Usage Records / 调用记录里确认时间、Key、模型和渠道。
“界面里显示了某个模型名”只能证明前端状态；后台实际出现对应请求，才更能说明 Provider 和 Endpoint 真的生效。
七、401、404、429、502 到底分别查什么？
| 错误 | 优先检查 | 不要先做什么 |
| 401 / Unauthorized | 认证路线、Key 是否有效、Key 属于哪个服务、凭证是否真正进入当前客户端 | 不要先换 Base URL |
| 404 / Not Found | Base URL、Endpoint 路径、CLI/API 端点是否混用 | 不要反复重新登录 |
| 429 | 额度、速率限制、账号/Key 限制、服务状态 | 不要直接删除 Key |
| 502 | 网关、渠道、上游模型或代理状态 | 不要继续折腾本地认证文件 |
| model not found | Model ID、Provider 是否真的提供该模型 | 不要用展示名称猜 ID |
| 配置完全不生效 | 是不是改了项目级配置、是否被 CLI 参数/其他配置层覆盖 | 不要直接重装 Codex |
一个现实例子：为什么 CLI 正常，Desktop 还是 401？
这类情况很容易把人带回“是不是 Key 坏了”的老路。实际上 CLI 和桌面端即使读取同一个 config.toml，也可能在认证来源或进程环境上存在差异。
例如 CLI 能拿到 shell 环境里的变量，而桌面应用可能没有；或者桌面端仍然保留旧会话，实际请求还在走另一个 Provider。
这时候最有用的不是再复制一次 Key，而是看 401 错误里真实的请求 URL。如果 URL 已经指向某个第三方 Provider，那么至少说明请求路由已经到了那里；接下来就专注查凭证是不是正确进入这个客户端。
八、自动化和 CI：Key 只应该属于需要它的那个进程
API Key 配置一旦进入自动化场景，风险会比本机手工运行高很多。因为 CI job 往往还会执行依赖安装、测试、构建脚本和仓库代码，这些进程理论上都可能读取 job 级环境变量。
所以不要把高权限 Key 直接暴露给整个 job。更合理的思路是：Secret 管理系统保存真实值，只在需要调用 Codex 的那一步注入。
CODEX_API_KEY=<secret-from-ci> codex exec --json "triage open bug reports"
真正的 Key 不应该写死在 YAML、脚本、日志、JSONL 输出或截图里。
九、哪些配置不要从旧文章里整段复制？
Codex 这类工具更新很快，最危险的不是某个旧教程一定错，而是你不知道它对应的是哪一版 Codex、哪个 Provider、什么协议。
尤其是下面几类字段，发布前最好实时核对当前官方文档：
• 登录命令和认证方式
• model_provider / model_providers 的 schema
• Base URL 和专用 Endpoint
• Model ID
• Provider 认证字段（env_key、requires_openai_auth 等）
• 桌面端与 CLI 是否共享或复用某些配置
一份“永远不变的 config.toml 模板”看起来省事，但往往是过几个月以后最难排错的来源。
十、我更推荐的完整配置顺序
1. codex login status
2. 决定 ChatGPT 登录 / OpenAI API Key / 第三方 Provider
3. 确认 Key 属于哪个服务
4. 核对 Provider
5. 核对 Base URL / Endpoint
6. 核对 Model ID
7. 只修改用户级 ~/.codex/config.toml
8. 完全重启需要重新读取配置的客户端
9. 发一个最小只读请求
10. 去对应服务后台核对真实调用记录
这个顺序比“看到报错就换 Key”慢不了多少，却能把绝大多数问题拆成一个非常明确的层级。
最后：先选路，再配置，再验证
Codex API Key 配置真正难的地方，从来不是复制那一串字符。难的是你要知道这串 Key 属于谁、Codex 请求交给哪个 Provider、请求到底发到哪个 Endpoint，以及这个 Provider 当前接受哪个 Model ID。
Key 负责认证，Provider 决定交给谁，Base URL 决定发到哪里，Model ID 决定调用什么。
四层拆开以后，401 就查认证，404 就查地址和路径，model not found 就查模型，502 就去看网关和上游。你不需要每次都重装 Codex，也不需要把整个 ~/.codex 删掉重来。
如果你本来就准备通过 AI Code With 接 Codex，那么最自然的下一步不是继续猜配置，而是在 AI Code With 创建一个专门给 Codex 用的 Key，打开当前 Codex 接入文档核对专用 Endpoint 和 Model ID，再用最小请求 + 后台调用记录完成验证。
相关阅读
• Codex auth.json 是什么：位置、风险与安全排错
• Codex config.toml 配置指南
• Codex 环境变量怎么配
• Codex Provider 怎么切换
• Codex Desktop 401 / Unauthorized 排错
参考资料
• OpenAI Codex Authentication
• OpenAI Codex Configuration Reference
• OpenAI Codex Advanced Configuration
• AI Code With Codex CLI
• AI Code With 创建 API Key
