本教程介绍如何通过 NapCat + OneBot v11 协议 将 OpenClaw 接入 QQ 个人号，实现用 QQ 个人账号与 AI 助手对话。

！！！区别于已有教程接入QQ官方机器人

技术架构

QQ 用户 <---> NapCat (QQ客户端) <---> OneBot v11 WebSocket <---> OpenClaw qq插件 <---> AI 模型

为什么选择 NapCat？

• NapCat 是基于 QQNT 的 Bot 框架，支持 OneBot v11 协议
• 相比官方 QQ 机器人 API，个人号可以直接私聊、群聊，无需审核
• 支持 Docker 部署，配置简单

---

前置条件

• 已安装 Docker
• 已部署 OpenClaw（Docker 方式）
• 一个 QQ 账号用于登录

---

第一步：安装 NapCat

NapCat 是一个基于 QQNT 的 Bot 框架，支持 OneBot v11 协议。

1.1 创建目录

mkdir -p /www/dk_project/dk_app/napcat/config
mkdir -p /www/dk_project/dk_app/napcat/logs

1.2 启动 NapCat 容器

docker run -d \
  --name napcat \
  -e NAPCAT_GID=$(id -g) \
  -e NAPCAT_UID=$(id -u) \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 6099:6099 \
  -v /www/dk_project/dk_app/napcat/config:/app/napcat/config \
  -v /www/dk_project/dk_app/napcat/logs:/app/napcat/logs \
  --restart always \
  mlikiowa/napcat-docker:latest

端口说明：

端口	用途
3000	HTTP API 端口
3001	WebSocket 端口（OpenClaw 连接用）
6099	WebUI 管理界面

---

第二步：登录 QQ 账号

2.1 获取登录二维码

查看 NapCat 日志获取二维码：

docker logs napcat 2>&1 | grep -A 50 "二维码"

或者访问 WebUI：

http://你的服务器IP:6099/webui

注意：首次访问 WebUI 需要从日志中获取 token

docker logs napcat 2>&1 | grep "WebUi Local"

2.2 扫码登录

用手机 QQ 扫描二维码完成登录。登录成功后，日志会显示：

[info] [Core] [Login] 登录成功! 昵称: xxx

---

第三步：配置 NapCat OneBot11 WebSocket

登录成功后，NapCat 会在 config 目录生成配置文件。

3.1 查找配置文件

ls /www/dk_project/dk_app/napcat/config/
# 输出示例: onebot11_123456789.json

文件名中的数字是你的 QQ 号。

3.2 编辑 OneBot11 配置

vim /www/dk_project/dk_app/napcat/config/onebot11_你的QQ号.json

修改为以下内容：

{
  "network": {
    "httpServers": [],
    "httpSseServers": [],
    "httpClients": [],
    "websocketServers": [
      {
        "name": "openclaw",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3001,
        "reportSelfMessage": false,
        "enableForcePushEvent": true,
        "messagePostFormat": "array",
        "token": "your_secure_token_here"
      }
    ],
    "websocketClients": [],
    "plugins": []
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false
}

重要参数说明：

参数	说明
enable	必须为 true，启用 WebSocket 服务
host	0.0.0.0 允许外部连接
port	WebSocket 端口，默认 3001
token	安全令牌，OpenClaw 连接时需要匹配

3.3 重启 NapCat 使配置生效

docker restart napcat

3.4 验证 WebSocket 服务启动

docker logs napcat 2>&1 | grep -i "websocket"

应该看到类似输出：

WebSocket服务: 0.0.0.0:3001, : 已启动

---

第四步：安装 OpenClaw qq 插件

4.1 克隆插件代码

进入 OpenClaw 容器安装 qq 插件（支持 OneBot v11 协议）：

# 替换 <openclaw容器名> 为你的实际容器名
docker exec -it <openclaw容器名> sh -c "cd /home/node/.openclaw/extensions && git clone https://github.com/constansino/moltbot_qq.git qq"

4.2 安装依赖

docker exec -u root <openclaw容器名> sh -c "cd /home/node/.openclaw/extensions/qq && yarn install"

如果提示缺少 zod 依赖：

docker exec -u root <openclaw容器名> sh -c "cd /home/node/.openclaw/extensions/qq && yarn add zod"

---

第五步：配置 OpenClaw 连接 NapCat

5.1 网络配置

如果 OpenClaw 和 NapCat 在不同的 Docker 网络，需要将它们连接到同一网络。

查看 OpenClaw 所在网络

docker network ls

将 NapCat 加入 OpenClaw 网络

# 假设 OpenClaw 网络名为 dk_openclaw_default
docker network connect dk_openclaw_default napcat

获取 NapCat 在该网络中的 IP

docker inspect napcat --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

记下输出的 IP 地址，例如 172.18.0.3。

5.2 编辑 OpenClaw 配置

找到并编辑 OpenClaw 配置文件 openclaw.json：

vim /path/to/openclaw/config/openclaw.json

在 plugins.entries 中添加 qq 插件：

{
  "plugins": {
    "entries": {
      "qq": {
        "enabled": true
      }
    }
  }
}

在 channels 中添加 qq 渠道配置：

{
  "channels": {
    "qq": {
      "enabled": true,
      "wsUrl": "ws://172.18.0.3:3001",
      "accessToken": "your_secure_token_here"
    }
  }
}

配置说明：

参数	说明
wsUrl	NapCat WebSocket 地址，格式 ws://IP:端口
accessToken	与 NapCat 配置中的 token 保持一致

5.3 重启 OpenClaw

docker restart <openclaw容器名>

---

第六步：验证连接

6.1 检查 OpenClaw 日志

docker logs <openclaw容器名> 2>&1 | grep -i "\[QQ\]"

成功连接会显示：

[QQ] Connected account default
[QQ] Connected to OneBot server

6.2 测试对话

用另一个 QQ 账号给登录的 QQ 号发送消息，OpenClaw 应该会自动回复。

---

常见问题排查

Q1: 连接超时 ETIMEDOUT

原因: OpenClaw 容器无法访问 NapCat 容器

解决方案:

1. 确保两个容器在同一 Docker 网络：

docker network connect <openclaw网络名> napcat

2. 使用正确的容器内部 IP 地址，不要使用 localhost 或 127.0.0.1

Q2: 连接被拒绝 ECONNREFUSED

原因: NapCat WebSocket 服务未启动

解决方案:

1. 检查 NapCat 配置文件中 enable 是否为 true
2. 检查端口是否正确
3. 重启 NapCat 容器：

docker restart napcat

Q3: 认证失败

原因: Token 不匹配

解决方案: 确保 OpenClaw 的 accessToken 与 NapCat 的 token 完全一致（区分大小写）

Q4: NapCat 需要重新登录

原因: QQ 会话过期或配置更改

解决方案: 重新扫码登录

docker logs napcat 2>&1 | grep -A 50 "二维码"

Q5: 找不到 host.docker.internal

原因: Linux 系统默认不支持 host.docker.internal

解决方案: 使用容器的实际 IP 地址，通过 docker inspect 获取

---

完整配置文件参考

NapCat OneBot11 配置

文件路径: /www/dk_project/dk_app/napcat/config/onebot11_QQ号.json

{
  "network": {
    "httpServers": [],
    "httpSseServers": [],
    "httpClients": [],
    "websocketServers": [
      {
        "name": "openclaw",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3001,
        "reportSelfMessage": false,
        "enableForcePushEvent": true,
        "messagePostFormat": "array",
        "token": "napcat_openclaw_token"
      }
    ],
    "websocketClients": [],
    "plugins": []
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false,
  "imageDownloadProxy": ""
}

OpenClaw 配置

文件路径: ~/.openclaw/openclaw.json 或挂载的配置目录

{
  "plugins": {
    "entries": {
      "qq": {
        "enabled": true
      }
    }
  },
  "channels": {
    "qq": {
      "enabled": true,
      "wsUrl": "ws://172.18.0.3:3001",
      "accessToken": "napcat_openclaw_token"
    }
  }
}

---

完成

现在你的 OpenClaw 已经成功接入 QQ 个人号！可以通过 QQ 私聊或群聊与 AI 助手进行对话。

使用提示

• 私聊: 直接发送消息即可触发回复
• 群聊: 需要 @机器人 才会触发回复（取决于插件配置）

相关链接

• NapCat 官方文档
• OpenClaw 官方文档
• OneBot v11 协议规范