连接 QQ

OpenClaw 通过 QQ Bot Channel 连接 QQ 官方机器人 API，支持 C2C 私聊、群 @ 消息、频道消息和部分富媒体能力。QQ 接入比 Telegram 更复杂，建议先完成模型配置和 Gateway 验证后再连接。

注意通道名

Channel 名称写 qqbot，不要写成 qq。

前置条件

• 已完成 OpenClaw Gateway 初始化
• 已有 QQ 开放平台账号
• 已创建 QQ Bot
• 已获取 AppID 和 AppSecret

是否需要安装插件

当前 OpenClaw 版本通常已经内置 QQ Bot，不需要先运行插件安装命令。

如果你使用的是较旧版本或自定义打包版本，openclaw channels status --probe 显示缺少 QQ Bot 能力时，再考虑安装：

openclaw plugins install @openclaw/qqbot

安装后重启 Gateway：

openclaw gateway restart

1. 创建 QQ Bot

1. 进入 QQ 开放平台。
2. 使用手机 QQ 扫码登录。
3. 创建新的 Bot。
4. 在 Bot 设置页复制 AppID 和 AppSecret。

AppSecret 离开页面后可能无法再次明文查看，请及时保存到安全位置。

2. 添加 QQ Channel

使用 AppID 和 AppSecret 添加 QQ Bot：

openclaw channels add --channel qqbot --token "AppID:AppSecret"

示例：

openclaw channels add --channel qqbot --token "123456789:YOUR_APP_SECRET"

也可以使用交互式向导：

openclaw channels add

在向导中选择 QQ Bot。

添加后重启 Gateway：

openclaw gateway restart

检查状态和日志：

openclaw channels status --probe
openclaw channels logs --channel qqbot
openclaw logs --follow

3. 配置文件示例

最小配置：

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET"
    }
  }
}

多账号示例：

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "111111111",
      clientSecret: "secret-of-bot-1",
      accounts: {
        bot2: {
          enabled: true,
          appId: "222222222",
          clientSecret: "secret-of-bot-2"
        }
      }
    }
  }
}

添加第二个账号：

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

4. 密钥保存方式

也可以使用环境变量：

export QQBOT_APP_ID="YOUR_APP_ID"
export QQBOT_CLIENT_SECRET="YOUR_APP_SECRET"

Windows PowerShell：

$env:QQBOT_APP_ID="YOUR_APP_ID"
$env:QQBOT_CLIENT_SECRET="YOUR_APP_SECRET"

如果不希望把 AppSecret 写进配置文件，可以使用文件：

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "/path/to/qqbot-secret.txt"
    }
  }
}

注意：--token-file 只提供 AppSecret，AppID 仍需要写在配置文件或 QQBOT_APP_ID 环境变量里。

5. 群聊配置

QQ Bot 群聊使用 group openid，不是群显示名称。建议默认要求 @ 机器人再回复：

{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groups: {
        "*": {
          requireMention: true,
          historyLimit: 50,
          toolPolicy: "restricted"
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          historyLimit: 20,
          prompt: "Keep answers brief and use an operations-oriented style."
        }
      }
    }
  }
}

6. 目标格式

常见发送目标：

格式	说明
qqbot:c2c:OPENID	C2C 私聊
qqbot:group:GROUP_OPENID	QQ 群
qqbot:channel:CHANNEL_ID	频道

同一个 OpenID 只属于对应 Bot 账号，不同 Bot 之间不能混用。

7. QR 码向导

部分版本支持 QQ Bot QR 码绑定流程：

openclaw channels add --channel qqbot

如果向导出现 QR 码选项，可以用绑定目标 QQ Bot 的手机 QQ 扫码确认。OpenClaw 会把返回的凭据保存到对应账号作用域。

常见问题

添加 channel 后不生效

按顺序检查：

openclaw gateway status
openclaw channels status --probe
openclaw channels logs --channel qqbot
openclaw logs --follow

常见原因：

• qqbot 通道名写错
• AppID 和 AppSecret 不匹配
• Gateway 没有重启
• QQ 开放平台里的 Bot 没有启用
• 使用 --token-file 但没有配置 AppID

提示缺少 QQ Bot 能力

当前版本通常内置 QQ Bot。若自定义安装确实缺少该能力，再安装插件：

openclaw plugins install @openclaw/qqbot
openclaw gateway restart

群消息不回复

常见原因：

• 群里没有 @ 机器人
• group openid 配置错误
• groupPolicy 没有放行对应群
• Bot 没有加入群
• QQ 平台侧没有启用对应能力

AppSecret 不想明文保存

优先使用 clientSecretFile 或 SecretRef 形式保存密钥，避免明文写入公开配置文件。

参考链接

• OpenClaw QQ Bot Channel