# 产品简介

# QQ 龙虾机器人是什么

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

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

QQ 龙虾机器人快捷创建入口（使用浏览器或QQ打开）：https://q.qq.com/qqbot/openclaw/login.html

⭐划重点啦！想用 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 部署工具。

在浏览器或手机 QQ 中点击打开快速注册创建 QQ机器人 (opens new window)，使用QQ登录。

点击创建机器人（点击后会立刻成功，此时 QQ机器人会给你 QQ 发送一条消息，头像昵称可按用户喜好自定义编辑）。

根据你安装 AI 产品的指引，使用手机QQ扫码或填入 QQ 机器人的 AppID 和 AppSecret，配置成功即可通过 QQ 使唤你的 AI。

图片 1-3

# 快速接入QQ Bot 指南

# 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 之后的版本）：

OpenClaw 配置消息通道时，选择 QQ Bot，回车。

选择扫码绑定，通过手机扫码

使用手机QQ扫描二维码，选择需要绑定的机器人：

方式二（通用）：

打开终端，在下面的命令中填入创建 QQ 机器人的 AppID 和 AppSecret【见图片1-3】，并运行完整命令：

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

重启设备上的 OpenClaw 服务：

openclaw gateway restart

# 👉 如果您安装的是 OpenClaw 3.31 以前的版本 / 想体验QQ Bot插件最新功能

OpenClaw 安装成功后，打开终端，运行以下命令，一键安装/升级最新 OpenClaw QQ Bot 插件：

npx -y @tencent-connect/openclaw-qqbot-cli@latest update -y

使用手机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)

接入步骤：

Hermes 安装成功后，在终端运行以下命令，打开配置 Hermes 消息通道：

hermes gateway setup

光标移动到对应位置，按空格选中，按回车确认到下一步

按空格选择扫码连接方式，可以选择扫描二维码或手动填写 App ID/AppSecret 两种方式

第一种方式：扫描二维码，选择你的 QQ机器人进行连接

第二种方式：手动填写QQ机器人的 AppID/AppSecret

允许哪些用户使用，直接回车，下一步选择第一个允许所有用户使用

设置主通道用于接收定时任务提醒，直接回车先留空

运行以下命令，重新启动 Hermes 网关：

hermes gateway restart

给你的QQ机器人发送一条消息，测试是否连接成功

# 腾讯云 OpenClaw 接入QQ Bot

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

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

# QClaw 接入QQ Bot

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

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

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

# Workbuddy 接入QQ Bot

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

👉 Workbuddy 官方网站：WorkBuddy - AI Agent 办公新范式 (opens new window)
👉 WorkBuddy 接入 QQ 指南：WorkBuddy 接入 QQ 指南 | 腾讯云代码助手 CodeBuddy (opens new window)

接入步骤：

打开 WorkBuddy，进入 Claw 设置。
选择 QQ 集成。
填入你创建QQ机器人的 AppID 和 AppSecret。【见图片1-3】
确认绑定即可。

# 从零开始接入 QQ 龙虾机器人

# 安装 Hermes 连接QQ龙虾

执行以下安装命令，支持平台：Linux / macOS / WSL2

原生Windows平台暂不支持，Windows系统需要先安装 WSL2 (opens new window) 使用Hermes-Agent。

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后，会自动运行配置流程。

配置Hermes-Agent

首先会询问是否需要导入OpenClaw配置，可以选择 n，不导入

选择 Quick Setup 快速接入

配置模型

可以选择上边的 Provider，按照指引配置模型
或者选择 Custom endpoint，下一步填入模型的 API URL 和 API Key

配置通道

光标移动到对应位置，按空格选中，按回车确认到下一步

选择扫码连接 QQBot

扫描二维码，选择机器人进行连接

允许哪些用户使用，直接回车，下一步选择第一个允许所有用户使用

设置主通道用于接收定时任务提醒，直接回车先留空

网关启动配置

是否安装后台自启动服务，选择：Y

选择启动方式，有root权限建议选择 System service，否则使用 User Service

是否启动服务，选择：y

是否启动 Hermes Chat，可以选择：n

新开一个终端窗口后，重新运行初始化流程：

hermes setup

Hermes 的Web UI 界面

输入指令后打开网页：

hermes dashboard

与 Hermes-Agent QQ机器人聊天：

# 首次安装 OpenClaw 连接QQ龙虾

❗ 如果你还没有安装任何版本的OpenClaw，可以根据OpenClaw官方指南 (opens new window)的方法安装OpenClaw。

⭐ 从OpenClaw 3.31 版开始，已内置整合QQ Bot插件，无需单独安装插件，装完 OpenClaw 直接就能连 QQ 机器人，一步到位。

💡 如想体验插件最新版本功能，可以在安装openclaw后，参考方法后面的方法安装最新QQ官方插件。

# 第一步：安装原生 OpenClaw

执行以下安装命令，安装最新版OpenClaw：

Linux/MacOS：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows：

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

根据提示信息完成 OpenClaw 配置。

以腾讯云 Token Plan 套餐进行对接为例，配置方式参考知识引擎原子能力 OpenClaw_腾讯云 (opens new window)，安装成功后，可以打开 OpenClaw Dashboard URL，正常显示管理后台则代表安装成功。

重启 Gateway 即可生效：

openclaw gateway restart

# 第二步：连接QQ机器人通道

如果您安装的是 OpenClaw 最新版本，在配置消息通道时可选择 QQ Bot，支持手机QQ扫码直接绑定机器人，或在 Openclaw 最新版安装成功后，通过以下命令添加QQ机器人（你的龙虾机器人AppID和AppSecret）：

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

重启 Gateway 即可生效：

openclaw gateway restart

（可参考 OpenClaw 官方 - QQ Bot (opens new window)）

# 其他配置

** 多账号（多机器人）配置 **

单实例 OpenClaw 可同时跑多个 QQ 机器人，互不干扰：

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "机器人1ID",
      "clientSecret": "机器人1密钥",
      "accounts": {
        "bot2": {
          "enabled": true,
          "appId": "机器人2ID",
          "clientSecret": "机器人2密钥"
        }
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

命令行添加第二个机器人：

openclaw channels add --channel qqbot --account bot2 --token "机器人2ID:密钥"

** 语音配置（STT）**

支持通道独立配置，不设置则自动继承全局默认配置：

{
  "channels": {
    "qqbot": {
      "stt": {
        "provider": "厂商",
        "model": "模型名"
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10

消息目标格式：

私聊：qqbot:c2c:OPENID
群聊：qqbot:group:GROUP_OPENID
频道：qqbot:channel:CHANNEL_ID

注意：不同机器人的 OpenID 不互通，A 机器人收到的 ID 不能用于 B 机器人发消息

内置快捷指令（在 QQ 里直接发送）：

/bot-ping：测试延迟
/bot-version：查看版本
/bot-help：查看指令列表
/bot-upgrade：升级指引
/bot-logs：导出日志文件

指令后加 ? 可查看帮助，例如：/bot-upgrade ?

常见问题排查：

机器人回复"去火星了"→ 凭证未配置或 Gateway 未启动
收不到消息 → 检查 AppID / AppSecret 是否正确，机器人在开放平台已启用
使用 --token-file 仍提示未配置 → 该参数仅设置密钥，仍需在配置或环境变量中填写 appId
主动发消息收不到 → QQ 限制：用户近期未互动，会被拦截
语音不识别 → 检查 STT 配置、厂商网络是否连通

# QQ官方 Openclaw 插件介绍

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

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

# 安装最新OpenClaw QQ Bot插件

💡 如果您安装的原生OpenClaw是3.31以前的版本，或者想体验插件最新功能，需要单独安装/升级QQ插件。如果您还未安装任何版本OpenClaw，可以参考上面方法先安装OpenClaw。

🎈 为了能给您带来更好的体验，产品研发团队火力全开，日夜优化，虾插件每日都在蜕变，稳定性逐步提升，部署流程愈发简易，功能也日益强大。QQ龙虾插件正处于快速迭代进程中，使用时还请您谨慎操作，若您想时刻掌握最新动态，记得收藏文档。

# 安装方式一：使用 npx 通用命令 + 扫码绑定

npx 命令安装最新版插件：

# 安装插件
npx -y @tencent-connect/openclaw-qqbot-cli@latest

# 一键安装/升级插件到最新版本
npx -y @tencent-connect/openclaw-qqbot-cli@latest update -y

# 一键卸载插件
npx -y @tencent-connect/openclaw-qqbot-cli@latest uninstall -y

1
2
3
4
5
6
7
8

使用手机QQ扫描上面的二维码，选择需要绑定的机器人：

更多使用帮助：

# 执行 help 查询帮助
npx -y @tencent-connect/openclaw-qqbot-cli@latest

1
2

# 安装方式二：npm 通用命令手动安装升级

# （首次安装可跳过）卸载旧插件
openclaw plugins uninstall qqbot
openclaw plugins uninstall openclaw-qqbot

# 安装 openclaw-qqbot 最新版本
openclaw plugins install @tencent-connect/openclaw-qqbot@latest

# 配置通道（首次安装必做）
openclaw channels add --channel qqbot --token "AppID:AppSecret"

# 启动 / 重启服务
openclaw gateway restart

1
2
3
4
5
6
7
8
9
10
11
12

已安装官方 openclaw-qqbot，升级版本命令：

# 通过 npm 包升级
openclaw plugins update openclaw-qqbot

# 启动 / 重启服务
openclaw gateway restart

1
2
3
4
5

# 安装方式三：MacOS/Linux 远程一键安装升级（推荐快速安装）

适合希望快速完成安装或升级的场景，无需手动 clone 仓库。

首次安装时，需提供 QQBot 通道凭证：

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET

1
2

该命令会自动完成以下步骤：

下载安装脚本
清理旧插件
安装新插件
配置 QQ Bot 通道
启动或重启 OpenClaw 服务

完成后即可打开 QQ 开始使用。

如果此前已经完成过通道配置，后续升级可直接执行：

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

如果想安装指定版本，后面可以跟 --version 命令：

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash -s -- --version 1.5.7 --appid YOUR_APPID --secret YOUR_SECRET

常用参数如下：

参数	说明
`--appid <id> --secret <secret>`	配置通道（首次安装必填，或更换凭证时使用）
`--version <版本号>`	安装指定版本（仅 npm 脚本）
`--self-version`	升级到当前仓库 package.json 里声明的版本
`-h / --help`	查看完整用法

# 安装方式四：MacOS/Linux 源码安装升级（适合先查看脚本再执行）

适合希望先查看仓库内容、在本地执行脚本，或希望更灵活控制安装流程的场景。

先拉取仓库：

git clone https://github.com/tencent-connect/openclaw-qqbot.git
cd openclaw-qqbot

1
2

通过本地脚本进行源码安装或升级：

bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET

说明：脚本执行到后面会让选择"是否后台重启 openclaw 网关服务？[Y/n]"，一般选择"Y"。如果后台启动正常，会执行 openclaw logs --follow 持续输出运行日志。看到有日志持续输出代表已经正常启动了，可以 Ctrl+C 关掉前台日志。

正常执行脚本到最后会输出log：

# 单独配置语音消息能力

语音消息（STT）需要单独配置模型能力，用于语音转文字后交给文本大模型处理。配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。

STT 支持两级配置，按优先级查找：channels.qqbot.stt（插件专属）→ tools.media.audio.models[0]（框架级回退）。以框架级配置为例：

{
  "tools": {
    "media": {
      "audio": {
        "models": [
          { "provider": "xxx", "model": "模型名称" }
        ]
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11

provider 引用 models.providers 中的 key，自动继承 baseUrl 和 apiKey，支持任何 OpenAI 兼容的 STT 接口。

另外，插件版本1.5.6已经支持当 STT 未配置或转写失败时，使用 QQ 平台内置 ASR 文本作为低置信度兜底结果。

** 发送语音（TTS）**

语音（TTS）需要单独配置模型能力，把文字转成语音通过QQ发给你。TTS 同样支持两级配置：channels.qqbot.tts（插件专属）→ messages.tts（框架级回退）。以插件专属配置为例：

{
  "channels": {
    "qqbot": {
      "tts": {
        "provider": "xxx",
        "model": "模型名称",
        "voice": "模型名称:音色名称"
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11

provider 引用 models.providers 中的 key，自动继承 baseUrl 和 apiKey。可通过 voice 选择音色，设置 enabled: false 可禁用。

# 插件安装结果检查

1. QQ Bot 插件是否正常加载：

openclaw plugins list | grep openclaw-qqbot

如果输出中存在对应插件条目，且状态为 loaded，说明 QQ Bot 插件已经安装好了，而且已经被 OpenClaw 成功加载。但并不能说明通道一定连上了。

2. QQ Bot通道是否正常连通：

openclaw channels status

openclaw channels status 中 QQ Bot 通道显示为 enabled, configured, running，且机器人实际可以正常收发消息或 in/out 时间持续更新时，可认为QQ Bot 通道已正常连通。

这里的 in:2m ago, out:2m ago 说明：

in:2m ago：2 分钟前还有入站消息
out:2m ago：2 分钟前还有出站消息

3. 发送图片或文件验证：

可以用以下方式验证 qqbot 通道发送图片或文件能力是否正常：发给模型一张图片，让模型把这张图回给你，如果能正常回复说明通道能力正常。

注意，生成图片或者对文件进行理解这些都是openclaw自己的能力，需要配置对应的模型或者skills，QQ Bot 插件只负责传输。

# 插件更新日志

最新插件更新日志：https://github.com/tencent-connect/openclaw-qqbot

⚠️ 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 后才需要重新安装插件

# [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

⚠️ 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 消息格式。
独立升级脚本，支持用户选择前台/后台启动。

# 第三方 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

# 快速开始

** 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：因为openclaw机器人暂不支持加群，仅支持个人用户私聊使用。

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

A：目前openclaw机器人不支持加群。如果有下一步支持计划，会及时更新文档通知大家。
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

Q：提示没有主Channel

解决方案：在给QQ机器人通道里，输入 sethome 设置通道

Q：如何查看日志
使用 hermes 命令：

hermes logs --follow

日志路径：~/.hermes/logs/agent.log

cat ~/.hermes/logs/agent.log

Q：如何停止服务

hermes gateway stop

Q：如何在前台启动

hermes gateway run --verbose

# 安全使用须知

** 💡 QQ 龙虾使用建议 **

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

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

# 1、凭证安全管理

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

# 2、功能使用安全

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

# 3、环境安全管理

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

# 4、应急处理规范

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