Codex 配置 API Key 和 Base URL：从安装到首次调用
简答：Codex 的 API Key 通常不直接写进 config.toml，而是通过环境变量交给 env_key；Base URL 写入用户级 config.toml，并按网关要求决定是否包含 /v1。先确认网关提供商给出的完整地址、模型名、认证变量和 Responses API 支持，再用 codex --version、codex doctor 或实际请求验证。
定义：Codex 配置 API Key 和 Base URL，是在用户级 config.toml 中指定模型提供商与接口地址，并通过环境变量或 Codex 凭证存储提供认证信息。
先用这张表确定配置方式
如果你准备让 Codex 连接某个 OpenAI 兼容网关，先不要把未经核实的品牌地址直接复制进配置。当前可核验的 Codex 文档要求网关支持 Responses API；以 Gateway compatibility requirements 为准，网关需要处理 POST /v1/responses、流式事件和最终的 response.completed。
| 场景 | 推荐配置 | Key 保存位置 |
|---|---|---|
| 已有 OpenAI 兼容地址 | openai_base_url 或自定义 provider | 环境变量或 Codex 凭证存储 |
| 网关有独立模型别名 | model_provider 加 [model_providers.id] | env_key 指向环境变量 |
| 需要管理员或脚本刷新令牌 | 自定义 provider 的 auth.command | 由命令输出 Bearer token |
| 只想临时测试 | 用 codex --config 或临时环境变量 | 测试结束后清理 shell 环境 |
Codex 的配置文件、项目配置边界和 CODEX_HOME 说明，可查看 Configuration Reference。本文不是 OrcaRouter 官方页面；OrcaRouter 的具体 Key、模型名和 Base URL 如果没有从其可核验文档取得，应保留为占位符，并以服务提供方给出的信息为准。
安装 Codex 并确认版本
- 使用 npm 安装：
npm install -g @openai/codex。 - 安装后执行：
codex --version。 - Windows 用户按官方说明通过 WSL2 使用 Linux 环境；Microsoft 的 Codex 配置示例将 Windows 场景列为 WSL2，并展示了安装与版本检查步骤，见 Codex with Azure OpenAI in Microsoft Foundry Models。
- 确认你拿到四项信息：完整 Base URL、模型名、认证方式、网关是否支持 Responses API。不要只凭一个能返回文本的 Chat Completions 地址判断兼容。
推荐方案：config.toml 加环境变量 API Key
用户级配置默认位于 macOS 和 Linux 的 ~/.codex/config.toml；Windows 原生客户端通常使用 %USERPROFILE%\.codex\config.toml。在 WSL 中，Codex 使用 Linux 的 CODEX_HOME 和路径。官方网关示例要求把模型、provider 选择放在第一个 TOML 表之前，示例可参考 Use API/provider credentials through a gateway。
下面是可复制的通用模板。所有大写占位符都必须替换成服务提供方实际给出的值：
model = "YOUR_MODEL_ID"
model_provider = "custom-gateway"
[model_providers.custom-gateway]
name = "Custom Gateway"
base_url = "https://YOUR_VERIFIED_BASE_URL/v1"
wire_api = "responses"
env_key = "YOUR_API_KEY_ENV"
如果提供方给出的完整地址已经包含 /v1，不要重复追加；如果文档给出的是资源根地址，则按该文档补齐路径。不要把 YOUR_API_KEY_ENV 换成 Key 本身，它必须是环境变量名。Microsoft 的官方示例也明确将 env_key 配置为变量名，并在终端中单独设置变量。
macOS、Linux、WSL：
export YOUR_API_KEY_ENV="你的_API_Key"
codex doctor
codex
PowerShell：
$env:YOUR_API_KEY_ENV = "你的_API_Key"
codex doctor
codex
为降低泄露风险，优先使用交互式读取或系统密钥环，不要把 Key 写进 Git、截图、命令历史或 URL 查询参数。Codex 的认证存储方式包括文件、keyring、自动选择和仅进程内存，详见 Authentication。
openai_base_url 与自定义 provider 怎么选
如果只是把内置 OpenAI provider 指向一个兼容网关，可以在 config.toml 中使用 openai_base_url；官方高级配置文档给出了这一用途。若网关有独立的 provider ID、专用环境变量、模型目录或自定义认证头，使用 model_provider 与 [model_providers.id] 更清晰，参考 Advanced Configuration。
| 配置项 | 适合情况 | 需要注意 |
|---|---|---|
openai_base_url | 只需要改变内置 OpenAI provider 的地址 | 仍要确认目标地址支持 Codex 所需的 Responses API |
model_provider | 网关有独立模型名、Key 变量或认证头 | provider ID、表名和顶层 model_provider 必须一致 |
wire_api = "responses" | Codex 连接 Responses API 网关 | 不能用 Chat Completions 的可用性替代验证 |
model_catalog_url 或 model_catalog_json | 网关使用 Codex 未内置的自定义模型别名 | 目录中的别名和 model 必须匹配 |
首次验证：按顺序检查四层
- 本地层：执行
codex --version，确认命令来自预期环境；WSL 与 Windows 原生终端不要混用配置目录。 - 配置层：执行
codex doctor，启动后使用/status查看当前模型和 provider。官方网关接入流程将这两项作为检查现有配置和确认连接的方式。 - 认证层：确认启动 Codex 的同一个进程能读取环境变量。桌面应用不一定继承你在终端临时设置的变量，因此需要重新启动应用或使用系统级环境配置。
- 接口层：用一个简单任务验证，例如让 Codex 返回固定短语；同时确认网关日志记录了正确的模型别名和 Responses 请求。仅有健康检查或普通文本返回，不能证明工具调用、流式输出和后续轮次都兼容。
401、403、404、429 与连接错误排查表
| 现象 | 优先检查 | 处理动作 |
|---|---|---|
| 401 Unauthorized | 环境变量未传入、Key 过期、认证头类型不匹配 | 确认 env_key 写的是变量名，重新打开当前终端或应用，再核对提供方要求的认证方式。 |
| 403 Forbidden | 账户、项目或模型权限 | 向服务提供方确认 Key 是否有该模型和 Responses API 权限；不要只更换模型名。 |
| 404 Not Found | Base URL 路径或 endpoint 不完整 | 核对是否应包含 /v1，并确认网关是否提供 /v1/responses。 |
| 429 Too Many Requests | 限速、并发或账户额度 | 查看响应头和网关控制台的限速信息，降低并发并等待服务端给出的重试时间。 |
| ENOTFOUND、DNS 或超时 | 域名解析、代理、网络或地址拼写 | 先用系统 DNS 和 HTTPS 连接检查，再确认 Base URL 没有多余空格、路径或端口。 |
| model not found | 模型别名不一致或模型目录缺失 | 让提供方确认可用模型名；自定义别名需要匹配的模型目录，不能把上游模型名想当然地填入。 |
| 余额不足或额度错误 | 服务提供方账户、项目余额或预算 | 在提供方控制台核对余额、预算和 Key 所属项目；该信息不是 Codex 本地配置能够修复的。 |
| 流式中断 | 网关缓冲、SSE 转发或未转发完成事件 | 确认网关按 Responses API 转发 SSE，并保留终止的 response.completed 事件。 |
三个常见配置误区
- 把 Key 写进 TOML：
env_key应指向环境变量名；Key 不应直接写入配置文件或提交到仓库。 - 把策略名写进请求体：
model_provider、wire_api和模型目录属于 Codex 配置；路由策略如果由网关控制台管理，就应按提供方说明配置，不要自行添加未知字段。 - 把 Chat Completions 地址当成 Codex 地址：Codex 网关兼容性要求针对 Responses API、流式事件、续写和工具调用；可用的普通聊天接口不等于可用的 Codex provider。
常见问题 FAQ
Codex 的 Base URL 要不要写 /v1？
没有统一答案，取决于服务提供方给出的完整 API 路径。若提供方给出的 Base URL 是 https://example.com/v1，就直接填写它；若只给资源根地址，应按其文档补齐。Codex 网关兼容文档以 POST /v1/responses 为示例，因此修改前先核对实际 endpoint。
API Key 应该放在 auth.json 还是环境变量？
对于网关 API Key，优先使用环境变量配合 env_key，便于轮换且不把密钥写入配置。auth.json 或系统 keyring 主要由 Codex 的登录凭证存储机制使用；具体存储模式可在官方认证文档中核对。
为什么配置了模型名仍然提示 model not found？
模型名必须是网关实际暴露的别名，不一定等于上游模型的公开名称。如果网关使用 Codex 未内置的自定义别名，还可能需要匹配的 model_catalog_url 或 model_catalog_json，修改后重启 Codex。
Windows 设置了 API Key，Codex 仍然 401，怎么办？
先确认是在启动 Codex 的同一个 PowerShell 或 WSL 环境中设置变量；再检查变量名与 env_key 完全一致。若从桌面应用启动，终端里的临时变量可能不会继承，需要重启应用或使用应用进程可读取的环境配置。
OrcaRouter 的地址和模型名在哪里填写？
填写位置与其他兼容网关相同：地址放在 base_url，模型放在顶层 model，Key 通过 env_key 指向环境变量。本文没有把 OrcaRouter 的具体端点、模型清单或价格当作已核实事实，实际值请以该服务提供方当前公开文档或控制台显示为准。
常见问题
Codex 的 Base URL 要不要写 /v1？
没有统一答案，取决于服务提供方给出的完整 API 路径。若提供方给出的 Base URL 已经是 https://example.com/v1%EF%BC%8C%E5%B0%B1%E7%9B%B4%E6%8E%A5%E5%A1%AB%E5%86%99%EF%BC%9B%E4%BF%AE%E6%94%B9%E5%89%8D%E7%A1%AE%E8%AE%A4%E5%AE%9E%E9%99%85%E8%AF%B7%E6%B1%82%E6%98%AF%E5%90%A6%E5%BA%94%E8%90%BD%E5%88%B0 /v1/responses。
API Key 应该放在 auth.json 还是环境变量？
对于网关 API Key，优先使用环境变量配合 env_key，避免把密钥写入配置文件。auth.json 或系统 keyring 主要用于 Codex 登录凭证，具体存储模式以官方认证文档为准。
为什么配置了模型名仍然提示 model not found？
模型名必须是网关实际暴露的别名，不一定等于上游模型名称。自定义别名可能还需要匹配的 model_catalog_url 或 model_catalog_json，修改后重启 Codex。
Windows 设置了 API Key，Codex 仍然 401，怎么办？
确认变量是在启动 Codex 的同一个 PowerShell 或 WSL 环境中设置，并检查变量名与 env_key 完全一致。桌面应用可能不会继承终端临时变量。
OrcaRouter 的地址和模型名在哪里填写？
地址写入 base_url，模型写入顶层 model，Key 由 env_key 指向环境变量。具体端点、模型清单和权限应以该服务提供方当前公开资料为准，本文不把未核实值当作固定配置。
相关阅读
参考资料
- Use API/provider credentials through a gateway（learn.chatgpt.com）
- Gateway compatibility requirements（learn.chatgpt.com）
- Configuration Reference（learn.chatgpt.com）
- Advanced Configuration（learn.chatgpt.com）
- Authentication（learn.chatgpt.com）
- Codex with Azure OpenAI in Microsoft Foundry Models
- codex/README.md at main