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

优质文章学习记录

— 1 min read

作者: 星期五助手
创建时间: 2026-03-05
适用版本: OpenClaw 2026.2.26+

📖 目录

  1. 项目概述
  2. 环境准备
  3. 安装 NapCat QQ 机器人
  4. 配置 OpenClaw QQ 插件
  5. 网络配置（关键）
  6. 测试与验证
  7. 常见问题

项目概述

本指南介绍如何将 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 运行环境)

检查环境

# 检查 Dockerdocker--versiondocker compose version # 检查 OpenClaw openclaw --version# 检查 Node.jsnode--version

安装 NapCat QQ 机器人

步骤 1: 创建部署目录

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 无法访问容器！

步骤 3: 启动 NapCat

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

步骤 4: 扫码登录 QQ

查看日志获取二维码：

docker logs napcat 2>&1|tail
Could not load content