OpenRouter.help
返回首页

openclaw-integration

阅读约 12 分钟

原文链接：https://openrouter.ai/docs/cookbook/coding-agents/openclaw-integration

OpenClaw 🦞

使用 OpenClaw（原 Moltbot，原 Clawdbot）连接 OpenRouter

什么是 OpenClaw？

OpenClaw（原 Moltbot，原 Clawdbot）是一个开源 AI 代理平台，将对话式 AI 引入多个消息渠道，包括 Telegram、Discord、Slack、Signal、iMessage 和 WhatsApp。它支持多种 LLM 提供商，允许您运行可以在所有这些平台上交互的 AI 代理。

设置

推荐方式：使用 OpenClaw 设置向导

使用内置设置向导配置 OpenClaw 与 OpenRouter 连接的最简单方式：

openclaw onboard

向导将指导您完成：

  • 选择 OpenRouter 作为您的提供商
  • 输入您的 API 密钥
  • 选择您喜欢的模型
  • 配置消息渠道

这是新用户的推荐方法，可确保所有配置都正确。

快速开始（CLI）

如果您已有 OpenRouter API 密钥并想跳过向导，请使用以下单行命令：

openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

这会自动配置 OpenClaw 使用 OpenRouter 和推荐的模型（openrouter/auto）。

手动配置

仅限高级用户：以下手动配置适用于需要直接编辑配置文件的大多数用户。对于大多数用户，我们建议使用上面的设置向导。

如果您需要手动编辑 OpenClaw 配置文件，请按照以下步骤操作：

步骤 1：获取您的 OpenRouter API 密钥

  1. 在 OpenRouter 注册或登录
  2. 导航到您的 API Keys 页面
  3. 创建一个新的 API 密钥
  4. 复制您的密钥（以 sk-or-... 开头）

步骤 2：设置您的 API 密钥

将您的 OpenRouter API 密钥添加到您的 ~/.openclaw/openclaw.json：

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.5"
      },
      "models": {
        "openrouter/anthropic/claude-sonnet-4.5": {}
      }
    }
  }
}

或将 API 密钥设置为 shell profile 中的环境变量：

export OPENROUTER_API_KEY="sk-or-..."

就是这样！OpenClaw 内置支持 OpenRouter。您无需配置 models.providers —— 只需设置您的 API 密钥并使用 openrouter/<author>/<slug> 格式引用模型。

步骤 3：选择您的模型

更新 primary 模型并将其添加到 models 列表。以下是一些流行选项：

Anthropic Claude：

"model": {
  "primary": "openrouter/anthropic/claude-sonnet-4.5"
},
"models": {
  "openrouter/anthropic/claude-sonnet-4.5": {}
}

Google Gemini：

"model": {
  "primary": "openrouter/google/gemini-pro-1.5"
},
"models": {
  "openrouter/google/gemini-pro-1.5": {}
}

DeepSeek：

"model": {
  "primary": "openrouter/deepseek/deepseek-chat"
},
"models": {
  "openrouter/deepseek/deepseek-chat": {}
}

Moonshot Kimi：

"model": {
  "primary": "openrouter/moonshotai/kimi-k2.5"
},
"models": {
  "openrouter/moonshotai/kimi-k2.5": {}
}

在 openrouter.ai/models 浏览所有可用模型。

步骤 4：启动 OpenClaw

更新配置后，启动或重启 OpenClaw：

openclaw gateway run

您的代理现在将使用 OpenRouter 路由请求到您选择的模型。

模型格式

OpenClaw 对 OpenRouter 模型使用格式 openrouter/<author>/<slug>。例如：

openrouter/anthropic/claude-sonnet-4.5
openrouter/google/gemini-pro-1.5
openrouter/moonshotai/kimi-k2.5
openrouter/openrouter/auto (自动路由器，根据您的提示选择最具成本效益的模型)

您可以在 OpenRouter models page 找到每个模型的确切格式。

使用后备的多模型

OpenClaw 支持模型后备。如果主要模型不可用，它会按顺序尝试备用模型：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.5",
        "fallbacks": [
          "openrouter/anthropic/claude-haiku-3.5"
        ]
      },
      "models": {
        "openrouter/anthropic/claude-sonnet-4.5": {},
        "openrouter/anthropic/claude-haiku-3.5": {}
      }
    }
  }
}

这在 OpenRouter 提供商级别故障转移的基础上提供了一层额外的可靠性。

使用 Auto Model 进行成本优化

OpenClaw 代理执行多种不同类型的操作，从简单的 heartbeat 处理到复杂的推理任务。为每个操作使用强大的模型会浪费不需要高级能力的任务的资金。

OpenRouter Auto Model（openrouter/openrouter/auto）根据您的提示自动选择最具成本效益的模型。这非常适合 OpenClaw，因为它将简单任务（如 heartbeat 和状态检查）路由到更便宜的模型，而仅在复杂交互需要时才使用更有能力的模型。

将 Auto Model 配置为您的 primary 模型：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/openrouter/auto"
      },
      "models": {
        "openrouter/openrouter/auto": {}
      }
    }
  }
}

您还可以将 Auto Model 与后备结合以获得最大可靠性：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/openrouter/auto",
        "fallbacks": [
          "openrouter/anthropic/claude-haiku-3.5"
        ]
      },
      "models": {
        "openrouter/openrouter/auto": {},
        "openrouter/anthropic/claude-haiku-3.5": {}
      }
    }
  }
}

在 openrouter.ai/models/openrouter/auto 了解更多关于 Auto Model 的工作原理。

使用 Auth Profiles

为了更安全的凭证管理，您可以使用 OpenClaw 的 auth profiles 而不是环境变量。当您使用 openclaw onboard 命令时，这会自动配置。

要手动创建 auth profile，请将此添加到您的 openclaw.json：

{
  "auth": {
    "profiles": {
      "openrouter:default": {
        "provider": "openrouter",
        "mode": "api_key"
      }
    }
  }
}

然后使用 OpenClaw CLI 在您的系统密钥链中设置密钥：

openclaw auth set openrouter:default --key "$OPENROUTER_API_KEY"

这会将您的 API 密钥从配置文件中移出，并安全地存储在系统密钥链中。

监控使用情况

实时跟踪您的 OpenClaw 使用情况：

  • 访问 OpenRouter Activity Dashboard
  • 查看跨所有 OpenClaw 代理的请求、成本和 Token 使用情况
  • 按模型、时间范围或其他条件过滤
  • 导出使用数据以进行计费或分析

常见错误

"No API key found for provider 'openrouter'"

OpenClaw 找不到您的 OpenRouter API 密钥。

修复方法：

  • 确保设置了 OPENROUTER_API_KEY 环境变量：echo $OPENROUTER_API_KEY
  • 或验证您的 auth profile 存在：openclaw auth list
  • 运行 onboard 命令：openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

认证错误 (401/403)

如果您看到认证错误：

修复方法：

  • 在 openrouter.ai/keys 验证您的 API 密钥是否有效
  • 检查您的账户是否有足够的信用额度
  • 确保您的密钥未被过期或撤销

模型不工作

如果特定模型不工作：

修复方法：

  • 在 OpenRouter models page 验证模型 ID 是否正确
  • 使用格式 openrouter/<author>/<slug>（例如 openrouter/anthropic/claude-sonnet-4.5）
  • 将模型添加到配置中的 agents.defaults.models

高级配置

每个渠道的模型

为不同的消息渠道配置不同的模型：

{
  "telegram": {
    "agents": {
      "defaults": {
        "model": {
          "primary": "openrouter/anthropic/claude-haiku-3.5"
        }
      }
    }
  },
  "discord": {
    "agents": {
      "defaults": {
        "model": {
          "primary": "openrouter/anthropic/claude-sonnet-4.5"
        }
      }
    }
  }
}
© 2026 OpenRouter.help
查看官方英文原件