Codex CLI 通过 ~/.codex/config.toml 配置文件原生支持 OpenRouter 作为模型 Provider。配置 [model_providers.openrouter] 块，设置 base_url=https://openrouter.ai/api/v1 和 env_key=OPENROUTER_API_KEY，运行时传入 -c 'model_provider="openrouter"' 即可路由到 OpenRouter。所有 OpenRouter 模型均可通过 model 字段指定使用，同时获得 Provider 故障转移、团队预算管控和用量可视化能力。

Codex CLI 是 OpenAI 开源的终端本地编程 agent，支持多个模型 Provider，包括 OpenRouter。

快速开始

第一步：安装 Codex CLI

按照 Codex CLI 安装说明在系统上安装 CLI。

第二步：获取 OpenRouter API Key

在 openrouter.ai/keys 创建 API key（以 sk-or-... 开头）。

第三步：配置 Codex

创建或编辑 ~/.codex/config.toml：

model_provider = "openrouter"
model_reasoning_effort = "high"
model = "openai/gpt-5.3-codex"

[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

第四步：设置 API Key

在 shell profile 中添加：

# 添加到 ~/.zshrc、~/.bashrc 或 ~/.config/fish/config.fish
export OPENROUTER_API_KEY="sk-or-..."

Codex 从 env_key 指定的环境变量读取 API key。

第五步：启动 Codex

cd /path/to/your/project
codex

请求将通过 OpenRouter 路由。

配置参考

核心配置项

配置项	说明	示例
model_provider	默认使用的 Provider	"openrouter"
model	OpenRouter 模型 ID	"openai/gpt-5.3-codex"
model_reasoning_effort	Codex 模型的推理强度	"low"、"medium"、"high"、"xhigh"
show_raw_agent_reasoning	是否在 UI 中显示推理 token	true 或 false
personality	Agent 个性预设	"pragmatic"、"helpful" 等

OpenRouter Provider 块

[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

• base_url：OpenRouter API 端点，生产环境使用 https://openrouter.ai/api/v1
• env_key：存储 API key 的环境变量名

项目信任级别

[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"

• trusted：agent 有完整访问权限（运行命令、编辑文件）
• untrusted：agent 访问受限

为什么要通过 OpenRouter 使用 Codex CLI？

Provider 故障转移

OpenRouter 跨多个 Provider 路由请求。若某个 Provider 不可用或限流，自动切换到其他 Provider，保持编程会话不中断。

团队预算管控

集中管理团队中所有使用 Codex 的开发者的积分预算和用量上限。

用量可视化

通过 OpenRouter 活动面板实时追踪 Codex 的费用、token 用量和请求模式。

模型灵活性

通过修改 config.toml 中的 model 字段即可在不同 Codex 模型（如 gpt-5.2-codex、gpt-5.3-codex）或其他 OpenRouter 模型之间切换，无需重装 Codex。

故障排除

• 认证错误：确认 OPENROUTER_API_KEY 已设置且有效，在 openrouter.ai/keys 验证
• 模型未找到：在 openrouter.ai/models 查找确切的模型 ID，格式如 openai/gpt-5.3-codex
• 隐私：OpenRouter 不记录源代码 prompt，除非主动开启 prompt 日志

常见问题

Q: 运行时如何临时覆盖模型或 Provider？

A: 使用 -c 参数传入运行时配置覆盖，例如：

codex -c 'model_provider="openrouter"' -c 'model="anthropic/claude-sonnet-4.6"'

注意：Codex CLI 没有 --provider 参数，所有运行时覆盖都必须用 -c。

Q: Codex CLI 和 Claude Code 的 base URL 为什么不同？

A: 两者使用不同的 API 协议层。Codex CLI 使用 OpenAI 兼容协议（需要 /v1 后缀：https://openrouter.ai/api/v1），Claude Code 使用 Anthropic 协议（不加 /v1：https://openrouter.ai/api）。混淆这两个 URL 会导致模型找不到错误。

Q: 通过 OpenRouter 使用 Codex 能访问哪些模型？

A: 所有在 openrouter.ai/models 上可用且支持 function calling 的模型均可使用，不限于 OpenAI 模型。推荐使用经过验证的 Codex 系列模型（openai/gpt-5.2-codex、openai/gpt-5.3-codex），或其他具备强代码能力的模型。