# OpenClaw QQ 机器人接入完整指南

项目概述

你是否希望将强大的 AI 助手带入日常聊天？本教程将指导你完成搭建流程，让你能在 QQ 上直接调用 OpenClaw 智能助手，实现无门槛的 AI 对话体验。

架构说明

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   QQ 用户   │ ──→ │    NapCat    │ ──→ │  OpenClaw  │
│  (发消息)   │     │ (QQ 机器人) │     │  (星期五)  │
└─────────────┘     └──────────────┘     └─────────────┘
                          ↓
                 (OneBot WebSocket)

技术栈

本方案基于成熟的开源组件构建，各模块分工明确，协同工作：

• NapCat：核心通信枢纽，一个遵循 OneBot v11 标准的 QQ 机器人框架，负责消息收发。
• OpenClaw QQ 插件：官方适配器，作为桥梁连接机器人框架与 OpenClaw AI 核心。
• Docker：采用容器化部署 NapCat，能有效避免环境冲突，简化安装步骤。
• Host 网络模式：部署关键配置，尤其在 WSL2 系统中，确保容器与宿主机网络直连，保障通信稳定。

环境准备

开始部署前，请对照清单确认你的软硬件环境已完备。充分的准备是成功部署 QQ AI 助手的第一步。

系统要求

• ✅ Linux 发行版 或 Windows WSL2 子系统
• ✅ Docker 引擎 20.10 及以上版本
• ✅ Docker Compose 2.0 及以上版本
• ✅ OpenClaw 2026.2.26 及以上版本（确保 AI 功能可用）
• ✅ Node.js 18 及以上版本（用于运行 OpenClaw 后端）

检查环境

打开终端（或 WSL2 窗口），依次执行下列命令验证基础环境是否就绪。

# 检查 Docker 及 Compose
docker --version
docker compose version

# 检查 OpenClaw 版本
openclaw --version

# 检查 Node.js 运行环境
node --version

安装 NapCat QQ 机器人

首先部署 QQ 机器人框架 NapCat，它将作为消息入口，接收并转发来自 QQ 的聊天信息。

步骤 1：创建部署目录

建议在 OpenClaw 扩展目录下创建专属文件夹，便于集中管理相关服务。

mkdir -p /home/gaof/.openclaw/extensions/qq/deploy/napcat
cd /home/gaof/.openclaw/extensions/qq/deploy/napcat

步骤 2：创建 Docker Compose 配置

在当前目录创建 docker-compose.yml 文件。以下配置，特别是网络模式，是保证后续插件顺利连接的关键。

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

请注意，network_mode: host 这一行配置至关重要。在 WSL2 环境下，它使得容器直接使用宿主机的网络栈，从而确保 OpenClaw 插件能通过本地地址成功访问到 NapCat 服务。

步骤 3：启动 NapCat

配置文件就绪后，使用一条命令拉起 NapCat 服务容器。

cd /home/gaof/.openclaw/extensions/qq/deploy/napcat
docker compose up -d

步骤 4：扫码登录 QQ

NapCat 容器运行后，需绑定一个 QQ 账号作为机器人。通过查看容器日志获取登录二维码。

docker logs napcat 2>&1 | tail 

执行上述命令，在输出的日志信息中找到二维码图片链接或字符画，使用你计划用作机器人的 QQ 号扫码授权登录。完成此步，NapCat QQ 机器人的基础部署即告成功。