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>` 格式引用模型即可。