Codex CLI 在你的终端中运行一个智能体编码循环，而且它已经支持自定义的 OpenAI 兼容提供商。有了这个钩子，你就能把它接入 OpenRouter。
回报是：一个 API key 就能对接 300+ 个模型、自动的提供商故障转移，以及统一的用量追踪，而且无需对 Codex 本身做任何改动。配置只是一小段 config.toml，但 Codex 有两个要求，如果你忽略了它们就会踩坑。本文将带你走完整个配置流程，以及你最可能遇到的两个错误。
五步将 Codex 指向 OpenRouter
从 openai/codex 仓库安装 Codex CLI，然后在你的 API Keys 页面创建一个 key。它以 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，包含提供商前缀，从 models 页面复制。而 wire_api 必须是 "responses"，我们下面会讲到。
还有一条放置规则：model_provider 和 model_providers 只在你用户级别的 ~/.codex/config.toml 中生效。Codex 会忽略项目本地的 .codex/config.toml 中的它们，并打印一条启动警告。
然后在你 Codex 加载的 shell 配置文件中导出你的 key，在一个项目中运行 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" 的自定义 provider，或者完全没有 wire_api 的 provider，现在会在启动时失败。
设置 wire_api = "responses" 会让 Codex 使用 Responses API，这正是 OpenRouter 所期望的。上面的配置块已经包含了它。一个相关的坑：provider ID openai、ollama 和 lmstudio 是保留的，所以你无法通过覆盖内置 openai provider 的 base URL 来访问 OpenRouter。请改为定义一个新的 provider，例如 openrouter。
固定一个 Codex 模型并关注花费
OpenRouter 上的 Codex 模型共享 400K 上下文窗口，因此选择取决于价格与任务难度的权衡。以下是来自 模型目录的当前费率，不含平台费用：
| OpenRouter slug | 输入 $/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。你也可以把 model 指向任何非 Codex 的 slug，比如 anthropic/claude-sonnet-4.6，而无需改动其他任何东西。
智能体会话消耗的 token 比提示词长度所暗示的要多，因为模型在每一轮都会重新处理仓库文件、工具输出和推理轨迹。有三项控制手段可以让开销保持可预测。在密钥上设置支出护栏，这样一旦达到每日或每月上限，请求就会被拒绝。让模型与任务相匹配，因为 gpt-5.3-codex 每输出 token 的成本是 gpt-5.1-codex-mini 的 7 倍。并且在日常编辑中将 model_reasoning_effort 降级为 "low" 或 "medium"。
费用计算很轻。OpenRouter 不会在提供商定价上加价，因此你支付上述费率，外加信用额度购买时 5.5% 的手续费。一次专注的会话在 gpt-5.3-codex 上读取 200K 输入 token 并写入 50K 输出 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 默认模型之外尝试开源模型、获得跨故障转移能力时，OpenRouter 在 Codex 工作流中便有了它的一席之地。70+ 家提供商，查看实时用量可见性，或在一个仪表盘中设置团队成本控制。切换模型只需改动一行model在config.toml中，无需新密钥，也无需重新安装。你还可以运行BYOK，通过你自己的提供商密钥进行路由，费用仅为该提供商原本计费的 5%，且每月前 1M 次请求免收此费用。
常见问题
Codex CLI 可以与 OpenRouter 一起使用吗？
可以。添加一个[model_providers.openrouter]块到你的用户级~/.codex/config.toml，将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 是最常见的原因。provider 块还必须放在用户级别的 ~/.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.