接入 QQ

QQ 是腾讯旗下的国民级即时通讯工具，尤其在年轻群体和游戏社区中使用广泛。OpenClaw 提供了官方 QQ 机器人插件，通过 QQ 开放平台的官方 Bot API 接入，安全合规。

一、QQ 机器人平台注册

1.1 进入 QQ 开放平台

  1. 访问 QQ 开放平台（QQ 机器人开发者平台）
  2. 使用你的 QQ 号登录
  3. 完成开发者认证（个人或企业认证）

💡 提示： 个人开发者也可以注册，但可能有一些功能限制。企业认证的 Bot 可以获得更多权限和更高的调用配额。

1.2 创建机器人

  1. 点击 创建机器人
  2. 填写机器人信息：
  • 机器人名称
  • 机器人简介
  • 头像
  1. 选择机器人类型和使用场景
  2. 提交审核

1.3 审核与上线

  • QQ 机器人需要经过平台审核
  • 审核通过后才能正式使用
  • 在审核期间，你可以使用沙箱模式进行测试

二、获取 AppID 和 Token

审核通过后，在机器人管理页面获取凭证：

2.1 AppID

在机器人管理页面的 开发设置 中可以找到：

  • AppID：一串数字，如 102840596

2.2 Client Secret

在同一页面可以找到：

  • AppSecret / Client Secret：用于身份验证的密钥

⚠️ 安全提示： Client Secret 只会显示一次，请妥善保管。如果丢失，需要重新生成。

三、OpenClaw 配置

3.1 编辑配置文件

打开 ~/.openclaw/openclaw.json，在 channels 中添加 QQ 配置：

json

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "102840596",
      "clientSecret": "your_client_secret_here"
    }
  }
}

注意配置字段名是 qqbot（不是 qq），这是插件的标识名称。

3.2 重启 Gateway

bash

openclaw gateway restart

启动后，OpenClaw 会通过 QQ Bot API 建立连接。你可以在日志中确认连接状态：

bash

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i qqbot

3.3 使用 onboard 向导（可选）

bash

openclaw onboard

向导会检测到已安装的 QQ Bot 插件，并引导你输入 AppID 和 Client Secret。

四、群聊和私聊支持

4.1 私聊

用户可以在 QQ 中搜索你的机器人，点击即可开始私聊对话。

  • 私聊 session：agent:<agentId>:qqbot:user:<userId>
  • 私聊中的所有消息都会被 OpenClaw 处理

4.2 群聊

将机器人添加到 QQ 群后，可以在群聊中使用。

添加机器人到群聊：
  1. 在 QQ 群中，打开群设置
  2. 找到 群机器人 或 应用 功能
  3. 搜索并添加你的机器人
群聊触发规则：
  • 默认需要 @机器人 才会触发回复
  • 群聊 session：agent:<agentId>:qqbot:group:<groupId>

4.3 频道支持

QQ 还支持 QQ 频道（类似 Discord 的 Server）。如果你的机器人审核通过了频道权限，也可以在 QQ 频道中使用。

五、QQ 平台特殊限制

QQ 机器人平台有一些需要特别注意的限制，这些限制是平台层面的，OpenClaw 无法绕过：

5.1 不能发送 URL 链接

这是 QQ 机器人最大的限制之一：

⚠️ QQ 机器人不能在消息中发送 URL 链接。 包含 URL 的消息会被平台静默过滤或拒绝发送。

这意味着如果 AI 回复中包含链接（比如搜索结果的 URL），这条消息可能会发送失败或被截断。

应对方式：
  • 可以让 AI 描述内容而不附带链接
  • 使用文字描述搜索关键词，让用户自行搜索
  • 在 OpenClaw 的 agent 提示词中说明"在 QQ 平台不要发送 URL"

5.2 消息格式限制

QQ 机器人支持的消息格式比较有限：

  • ✅ 纯文本
  • ✅ 图片（有大小限制）
  • ✅ @用户
  • ✅ 表情（QQ 原生表情）
  • ❌ Markdown（不支持或支持极有限）
  • ❌ 富文本卡片（有限支持）
  • ❌ URL 链接

5.3 消息长度限制

QQ 对单条消息有长度限制。如果 AI 回复较长，OpenClaw 会自动分割为多条消息发送。

5.4 主动消息限制

QQ 机器人对主动消息（不是回复用户消息，而是主动推送）有严格限制：

  • 需要用户先发消息给机器人，才能在一定时间窗口内回复
  • 超过时间窗口的主动消息可能被拒绝
  • 这会影响 OpenClaw 的 heartbeat 和主动通知功能

5.5 调用频率限制

QQ 平台对 API 调用有频率限制，具体限额取决于机器人的认证级别和审核结果。

六、注意事项

6.1 审核要求

QQ 机器人平台的审核相对严格：

  • 需要提供机器人的功能说明和使用场景
  • 可能需要提供隐私政策和服务条款
  • 个人开发者和企业开发者的审核标准不同
  • 审核周期通常为 1-7 个工作日

6.2 沙箱模式

在正式上线前，可以使用沙箱模式进行测试：

  • 沙箱模式下只有指定的测试用户可以使用
  • 功能与正式环境一致
  • 适合开发和调试阶段

6.3 安全建议

  • Client Secret 保密：不要泄露凭证信息
  • 最小权限原则：只申请必要的权限
  • 监控使用情况：定期检查机器人的使用日志

6.4 与其他平台的对比

相比其他平台，QQ 机器人的优劣势：

优势：
  • 用户基数大，尤其是年轻群体
  • 群聊生态活跃
  • 官方支持，合规无封号风险
劣势：
  • 不能发 URL（最大痛点）
  • 消息格式限制多
  • 审核流程较慢
  • 主动消息限制严格

6.5 调试技巧

bash

# 查看日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i qqbot

# 检查 Gateway 状态
openclaw gateway status

常见问题：

  • 连接失败：检查 AppID 和 Client Secret 是否正确
  • 消息发送失败：检查消息中是否包含 URL（会被拦截）
  • 群聊无反应：确认机器人已添加到群中，且用户 @了机器人
  • 审核不通过：检查应用信息是否完善，功能描述是否清晰

💬 有问题或建议？ 欢迎在下方评论区留言讨论。