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

在服务器上，请在 env 块中设置密钥，而不是在 shell 配置文件中。以不同用户或 shell 运行的服务不会读取交互式配置文件，而 env 块会在进程启动时被注入。若要稍后更改密钥，请编辑 env.OPENROUTER_API_KEY 并使用 openclaw gateway run 重启。

然后确认你的模型已加载：

openclaw models list

使用 openrouter/<author>/<slug> 格式引用模型

OpenClaw 以 openrouter/<author>/<slug> 的形式引用 OpenRouter 模型。在作者前加上 ~ 可跟踪某个模型系列的最新版本，去掉它则可固定到某个确切版本。在确定使用某个标识符之前，请先在 模型页面上查看当前的 slug，因为随着新版本发布，标识符会发生变化。

追加一个变体后缀，即可在同一模型上改变路由。:free 会路由到一个免费端点，:nitro 会按吞吐量对提供商排序，而 :thinking 则请求扩展推理。若要在之后更改某个智能体的模型，请更新 agents.defaults.model.primary 并重启网关。

Auto Router 的引用形式为 openrouter/openrouter/auto：作者是 openrouter，模型是 auto。那个双写 openrouter 很容易写错，而它正是下方 unknown model 错误的修复方法。

当提供商掉线时，让智能体继续运行

一次失败的单次 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 就能跑得很好。

Auto Router（openrouter/openrouter/auto）由 NotDiamond 提供支持，会为每个请求挑选一个高性价比的模型，并按该模型的标准费率计费，不额外收取路由费用。对于大多是心跳检测和状态检查这类低风险工作的智能体流量来说，它是一个不错的默认选择。

当你想要显式控制时，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 万次请求免收此费。可在活动仪表盘中按模型追踪支出。

当你运行不止一个模型、希望请求能在服务中断时存活下来，或者想通过修改一个字符串来切换模型时，这个统一端点就物有所值了。

修复最常见的连接错误

“未找到提供商‘openrouter’的 API 密钥”意味着密钥没有送达 OpenClaw。运行 echo $OPENROUTER_API_KEY 来检查它，用 openclaw auth list 验证你的认证配置，或者重新运行引导命令。在 VPS 上，常见原因是该变量在你的交互式 shell 中加载了，但在服务的 shell 中没有加载，因此请在配置的 env 块中设置它。

“未知模型：openrouter/auto”意味着 Auto Router 的引用有误。使用 openrouter/openrouter/auto 并将其列在 agents.defaults.models 下。OpenClaw 期望完整的 openrouter/<author>/<slug> 路径。

“OpenRouter 无响应”意味着请求发出去了，但没有任何返回。按以下四项检查逐一排查：在 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/<author>/<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/<author>/<slug> 路径，而 Auto Router 的作者是 openrouter。

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

可以。在引用后追加 :free，例如 openrouter/meta-llama/llama-3.3-70b-instruct:free。再搭配一个备用模型，这样当免费额度被占用时，智能体仍能继续运行。

我需要为 OpenClaw 设置 base URL 吗？

不需要。OpenClaw 内置的 OpenRouter 支持会在内部处理路由。使用 openrouter/<author>/<slug> 设置 API key 和引用模型即可。