OpenRouter：Announcements（RSS）

精选

AI 编辑部评分，满分 100

OpenClaw 接入 OpenRouter

2026-06-19 03:00· 48天前· OpenRouter

AI 导读

OpenClaw 已内置 OpenRouter 支持，一条命令即可为 AI 智能体配置统一密钥、统一账单，并实现跨 300 多个模型的自动故障转移。同时提供具体设置步骤以及常见错误的修复方法。

推荐理由

给用 OpenClaw 搭 agent 的人一个直接可用的集成指南，还附带了常见报错修复，比零散摸索省时间。

正文 · AI 翻译

一条命令即可将 OpenClaw 连接到 OpenRouter
使用 openrouter/<作者>/<标识符> 格式引用模型
当某个提供商中断时，保持智能体继续运行
为智能体匹配合适的模型以控制成本
修复最常见的连接错误
常见问题解答

OpenClaw 可在同一处管理横跨 Telegram、Discord、Slack、Signal、iMessage 和 WhatsApp 的 AI 智能体。它是开源的，并且需要一个模型提供商作为后端。如果直接指向一个提供商，你就完全掌控了这种关系：一个密钥、一张账单，但一旦该提供商出现短暂故障，智能体就会停止运行。

OpenClaw 内置了 OpenRouter 支持，因此一个密钥即可访问 70 多个提供商的 300 多个模型，账单统一结算，并且请求会自动故障转移到另一个提供商。连接只需一条命令。本指南将介绍该设置过程，然后是模型格式、故障转移、成本控制以及最常见的错误。

一条命令即可将 OpenClaw 连接到 OpenRouter

使用你的密钥运行以下内置命令：

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": {}
      }
    }
  }
}

在服务器上，将密钥设置在环境变量块中，而不是 shell 配置文件里。在不同用户或 shell 下运行的服务无法读取交互式配置文件，而环境变量块会在进程启动时注入。之后如需更改密钥，编辑 `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 里，因此请将其设置在配置的 env 块中。

“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 模型。你不需要配置基础 URL 或 models.providers 块。

OpenClaw 使用什么模型引用格式？

格式为 `openrouter/<作者>/<标识>`，例如 `openrouter/deepseek/deepseek-chat`。在作者名前添加 `~` 可追踪同一模型系列的最新版本（如 `openrouter/~anthropic/claude-sonnet-latest`），或追加 `:free`、`:nitro`、`:thinking` 来改变路由行为。

如何修复"未知模型：openrouter/auto"错误？

使用 `openrouter/openrouter/auto`，并将其列在 `agents.defaults.models` 下。OpenClaw 需要完整的 `openrouter/<作者>/<标识>` 路径，而自动路由器的作者名就是 openrouter。

我可以在 OpenClaw 中使用免费的 OpenRouter 模型吗？

可以。在引用后追加 `:free`，例如 `openrouter/meta-llama/llama-3.3-70b-instruct:free`。建议搭配一个备用模型，这样当免费通道繁忙时智能体仍能继续运行。

我需要为 OpenClaw 设置基础 URL 吗？

不需要。OpenClaw 内置的 OpenRouter 支持会自动处理路由。只需设置 API 密钥，并使用 `openrouter/<作者>/<标识>` 格式引用模型即可。

智能体教程/实践部署/工程

来源：OpenRouter：Announcements（RSS） · openrouter.ai

导出 Markdown