---
title: "通过 OpenRouter 连接模型服务"
summary: "用户 config 写 [model_providers.openrouter]，base_url 是 https://openrouter.ai/api/v1，wire_api = responses。主路径是 [model_providers.openrouter.auth] 用 sh 回显 OPENROUTER_API_KEY，与 env_key 二选一。"
category: config
level: intermediate
surfaces: [cli, app]
tags: ["model_providers", "OpenRouter", "wire_api", "profile"]
canonical: /tips/openrouter-codex-gateway/
---

# 通过 OpenRouter 连接模型服务

用户 config 写 [model_providers.openrouter]，base_url 是 https://openrouter.ai/api/v1，wire_api = responses。主路径是 [model_providers.openrouter.auth] 用 sh 回显 OPENROUTER_API_KEY，与 env_key 二选一。

OpenRouter 官方 Codex 网关：用户层 [model_providers.openrouter]，base_url 是 https://openrouter.ai/api/v1，auth 命令回显 OPENROUTER_API_KEY。

这是换 Codex **使用的模型**，不是添加 MCP 服务。官方 CLI 教程的主路径是命令式 `auth`：Codex 跑一条命令拿到密钥，才会去拉 OpenRouter 的模型目录。只写 `env_key = "OPENROUTER_API_KEY"` 也能连上，但不会拉目录，非 OpenAI 模型会警告 Unknown model，用内置回退 metadata。Learn 写明 `auth` 不要和 `env_key` / `experimental_bearer_token` / `requires_openai_auth` 叠。

供应商表放**用户** `~/.codex/config.toml`：

```toml
# ~/.codex/config.toml
[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 没有 `sh`，改 PowerShell：

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

`auth` 读的是进程环境里的 `OPENROUTER_API_KEY`（密钥以 `sk-or-` 开头）。不要把 `sk-or-` 写进 TOML。从已经 `export OPENROUTER_API_KEY` 的终端启动。Dock / Start 打开的桌面不会读你刚改的 zshrc。官方桌面页：macOS 用 `launchctl setenv OPENROUTER_API_KEY …`，Windows 用 `setx OPENROUTER_API_KEY …`，然后完全退出再开。桌面页示例写了 `env_key` 和 `supports_websockets = false`；命令式 `auth` 在桌面同样可用，只要 GUI 进程看得到那条环境变量。OpenRouter 不支持 Responses WebSocket，不要开 `supports_websockets = true`。

不要把顶层 `model_provider = "openrouter"` 一上来写进用户 config，除非你就是要把**所有**会话都改走网关。更稳妥是独立 profile：

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

```bash
codex --profile openrouter
codex --profile openrouter -m openai/gpt-5.6-luna
```

0.134 起不要再写 `[profiles.openrouter]`。模型 slug 必须带厂商前缀，从 openrouter.ai/models 原样复制，例如 `openai/gpt-5.6-sol`。不要写成不带厂商前缀的 `gpt-5.6-sol`。波浪号别名 `~openai/gpt-sol-latest`、`~openai/gpt-latest` 会随目录更新，要固定版本就写死 slug。

配置说明：

- Codex 入口是 `https://openrouter.ai/api/v1`。
- 不要写 `wire_api = "chat"`。现行只认 `responses`。
- 不要写进项目 `.codex/config.toml`。项目文件无法修改 `model_provider` / `model_providers`。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`openrouter` 是新 ID，可以。
- 不要把官方示例里的项目 `trust_level` 当成这张网关表的必填项。
- 不要把密钥写进 `http_headers`。

自定义供应商没有应用内模型选择器。改 `model` 后必须**新开会话**。`codex --profile openrouter` 启动后，发送一条简短请求验证连接。401 / Missing Authentication header 先看 `auth` 命令有没有跑起来、进程里有没有密钥；Unknown model 先看是不是误用了 `env_key`；`model_not_found` 先对照目录改 slug。用量看 OpenRouter Activity。

## 来源

- [OpenRouter · Codex CLI](https://openrouter.ai/docs/cookbook/coding-agents/codex-cli)
- [OpenRouter · Codex Desktop App](https://openrouter.ai/docs/cookbook/coding-agents/codex-desktop)
- [OpenRouter Blog · Codex CLI with OpenRouter](https://openrouter.ai/blog/tutorials/codex-cli-openrouter/)