OpenClaw 如何接入 OpenRouter：一条命令连接 300+ 模型

OpenClaw 可在一个地方跨 Telegram、Discord、Slack、Signal、iMessage 和 WhatsApp 运行 AI 代理。它是开源的，并且需要背后有一个模型提供商。直接将它指向一个提供商，你就拥有了这段关系：一个密钥、一份账单，以及一个在该提供商出问题的那一刻就会停止的代理。

OpenClaw 自带内置的 OpenRouter 支持，因此一个密钥即可访问 70+ 个提供商的 300+ 个模型，账单集中在一处，请求会自动故障转移到另一个提供商。连接只需一条命令。如果你还运行终端编码代理，同一个密钥也能覆盖它，请参阅如何将 OpenRouter 与任何编码代理配合使用。本指南涵盖该设置，然后是模型格式、故障转移、成本控制，以及最常出现的错误。

用一条命令将 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 模型引用为 openrouter/<author>/<slug>。在作者前加上 ~ 以跟踪某个系列的最新版本，或去掉它以固定到确切版本。在确定使用某个模型之前，请在模型页面上查看当前 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）由市场智慧驱动，会对每个提示词进行分类，并根据 OpenRouter 社区在过去 7 天窗口内对该任务类型的总支出对候选模型进行排名。它会为每个请求选择一个高性价比的模型，并按该模型的标准费率收费，不额外收取路由费。对于大多是低风险工作（如心跳和状态检查）的代理流量来说，这是一个不错的默认选择。

当你想要明确控制时，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 费用 为等效 OpenRouter 成本的 5%，并享有取决于套餐的免费额度；当前详情请参阅 定价页面。在 活动仪表盘 上按模型跟踪支出。

一旦你运行多个模型、希望请求在故障期间仍能存活，或希望通过编辑一个字符串来切换模型，统一端点就物有所值了。

修复最常见的连接错误

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

“unknown model: openrouter/auto” 意味着 Auto Router 引用有误。使用 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/<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 设置基础 URL 吗？

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