Skip to Content
📖 教程📱 渠道接入QQ

接入 QQ

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

一、QQ 机器人平台注册

1.1 进入 QQ 开放平台

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

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

1.2 创建机器人

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

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 配置：

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

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

3.2 重启 Gateway

openclaw gateway restart

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

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

3.3 使用 onboard 向导（可选）

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 调试技巧

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

常见问题：

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

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

Last updated on
企业微信微信