Codex CLI 接入 OpenRouter
已验证通过一个密钥在 Codex CLI 中使用 OpenRouter 模型目录中的模型。OpenRouter 为该编码 Agent 文档化了此集成。
已于 2026-07-30 依据服务商官方文档验证。
关于 Codex CLI
Codex CLI 是 OpenAI 开源的终端编程代理，通过 ~/.codex/config.toml 读取自定义模型服务商，并使用环境变量认证。
关于 OpenRouter
OpenRouter 是聚合了数百个模型的统一 API 网关。一个密钥即可访问模型目录中的模型，并支持服务商故障转移与统一计费。
要点
- 模型 slug 必须与 OpenRouter 目录完全一致，包括服务商前缀（例如 openai/gpt-5.3-codex）。
- 必须使用 wire_api = "responses"：Codex 已于 2026 年 2 月移除 chat completions 协议。
- openai、ollama、lmstudio 是保留 ID；请按示例新建名为 openrouter 的配置块。
- 密钥通过 env_key 从 OPENROUTER_API_KEY 环境变量读取。
接入 Codex CLI 接入 OpenRouter
选择操作系统、Shell 与模型。下方步骤会实时更新，且全部在浏览器本地生成。
任意 OpenRouter slug 均可使用。openai/gpt-5.3-codex 针对 Agent 编程优化；~ 别名会自动解析为最新模型。
Browse the full OpenRouter model catalog获取 API Key
创建 OpenRouter API Key。Codex CLI 通过它进行认证——它永远不会离开你的设备。
获取 OpenRouter API Key- 安装 Codex CLI：npm install -g @openai/codex
- Sign in, open Keys, and create a key that starts with sk-or-. Free-tier requests are available; adding $10 in credits raises your daily free limit.
配置连接
将 provider 配置块添加到 Codex 配置，然后导出你的 API Key。
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"
wire_api = "responses"
env_key = "OPENROUTER_API_KEY"如果文件不存在请创建。Provider 配置仅在用户级配置中生效。
- 1添加到 ~/.zshrc
export OPENROUTER_API_KEY="sk-or-"验证配置
在新终端中运行以下命令。成功返回即表示 Codex CLI 已连接到目标端点。
codex exec "Say hello in one sentence."The exact reply varies. You can also verify the request appears in the provider dashboard (billing / activity page).
开始使用
启动 Codex CLI 并发送第一条消息。
- 输入：Explain the files in this project.
codex故障排查
大多数问题可以归为以下几类，每一条都包含原因、解决方法与验证方式。
401 未授权
排障指南API Key 错误、已过期，或服务商账户余额不足。
在服务商后台创建新密钥，然后用新密钥重新生成配置。如果密钥保存在 Shell 配置文件中，请打开新终端使导出生效。
验证： 运行 `echo $ANTHROPIC_AUTH_TOKEN`（Codex 使用 `echo $DEEPSEEK_API_KEY` / `$OPENROUTER_API_KEY`），确认输出形如有效的密钥。
404 未找到
排障指南Base URL 错误（拼写错误、多余路径段），或 Codex 的 wire 协议与服务商提供的不匹配。
从本页复制准确的 Base URL。Codex 搭配 OpenRouter 时保留 `wire_api = "responses"`；如果 DeepSeek 在 /responses 返回 404，尝试删除 wire_api 行以匹配服务商提供的端点。
验证： 重新运行第 3 步的验证命令，检查报错路径：应指向 /anthropic（Claude Code）或 /responses（Codex）。
模型不存在
排障指南模型名称在服务商处不存在，或 Agent 缓存了旧登录状态，覆盖了环境变量。
从本页的模型列表中选择。Claude Code 搭配 OpenRouter 时，先在 Claude Code 内执行 `/logout` 再重新启动——缓存的 Anthropic 登录会覆盖你的环境变量。
验证： 确认 ANTHROPIC_API_KEY 已置空（OpenRouter）或未设置（DeepSeek），然后重新运行 `claude /status`。
限流 / 配额不足
排障指南服务商限制了每分钟请求数，或账户余额用尽。
等待限流窗口结束、充值账户余额，或改用更便宜的模型。OpenRouter 用户可以通过充值提升免费额度上限。
验证： 到服务商后台（余额与用量页面）查看被拒绝的请求。
网络错误 / 连接失败
排障指南本机无法访问服务商端点，或代理拦截并改写了请求。
检查到 Base URL 的 DNS 与连通性，检查代理与防火墙设置后重试。请使用本页给出的端点；第三方镜像不受支持。
验证： 运行 `curl -I <base url>`（例如 `curl -I https://api.deepseek.com/anthropic`），确认可以访问。
超时 / 请求超时
排障指南模型响应慢、提示词过长，或与服务商所在地区的网络受限。
重试请求、缩短提示词，或改用更快的模型。区域性的网络问题可能需要更换网络或选择节点更近的服务商。
验证： 在网络空闲时重新运行验证命令，确认可以完成。
提示 "wire_api chat" 错误
Codex 已于 2026 年 2 月移除 chat completions wire 协议。
在 openrouter provider 配置块中设置 wire_api = "responses"（生成的配置已包含）。
验证： `codex exec "hi"` 启动时不再报协议错误。
常见问题
为什么非 OpenAI 模型显示 "Unknown model"？
使用 env_key 认证时 Codex 无法获取 OpenRouter 模型目录，因此显示回退元数据。请求仍可正常使用；改用 command 认证可恢复目录。
为什么不能直接用保留 ID openrouter？
openai、ollama、lmstudio 是内置 ID。其他任意名称（包括 openrouter）都可以使用——按生成的配置块配置即可。
model_reasoning_effort 对所有模型生效吗？
不支持推理等级控制的模型会忽略该设置。保留在配置中没有副作用。