Codex CLI 在你的终端中运行一个智能体编码循环，并且它已经支持自定义的 OpenAI 兼容提供商。这个钩子就是你通过 OpenRouter 路由它所需的全部。
其回报是：一个 API 密钥即可对接 300 多个模型、自动提供商故障转移，以及整合的使用情况追踪，且无需对 Codex 本身做任何更改。配置只需一个小的 config.toml 代码块，但 Codex 有两个要求，如果你忽略了它们，就会遇到麻烦。本文将带你完成完整的设置，以及你最可能遇到的两个错误。
五步将 Codex 指向 OpenRouter
从 openai/codex 仓库安装 Codex CLI，然后在你的 API 密钥页面创建一个密钥。密钥以 sk-or- 开头。
打开 ~/.codex/config.toml（如果文件不存在则创建），并添加以下内容：
# ~/.codex/config.toml
model = "openai/gpt-5.3-codex"
model_provider = "openrouter"
model_reasoning_effort = "high"
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"有两个字段需要注意。model 必须是一个完整的 OpenRouter 标识符（slug），包括提供商前缀，可从模型页面复制。而 wire_api 必须设置为 "responses"，我们将在下面说明原因。
另一个放置规则：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打开活动仪表盘，确认请求显示正确的模型名称和 token 数量。如果显示正确，说明路由已成功。
将 wire_api 设置为 responses
Codex 过去使用较旧的 chat/completions 协议，但 OpenAI 已弃用该路径，并于 2026 年 2 月将其移除。一个 wire_api = "chat" 或根本没有 wire_api 的自定义提供商，现在会在启动时失败。
将 wire_api 设置为 "responses" 会使 Codex 使用 Responses API，这正是 OpenRouter 所期望的。上面的配置代码块已经包含了这一项。一个相关的陷阱是：提供商 ID openai、ollama 和 lmstudio 是保留的，因此你无法通过覆盖内置 openai 提供商的 base URL 来访问 OpenRouter。请改为定义一个像 openrouter 这样的新提供商。
固定一个 Codex 模型并监控支出
OpenRouter 上的 Codex 模型共享一个 400K 的上下文窗口，因此选择取决于价格与任务难度的权衡。以下是来自模型目录的当前费率（不含平台费用）：
| OpenRouter 标识符 | 输入 $/M | 输出 $/M |
|---|---|---|
| openai/gpt-5.3-codex | 1.75 美元 | 14 美元 |
| openai/gpt-5.1-codex | 1.25 美元 | 10 美元 |
| openai/gpt-5.1-codex-mini | 0.25 美元 | 2 美元 |
在迭代性或探索性工作中使用 gpt-5.1-codex-mini，在最困难的任务中使用 gpt-5.3-codex。你也可以将模型指向任何非 Codex 的 slug，例如 anthropic/claude-sonnet-4.6，而无需改动其他任何设置。
智能体会话消耗的 token 数量远超提示词长度所暗示的量，因为模型在每一轮交互中都会重新处理仓库文件、工具输出和推理轨迹。三项控制措施可让这一过程保持可预测。在密钥上设置支出防护栏，这样一旦达到每日或每月上限，请求就会被拒绝。根据任务匹配合适的模型，因为 gpt-5.3-codex 每个输出 token 的成本是 gpt-5.1-codex-mini 的 7 倍。对于常规编辑，可将模型推理努力程度（model_reasoning_effort）设为“低”或“中”。
费用计算很轻。OpenRouter 不对提供商定价加价，因此你只需支付上述费率，外加信用额度购买时 5.5% 的手续费。一次专注的会话，在 gpt-5.3-codex 上读取 20 万输入 token 并写入 5 万输出 token，token 成本约为 1.05 美元，信用额度手续费约增加 6 美分。失败的请求不收费。
修复 model_not_found
model_not_found 是另一种常见错误。请按以下顺序逐一排查：
- slug 不精确。它必须与 OpenRouter 的 slug 逐字符匹配。请直接从 openrouter.ai/models 复制。
- 前缀缺失。Codex slug 的格式为 openai/gpt-5.3-codex。openai/ 前缀是必需的；仅使用 gpt-5.3-codex 无法匹配。
- 简写指向了其他地方。~openai/gpt-latest 别名指向 OpenAI 最新的通用模型，这可能不是你想要的 Codex 变体，因此请明确指定一个 Codex slug。
- 配置放在了错误的文件中。请将 model_provider 和 model_providers 移至用户级别的 ~/.codex/config.toml 文件中。
何时通过 OpenRouter 路由才划算
当您需要在多个模型间快速切换、在 OpenAI 默认模型之外尝试开源模型、在 70 多个提供商之间实现故障转移、查看实时用量，或通过一个控制面板设置团队成本控制时，OpenRouter 就能在 Codex 工作流中占据一席之地。切换模型只需在 config.toml 中修改 model 一行，无需新密钥，也无需重新安装。您还可以运行 BYOK，通过您自己的提供商密钥进行路由，只需支付提供商账单金额的 5%，且每月前 100 万次请求免收此费用。
常见问题
Codex CLI 能否与 OpenRouter 一起使用？
可以。在用户级别的 ~/.codex/config.toml 中添加一个 [model_providers.openrouter] 块，将 base_url 指向 https://openrouter.ai/api/v1，设置 model_provider = "openrouter" 和 wire_api = "responses"，然后固定一个模型 slug。此后，Codex 将通过 OpenRouter 进行路由。
为什么在 Codex 和 OpenRouter 中会出现 model_not_found 错误？
model 的值必须是包含提供商前缀的精确 OpenRouter slug，例如 openai/gpt-5.3-codex。仅使用 gpt-5.3-codex 是最常见的原因。此外，提供商块必须位于用户级别的 ~/.codex/config.toml 中，而不是项目本地的配置文件中。
通过 OpenRouter 使用 Codex CLI 是否需要 OpenAI 订阅？
不需要。一旦您配置了自定义提供商并导出 OPENROUTER_API_KEY，请求就会通过 OpenRouter 路由并计费。无需单独的 OpenAI 套餐。
通过 OpenRouter 使用 Codex 的费用是多少？
您需要支付提供商的每 token 费率，外加信用购买金额 5.5% 的手续费，提供商不收取额外加价。例如，gpt-5.3-codex 在扣除该手续费前，每百万输入 token 收费 1.75 美元，每百万输出 token 收费 14 美元。失败的请求不计费。
什么是 wire_api，为什么需要设置它？
wire_api 控制 Codex 用于与提供商通信的 API 协议。自 2026 年 2 月起，Codex 移除了对较旧的 chat 值的支持，因此自定义提供商必须设置 wire_api = "responses"，否则 Codex 会在启动时报错。
Codex CLI runs an agentic coding loop in your terminal, and it already supports custom OpenAI-compatible providers. That hook is all you need to route it through OpenRouter.
The payoff is one API key in front of 300+ models, automatic provider failover, and consolidated usage tracking, with no change to Codex itself. The setup is a small config.toml block, but Codex has two requirements that trip people up if you miss them. This walks through the full setup and the two errors you’re most likely to hit.
Point Codex at OpenRouter in five steps
Install Codex CLI from the openai/codex repo, then create a key on your API Keys page. It starts with sk-or-.
Open ~/.codex/config.toml, creating it if it doesn’t exist, and add this:
# ~/.codex/config.toml
model = "openai/gpt-5.3-codex"
model_provider = "openrouter"
model_reasoning_effort = "high"
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"Two fields need attention. model must be a complete OpenRouter slug including the provider prefix, copied from the models page. And wire_api must be "responses", which we get to below.
One more placement rule: model_provider and model_providers only take effect in your user-level ~/.codex/config.toml. Codex ignores them in a project-local .codex/config.toml and prints a startup warning.
Then export your key in the shell profile Codex loads, run codex in a project, and send a test prompt:
export OPENROUTER_API_KEY="sk-or-..."
cd /path/to/your/project
codexOpen the Activity dashboard and confirm the request shows up with the right model name and a token count. If it does, you’re routed.
Set wire_api to responses
Codex used to speak the older chat/completions protocol, but OpenAI deprecated that path and removed it in February 2026. A custom provider with wire_api = "chat", or with no wire_api at all, now fails on startup.
Setting wire_api = "responses" puts Codex on the Responses API, which is what OpenRouter expects. The config block above already includes it. One related gotcha: the provider IDs openai, ollama, and lmstudio are reserved, so you can’t reach OpenRouter by overriding the built-in openai provider’s base URL. Define a new provider like openrouter instead.
Pin a Codex model and watch the spend
Codex models on OpenRouter share a 400K context window, so the choice comes down to price against task difficulty. Current rates from the model catalog, before the platform fee:
| OpenRouter slug | Input $/M | Output $/M |
|---|---|---|
openai/gpt-5.3-codex | $1.75 | $14 |
openai/gpt-5.1-codex | $1.25 | $10 |
openai/gpt-5.1-codex-mini | $0.25 | $2 |
Reach for gpt-5.1-codex-mini on iterative or exploratory work, and gpt-5.3-codex on the hardest tasks. You can also point model at any non-Codex slug, say anthropic/claude-sonnet-4.6, without touching anything else.
Agentic sessions burn more tokens than a prompt’s length suggests, because the model reprocesses repo files, tool outputs, and reasoning traces on every turn. Three controls keep that predictable. Set a spending guardrail on the key so requests are rejected once you hit a daily or monthly cap. Match the model to the task, since gpt-5.3-codex costs 7x more per output token than gpt-5.1-codex-mini. And drop model_reasoning_effort to "low" or "medium" on routine edits.
The fee math is light. OpenRouter doesn’t mark up provider pricing, so you pay the rates above plus a 5.5% fee on credit purchases. A focused session that reads 200K input tokens and writes 50K output on gpt-5.3-codex runs about $1.05 in token cost, and the credit fee adds about 6 cents. Failed requests aren’t billed.
Fix model_not_found
model_not_found is the other common error. Work through these in order:
- The slug isn’t exact. It has to match an OpenRouter slug character for character. Copy it straight from openrouter.ai/models.
- The prefix is missing. Codex slugs look like
openai/gpt-5.3-codex. Theopenai/prefix is required;gpt-5.3-codexalone won’t match. - The shorthand points elsewhere. The
~openai/gpt-latestalias tracks OpenAI’s latest general model, which may not be the Codex variant you want, so pin a Codex slug explicitly. - The config is in the wrong file. Move
model_providerandmodel_providersto your user-level~/.codex/config.toml.
When routing through OpenRouter pays off
OpenRouter earns its place in a Codex workflow when you want to switch quickly between many models, try open-source models alongside the OpenAI defaults, get failover across 70+ providers, see real-time usage visibility, or set team cost controls from one dashboard. Switching models is a one-line change to model in config.toml, with no new key and no reinstall. You can also run BYOK, routing through your own provider key for 5% of what the provider would bill, a fee waived for the first 1M requests each month.
Frequently asked questions
Can Codex CLI be used with OpenRouter?
Yes. Add a [model_providers.openrouter] block in your user-level ~/.codex/config.toml, point base_url at https://openrouter.ai/api/v1, set model_provider = "openrouter" and wire_api = "responses", then pin a model slug. Codex routes through OpenRouter from that point on.
Why do I get model_not_found with Codex and OpenRouter?
The model value has to be an exact OpenRouter slug including the provider prefix, like openai/gpt-5.3-codex. A bare gpt-5.3-codex is the most common cause. The provider block also has to live in your user-level ~/.codex/config.toml, not a project-local one.
Do I need an OpenAI subscription to use Codex CLI through OpenRouter?
No. Once you configure the custom provider and export OPENROUTER_API_KEY, requests route through and bill on OpenRouter. No separate OpenAI plan is required.
How much does Codex cost through OpenRouter?
You pay the provider’s per-token rate plus a 5.5% fee on credit purchases, with no provider markup. For example, gpt-5.3-codex is $1.75 per million input tokens and $14 per million output tokens before that fee. Failed requests aren’t billed.
What is wire_api and why does it need to be set?
wire_api controls which API protocol Codex uses to talk to a provider. As of February 2026, Codex removed support for the older chat value, so custom providers must set wire_api = "responses" or Codex errors on startup.