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

2026-05-06阅读 0热度 0

机器人 Python 容器

项目概述

你是否想过，让你在电脑上使用的强大AI助手，也能随时在QQ上回应你的召唤？本指南要做的，就是帮你搭建这座桥梁，让你通过熟悉的QQ界面，直接与OpenClaw智能助手对话。

架构说明

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

技术栈

整个方案的实现，主要依赖于几个核心组件，它们就像精密齿轮一样环环相扣：

NapCat：充当“信使”，这是一个基于 OneBot v11 协议的 QQ 机器人框架。
OpenClaw QQ 插件：官方提供的“适配器”，负责接收 NapCat 的消息并转交给 OpenClaw 核心。
Docker：NapCat 推荐采用容器化部署，这能极大简化环境配置。
Host 网络模式：这是整个部署中保证网络畅通的关键，尤其是在 WSL2 环境下。

环境准备

在动手之前，请确保你的工作环境满足以下基本要求。俗话说，工欲善其事，必先利其器。

系统要求

✅ 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 机器人

我们的第一步，是让 QQ 机器人“NapCat”先跑起来，它将成为接收QQ消息的入口。

步骤 1：创建部署目录

首先，为NapCat找个安家之地。建议将其放在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环境下，这是保证容器内外网络能够互通的必要设置，后续插件的连接就依赖于此。

步骤 3：启动 NapCat

配置完成后，一句命令即可启动容器。

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

步骤 4：扫码登录 QQ

NapCat启动后，它自己还没有QQ账号呢。我们需要让这个机器人登录一个QQ号。通过查看容器日志，可以获取登录二维码。

docker logs napcat 2>&1 | tail

执行命令后，在日志中找到二维码，使用你要作为机器人的QQ号扫码登录即可。至此，NapCat的部署与登录就完成了。