OpenClaw（原名Clawdbot）是一款开源AI助手框架，支持在用户自己的设备上运行，并通过Discord、Telegram、Slack等20多个渠道与用户交互。2026年4月，腾讯QQ正式原生接入OpenClaw，官方QQ Bot插件被合并到OpenClaw主代码仓库，支持私聊及各类多媒体消息交互。

本文将完整介绍从环境准备到QQ机器人上线的全流程，并补充官方文档中未覆盖的常见问题解决方案。

一、前置准备

在开始部署之前，需要确认以下条件：

1. OpenClaw环境。 确保已安装OpenClaw 2026.3.31或更高版本。安装方式支持macOS、Linux、Windows（推荐WSL2）：

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

如果已经安装，可通过 openclaw --version 检查版本。

2. QQ开放平台账号。 需要前往QQ开放平台（q.qq.com），使用手机QQ扫码注册/登录，并完成实名认证。

3. 可选：服务器或本地环境。 本地运行和云服务器部署均可。如果选择云服务器，腾讯轻量云和阿里云轻量应用服务器均提供OpenClaw应用镜像，可一键部署。

二、第一步：创建QQ机器人

1. 登录QQ开放平台。 访问 q.qq.com，使用手机QQ扫描二维码登录。首次使用需要完成实名认证，输入身份证、姓名和手机号，并绑定管理员QQ账号。

2. 创建机器人。 登录后，在首页点击“Create Bot”创建新的QQ机器人。如果页面显示“龙虾专用入口”，可直接点击进入。

3. 获取AppID和AppSecret。 机器人创建完成后，进入机器人设置页面，找到AppID和AppSecret。注意：AppSecret不会以明文存储，如果未保存就离开页面，必须重新生成一个新的。建议立即将这两个凭证复制到安全位置。

三、第二步：安装QQ Bot插件

在OpenClaw终端中执行插件安装命令：

openclaw plugins install @openclaw/qqbot

该插件为官方可下载插件，安装完成后需要重启Gateway使插件生效。

四、第三步：配置QQ渠道

有两种配置方式，任选其一即可。

方式一：命令行快速配置（推荐）

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

将AppID和AppSecret替换为实际值。例如：

openclaw channels add --channel qqbot --token "1234567890:abcdef1234567890"

配置完成后重启Gateway：

openclaw gateway restart

方式二：编辑配置文件

打开 ~/.openclaw/openclaw.json，添加以下配置：

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

更安全的做法是使用环境变量或文件引用，避免将密钥明文写在配置文件中。

使用环境变量：

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

配置文件中改为：

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "YOUR_APP_ID",
      "clientSecret": {
        "source": "env",
        "provider": "default",
        "id": "QQBOT_CLIENT_SECRET"
      }
    }
  }
}

使用文件引用：

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

注意：clientSecret 不接受旧版 secretref:... 标记字符串，需要使用结构化SecretRef对象。

五、第四步：验证与测试

1. 检查Gateway状态：

openclaw gateway status

2. 查看日志确认渠道连接：

openclaw logs --channel qqbot

3. 发送测试消息。 在QQ中找到你创建的机器人，发送一条私聊消息。如果配置正确，OpenClaw会返回AI助手的回复。

六、常见问题与解决方案

问题1：插件安装失败，提示“dangerous code patterns detected”

这是OpenClaw 2026.4.9版本后引入的安全检测机制导致的。解决方案：确认使用的是官方插件 @openclaw/qqbot，如果仍被拦截，可尝试更新OpenClaw到最新版本。

问题2：机器人离线，错误码4009（Session timed out）

QQ Bot WebSocket连接大约每30分钟会因会话超时断开一次。OpenClaw的入站持久性机制会保存原始事件，重连后可继续处理待处理消息，不会丢失数据。如果频繁出现此问题，检查网络稳定性，或查看是否有防火墙阻断长连接。

问题3：发送消息无响应

按以下顺序排查：

• 确认 openclaw gateway status 显示running状态；

• 检查 openclaw logs --channel qqbot 是否有认证失败（auth failed）日志；

• 确认AppID和AppSecret是否与QQ开放平台中的一致；

• 检查模型账号是否欠费或余额不足。

问题4：群聊中收不到消息

QQ官方对AIGC机器人有群聊限制，部分类型的机器人不允许被拉入群聊或提供给他人使用。需要在QQ开放平台中确认机器人类型和权限范围。

问题5：配置修改后不生效

OpenClaw支持配置热重载，Gateway会监视 ~/.openclaw/openclaw.json 文件并自动应用更改。如果未生效，执行 openclaw gateway restart 手动重启。

七、进阶配置

流式传输

QQ Bot插件支持分块流式传输，可在配置中开启：

{
  "channels": {
    "qqbot": {
      "streaming": {
        "mode": "partial",
        "nativeTransport": true
      }
    }
  }
}

• streaming.mode："partial"（默认）开启分块流式，"off" 关闭；

• streaming.nativeTransport：true 时对私信使用QQ官方C2C stream_messages API。

二维码绑定（替代手动输入密钥）

除了手动输入AppID/AppSecret，OpenClaw的配置向导还支持二维码绑定。执行 openclaw channels add 后，使用与目标QQ Bot绑定的手机QQ扫描二维码即可完成绑定，OpenClaw会将凭据保存到该账号的配置作用域中。

多账号管理

QQ Bot插件支持多账号管理。在配置文件中可添加多个账号条目，每个账号拥有独立的AppID和AppSecret。

八、附录：文件结构参考

~/.openclaw/
├── openclaw.json          # 主配置文件
├── workspace/             # Agent工作区
└── qqbot-secret.txt       # 可选的密钥文件

参考来源：

• OpenClaw官方文档 - QQ Bot渠道：https://docs2.openclaw.ai/zh-CN/channels/qqbot

• OpenClaw官方文档 - 配置指南：https://docs2.openclaw.ai/zh-CN/gateway/configuration

• OpenClaw GitHub仓库：https://github.com/openclaw/openclaw

• 腾讯云开发者社区 - OpenClaw接入QQ机器人

• 阿里云开发者社区 - OpenClaw集成QQ图文教程

• 腾讯QQ原生接入OpenClaw官方公告（2026-04-02）

免责声明：
本教程基于OpenClaw官方文档与社区公开资料整理。OpenClaw版本迭代较快，配置项和插件行为可能随版本更新而变化，请以官方最新文档为准。部署前请确保遵守QQ开放平台的相关规定。