🚀 从 1 到 2：让 OpenClaw Agent 接管 QQ 的硬核指南_发布版04-27

3.《OpenClaw (Docker手工部署版) 终极避坑与实战指南》03-23

收起

作者： 杨易 & 赛博龙虾 环境： RackNerd VPS (Linux) + OpenClaw Kernel (Docker) + NapCatQQ (Docker) 目标： 突破 Telegram 严苛的 PC 端风控限制，使用 QQ 小号完美接入 OpenClaw，实现带有长文本思考、人设继承、全双工 WebSocket 通讯的 24 小时私人管家。

在折腾了几十个小时、经历了无数次报错、甚至和 AI Agent 发生“逻辑斗智斗勇”之后，我们终于打通了这套“脑机接口”，并完成了底层架构的“统一网关路由”升级。为了不让后来者重蹈覆辙，特整理此份血泪史。

🏗️ 终极架构速览 (同一大脑，多端共享)

最终跑通的完美架构如下：

• 宿主机 Docker 网络：搭建起隔离但互通的虚拟网络。

• NapCatQQ 容器：负责模拟 iPad/Linux 登录 QQ 小号，通过 OneBot v11 协议对外暴露 WebSocket (3001 端口) 作为“耳朵和嘴巴”。

• OpenClaw Kernel 容器：运行 Agent 大脑中枢。内部挂载一个 Python 桥接脚本（QQ Ears），它不再直接请求大模型 API，而是作为统一网关路由，遇到消息直接调用底层 openclaw agent 命令。这使得 QQ 端完美继承了官方 Telegram 机器人的长期记忆、系统人设与本地工具链！

💣 核心避坑指南（按掉坑顺序排列）

坑一：OpenClaw 的安全机制与“文件覆盖陷阱”

• 表现： Agent 假死不回话；或者明明修改了宿主机的 Python 脚本并保存，运行出来的依然是旧版本的代码报错。

• 真相：

  1. OpenClaw 严格禁止 Agent 运行复合后台命令。

  2. Docker 容器是极其封闭的集装箱。在宿主机 /root/ 下修改并保存的文件，绝对不会自动同步到容器内的 /home/node/ 目录。

• 解法： 每次修改代码后，必须执行“极客三件套”强行覆盖并重启内存：

Bash

# 1. 强行越权把宿主机的新文件塞进容器
sudo docker cp /root/qq_ears_brain.py openclaw_kernel:/home/node/qq_ears_brain.py
# 2. 强制杀掉旧容器里的幽灵进程，清理内存
sudo docker restart openclaw_kernel
# 3. 前台点火监工 (没问题后再加 -d 放入后台)
sudo docker exec -it openclaw_kernel python3 /home/node/qq_ears_brain.py

坑二：灵魂隔离与 Linux “位置法则” (告别手搓 API)

• 表现： QQ 端成了失忆的“复读机”，性格与 Telegram 端截然不同，且执行 openclaw agent 命令时频繁报错 unknown option '--no-color'。

• 真相：

  1. 自己写代码直连 DeepSeek API，会丢失 OpenClaw 强大的上下文记忆和工具链。

  2. Linux 命令行的严苛法则：全局选项（--no-color）必须紧跟在主程序后面，子命令（agent）之前。位置一错，全盘崩溃。

• 解法： 实现“统一网关路由”。砍掉 API 密钥，直接通过 asyncio.create_subprocess_exec 召唤底层内核，并绝对精准地排列参数顺序：openclaw, --no-color, agent。

坑三：企鹅厂的风控玄学与“幽灵假死”（如何处理 QQ 掉线）

• 表现： 终端完美打印 ✅ 上线通知已发送，代码无任何报错，但你的大号 QQ 死活收不到消息，发消息也不回。

• 真相： NapCat 遇到了“幽灵假死”。本地 Token 尚未过期（所以不报错也不弹二维码），但腾