如何让 OpenAI Codex CLI 通过 OpenRouter 路由

Codex CLI 在你的终端中运行一个智能体编码循环，而且它已经支持自定义的 OpenAI 兼容提供商。这个钩子就是你通过 OpenRouter 路由它所需的全部。

回报是：一个 API 密钥即可访问 300+ 模型、自动提供商故障转移和统一的用量跟踪，而无需对 Codex 本身做任何改动。配置只需一小段 config.toml，但 Codex 有两个要求，如果你忽略了它们就会踩坑。本文将带你走完整个配置流程，以及你最可能遇到的两个错误。同一个密钥也适用于 Claude Code、Cursor，以及 如何将 OpenRouter 与任何编码智能体配合使用 中介绍的其他工具。

五步将 Codex 指向 OpenRouter

从 openai/codex 仓库安装 Codex CLI，然后在你的 API Keys 页面 创建一个密钥。它以 sk-or- 开头。

打开 ~/.codex/config.toml，如果不存在就创建它，并添加以下内容：

# ~/.codex/config.toml
model = "openai/gpt-5.6-sol"
model_provider = "openrouter"
model_reasoning_effort = "high"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
wire_api = "responses"

[model_providers.openrouter.auth]
command = "sh"
args = ["-c", "echo $OPENROUTER_API_KEY"]

在 Windows 上，改用 PowerShell 来配置认证块：

[model_providers.openrouter.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:OPENROUTER_API_KEY"]

有三个字段需要注意。model 必须是完整的 OpenRouter slug，包含提供商前缀，从 模型页面 复制。wire_api 如果设置的话必须是 "responses"，我们下面会讲到。而 auth 块会运行一个命令来获取你的密钥，而不是直接读取 env_key——基于命令的认证正是触发 Codex 针对 OpenRouter 刷新模型目录的原因，这样非 OpenAI 模型就能获得正确的上下文窗口和推理元数据，并出现在 /model 选择器中。

普通的 env_key = "OPENROUTER_API_KEY" 也可用于认证，但在该模式下 Codex 不会使用 OpenRouter 模型目录：非 OpenAI 模型会显示“Unknown model … fallback metadata”警告，并以假定的默认值运行。请优先使用上面的基于命令的 auth 块。

还有一条放置规则：model_provider 和 model_providers 只在你用户级别的 ~/.codex/config.toml 中生效。Codex 会忽略项目本地的 .codex/config.toml 中的它们，并打印启动警告。

然后在 Codex 加载的 shell 配置文件中导出你的密钥，在项目中运行 codex，并发送一个测试提示：

export OPENROUTER_API_KEY="sk-or-..."
cd /path/to/your/project
codex

打开 Activity 仪表盘，确认请求以正确的模型名称和 token 计数出现。如果出现了，你就已经完成路由了。

将 wire_api 设置为 responses

Codex 过去使用较旧的 chat/completions 协议，但 OpenAI 已弃用该路径并在 2026 年 2 月将其移除。使用 wire_api = "chat" 的自定义提供商现在会在启动时失败；如果你从旧配置中沿用了那一行，请将其改为 "responses"。

Responses API 正是 OpenRouter 所期望的，而且在当前 Codex 版本中它也是默认值，所以省略 wire_api 也可以——上面配置中显式的那一行只是记录了这一选择。一个相关的坑：提供商 ID openai、ollama 和 lmstudio 是保留的，所以你无法通过覆盖内置 openai 提供商的 base URL 来访问 OpenRouter。请改为定义一个新的提供商，比如 openrouter。

固定一个模型并关注花费

专用的 Codex 模型大多已弃用，所以 GPT-5.6 系列是 Codex CLI 更好的默认选择。5.6 模型共享 100 万 token 的上下文窗口，因此选择取决于价格与任务难度的权衡。以下是来自 模型目录 的当前费率，不含平台费用：

在迭代或探索性工作中使用 gpt-5.6-luna，在最困难的任务上使用 gpt-5.6-sol。你也可以将 model 指向任何非 Codex 的 slug，比如 anthropic/claude-sonnet-4.6，而无需改动其他任何东西。

Agentic 会话消耗的 token 比提示词长度所暗示的要多，因为模型每一轮都会重新处理仓库文件、工具输出和推理轨迹。三个控制手段可以让这一切变得可预测。在密钥上设置 支出护栏，这样一旦达到每日或每月上限，请求就会被拒绝。让模型与任务相匹配，因为 gpt-5.6-sol 每输出 token 的成本是 gpt-5.6-luna 的 8 倍以上。并且在日常编辑中把 model_reasoning_effort 换成 "low" 或 "medium"。

费用计算很轻。OpenRouter 不会在提供商定价上加价，所以你支付上述费率，外加信用购买时 5.5% 的手续费。一次专注的会话在 gpt-5.6-sol 上读取 200K 输入 token 并写入 50K 输出，token 成本约为 $0.90，信用手续费增加约 5 美分。失败的请求不计费。

修复 model_not_found

model_not_found 是另一个常见错误。按顺序处理这些：

• slug 不精确。它必须与 OpenRouter slug 逐字符匹配。直接从 openrouter.ai/models 复制。
• 缺少前缀。OpenAI slug 看起来像 openai/gpt-5.6-sol。openai/ 前缀是必需的；单独的 gpt-5.6-sol 不会匹配。
• 简写指向别处。~openai/gpt-latest 别名跟踪 OpenAI 最新的通用模型，可能不是你想要的变体，所以明确固定一个 slug。
• 配置在错误的文件中。把 model_provider 和 model_providers 移到你的用户级 ~/.codex/config.toml。
• Codex 警告“Unknown model”或回退元数据。你的 provider 块使用了 env_key，所以 Codex 永远不会获取 OpenRouter 模型目录。切换到上面配置中基于命令的 auth 块。

通过 OpenRouter 路由何时划算

当你想在众多模型之间快速切换、在 OpenAI 默认模型之外尝试开源模型、获得跨 70+ 提供商 的故障转移、查看实时 使用可见性，或从一个仪表盘设置团队成本控制时，OpenRouter 在 Codex 工作流中就占有一席之地。切换模型只需在 config.toml 中改一行 model，无需新密钥，也无需重新安装。你还可以运行 BYOK，通过你自己的提供商密钥路由，在计划相关的免费额度之后，按等效 OpenRouter 成本的 5% 收费；当前详情请参阅 定价页面。

常见问题

Codex CLI 可以与 OpenRouter 一起使用吗？

可以。在你的用户级 ~/.codex/config.toml 中添加一个 [model_providers.openrouter] 块，将 base_url 指向 https://openrouter.ai/api/v1，设置 model_provider = "openrouter"，添加一个基于命令的 auth 块来回显 OPENROUTER_API_KEY，然后固定一个模型 slug。从那时起，Codex 就会通过 OpenRouter 路由。

为什么我在 Codex 和 OpenRouter 中会得到 model_not_found？

model 值必须是精确的 OpenRouter slug，包括提供商前缀，例如 openai/gpt-5.6-sol。单独的 gpt-5.6-sol 是最常见的原因。provider 块还必须位于你的用户级 ~/.codex/config.toml 中，而不是项目本地。

通过 OpenRouter 使用 Codex CLI 需要 OpenAI 订阅吗？

不需要。一旦你配置了自定义提供商并导出 OPENROUTER_API_KEY，请求就会通过 OpenRouter 路由并计费。不需要单独的 OpenAI 计划。

通过 OpenRouter 使用 Codex 的费用是多少？

你支付提供商的每 token 费率，外加信用购买时 5.5% 的手续费，没有提供商加价。例如，gpt-5.6-sol 是每百万输入 token $2 和每百万输出 token $10，不含该手续费。失败的请求不计费。

为什么 Codex 会警告 OpenRouter 的未知模型或回退元数据？

你的 provider 块使用 env_key 进行身份验证，因此 Codex 会跳过获取 OpenRouter 模型目录，转而回退到内置元数据——非 OpenAI 模型将以假定的默认值运行。改用基于命令的 auth 块，回显 OPENROUTER_API_KEY，警告就会消失。

什么是 wire_api，它需要设置吗？

wire_api 控制 Codex 使用哪种 API 协议与 provider 通信。截至 2026 年 2 月，Codex 已移除对旧版 chat 值的支持，因此 wire_api = "chat" 会在启动时失败。在当前 Codex 版本中，"responses" 是默认值，因此省略 wire_api 也可以——显式设置它只是记录这一选择。