OpenClaw 接入 OpenRouter
给用 OpenClaw 搭 agent 的人一个直接可用的集成指南,还附带了常见报错修复,比零散摸索省时间。
OpenClaw 已内置 OpenRouter 支持,一条命令即可为 AI 智能体配置统一密钥、统一账单,并实现跨 300 多个模型的自动故障转移。同时提供具体设置步骤以及常见错误的修复方法。
将 OpenClaw 连接到 OpenRouter
OpenRouter · 2026/6/18
- 一条命令将 OpenClaw 连接到 OpenRouter
- 使用 openrouter/<作者>/<标识符> 格式引用模型
- 当某个提供商掉线时,让智能体继续运行
- 将模型与智能体匹配,以控制成本
- 修复最常见的连接错误
- 常见问题解答
OpenClaw 可在同一个地方跨 Telegram、Discord、Slack、Signal、iMessage 和 WhatsApp 运行 AI 智能体。它是开源的,需要一个模型提供商作为后端。如果直接指向单个提供商,你就拥有了那种关系:一把密钥、一张账单,以及一个在该提供商出现短暂故障时就会停摆的智能体。
OpenClaw 自带内置 OpenRouter 支持,因此一把密钥即可访问 70 多个提供商的 300 多个模型,账单汇总到一处,请求会自动故障转移到其他提供商。连接只需一条命令。本指南涵盖了该设置,然后是模型格式、故障转移、成本控制以及最常见错误。
一条命令将 OpenClaw 连接到 OpenRouter
使用你的密钥运行 onboard 命令:
openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY" 该命令会将你的凭据写入 ~/.openclaw/openclaw.json,并设置 openrouter/auto 模型。你就连接上了。
如果你更愿意手动编辑配置,文件位于运行 OpenClaw 的用户主目录下的 ~/.openclaw/openclaw.json。最小配置需要你的密钥和一个模型:
{
"env": {
"OPENROUTER_API_KEY": "sk-or-..."
},
"agents": {
"defaults": {
"model": {
"primary": "openrouter/openrouter/auto"
},
"models": {
"openrouter/openrouter/auto": {}
}
}
}
} 在服务器上,将密钥设置在 env 块而非 shell 配置文件中。运行在不同用户或 shell 下的服务不会读取交互式配置文件,而 env 块会在进程启动时注入。之后要更改密钥,编辑 env.OPENROUTER_API_KEY 并用 openclaw gateway run 重启。
然后确认你的模型已加载:
openclaw models list 使用 openrouter/<作者>/<标识符> 格式引用模型
OpenClaw 将 OpenRouter 模型引用为 openrouter/<作者>/<标识符>。在作者前加 ~ 可追踪该系列的最新版本,去掉则可锁定精确版本。在提交某个标识符之前,先在模型页面检查当前标识符,因为随着新版本发布,标识符会发生变化。
| 模型 | 引用格式 |
|---|---|
| Claude Sonnet(最新版) | openrouter/~anthropic/claude-sonnet-latest |
| Gemini Flash(最新版) | openrouter/~google/gemini-flash-latest |
| DeepSeek | openrouter/deepseek/deepseek-chat |
| Kimi(最新版) | openrouter/~moonshotai/kimi-latest |
| Llama 3.3 70B | openrouter/meta-llama/llama-3.3-70b-instruct |
附加变体后缀可更改同一模型的路由方式。`:free` 路由到免费端点,`:nitro` 按吞吐量排列提供商,`:thinking` 请求扩展推理。若之后要更改智能体的模型,更新 `agents.defaults.model.primary` 并重启网关。
自动路由器的引用方式为 `openrouter/openrouter/auto`:作者是 `openrouter`,模型是 `auto`。这种双重的 `openrouter` 很容易搞错,而下面的未知模型错误正是由此修复。
当提供商掉线时保持智能体继续运行
单次失败的 API 调用很容易重试。但一个跨多步 Telegram 对话维护状态的 OpenClaw 智能体则不然,因为运行中途的失败可能导致消息看似已发送但实际上并未发送,或者工具调用从未返回结果。OpenRouter 在两个层面处理这一问题。
提供商故障转移是自动的。大多数模型由多个提供商提供服务,如果 OpenRouter 尝试的第一个提供商宕机或对您进行速率限制,则会将同一请求路由到另一个提供商。您无需配置,且仅对成功完成的请求收费。
模型回退用于处理模型在所有地方都不可用的情况。添加一个 `fallbacks` 数组,OpenRouter 将按顺序尝试每个模型:
{
"agents": {
"defaults": {
"model": {
"primary": "openrouter/~anthropic/claude-sonnet-latest",
"fallbacks": [
"openrouter/~google/gemini-flash-latest",
"openrouter/deepseek/deepseek-chat"
]
}
}
}
} 两者可叠加使用。提供商故障转移会在同一模型背后切换提供商;而回退数组则会完全切换模型。请检查响应中的 `model` 字段以查看实际运行的是哪个模型。完整配置请参阅模型回退文档。
如果您的提示词包含数据驻留或合规性要求,请使用 `data_collection` 和 `zdr` 提供商路由控制,将路由限制在不保留请求数据的提供商。提供商选择文档涵盖了相关参数,提供商日志列表列出了哪些提供商符合条件。
为智能体匹配合适的模型以控制成本
为每个智能体操作都运行一个强大模型,会在不需要的任务上浪费资金。一个阅读长文档的研究智能体需要前沿模型。处理短文本的摘要智能体在免费 Llama 上就能良好运行。一个快速回答问题的机器人使用 Gemini Flash 就能很好运行。
由 NotDiamond 驱动的自动路由(openrouter/openrouter/auto)会为每次请求选择一个性价比高的模型,并按该模型的标准费率收费,不额外收取路由费用。它很适合智能体流量中大部分低风险任务(如心跳和状态检查)的默认路由。
当您希望进行明确控制时,OpenClaw 允许您按智能体拆分模型。在 agents.overrides.<name>.model 下为每个智能体设置覆盖:
{
"agents": {
"overrides": {
"researcher": {
"model": { "primary": "openrouter/anthropic/claude-opus-4.6" }
},
"summarizer": {
"model": { "primary": "openrouter/meta-llama/llama-3.3-70b-instruct:free" }
}
}
}
} 关于成本:OpenRouter 不对提供商定价加价。按量付费模式下,平台费为 5.5%,这一笔费用涵盖了统一计费、故障切换以及跨所有提供商的单密钥使用。对于低风险操作,20 多个免费模型按 token 计费为零成本。如果您自带提供商密钥,BYOK 费率为 5%,且每月前 100 万次请求免收此费用。可在 Activity 仪表板中按模型跟踪支出。
当您运行多个模型、希望请求在故障时仍能成功,或者想通过编辑字符串来切换模型时,统一端点便体现出其价值。
修复最常见的连接错误
“No API key found for provider ‘openrouter’” 表示密钥未到达 OpenClaw。运行 echo $OPENROUTER_API_KEY 检查密钥,使用 openclaw auth list 验证您的认证配置,或重新运行 onboard 命令。在 VPS 上,常见原因是变量加载在您的交互式 shell 中,但未加载到服务的 shell 中,因此请在配置文件的环境变量块中设置它。
“unknown model: openrouter/auto” 表示自动路由引用错误。应使用 openrouter/openrouter/auto,并将其列在 agents.defaults.models 下。OpenClaw 需要完整的 openrouter/<author>/<slug> 路径。
“OpenRouter not responding” 表示请求已发出但未收到任何响应。请执行四项检查:在 openrouter.ai/keys 确认您的余额,运行 openclaw models list 确认 slug 可解析,运行 openclaw logs --follow 查看实际错误,并确保您的主机可以访问 https://openrouter.ai/api/v1。阻止该主机的出站规则会直接导致此无响应问题。
401 或 403 错误属于账户端问题:密钥无效、已被撤销或余额不足。请在 openrouter.ai/keys 检查密钥,更新 env.OPENROUTER_API_KEY,然后重启网关。
常见问题
如何将 OpenClaw 连接到 OpenRouter?
运行 `openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"`。它会写入你的凭据,并设置 openrouter/auto 模型。你不需要设置 base URL 或 models.providers 块。
OpenClaw 使用什么模型引用格式?
格式为 `openrouter/<作者>/<slug>`,例如 `openrouter/deepseek/deepseek-chat`。在作者前加上 `~` 可以跟踪同一模型族的最新版本(如 `openrouter/~anthropic/claude-sonnet-latest`),或者追加 `:free`、`:nitro` 或 `:thinking` 来改变路由行为。
如何修复“unknown model: openrouter/auto”错误?
使用 `openrouter/openrouter/auto`,并将其列在 `agents.defaults.models` 下。OpenClaw 需要完整的 `openrouter/<作者>/<slug>` 路径,而 Auto Router 的作者名就是 `openrouter`。
我可以在 OpenClaw 中使用免费的 OpenRouter 模型吗?
可以。在引用后追加 `:free`,例如 `openrouter/meta-llama/llama-3.3-70b-instruct:free`。建议配合一个备用模型,以便在免费通道繁忙时智能体仍能继续运行。
我需要为 OpenClaw 设置 base URL 吗?
不需要。OpenClaw 内置的 OpenRouter 支持会内部处理路由。只需设置 API 密钥,并用 `openrouter/<作者>/<slug>` 格式引用模型即可。