OpenClaw 接入 QQ 机器人完整部署指南
版本要求: OpenClaw 2026.2.26+
项目概述
本指南介绍如何将 OpenClaw 接入 QQ，实现通过 QQ 与 OpenClaw 智能助手对话。
架构说明
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ QQ 用户 │ ──→ │ NapCat │ ──→ │ OpenClaw │
│ (发消息) │ │ (QQ 机器人) │ │ (星期五) │
└─────────────┘ └──────────────┘ └─────────────┘
↓
(OneBot WebSocket)
技术栈
- NapCat: QQ 机器人框架（基于 OneBot v11 协议）
- OpenClaw QQ 插件: OpenClaw 官方 QQ 频道插件
- Docker: NapCat 容器化部署
- Host 网络模式: 解决 WSL2 与 Docker 网络互通问题
环境准备
系统要求
- ✅ Linux / WSL2 (Windows Subsystem for Linux)
- ✅ Docker 20.10+
- ✅ Docker Compose 2.0+
- ✅ OpenClaw 2026.2.26+
- ✅ Node.js 18+ (OpenClaw 运行环境)
检查环境
在开始之前，建议先确认本地环境是否满足要求：
# 检查 Docker 版本
docker --version
docker compose version
# 检查 OpenClaw
openclaw --version
# 检查 Node.js
node --version
安装 NapCat QQ 机器人
创建部署目录
我们需要在 OpenClaw 的扩展目录下创建一个专门存放 NapCat 的路径。这里以 /home/gaof/.openclaw/extensions/qq/deploy/napcat 为例：
mkdir -p /home/gaof/.openclaw/extensions/qq/deploy/napcat
cd /home/gaof/.openclaw/extensions/qq/deploy/napcat
编写 Docker Compose 配置
接下来创建 docker-compose.yml 文件。这里有一个关键点：必须使用 network_mode: host。这是因为在 WSL2 环境下，如果默认桥接模式，容器内的服务可能无法被宿主机或 WSL2 正确访问。
version: "3"
services:
napcat:
environment:
- NAPCAT_UID=${NAPCAT_UID}
- NAPCAT_GID=${NAPCAT_GID}
container_name: napcat
network_mode: host # ⚠️ 关键：使用 host 网络模式
restart: always
image: mlikiowa/napcat-docker:latest
启动容器
配置完成后，直接启动服务即可：
cd /home/gaof/.openclaw/extensions/qq/deploy/napcat
docker compose up -d
扫码登录
容器启动后，需要扫码完成 QQ 账号绑定。查看日志获取二维码：
docker logs napcat | tail
根据日志输出的二维码信息进行扫码登录，登录成功后即可进行后续插件配置。
