OpenClaw 接入 QQ 集成指南

本教程将指导您完成 OpenClaw 与 QQ 的集成配置，使您能够在 QQ 群中使用 OpenClaw 机器人功能。

前置条件

在开始集成之前，请确保满足以下条件：

  • OpenClaw 已安装并运行: 请先完成 Windows 或 Mac 平台的安装教程
  • QQ 账号: 需要一个 QQ 账号用于注册开放平台
  • QQ 开放平台账号: 需要在 QQ 开放平台完成开发者认证
  • 网络环境: OpenClaw 服务需要能访问 QQ 开放平台的 API
  • OpenClaw 版本: v1.0.0 或更高版本

QQ 平台配置

步骤 1: 注册 QQ 开放平台

  1. 访问 QQ 开放平台
  2. 使用 QQ 账号登录
  3. 完成开发者认证（需要实名认证）
  4. 等待审核通过（通常 1-3 个工作日）

步骤 2: 创建机器人应用

  1. 在开放平台控制台，点击 创建应用
  2. 选择 QQ 群机器人 类型
  3. 填写应用信息：
    • 应用名称: OpenClaw 助手
    • 应用描述: OpenClaw 智能助手机器人
    • 应用图标: 上传 OpenClaw 图标
  4. 提交创建申请

步骤 3: 配置权限

在应用管理页面，进入 权限管理，开启以下权限：

  • 群聊消息收发 - 在群聊中接收和发送消息
  • 群成员信息 - 获取群成员基本信息
  • @机器人消息 - 接收群内 @机器人 的消息
  • 主动消息 - 允许机器人主动发送消息

步骤 4: 获取凭证

在 开发设置 页面，记录以下信息：

  • AppID: 应用唯一标识
  • AppSecret: 应用密钥
  • Token: 用于验证消息来源
text
# 示例（请替换为您的实际凭证）
AppID: 123456789
AppSecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Token: your_verification_token

OpenClaw 配置

步骤 5: 配置集成参数

使用 openclaw config 命令配置 QQ 凭证：

bash
openclaw config set channels.qq.appId "123456789"
openclaw config set channels.qq.token "your_verification_token"
openclaw config set channels.qq.enable true

也可以直接编辑 ~/.openclaw/config.yaml：

yaml
channels:
  qq:
    enable: true
    appId: "123456789"
    token: "your_verification_token"
    sandbox: true  # 开发测试用，上线后改为 false

参数说明:

  • sandbox: 设为 true 表示沙箱环境（开发测试用），上线后改为 false

步骤 6: 安装 QQ 适配插件

OpenClaw 2026 版内置 QQ 插件支持，也可以手动安装：

bash
openclaw plugins install qq-adapter

集成步骤

步骤 7: 配置 WebSocket 连接

QQ 机器人使用 WebSocket 协议与 QQ 服务器通信。OpenClaw 会自动管理 WebSocket 连接，您只需确保网络畅通。

如果您的服务器在防火墙后面，需要允许出站 WebSocket 连接：

bash
# 确保可以访问 QQ 开放平台 API
curl -I https://api.sgroup.qq.com

步骤 8: 验证连接

重启 OpenClaw 服务，观察日志中的连接状态：

bash
# 重启服务
openclaw restart

# 查看连接日志
openclaw logs | grep qq

如果连接成功，日志中会显示：

text
[QQ] WebSocket connected successfully
[QQ] Bot is ready: OpenClaw助手#1234

步骤 9: 发布上线

  1. 在 QQ 开放平台提交应用审核
  2. 填写应用功能说明和使用场景
  3. 等待审核通过（通常 3-5 个工作日）
  4. 审核通过后，将配置中的 sandbox 改为 false：openclaw config set channels.qq.sandbox false
  5. 重启 OpenClaw 服务

步骤 10: 添加到群聊

  1. 打开 QQ 客户端
  2. 进入目标群聊
  3. 点击群设置 → 群机器人 → 添加机器人
  4. 搜索 "OpenClaw 助手" 并添加
  5. 确认机器人权限

集成验证

完成所有配置后，按以下步骤验证集成是否成功：

  1. 在 QQ 群聊中 @OpenClaw助手，发送测试消息：
text
@OpenClaw助手 你好
  1. 如果集成成功，机器人会回复确认消息
  2. 查看集成状态：
bash
openclaw status

常见问题

问题 1: WebSocket 连接失败

症状: 日志中显示 WebSocket connection failed 或超时。

解决方案:

  1. 检查 AppID 和 AppSecret 是否正确
  2. 确认网络可以访问 QQ 开放平台 API：
bash
curl -I https://api.sgroup.qq.com
  1. 检查防火墙是否阻止了 WebSocket 出站连接

问题 2: 机器人不响应群消息

症状: 在群聊中 @机器人 后没有回复。

解决方案:

  1. 确认 QQ_BOT_INTENTS 包含 GROUP_AT_MESSAGE_CREATE
  2. 确认机器人已被添加到群聊中
  3. 检查沙箱模式设置是否正确
  4. 查看日志确认是否收到消息事件：
bash
openclaw logs --level debug | grep qq

问题 3: 沙箱环境与正式环境区别

症状: 沙箱环境正常但正式环境不工作。

解决方案:

  1. 确认应用已通过审核并上线
  2. 将 QQ_BOT_SANDBOX 设为 false
  3. 重启 OpenClaw 服务
  4. 沙箱环境和正式环境使用不同的 API 地址，切换后需要重新连接

问题 4: 消息发送频率限制

症状: 部分消息发送失败，日志显示 rate limit exceeded。

解决方案:

  1. QQ 开放平台对消息发送有频率限制
  2. OpenClaw 内置了消息队列和重试机制，通常会自动处理
  3. 如果频繁触发限制，可以在配置中调整发送间隔：
bash
openclaw config set channels.qq.messageInterval 1500