将QQ接入OpenClaw的详细教程

发表于 更新于 分类于 Waline： 阅读次数： 本文字数： 3.5k 阅读时长 ≈ 3 分钟
将 QQ 接入 OpenClaw（原Clawdbot/Moltbot）,支持 C2C 私聊、群聊 @消息、频道消息。

说明

在开始今天的正文前，需要做两个说明

关于容器

ClawdBot 一周改名三次，先是改为了 MoltBot，现在最新的名字是 OpenClaw

代码仓库改名之后，在页面上找不到镜像的入口了，但是实际上是存在的。在浏览器中打开 https://ghcr.io/openclaw/openclaw 会看到多个版本

其中

  • main：应该是最新的开发版本；
  • latest：则应该是稳定版本；

完整示例

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
32
33
34
version: '3.8'

services:
  moltbot-gateway:
    image: ghcr.io/openclaw/openclaw:main
    container_name: moltbot-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
    #  - ./config:/home/node/.clawdbot
    #  - ./config:/home/node/.moltbot
      - ./config:/home/node/.openclaw
      - ./data:/home/node/clawd
    environment:
      - HTTP_PROXY=http://192.168.0.206:2081
      - HTTPS_PROXY=http://192.168.0.206:2081
      - NO_PROXY="localhost,127.0.0.1,::1"
    shm_size: 2g          # 必须加，至少 1g，推荐 2g 或更大
    # privileged: true      # 可选2：如果仍报权限问题，临时加这个（不推荐长期用）
    # cap_add:
    #   - SYS_ADMIN         # 可选1：解决部分沙箱问题和安装skill权限不足
    command: node /app/dist/index.js gateway --port 18789

  moltbot-cli:
    image: ghcr.io/openclaw/openclaw:main
    container_name: moltbot-cli
    network_mode: "service:moltbot-gateway"   # ← 关键：共享 gateway 容器的网络栈和端口
    volumes:
    #  - ./config:/home/node/.clawdbot
    #  - ./config:/home/node/.moltbot
      - ./config:/home/node/.openclaw
      - ./data:/home/node/clawd
    entrypoint: ["node", "dist/index.js"]

为了最大程度跟上一篇文章保持一致，所以只改了镜像名称和容器内的路径，启动之前，需将 moltbot.json 改名为 openclaw.json，否则可能会一直提示 Missing config. Run openclaw setup or set gateway.mode=local (or pass --allow-unconfigured).

如果你的 config 目录中还没有 moltbot.json 或者 openclaw.json，需要先运行 onboarding 向导

上期的勘误

另外做个勘误，上文 Docker方式安装你的私人AI电脑助手Moltbot] 中启动 onboarding 向导写的是

1
2
# 运行设置
docker compose run --rm -it moltbot-cli onboard

但是实际上应该用👇 这个

1
2
# 运行设置
docker-compose run --rm moltbot-cli onboard

截图中是正确的

接下来进入我们今天的正题

简介

什么是 qqbot ?

qqbot 全称是 QQ Bot Channel Plugin for Moltbot，是 QQ 开放平台Bot API 的 OpenClaw（原Clawdbot/Moltbot） 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。

功能特性

  • 多场景支持：C2C 单聊、QQ 群 @消息、频道公开消息、频道私信
  • 自动重连：WebSocket 断连后自动重连，支持 Session Resume
  • 消息去重：自动管理 msg_seq，支持对同一消息多次回复
  • 系统提示词：可配置自定义系统提示词注入到 AI 请求
  • 错误提示：AI 无响应时自动提示用户检查配置
  • 易于安装与配置：提供交互式配置方式和命令行配置选项，简化设置过程。

安装与配置

安装 QQ 插件

1
2
3
4
5
6
7
8
# 进入 moltbot 目录
cd /volume1/docker/moltbot

# 延长超时时间（如果你的机器性能比较弱，可以设置的再大一点）
export COMPOSE_HTTP_TIMEOUT=600

# 查看当前所有插件
docker-compose run --rm moltbot-cli plugins list

下载 QQ 插件，地址：https://github.com/sliverp/qqbot

解压后放入到 data 目录中

对应容器内的目录为 /home/node/clawd/qqbot-main

1
2
# 安装 QQ 插件
docker-compose run --rm moltbot-cli plugins install /home/node/clawd/qqbot-main/.

检查一下是否安装成功

1
2
# 查看当前所有插件
docker-compose run --rm moltbot-cli plugins list

配置

获取 QQ 机器人凭证

  1. 访问 QQ 开放平台，地址：https://q.qq.com，完成注册和审核

  1. 创建机器人应用，注意不是小程序、游戏

  1. 进入开发管理获取 AppID 和 AppSecret

  1. Token 格式为 AppID:AppSecret，例如 102146862:Xjv7JVhu7KXkxANbp3HVjxCRgvAPeuAQ

  2. 添加 IP 白名单，因为 NAS 服务器部署在家中，所以这里是我们家宽的公网 IP，可以通过访问 https://myip.ipip.net 来获取

添加配置

方式一：交互式配置

通过交互方式进行配置

1
2
# 选择 qqbot，按提示输入 Token
docker-compose run --rm moltbot-cli channels add

选中 QQ Bot

输入 AppID

输入 ClientSecret，也就是 AppSecret

方式二：命令行配置

也可以直接用命令行配置

1
2
3
4
5
# 命令行配置
docker-compose run --rm moltbot-cli channels add --channel qqbot --token "AppID:AppSecret"

# 示例
docker-compose run --rm moltbot-cli channels add --channel qqbot --token "102146862:xxxxxxxx"

手动编辑配置

如果你比较熟悉，可以直接编辑配置文件 moltdbot.json

配置项 类型 必填 说明
appId string 是 QQ 机器人 AppID
clientSecret string 是* AppSecret，与 clientSecretFile 二选一
clientSecretFile string 是* AppSecret 文件路径
enabled boolean 否 是否启用，默认 true
name string 否 账户显示名称
systemPrompt string 否 自定义系统提示词

下面是一个示例

1
2
3
4
5
6
7
8
9
10
{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "你的AppID",
      "clientSecret": "你的AppSecret",
      "systemPrompt": "你是老苏的AI助手"
    }
  }
}

使用

在沙箱配置中，可以扫描 添加成员 旁边的二维码，通过扫码，把机器人添加到自己的聊天界面

现在随便问个问题

参考文档

sliverp/qqbot: qqbot
地址：https://github.com/sliverp/qqbot

QQ机器人管理端
地址：https://q.qq.com/qqbot/#/home

Package openclaw
地址：https://ghcr.io/openclaw/openclaw