QQ 机器人官方文档

# Agent 接入

# QQ 龙虾机器人是什么

QQ 龙虾机器人（简称"龙虾Bot"），是基于 QQ 原生生态打造的一站式龙虾管理与交互入口，专为需要调用各类 Claw 服务（如 Openclaw、Hermes、Workbuddy、Qclaw 等）的使用者设计。龙虾Bot 像是一个"龙虾外壳"——它本身不自带智能交互功能，它的核心作用是能够让各种龙虾产品都能在 QQ 上"安家落户"，您可以通过 QQ 像与朋友聊天一样，随时随地给这些"龙虾Bot"发送消息，实现一站式的管理与调用。

龙虾Bot 支持文字、图片、视频、文件等多种消息类型，无论在手机端还是电脑端，都能贴合您的日常使用习惯，让 Claw 服务能轻松和 QQ 联动起来。

QQ 龙虾机器人快捷创建入口（使用浏览器或QQ打开）：快速注册创建 QQ机器人 (opens new window)

⭐划重点啦！想用 QQ 龙虾Bot，有个小前提——你得先装好任意一种 Claw 服务（比如 OpenClaw、Workbuddy 都可以），这就相当于给"龙虾外壳"装上"大脑"，不然龙虾Bot 就只是个"空壳子"。至于怎么装 Claw 服务、怎么关联龙虾Bot，还有本地部署、云部署的具体步骤，下面会讲，跟着操作就好！

# QQ 龙虾机器人的优势

  • 全民入口，毫无门槛：几乎人人都有的 QQ 账号，使用 QQ 龙虾机器人无需注册新平台，直接上手就能开启智能交互，真正做到零门槛使用。

  • 极速部署，三步搞定：接入方式极其简便，只需简单三步：扫码创建、复制龙虾key、粘贴至Claw端，即可轻松完成配置。

  • 自然交互，无需学习：沿用日常聊天的操作习惯，无需额外学习复杂操作，兼容各类常见消息，无论是日常生活、工作场景，都能全方位满足您的交互需求。

  • 全生态联动，持续迭代：龙虾Bot 深度对接 Openclaw、Workbuddy、Qclaw、腾讯云等多 Claw 生态，QQ 官方原生 OpenClaw 开源插件，功能持续优化。

# QQ 龙虾机器人适用场景

龙虾 Bot 适配生活、工作、学习等多类场景，满足多样化智能交互需求，核心应用场景包括：

  • 日常便捷交互：通过 QQ 发送指令，快速调用龙虾功能，无需切换其他应用，提升操作效率；
  • 多端协同办公：电脑端、手机端同步操作，交互记录、任务进度实时同步，适配办公室、户外、通勤等多场景办公需求；
  • 多模态信息传递：支持文字、语音、图片、视频、文件等消息上下行，轻松完成各类信息的发送与接收，适配复杂沟通场景；
  • 多场景定制适配：单个 QQ 账号可创建5只独立龙虾 Bot，分别对接不同云智工具、适配不同使用场景，按需调配更灵活。

# 快速创建一个 QQ 机器人

QQ 开放平台提供了快捷创建QQ机器人的通道，三步即可创建一个可用的QQ Bot，用于接入各类 agent 部署工具。

  1. 在浏览器或手机 QQ 中点击打开 快速注册创建 QQ机器人 (opens new window)，使用QQ登录。
  1. 点击创建机器人（点击后会立刻成功，此时 QQ机器人会给你 QQ 发送一条消息，头像昵称可按用户喜好自定义编辑）。
  1. 根据你安装 AI 产品的指引，使用手机QQ扫码或填入 QQ 机器人的 AppID 和 AppSecret，配置成功即可通过 QQ 使唤你的 AI。

图片 1-3

👉 如需体验更多的QQ Bot服务，请前往登录QQ开放平台 (opens new window)，完善主体认证信息，进入机器人管理端，管理你的 QQ Bot。

# Agent 快速接入QQ Bot指南

# Workbuddy 接入QQ Bot

解锁办公协同、任务管理、日程提醒等能力，让 QQ Bot 成为办公效率神器。

接入步骤：

  1. 安装后打开 WorkBuddy设置，点击助理设置，选择「QQ 机器人集成」配置。
  1. 连接方式：推荐使用 扫码绑定，使用手机QQ扫码二维码， 连接你的QQ Bot，确认绑定即可。
  1. 绑定成功后，即可开启对话。

# QClaw 接入QQ Bot

👉 QClaw 官方网站：QClaw - 微信远程办公 AI 助手 | 腾讯出品 (opens new window)

🦞 QClaw 接入 QQ 指南：本指南将帮助您在QQ中配置 QClaw (opens new window)

  1. 打开 QClaw，点击设置，进入远控通道。
  2. 选择 QQ，点击添加。
  3. 选择快捷绑定，通过手机QQ扫码绑定你的 QQ 机器人。

# OpenClaw 接入 QQ Bot

⚠️ OpenClaw 2026.5.2 版本起，所有插件改为动态下载方式，升级后内置版 QQ 插件需重新安装才能使用。

方式一：onboard 引导绑定

openclaw onboard
1

方式二：手动安装

openclaw plugins install @openclaw/qqbot
1

说明：使用独立版qqbot插件不受影响，低版本用户无需操作。

# OpenClaw 3.31之后的版本

方式一（适合 OpenClaw 4.26 之后的版本）：

  1. OpenClaw 配置消息通道时，选择 QQ Bot，回车。
  1. 选择扫码绑定，通过手机扫码
  1. 使用手机QQ扫描二维码，选择需要绑定的机器人：

方式二（通用）：

  1. 打开终端，在下面的命令中填入创建 QQ 机器人的 AppID 和 AppSecret【见图片1-3】，并运行完整命令：
openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"
1
  1. 重启设备上的 OpenClaw 服务：
openclaw gateway restart
1

# OpenClaw 3.31以前的版本

如果您安装的是OpenClaw 3.31以前版本，或者想体验QQ Bot插件最新功能。

  1. OpenClaw 安装成功后，打开终端，运行以下命令，一键安装/升级最新 OpenClaw QQ Bot 插件：
npx -y @tencent-connect/openclaw-qqbot-cli@latest update -y
1
  1. 使用手机QQ扫描上面的二维码，选择你创建需要绑定的QQ机器人。

# Hermes Agent 接入QQ Bot

Hermes Agent「爱马仕」自2026年发布便迅速走红🔥，它着重强调"可成长性"，不仅具备出色的记忆与回忆能力，还引入完整自我学习机制，能在使用中自主创建和优化技能，真正做到"越用越聪明"。

Hermes Agent 内置 QQ Bot 通道可直接接入QQ机器人。安装Agent、配模型、接通道，三步开启体验，可快速完成对话通道链路搭建。

👉 Hermes Agent 官 QQ Bot 配置教程：QQ Bot | Hermes Agent (opens new window)

👉 腾讯云部署 Hermes 教程：玩转Hermes Agent｜使用Lighthouse快速部署 (opens new window)

接入步骤：

  1. Hermes 安装成功后，在终端运行以下命令，打开配置 Hermes 消息通道：
hermes gateway setup
1
  1. 光标移动到对应位置，按空格选中，按回车确认到下一步
  1. 按空格选择扫码连接方式，可以选择扫描二维码或手动填写 App ID/AppSecret 两种方式
  • 第一种方式：扫描二维码，选择你的 QQ机器人 进行连接
  • 第二种方式：手动填写QQ机器人的 AppID/AppSecret
  1. 允许哪些用户使用，直接回车，下一步选择第一个允许所有用户使用
  1. 设置主通道用于接收定时任务提醒，直接回车先留空
  1. 运行以下命令，重新启动 Hermes 网关：
hermes gateway restart
1
  1. 给你的QQ机器人发送一条消息，测试是否连接成功

# LightVela 接入QQ Bot

免安装使用，云端托管 Hermes Agent

👉官方网站：LightVela 云端专属个人 Agent | LightVela (opens new window)

👉接入指南：配置通道 - QQ | LightVela (opens new window)

  1. 打开 LightVela 官网并注册登录，点击「我的智能体伙伴」。
  1. 在左侧边栏选择「通道」，选择 QQ，点击「连接」。
  1. 选择「扫码连接」，点击「确认」，屏幕中出现二维码即可扫码连接 QQ 机器人。

# 腾讯云OpenClaw 接入QQ Bot

依托腾讯云轻量应用服务器，实现机器人稳定部署、灵活扩展，保障高并发场景下的流畅运行。

👉 接入参考：玩转OpenClaw｜云上OpenClaw快速接入QQ指南 (opens new window)

# QQ官方 OpenClaw 插件介绍

QQ官方 OpenClaw插件是由QQ开放平台团队自主研发、免费维护的开源插件，专为龙虾Bot设计，用于衔接龙虾Bot与OpenClaw服务，解锁更多智能交互功能，无需用户自行开发，上手即用，是龙虾Bot核心功能的重要支撑。

原生OpenClaw QQ Bot插件仅作为消息通道，负责在 QQ 和 OpenClaw 之间传递消息。图片理解、语音转录、AI 画图等能力取决于你配置的 AI 模型以及在 OpenClaw 中安装的 skill，而非插件本身提供。

更多安装方法请参考文档：QQ 龙虾机器人使用文档 (opens new window)

QQ官方 OpenClaw 插件更新日志：插件更新日志 (opens new window)

# 第三方 Agent 接入

QQ 机器人扫码连接 SDK，在控制台展示二维码，用户使用手机 QQ 扫码后自动获取机器人的 AppID 与 AppSecret。

默认情况下扫码页面会将接入方统一显示为"第三方机器人"。如需在扫码页面展示你的平台名称，或有其他商务合作需求，请通过邮件与我们联系：qq_bot_api@tencent.com

👉 详细地址：第三方 Agent 接入 (opens new window)

系统要求：

  • Node.js >= 18.0.0

安装：

npm install @tencent-connect/qqbot-connector
1

# 快速开始

** Promise 风格 **

始终在控制台打印二维码，扫码后返回凭据：

import { qrConnect } from '@tencent-connect/qqbot-connector';

try {
  const [{ appId, appSecret }] = await qrConnect();
  console.log('绑定成功！');
  console.log('AppID:', appId);
  console.log('AppSecret:', appSecret);
} catch (err) {
  console.error('绑定失败:', err.message);
}
1
2
3
4
5
6
7
8
9
10

** 回调风格 **

通过 displayQrCodeToConsole 控制是否在控制台打印二维码，onQrDisplayed 始终会在轮询开始前回调二维码 URL：

import { startQrConnect } from '@tencent-connect/qqbot-connector';

// 不打印二维码到控制台，通过 onQrDisplayed 自行处理 URL
const stop = startQrConnect({
  onSuccess([{ appId, appSecret }]) {
    console.log('绑定成功！');
    console.log('AppID:', appId);
    console.log('AppSecret:', appSecret);
  },
  onFailure(err) {
    console.error('绑定失败:', err.message);
  },
  onQrDisplayed(url) {
    // 始终回调，可自行生成二维码图片、发送给用户等
    console.log('二维码链接:', url);
  },
  onQrExpired() {
    console.log('二维码已过期，正在刷新…');
  },
}, {
  displayQrCodeToConsole: false,
});

// 需要取消时调用 stop(" width="70%" style="display: block; margin: 0 auto;">
// stop();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# API

qrConnect(options?): Promise<QrConnectCredentials[]>

在控制台展示二维码并等待扫码，返回 Promise。

此模式下始终在控制台打印二维码（displayQrCodeToConsole 固定为 true，不可关闭）。如需自行处理二维码 URL 而不打印，请使用回调风格的 startQrConnect。

参数：

名称 类型 默认值 说明
options.source string '' 接入平台标识，留空则显示为"第三方机器人"
options.signal AbortSignal — 外部取消信号

返回值：

interface QrConnectCredentials {
  appId: string;
  appSecret: string;
}
1
2
3
4

注意： 绑定成功后返回的凭据类型是 QrConnectCredentials[] 数组。目前扫码仅支持绑定单个 QQ 机器人（数组长度为 1），未来可能会拓展支持同时绑定多个 QQ 机器人，建议业务侧提前做好对数组的遍历处理，以便后续平滑升级。

startQrConnect(callbacks, options?): () => void

轮询等待扫码结果（回调风格）。返回一个 stop 函数，调用后可中止流程。

二维码过期后会自动刷新并重新轮询，直到用户扫码成功或主动取消。

callbacks：

名称 类型 说明
onSuccess (credentials: QrConnectCredentials[]) => void 扫码成功回调
onFailure (error: Error) => void 失败或取消回调
onQrDisplayed? (url: string) => void 二维码 URL 就绪，轮询开始前始终触发
onQrExpired? () => void 二维码已过期，即将刷新（可选）

options：

名称 类型 默认值 说明
options.displayQrCodeToConsole boolean true 是否在控制台打印二维码
options.source string '' 接入平台标识，留空则显示为"第三方机器人"
options.signal AbortSignal — 外部取消信号

** 取消支持 **

两种取消方式：

// 方式一：使用返回的 stop 函数
const stop = startQrConnect({ ... });
stop();

// 方式二：使用 AbortController
const ac = new AbortController();
qrConnect({ signal: ac.signal }).catch(console.error);
ac.abort();
1
2
3
4
5
6
7
8

# 协助与反馈

如在使用过程中遇到问题，欢迎前往以下地址查阅已有议题或提交新问题：

https://github.com/tencent-connect/openclaw-qqbot/issues

# Skills 安装技巧

# 腾讯云安装 clawhub 的 Skills

在 lighthouse 实例的应用管理页面上可以直接安装 skills，如图：

点击页面上【获取更多skills】的链接跳到开源社区 ClawHub 的官网 (opens new window)，选择你需要的 skills，注意这里 skills 的名字就是点击跳转某个 skills 的页面链接 URL 最后的内容：

确定名字后直接在 lighthouse 应用管理页面上点击【安装技能】即可。

# 手动安装 clawhub 的 Skills

如果想手动安装 clawhub 上的 skills，具体步骤如下：

# 1. 安装 clawhub cli
npm i -g clawhub

# 2. 装完确定下是否可用：
clawhub --help

# 3. 进入 OpenClaw workspace
cd ~/.openclaw/workspace

# 4. 搜索 skill
clawhub search "你想要的功能关键词"

# 5. 安装 skill
clawhub install <skill-slug>

# 6. 检查是否识别到
openclaw skills list
openclaw skills check

# 7. 如需配置 API Key，则编辑配置文件
vi ~/.openclaw/openclaw.json

# 8. 重启 gateway
openclaw gateway restart

# 9. 看日志
openclaw logs --follow

# 10. 检查目前已经安装了哪些 skills
openclaw skills list --eligible
openclaw skills info <这里填 list 里显示的某个skills的名字>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

如果完成以上安装后，agent 提示仍找不到对应 skills，可以通过和 agent 对话的方式让 openclaw 分析问题并完成安装：

# 手动安装自己写的 Skills

安装自己写的 skills 最主要的就是把你的 skills 建一个文件夹放在 ~/.openclaw/workspace/skills/ 目录下。

这里提供了一个安装 my-demo-skill 的简单示例：

# 1. 创建 skills 目录，假设这里的 skills 叫 my-demo-skill
mkdir -p ~/.openclaw/workspace/skills/my-demo-skill

# 2. 写入 skills，或者把已经写好的 skills 放在对应目录下
cat > ~/.openclaw/workspace/skills/my-demo-skill/SKILL.md <<'EOF'
---
name: my_demo_skill
description: A simple custom skill for testing.
---
# My Demo Skill
当用户要求测试自定义 skill 时，优先遵循这里的说明。
触发示例：
- "调用 my demo skill"
行为：
- 回复："已命中 my_demo_skill"
EOF

# 3. 让 OpenClaw 重新发现这个 skill，可以通过对话让 agent "refresh skills"，或者直接重启 gateway
openclaw gateway restart
openclaw skills list
openclaw skills info my_demo_skill
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

通过对话验证 my-demo-skill 触发成功：

# 常用(FAQ)指引（持续更新）

# Openclaw 接入常见问题

  • Q：为什么一直输出"你好，我不能提供相关信息"

    A：模型输入输出内容被安全审查，可以通过 /new 开启新对话，或者更换模型。

  • Q：为什么设置好qq机器人信息后，与机器人对话小灰条提示"我的'灵魂'不在线"等错误

    A1：如果是第一次配置，OpenClaw 与机器人建立联系需要一定时间，可尝试重启几次 openclaw gateway。

    A2：如果原来已经有机器人，又重新更换配置了新的APPID，如果机器人无法回复：

    • 解决方式1：删除下面的文件然后重启：~/.openclaw/qqbot/sessions/session-default.json
    • 解决方式2：更新 qqbot 插件（见前文更新教程）

    A3：如果一直提示此错误，是因为机器人没有在线，检查机器人APPID和密钥配置是否正常。

  • Q：机器人已经被注销怎么办？

    A：检查是否删除了机器人，如果删除了7天内可以前往QQ开放平台 (opens new window)进行恢复。

  • Q：为什么在群里面@机器人，遇到提示："该机器人当前服务状态异常，暂时无法回复消息"？

    A：请升级最新版手机QQ，旧版本手机QQ仅支持个人用户私聊使用不支持群功能。

  • Q：创建的OpenClaw机器人是否支持加群？

    A：QQ 机器人进群能力现已全面开放，群主可直接添加所创建的 QQ 机器人加入群聊 (升级最新版QQ)，并支持相关权限设置。 接收全量消息能力：当群主设定允许该机器人接收群内全部消息时，机器人可接收到群内所有成员在群内的发言消息。 主动推送消息能力：机器人主动在群聊内发言，如定时任务推送等。 机器人撤回成员消息能力：当机器人被群主设置为群管理员时，可撤回成员发送的消息。

  • Q：快速创建的OpenClaw机器人是否支持在开放平台修改信息？

    A：可以在开放平台修改信息：

  • Q：机器人为什么回复"401 not authorized"

    A：模型配置没有成功，请注意检查下模型 api key 配置，注意并不是 qqbot api secret 哦。

  • Q：机器人为什么回复"API rate limit reached. Please try again later."

    A：模型调用频率太快了，请检查模型使用情况或更换模型。

  • Q：如何联系官方人员？

    A：可加入讨论群、讨论频道或者添加机器人进行反馈，开发社区频道见本文右侧浮动的二维码。

  • Q：如何查询日志？

    A：请登录OpenClaw运行的机器，使用终端输入 openclaw logs --follow 以显示实时日志。

  • Q：为什么OpenClaw机器人发不出图片？

    A：可以发一张图片让机器人原样回给你，验证下是通道的问题，还是模型没有画图skills工具。如果是需要画图能力，需要自己配置画图skills，一般需要自己购买生图模型获得生图的api key。

  • Q：如果我从其他渠道的qqbot插件想升级到官方插件@tencent-connect/openclaw-qqbot，应该怎么操作？

    A：升级方式参考本文里的【原生 OpenClaw 安装插件 QQBot 插件】这部分内容。

  • Q：插件支持多账号多Agent配置，可以参考以下命令配置：

# 添加账号
openclaw channels add --channel qqbot --account bota --token "appid:secret"

# 添加 Agent
openclaw agents add agentA --workspace ~/.openclaw/workspace-agentA --non-interactive

# 绑定路由
openclaw agents bind --agent agentA --bind qqbot:bota
1
2
3
4
5
6
7
8

# Hermes 接入常见问题

  • Q：配置流程没有设置到QQ Bot

    • 需要按空格选中 QQ Bot，然后按回车进入到设置页面
    • 重新运行网关配置：
hermes gateway setup
1
  • Q：提示没有主Channel
  • 解决方案：在给QQ机器人通道里，输入 sethome 设置通道

  • Q：如何查看日志

  • 使用 hermes 命令：

hermes logs --follow
1
  • 日志路径：~/.hermes/logs/agent.log
cat ~/.hermes/logs/agent.log
1
  • Q：如何停止服务
hermes gateway stop
1
  • Q：如何在前台启动
hermes gateway run --verbose
1

# 安全使用须知

💡 QQ 龙虾使用建议

建议您先用个人账号安全尝试，待后续安全隔离能力更为成熟，再考虑接入真实工作环境。若在使用过程中遭遇任何问题，或体验欠佳，请随时向我们反馈，我们始终致力于持续快速迭代优化！

为保障QQ龙虾Bot、Claw服务及用户信息的安全，避免出现安全隐患（如机器人被非法调用、信息泄露、功能异常），开发者及使用者需严格遵守以下安全使用须知，规范操作流程。

# 1、凭证安全管理

  • 核心凭证（AppID、AppSecret等）是QQ Bot与Agent服务关联的关键，请勿泄露给无关人员，包括截图、文字转发、口头等形式；
  • 定期重置核心凭证，建议每3个月重置一次Key、AppSecret，若发现凭证泄露，需立即重置，并检查机器人是否存在非法调用记录；
  • 凭证需妥善存储，建议存储在加密文档或专用密码管理工具中，避免存储在公共设备（如网吧电脑）中，防止被他人获取；
  • 关联Claw服务时，仅填写官方要求的凭证信息，切勿向第三方平台或个人提供凭证，避免被恶意利用。

# 2、功能使用安全

  • 禁止利用QQ Bot、Claw服务从事违规活动，包括但不限于发送违规信息、恶意骚扰他人、传播不良内容、非法收集用户信息等；
  • 严格控制机器人调用权限，根据场景设置合理权限（如仅自己可调用、指定好友可调用），避免开放公共调用权限，防止被恶意滥用；
  • 不安装来源不明第三方插件、SKills，建议下载官方或经过认证的插件、Skills，避免安装恶意程序；
  • 定期检查机器人交互日志，若发现异常调用（如陌生IP调用、违规指令调用），需立即禁用机器人，排查安全隐患后再重新启用；
  • 禁止修改机器人、插件、Skills核心代码，避免导致功能异常、安全漏洞，若需自定义功能，需通过官方提供自定义接口进行开发。

# 3、环境安全管理

  • 云部署端（如腾讯云Lighthouse）需定期更新系统版本、安装安全补丁，开启防火墙，禁止开放不必要的端口，防止被非法入侵；
  • 电脑端安装客户端（如Workbuddy等），需从官方渠道下载，安装前进行病毒扫描，避免安装恶意软件；
  • 保持网络环境安全，避免在公共Wi-Fi（如网吧、商场Wi-Fi）环境下配置QQ龙虾Bot、修改核心凭证，防止信息被窃取；
  • 定期备份机器人配置、交互日志、Skills配置，若出现机器人崩溃、数据丢失等情况，可快速恢复，减少损失。

# 4、应急处理规范

  • 若发现机器人被非法调用、凭证泄露，立即采取以下措施：① 重置核心凭证 ② 禁用机器人 ③ 查看交互日志，排查非法调用来源；
  • 若机器人出现功能异常、崩溃等情况，先检查网络状态、Claw服务状态、插件，若无法解决，导出交互日志，联系官方客服排查；
  • 若收到QQ开放平台安全提醒（如违规使用警告），需在规定时间内整改，整改完成后提交审核，避免机器人被封禁；
  • 若发现第三方插件、Skills存在安全隐患（如恶意收集信息、违规调用功能），立即卸载该插件、Skills，并向QQ开放平台反馈。

# 插件更新日志

最新插件更新日志：openclaw-qqbot 插件更新日志 (opens new window)

⚠️ OpenClaw 2026.5.2 版本插件加载变更说明

各位开发者，OpenClaw 2026.5.2 版本起，所有插件改为动态下载方式。升级后内置版 QQ 插件需重新安装才能使用。

安装方式（二选一）

方式一：onboard 引导绑定

openclaw onboard
1

方式二：手动安装

openclaw plugins install @openclaw/qqbot
1

说明：

  • 使用独立版qqbot插件（openclaw-qqbot）不受影响
  • 低版本用户无需操作，升级到 2026.5.2 后才需要重新安装插件

# [2.0.0] - 2026-07-13

新增

  • 模块化分层架构：代码重构为 12 个子模块（adapter / dispatch / gateway / middleware / outbound / transport 等），提升可维护性和扩展性。
  • Runtime Adapter：新增运行时适配层，支持多版本 OpenClaw SDK 自动适配，兼容低版本 OpenClaw。
  • 出站流水线：统一出站分发管道（TTS 语音 → 媒体 → 文本 debounce），新增流式控制器、回复限速、出站文本清理（剥离 thinking 标签）。
  • 中间件层：新增访问控制、附件处理、策略注入三个中间件，支持灵活编排。 新增斜杠指令：/bot-pairing（QR 码配对）。

变更

  • 构建方式改为 tsup 预编译（dist/index.cjs），提升加载速度。
  • qqbot_channel_api 工具重命名为 qqbot_platform_api。
  • 依赖升级：@tencent-connect/qqbot-connector 1.2.0，新增 @tencent-connect/qqbot-nodejs ^1.0.3。

改进

  • 启动时 runtime contract 预检，提前发现 API 缺失。
  • 统一日志体系（PluginLogger），支持前缀分级。
  • 新增 Markdown 表格分块和文本清理单元测试。

# [1.7.2] - 2026-06-05

新增

  • Webhook 传输模式：新增 HTTP 回调入站方式，与 WebSocket 并列为两种可选传输模式。支持 Ed25519 签名鉴权，多账户场景下基于签名自动路由到对应账户。
  • 群聊 @触发规则灵活配置：新增账户级 defaultRequireMention 字段，形成「具体群 > 通配符 * > 账户级 > 默认值」四级优先级链，可针对不同群设置仅@回复或自主发言。
  • /bot-group-allways 指令：运行时动态切换群响应模式（on / off），修改即时持久化到 openclaw.json，无需重启网关。

# [1.7.1] - 2026-04-10

修复

升级脚本适配OpenClaw 2026.4.9版本：

  • 修复独立版插件安装失败问题。
  • 修复独立版与融合版兼容问题。
  • 新增通道配置自动修复（additional properties 校验错误）。

⚠️ OpenClaw 2026.4.5 注意事项

OpenClaw 2026.4.5 对通道配置引入了严格的合法性校验，流式输出、群聊等独立插件扩展的新增的配置字段会被判定为非法属性，导致 gateway 无法启动。升级脚本已自动备份原配置并移除不被识别的字段以恢复启动。如需使用流式输出、群聊等独立插件专属能力，建议将 OpenClaw 降级到 2026.4.2 及以下版本。

# [1.7.1] - 2026-04-03

新增

  • 命令执行审批：AI 执行命令前通过 QQ 消息发送带按钮（✅ 允许一次 / ⭐ 始终允许 / ❌ 拒绝）的审批请求，用户点击按钮即可完成审批。
  • /bot-approve 指令：新增审批配置管理指令，支持 on（打开白名单模式审批）、off（关闭审批）、always（严格模式）、reset（恢复默认）、status（查看配置）。

# [1.7.0] - 2026-04-02

新增：

  • 消息引用优化：支持解析 QQ 消息事件中新增的引用消息字段，换设备也支持引用，使 AI 能够感知用户在回复哪条消息，从而在对话中准确理解引用上下文、实现更连贯的回复。
  • qqbot-upgrade Skill：新增插件升级引导 Skill，支持自然语言触发版本更新；优化 Skill 升级交互体验。

修复：

  • Windows 文件路径编码异常：修复 Windows 下路径编码异常导致文件无法正常发送的问题。

变更：

  • 升级脚本重构 v4：重构降级架构，兼容OpenClaw 2026.3.31版本，提升升级流程的稳定性与兼容性。

⚠️ 特别注意：OpenClaw 2026.3.31 内置插件冲突

OpenClaw 于 2026.3.31 版本起已内置 QQ Bot 插件。若直接将 OpenClaw 升级到最新版，可能与独立插件产生冲突，导致新增功能不可用。

解决方案一：使用升级脚本更新本插件到最新版（推荐）

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
1

解决方案二：通过配置禁用内置版本

openclaw config set plugins.entries.qqbot.enabled false
1

# [1.6.7] - 2026-03-30

  • 多账户提醒投递失败：修复 cron 任务 delivery 缺少 accountId，导致多账户场景下提醒消息无法通过正确的机器人账户发送。
  • 升级脚本与 /bot-upgrade 改进：完善 --version 参数解析逻辑，优化版本检查流程；升级脚本（npm/source）增强兼容性。
  • postinstall-link-sdk 脚本优化：改进安装后 SDK 链接脚本的健壮性。

升级方式：

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
1

⚠️ v1.6.6 及以下版本暂不支持通过 /bot-upgrade 执行热更新，请使用上述命令进行升级。

# [1.6.6] - 2026-03-26

新增：

  • 大文件分片上传：新增 chunked-upload.ts 模块，支持对大文件自动分片并行上传，包含分片级重试、进度回调和超时控制。同时支持 C2C 和群聊场景。
  • /bot-clear-storage 指令：新增存储清理指令，可清理插件本地缓存数据。
  • 文件下载 SSRF 防护：新增 ssrf-guard.ts 模块，下载远程文件前对 URL 做 DNS 解析并校验 IP，拒绝内网/保留网段地址，防止模型输出的恶意链接触达内网服务。

变更：

  • 下载目录按账户/对话隔离：附件下载路径从统一的 ~/.openclaw/media/qqbot/downloads/ 改为 downloads/{appId}/{peerId}/，按账户和对话隔离，避免多账户文件互相覆盖。
  • 附件下载失败提示优化：下载失败时区分"超时"和"失败"，给模型更明确的上下文提示。

# [1.6.5] - 2026-03-24

OpenClaw 3.23 兼容适配

本版本对所有升级路径进行了 3.23+ 适配：

  • CLI 命令前配置暂存/恢复：upgrade-via-npm.sh 和 upgrade-via-source.sh 在执行任何 openclaw CLI 命令前临时移除 channels.qqbot，完成后恢复。
  • 安装前预停 Gateway：upgrade-via-source.sh 在 plugins install 前先停止 gateway，防止 chokidar 在配置中间状态时触发 restart。

修复：

  • 启动问候 marker 路径：修复 marker 目录使用 $CMD 变量替代硬编码路径，支持多 CLI 环境。

变更：

  • 静默非升级启动问候：启动问候仅在 /bot-upgrade 热更新触发时发送，常规 gateway 重启不再发送，减少消息干扰。

# [1.6.4] - 2026-03-20

新增：

  • 一键热更新指令 /bot-upgrade：在私聊中直接完成版本升级，无需登录服务器。支持 --latest（升级到最新）、--version X（指定版本）、--force（强制重装）参数。升级前自动校验版本是否存在于 npm。
  • 频道 API 代理工具 qqbot_channel_api：AI 可直接调用 QQ 开放平台频道 HTTP 接口，自动 Token 鉴权，内置 SSRF 防护。
  • 凭证备份保护：新增 credential-backup.ts 模块，热更新前自动备份 appId/clientSecret 到独立文件。
  • 指令用法查询：所有斜杠指令支持 ? 后缀查看详细用法（如 /bot-upgrade ?）。

# [1.6.3] - 2026-03-18

变更：

  • 版本检查改用 HTTPS 原生请求 + 多 registry 兜底：支持 npmjs.org → npmmirror.com 自动降级，解决国内网络环境下版本检查失败的问题。
  • 升级脚本多 registry 兜底：upgrade-via-npm.sh 现在依次尝试 npmjs.org → npmmirror.com → 默认 registry。

# [1.6.2] - 2026-03-18

变更：

  • Markdown 感知文本分块：使用 SDK 内置 chunkMarkdownText 替代自定义分块函数，支持代码块自动关闭/重开、括号感知等。
  • 启用块流式（blockStreaming）：设置 blockStreaming: true，框架收集流式响应后通过 deliver 回调统一发送。
  • 降低文本分块上限：textChunkLimit 从 20000 调整为 5000，提升消息可读性。
  • 静默媒体发送错误：图片/语音/视频/文件发送失败时仅写日志，不再向用户展示错误提示。

# [1.6.0] - 2026-03-16

新增：

  • 斜杠指令体系：新增 /bot-ping、/bot-version、/bot-help、/bot-upgrade、/bot-logs 五个插件级指令。
  • 版本检查：后台定时检查 npm 最新版本，/bot-version 展示更新状态，/bot-upgrade 提供升级指引。
  • 启动问候语：区分首次安装与普通重启，发送不同问候语。
  • 日志下载：/bot-logs 打包最近 2000 行日志发送文件给用户。

变更：

  • 统一富媒体标签：将 <qqimg>、<qqvoice>、<qqfile>、<qqvideo> 统一为 <qqmedia> 标签，系统根据文件扩展名自动识别媒体类型。

# [1.5.2] - 2026-03-05

新增：

  • 语音/文件发送能力，支持 TTS 文字转语音。
  • 富媒体增强：上传缓存、视频支持、失败自动重试。
  • 默认启用 Markdown 消息格式。
  • 独立升级脚本，支持用户选择前台/后台启动。
上次更新: 7/22/2026, 5:05:49 PM
手机QQ扫码
开发者社区
加入官方频道开发者社区