我是如何为 Open Claw 配置 OpenRouter 模型的：一份实战操作手册

概述

今天我想和大家分享一下我最近使用 OpenRouter 来配置 Open Claw 的经验。OpenRouter 这个平台真的很棒，它就像一个 AI 模型的“聚合器”，用一个统一的 API 端点和一把钥匙（API Key），就能访问到市面上几乎所有主流提供商的模型。最让我惊喜的是，它和 OpenAI 的 API 是兼容的，这意味着很多基于 OpenAI SDK 的工具，包括 Open Claw，只需要切换一下 base URL 就能无缝接入。

我总结了一下它的几个核心特点：
- ✅ 一个 API Key 就能访问多家模型提供商，再也不用记一堆密钥了
- ✅ 完美兼容 OpenAI API，迁移成本极低
- ✅ 支持超过 100 种模型（Claude、GPT、Gemini、Llama 等等，应有尽有）
- ✅ 按实际使用量计费，没有强制月费，对个人开发者很友好
- ✅ 统一的后台可以查看所有模型的使用统计，管理起来非常方便

快速开始

步骤一：获取 OpenRouter API Key

这个过程其实很简单，我几分钟就搞定了：
1. 首先，访问 OpenRouter 官网
2. 点击页面右上角的 Sign In 按钮登录或注册一个新账号
3. 登录后，进入 Keys 管理页面：https://openrouter.ai/keys
4. 点击 Create Key 按钮来生成一个新的 API Key
5. 最重要的一步：复制并妥善保存生成的 API Key（它的格式通常是 sk-or-v1-xxxxxxxxxxxxx）

下面这个示意图基本还原了我当时看到的界面，非常直观：

┌─────────────────────────────────────────────────────────┐
│  OpenRouter API Keys                                    │
├─────────────────────────────────────────────────────────┤
│  Your API Key                                           │
│  ┌─────────────────────────────────────────────────┐   │
│  │ sk-or-v1-a1b2c3d4e5f6g7h8i9j0                   │ [复制] │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  [+ Create Key]                                         │
└─────────────────────────────────────────────────────────┘

CLI 设置方法

拿到 API Key 后，我们就可以在 Open Claw 里进行配置了。我尝试了两种方法，都挺方便的。

方法一：使用 CLI 命令设置（推荐）

这是我个人最喜欢的方式，直接在终端里交互式操作，非常快捷。

# 使用交互式命令添加认证，系统会引导你一步步完成
openclaw auth add

# 如果你喜欢一步到位，也可以用这个命令直接指定
openclaw onboard --auth-choice apiKey --token-provider openrouter --token "sk-or-v1-xxxxxxxxxxxxx"

方法二：通过配置文件设置

如果你更喜欢直接编辑配置文件，或者需要更复杂的配置，这个方法也很合适。

首先，找到你的 OpenClaw 配置文件位置：
- Windows 系统：C:\Users\<你的用户名>\.openclaw\config.yaml
- macOS/Linux 系统：~/.openclaw/config.yaml

然后，在配置文件中添加类似下面的 OpenRouter 配置。我个人习惯用环境变量来管理密钥，这样更安全：

# 通过环境变量设置密钥（推荐）
env:
  OPENROUTER_API_KEY: "sk-or-v1-xxxxxxxxxxxxx"

# Agent 的配置部分
agents:
  default:
    auth:
      - provider: openrouter
        api_key: ${OPENROUTER_API_KEY} # 这里引用上面的环境变量
    models:
      - id: openrouter/anthropic/claude-sonnet-4-5 # 指定一个默认模型

模型引用格式

在 OpenRouter 里调用模型，有一个固定的格式，刚开始我也有点迷糊，弄明白后就很简单了。它的格式是：

openrouter/<提供商>/<具体模型名>

我整理了一些常用的例子：

模型引用	说明
`openrouter/anthropic/claude-opus-4-6`	Anthropic 家的顶级模型 Claude Opus 4.6
`openrouter/anthropic/claude-sonnet-4-5`	性能均衡的 Claude Sonnet 4.5
`openrouter/openai/gpt-4.1`	OpenAI 的 GPT-4.1
`openrouter/google/gemini-pro-1.5`	Google 的 Gemini Pro 1.5
`openrouter/meta-llama/llama-3.1-405b-instruct`	Meta 的 Llama 3.1 405B 大模型
`openrouter/moonshotai/kimi-k2`	国产的月之暗面 Kimi K2

这里有几个小坑需要注意：
- 模型 ID 是通过第一个 / 来分割提供商和模型名的。
- 如果模型 ID 本身包含 /（这是 OpenRouter 的风格），那么就必须带上 openrouter/ 这个前缀。
- 如果你省略了 openrouter/ 前缀，OpenClaw 会把它当作一个别名，或者认为是默认提供商的模型，这可能会导致找不到模型。

切换模型

配置好认证后，最爽的就是可以随时切换不同的模型了。Open Claw 的命令行工具让这一切变得非常容易。

查看当前模型状态

在切换之前，先看看当前是什么状态总没错。

# 查看当前默认使用的是哪个模型
openclaw models status

# 如果你需要更结构化的信息，可以用 JSON 格式输出
openclaw models status --json

# 这个命令很实用，它会实时探测你的认证是否有效
openclaw models status --probe

设置 OpenRouter 模型

切换模型的核心命令就是 openclaw models set。下面是我常用的一些例子：

# 设置 Claude Sonnet 4.5（记得用完整的格式）
openclaw models set openrouter/anthropic/claude-sonnet-4-5

# 切换到国产的 Kimi 模型试试
openclaw models set openrouter/moonshotai/kimi-k2

# 或者换回熟悉的 GPT-4 系列
openclaw models set openrouter/openai/gpt-4.1

列出所有可用模型

有时候记不清模型全名，或者想看看 OpenRouter 又上了什么新模型，可以用这些命令：

# 列出 Open Claw 当前已知的所有可用模型
openclaw models list

# 这个命令会主动扫描并发现新的模型
openclaw models scan

Config Snippet（配置代码片段）

为了方便大家复制粘贴，我这里提供几个现成的配置片段，你可以直接用到自己的 config.yaml 文件里。

基础配置

这是一个最精简的配置，适合快速上手。

{
  env: { OPENROUTER_API_KEY: "sk-or-v1-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
    },
  },
}

完整配置示例

如果你需要更复杂的场景，比如为不同的任务（编码、聊天）配置不同的模型，可以参考下面这个更完整的例子：

# OpenRouter 提供商的全局配置
providers:
  openrouter:
    api_key: ${OPENROUTER_API_KEY}
    base_url: https://openrouter.ai/api/v1

# 定义多个 Agent，每个可以有自己的模型偏好
agents:
  - id: default # 默认 Agent
    models:
      - id: openrouter/anthropic/claude-opus-4-6
        thinking: enabled # 启用深度思考模式
      - id: openrouter/anthropic/claude-sonnet-4-5

  - id: coding # 专门用于编码的 Agent
    models:
      - id: openrouter/anthropic/claude-opus-4-6

  - id: chat # 专门用于聊天的 Agent
    models:
      - id: openrouter/google/gemini-pro-1.5

常用 OpenRouter 模型列表

OpenRouter 上的模型实在太多了，我根据自己的使用体验，整理了一份常用模型的清单，包括价格参考（价格可能会有变动，请以官网为准）。

Anthropic Claude 系列

模型 ID	说明	价格（每 100万 tokens）
`openrouter/anthropic/claude-opus-4-6`	能力最强的模型，适合复杂任务	$15 (输入) / $75 (输出)
`openrouter/anthropic/claude-sonnet-4-5`	性能和速度的平衡之选，我的主力	$3 / $15
`openrouter/anthropic/claude-haiku-4-5`	速度飞快，适合轻量级交互	$1 / $5

OpenAI GPT 系列

模型 ID	说明	价格（每 100万 tokens）
`openrouter/openai/gpt-4.1`	最新的 GPT-4.1	$10 / $30
`openrouter/openai/gpt-4.1-mini`	GPT-4.1 的轻量版	$3 / $10
`openrouter/openai/gpt-4o`	多模态模型 GPT-4o	$5 / $15

Google Gemini 系列

模型 ID	说明	价格（每 100万 tokens）
`openrouter/google/gemini-pro-1.5`	上下文超长的 Gemini Pro 1.5	$3 / $10
`openrouter/google/gemini-flash-1.5`	性价比极高的 Gemini Flash 1.5	$0.15 / $0.60

国产模型

国产模型最近进步神速，在 OpenRouter 上也能很方便地用到。

模型 ID	提供商	说明
`openrouter/moonshotai/kimi-k2`	月之暗面	长上下文能力突出的 Kimi K2
`openrouter/qwen/qwen-2.5-72b-instruct`	阿里云	通义千问 2.5 版本
`openrouter/deepseek-ai/deepseek-chat`	深度求索	广受好评的 DeepSeek Chat

故障排除

在使用过程中，我也遇到过一些报错。这里把我踩过的坑和解决方法分享给大家。

401 Unauthorized 错误

可能原因：
- API Key 无效、过期或者复制时多了空格。
- API Key 的格式不对（比如漏了 sk-or-v1- 前缀）。

我是这样解决的：

# 最直接的方法，重新运行认证添加命令
openclaw auth add

# 或者，仔细检查配置文件里的 API Key 字符串是否正确，注意引号和缩进

403 Forbidden 错误

可能原因：
- 账户余额用完了。
- 你想用的那个模型暂时没有对你的账户开放权限。

解决方法：
1. 立刻去 OpenRouter 官网登录，在账户页面检查一下余额和信用。
2. 在 OpenRouter 的模型列表页，确认一下你想用的模型是否显示为“可用”。

429 Too Many Requests 错误

可能原因：
- 你的请求发送得太快了，触发了频率限制。
- 你的账户有总额度限制（比如免费试用额度）。

解决方法：
- 在代码或工具中适当加入延迟，降低请求频率。
- 如果确实需要更高限额，可以考虑联系 OpenRouter 支持或升级账户。

模型找不到错误

可能原因：
- 模型引用格式写错了，这是最常见的原因。
- 模型名称拼写有误，或者大小写不对。

解决方法：

# 确保使用了正确的三段式格式：openrouter/<提供商>/<模型>
openclaw models set openrouter/anthropic/claude-sonnet-4-5

# 如果不确定名字，先用 list 命令查一下
openclaw models list

高级配置

当你熟悉了基础操作后，可以尝试一些更高级的配置，让 Open Claw 更加强大和灵活。

多 Provider 配置

你可以在 Open Claw 里同时配置 OpenRouter 和模型厂商的直连 API。这样可以在 OpenRouter 出问题时快速切换，或者对比同一个模型在不同渠道的表现。

providers:
  openrouter:
    api_key: ${OPENROUTER_API_KEY}
  anthropic: # 同时配置 Anthropic 直连
    api_key: ${ANTHROPIC_API_KEY}

agents:
  - id: default
    models:
      - id: openrouter/anthropic/claude-opus-4-6 # 通过 OpenRouter 调用
      - id: anthropic/claude-opus-4-6  # 直连 Anthropic 官方 API

自定义 Base URL

虽然 OpenRouter 的默认地址一般不用改，但知道可以自定义总是好的。

providers:
  openrouter:
    api_key: ${OPENROUTER_API_KEY}
    base_url: https://openrouter.ai/api/v1 # 默认就是这个，可以省略

模型 fallback 配置

这个功能非常实用！你可以为 Agent 设置一个备选模型列表。当首选模型因为任何原因（如超时、额度不足）失败时，Open Claw 会自动尝试列表中的下一个模型。

agents:
  default:
    models:
      - id: openrouter/anthropic/claude-opus-4-6 # 首选
    fallbacks: # 备选列表
      - openrouter/anthropic/claude-sonnet-4-5
      - openrouter/google/gemini-pro-1.5

常用命令速查

最后，我把我最常用的几个 Open Claw 命令整理成了一张表，方便随时查阅。

操作	命令
添加认证	`openclaw auth add`
查看模型状态	`openclaw models status`
设置模型	`openclaw models set <模型ID>`
列出所有模型	`openclaw models list`
扫描新模型	`openclaw models scan`
探测认证状态	`openclaw models status --probe`
查看已安装插件	`openclaw plugins list`

你可能感兴趣的文章

来源：每日教程， 每日一例，深入学习实用技术教程，关注公众号TeachCourse
转载请注明出处： https://teachcourse.cn/3887.html ，谢谢支持！

资源分享

分类：编程工具 标签：AI模型, API配置, CLI, OpenClaw, OpenRouter, 故障排除, 模型切换, 配置管理