在任意文件夹创建项目文件夹napcat及需要的文件夹，并创建docker-compose.yml

mkdir -p napcat && cd napcat
mkdir -p config .config logs

docker-compose.yml内容参考

services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: unless-stopped
    
    environment:
      - NAPCAT_UID=${NAPCAT_UID:-1000}
      - NAPCAT_GID=${NAPCAT_GID:-1000}
      - MESSAGE_POST_FORMAT=string
      
      # 网络服务（根据需求启用）
      - HTTP_ENABLE=true
      - HTTP_HOST=0.0.0.0
      - HTTP_PORT=3000
      - WS_ENABLE=true
      - WS_HOST=0.0.0.0
      - WS_PORT=3001
    
    ports:
      - "3000:3000"
      - "3001:3001"
      - "6099:6099"
    
    volumes:
      # 1. NapCat 配置（网络设置、WebUI token）
      - ./config:/app/napcat/config
      
      # 2. QQ 数据（登录凭证、持久化登录状态）
      # 官方路径是 /app/.config/QQ，
      - ./.config:/app/.config/QQ
      
      # 3. 日志（可选）
      - ./logs:/app/napcat/logs
    
    # 注意：没有 network_mode: bridge，与 ports 冲突
    stdin_open: true
    tty: true

启动docker，并执行NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker-compose up -d

命令拆解	含义
NAPCAT_UID=$(id -u)	设置环境变量 NAPCAT_UID 为当前用户的用户 ID
NAPCAT_GID=$(id -g)	设置环境变量 NAPCAT_GID 为当前用户的组 ID
docker-compose up -d	在后台启动 Docker Compose 服务

因为NapCat 容器内以 NAPCAT_UID 用户运行，需要与宿主机用户权限匹配，所以动态获取当前用户 ID，环境变量传递给 Docker Compose

启动完成

执行docker-compose logs -f，手机qq扫描登录日志的二维码登录

也可以根据日志的token打开http://127.0.0.1:6099/webui?token=你的token，输入账号和密码

如果提示需要验证码，暂时不支持的话就扫码登录

点击网络配置，添加

复制websocket server的token

两个插件选一个即可，建议用openclaw_qq，因为目前@izhimu/qq插件似乎群里有人发消息就一定会回复且不支持/model等命令（可能要自己研究怎么配置或修改源码？），而openclaw_qq在群@机器人的名字或设置关键词触发

插件1（推荐）:

在另一个终端执行cd ~/.openclaw/extensions && git clone https://github.com/constansino/openclaw_qq.git qq命令给openclaw安装插件，然后执行cd ~/.openclaw/extensions/qq && pnpm install 2>&1 | tail -20编译安装

插件2:

执行pnpm openclaw plugins install @izhimu/qq给openclaw安装插件，如果你的openclaw不是通过pnpm安装则去掉pnpm，下同

输入pnpm openclaw gateway restart重启，然后打开http://127.0.0.1:18789/channels，粘贴websocket的token，点击保存，过一会看到yes即成功连接

如果qq机器人回复出现Connection error（这里已经换成小号当QQ机器人，防止主号乱发消息被封），去用户目录的.opneclaw里，比如/Users/Zhuanz/.openclaw，打开openclaw.json，找到channels，再找qq，将enable改为true；如果还是这样，看看agents.defaults.model.primary是不是本地 ollama 模型且此时没启动ollama（注意在网页或tui输入/model等命令要在对应的qq聊天session执行才对qq机器人有效）

之后执行pnpm openclaw gateway restart或其他命令重启，测试效果，如果你的openclaw不是通过pnpm安装则去掉pnpm，下同

用@izhimu/qq插件的情况

已经成功回复，但如果是用@izhimu/qq插件不会对聊天中直接发/model等命令执行且给结果，只有让对话中强调执行这个命令才有效，但在openclaw_qq可以直接执行命令给结果（下图）

openclaw_qq配置参考

插件功能差异对比（原因：目前这个QQ 插件缺少 CommandAuthorized 参数）

插件	finalizeInboundContext 参数	命令支持
飞书	包含 CommandAuthorized: commandAuthorized	✅ 支持
QQ	缺乏 CommandAuthorized 参数	❌ 不支持

两个 QQ 插件功能对比

1.配置项对比

功能	@izhimu/qq	openclaw_qq	说明
wsUrl	✅	✅	WebSocket 地址
accessToken	✅	✅	访问令牌
enable	✅	❌	启用开关
requireMention	❌	✅ 默认 true	群聊需要 @ 才触发
keywordTriggers	❌	✅	关键词唤醒
admins	❌	✅	管理员列表
adminOnlyChat	❌	✅	仅管理员可触发
allowedGroups	❌	✅	群白名单
blockedUsers	❌	✅	用户黑名单
systemPrompt	❌	✅	自定义人设
historyLimit	❌	✅	历史消息注入
autoApproveRequests	❌	✅	自动通过好友 / 群邀请
enableTTS	❌	✅	语音回复
enableGuilds	❌	✅	QQ 频道支持
rateLimitMs	❌	✅ 默认 1000ms	发送限速防风控
antiRiskMode	❌	✅	URL 风控规避
maxMessageLength	❌	✅ 默认 4000	消息分片
formatMarkdown	❌	✅	Markdown 转纯文本
showProcessingStatus	❌	✅	群名片显示 "输入中"
sharedMediaHostDir	❌	✅	跨容器媒体共享

2.核心功能差异

功能	@izhimu/qq	openclaw_qq	原因
群聊 @ 触发	❌ 所有消息都回复	✅ 默认仅 @ 触发	新插件有 requireMention 配置
关键词唤醒	❌	✅ 如 "小助手"	新插件有 keywordTriggers
管理员命令	❌	✅ /model, /status 等	新插件实现了命令处理
/model 命令	❌	✅ 仅管理员	新插件支持模型切换
群白名单	❌	✅	新插件有 allowedGroups
用户黑名单	❌	✅	新插件有 blockedUsers
风控优化	❌	✅ 限速、URL 规避	新插件针对 QQ 风控设计
戳一戳响应	❌	✅	新插件处理 poke 事件
自动通过请求	❌	✅	新插件有 autoApproveRequests
消息去重	❌	✅	新插件有 enableDeduplication
空回复兜底	❌	✅	新插件有 enableEmptyReplyFallback

参考教程：

1.https://blog.csdn.net/qq_14956715/article/details/157942635

2.https://blog.csdn.net/m0_60046831/article/details/157696672

创作不易，禁止抄袭，转载请附上原文链接及标题