1. 为什么要在 Docker 里跑 OpenClaw NapCat 这套组合OpenClaw 接入 QQ 个人号这件事核心链路其实就一句话让一个跑在容器里的 AI 助手通过 OneBot v11 协议连上一个模拟 QQ 客户端行为的容器从而在私聊和群聊里收发消息。听起来绕但拆开看每一段都不复杂。NapCat 是基于 QQNT 的 Bot 框架对外暴露 OneBot v11 标准的 WebSocket 服务OpenClaw 的 qq 插件作为客户端去连这个 WebSocket中间用 Docker 网络打通配置一次就能长期跑。适合谁看如果你已经用 Docker 部署了 OpenClaw想让它在 QQ 里能对话又不想碰官方机器人那套审核流程这套方案就是为你准备的。需要提前说明的是用第三方客户端登录 QQ 存在账号风险强烈建议用小号测试别拿主力号折腾风险自担。本文只做技术链路整合不涉及任何协议逆向或破解。我试过把 NapCat 和 OpenClaw 放在同一个 Docker 网络里最大的坑不是配置本身而是容器间网络隔离导致的连接超时。很多人卡在ETIMEDOUT就是因为两个容器各在各的 bridge 网络里互相看不见。所以这篇教程会把网络打通这一步讲透包括怎么查 IP、怎么把容器接进同一个网络。整条链路的数据流向是这样的QQ 用户发消息 → NapCat 收到并转成 OneBot 事件 → 通过 WebSocket 推给 OpenClaw qq 插件 → 插件交给 AI 模型处理 → 回复再原路返回。你只需要保证 NapCat 的 WebSocket 服务开着、OpenClaw 的 wsUrl 指对、token 两边一致剩下的就是验证。下面从零开始每一步都给可复制的命令和配置。前置条件只有三个装好 Docker、已经用 Docker 方式跑着 OpenClaw、有一个可以登录的 QQ 小号。2. TaoToken 前置给 OpenClaw 配一个统一的模型通道OpenClaw 本身只是个调度框架真正干活的是背后的 AI 模型。如果你还没配模型通道或者想用一个 Key 同时调多个模型可以先把 TaoToken 的 API 通道接进来。它的作用是提供一个统一的 OpenAI 兼容接口OpenClaw 里配置 base URL 和 Key 就能用不用为每个模型单独折腾。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。API 地址是 https://taotoken.net/api 注意这个不带 UTM 参数配置里填的就是它。具体操作登录后进控制台找到 API Keys 页面新建一个 Key复制出来备用。然后在 OpenClaw 的模型配置里把 provider 的 base URL 指向https://taotoken.net/api把 Key 填进去。模型 ID 按你实际要用的填比如claude-sonnet-4-5这类。这样 OpenClaw 处理 QQ 消息时就会走这条通道去请求模型。如果你还没决定用哪个模型可以先去模型对话页面试试效果确认能正常返回再写进配置。对于长期跑编码类或 Agent 类任务的场景Coding Plan 会更划算适合把 OpenClaw 当常驻助手用的朋友。需要强调的是TaoToken 在这里的角色只是模型 API 通道它不参与 QQ 协议那一层。QQ 消息的收发完全由 NapCat 和 OpenClaw qq 插件负责两者是解耦的。你甚至可以先不接模型把 QQ 链路跑通、看到日志里消息进来了再去配模型通道这样排障更清晰。配置模型通道时最容易出错的是 base URL 结尾多写或少写斜杠。OpenClaw 内部拼接路径时对斜杠敏感建议就按https://taotoken.net/api这个形式填不要自己加/v1之类的后缀除非文档明确要求。Key 要完整复制前后别带空格。3. 可复制配置docker-compose 一次拉起 NapCat 与网络打通这一节给完整的可复制配置。先建目录再写 docker-compose最后处理网络。目录结构建议这样mkdir -p /www/dk_project/dk_app/napcat/config mkdir -p /www/dk_project/dk_app/napcat/logs如果你习惯用docker run命令如下端口映射和挂载路径要和后面 OpenClaw 的配置对应上docker run -d \ --name napcat \ -e NAPCAT_GID$(id -g) \ -e NAPCAT_UID$(id -u) \ -p 3000:3000 \ -p 3001:3001 \ -p 6099:6099 \ -v /www/dk_project/dk_app/napcat/config:/app/napcat/config \ -v /www/dk_project/dk_app/napcat/logs:/app/napcat/logs \ --restart always \ mlikiowa/napcat-docker:latest端口用途对照一下3000 是 HTTP API3001 是 WebSocketOpenClaw 要连的就是它6099 是 WebUI 管理界面。三个端口里 3001 最关键连不上就是它的问题。更推荐用 docker-compose 管理方便和 OpenClaw 放一起。新建docker-compose.ymlservices: napcat: image: mlikiowa/napcat-docker:latest container_name: napcat environment: - NAPCAT_GID1000 - NAPCAT_UID1000 ports: - 3000:3000 - 3001:3001 - 6099:6099 volumes: - /www/dk_project/dk_app/napcat/config:/app/napcat/config - /www/dk_project/dk_app/napcat/logs:/app/napcat/logs restart: always networks: - openclaw_net networks: openclaw_net: external: true name: dk_openclaw_default这里有个关键点networks里引用的dk_openclaw_default必须是你 OpenClaw 实际所在的网络名。先用docker network ls查一下找到 OpenClaw 容器挂的那个网络。如果 OpenClaw 是用 compose 起的网络名通常是项目名_default。把 NapCat 直接接进同一个网络就省掉了后面手动docker network connect的步骤。启动docker compose up -d启动后确认容器在跑docker ps | grep napcat如果网络名写错了compose 会报 network not found。这时候要么改成正确的网络名要么先docker network create建一个再把 OpenClaw 也接进来。网络打通是后面 WebSocket 能连上的前提这一步别跳过。4. 验证请求扫码登录、WebSocket 生效与消息回调容器起来后先登录 QQ。查看日志拿二维码docker logs napcat 21 | grep -A 50 二维码或者直接访问 WebUIhttp://你的服务器IP:6099/webui。首次访问需要从日志里拿 tokendocker logs napcat 21 | grep WebUi Local用手机 QQ 扫码完成登录。登录成功后日志会打印类似[info] [Core] [Login] 登录成功! 昵称: xxx。这一步如果二维码刷不出来多半是容器时区或字体问题重启容器再试。登录成功后NapCat 会在 config 目录生成配置文件文件名带你的 QQ 号ls /www/dk_project/dk_app/napcat/config/ # 输出示例: onebot11_123456789.json编辑这个文件配置 WebSocket 服务端{ network: { httpServers: [], httpSseServers: [], httpClients: [], websocketServers: [ { name: openclaw, enable: true, host: 0.0.0.0, port: 3001, reportSelfMessage: false, enableForcePushEvent: true, messagePostFormat: array, token: napcat_openclaw_token } ], websocketClients: [], plugins: [] }, musicSignUrl: , enableLocalFile2Url: false, parseMultMsg: false }enable必须为 truehost用0.0.0.0允许容器外连入token自己设一个后面 OpenClaw 要填一样的。改完重启 NapCatdocker restart napcat验证 WebSocket 服务是否起来docker logs napcat 21 | grep -i websocket看到类似WebSocket服务: 0.0.0.0:3001, : 已启动就对了。接下来装 OpenClaw 的 qq 插件。进入 OpenClaw 容器docker exec -it openclaw容器名 sh -c cd /home/node/.openclaw/extensions git clone https://github.com/constansino/moltbot_qq.git qq装依赖docker exec -u root openclaw容器名 sh -c cd /home/node/.openclaw/extensions/qq yarn install如果提示缺 zoddocker exec -u root openclaw容器名 sh -c cd /home/node/.openclaw/extensions/qq yarn add zod然后配 OpenClaw 的openclaw.json。先确认 NapCat 在共享网络里的 IPdocker inspect napcat --format {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}假设输出172.18.0.3在配置里加上 qq 插件和 channel{ plugins: { entries: { qq: { enabled: true } } }, channels: { qq: { enabled: true, wsUrl: ws://172.18.0.3:3001, accessToken: napcat_openclaw_token } } }wsUrl用容器内部 IP别用 localhost 或 127.0.0.1那是容器自己的回环。accessToken和 NapCat 里的 token 完全一致大小写敏感。重启 OpenClawdocker restart openclaw容器名看日志确认连接docker logs openclaw容器名 21 | grep -i \[QQ\]成功会显示[QQ] Connected account default和[QQ] Connected to OneBot server。最后用另一个 QQ 号给登录的号发条消息OpenClaw 应该会自动回复。私聊直接发就触发群聊需要 机器人取决于插件配置。5. 本篇常见错排查从 401 到 ETIMEDOUT 逐个拆排障这块按真实报错来。第一个高频错误是ETIMEDOUT原因几乎都是两个容器不在同一网络。解决确认 NapCat 和 OpenClaw 挂在同一个网络用docker network connect dk_openclaw_default napcat补接然后用docker inspect拿到的容器内部 IP 填 wsUrl绝对不要用 localhost。第二个是ECONNREFUSED连接被拒绝。这通常是 NapCat 的 WebSocket 服务没起来。检查配置文件里enable是不是 true端口是不是 3001改完有没有docker restart napcat。日志里搜 websocket 关键字没看到「已启动」就是没生效。第三个是认证失败对应 401 类错误。原因就一个token 不匹配。OpenClaw 的accessToken和 NapCat 的token必须一字不差注意大小写和前后空格。改完两边都要重启。第四个是 NapCat 需要重新登录。QQ 登录态会过期或者你改了配置触发了重登。重新拿二维码扫码即可docker logs napcat 21 | grep -A 50 二维码第五个是找不到host.docker.internal。Linux 下 Docker 默认不支持这个主机名别用它。正确做法是用容器实际 IP通过docker inspect获取。如果你在 macOS 或 Windows 上host.docker.internal可用但跨平台配置不通用建议统一用容器 IP。还有一个容易忽略的OpenClaw 日志里出现reading choices之类的报错这通常是模型通道返回格式不对检查 TaoToken 的 base URL 和 Key 是否正确模型 ID 是否拼写无误。这跟 QQ 链路无关是模型层的问题分开排查。排查顺序建议先确认 NapCat WebSocket 起来 → 再确认两容器同网络 → 再确认 IP 和 token → 最后看 OpenClaw 日志。按这个顺序走基本不会绕弯路。6. 把 QQ 链路接进你的日常助手工作流链路跑通之后OpenClaw 在 QQ 里就是一个能对话的助手。私聊直接发消息触发群聊 触发。你可以把它当成一个常驻的 AI 入口配合 TaoToken 的模型通道随时切换模型。如果后面要长期跑编码或 Agent 类任务建议把模型通道换成 Coding Plan稳定性和成本都更可控。API Key 在控制台随时能新建和吊销接入文档里有各语言的调用示例遇到模型层的问题可以先翻文档。QQ 这条链路本身NapCat 和 OpenClaw qq 插件都是开源组件各自遵循自己的许可。用第三方客户端登录 QQ 有账号风险务必用小号别拿主力号试。配置文件和 token 别提交到公开仓库容器网络也尽量隔离。最后留一个实用技巧把 NapCat 的 config 目录和 OpenClaw 的配置目录都做好备份QQ 登录态过期或容器重建时恢复配置能省很多事。日志目录也留着出问题时docker logs是最快的定位手段。