作者： 杨易 & 赛博龙虾
环境： RackNerd VPS (Linux) + OpenClaw Kernel (Docker) + NapCatQQ (Docker)
目标： 让 OpenClaw 的 Agent（智能体）突破 Telegram 的限制（我的两个Telegram账号登录PC端后立即风控，在PC端使用很不方便），所以使用 QQ 小号完美接入 OpenClaw ，实现带有长文本思考、人设继承、全双工 WebSocket 通讯的 24 小时私人助手。
在折腾了十几个小时、经历了无数次报错、甚至和 AI Agent 发生“逻辑斗智斗勇”之后，我们终于打通了这套“脑机接口”。为了不让后来者重蹈覆辙，特整理此份《赛博排坑血泪史》。
🏗️ 架构速览
最终跑通的完美架构如下：
宿主机 Docker 网络：搭建起隔离但互通的虚拟网络。
NapCatQQ 容器：负责模拟 iPad/Linux 登录 QQ 小号，通过 OneBot v11 协议对外暴露 WebSocket (3001 端口)。
OpenClaw Kernel 容器：运行 Agent 大脑，内部挂载一个 Python 桥接脚本（QQ Ears），通过 asyncio 和 websockets 与 NapCat 维持长连接，遇到消息调用 DeepSeek API 并实时返回。
💣 核心避坑指南（按掉坑顺序排列）
坑一：NapCat 的“绝对静默”模式
表现： AI 脚本疯狂报错 Connection refused，死活连不上 NapCat 的 3000/3001 端口。
真相： 即使你装好了 NapCat，默认的配置文件里接口是空的。
解法：
不要去改全局的 napcat.json，要精准定位到小号的配置文件（如 data/onebot11_496750941.json）。将 network 字段补全，必须将 host 设置为 0.0.0.0，允许 Docker 跨容器访问。
坑二：Docker 的“铜墙铁壁”（放弃 HTTP，拥抱 WS）
表现： 配置文件已经改了 0.0.0.0，3001(WS) 端口通了，但 3000(HTTP) 端口依然死活连不上。
真相： 最初启动 NapCat 容器时，Docker 的 -p 参数只映射了 3001，根本没暴露 3000！
极客解法：
不要去重建容器！根据 OneBot 协议标准，WebSocket 隧道是全双工的。直接放弃 HTTP，让 Python 脚本连接 3001 端口，既用它 recv() 接收消息，也直接用它 send() 发送 API 动作（如 send_private_msg），一条专线解决所有问题。
坑三：Agent 的“炫技式翻车”（千万别手搓底层协议）
表现： 脚本直接崩溃报 Missing or invalid Sec-WebSocket-Key header；或者 CPU 占用率瞬间飙升到 100%，疯狂输出几百万次“空循环”。
真相： Agent 发现环境里没有 websockets 库，为了证明自己，居然用 Python 原生 socket 强行手搓握手协议和 while True 死循环（Busy Wait），导致极其灾难的内存和 CPU 泄漏。
解法：
以老板的口吻严厉制止它的炫技行为！强制要求它引入工业级标准：import asyncio + websockets，把阻塞和心跳保活全权交给操作系统底层的事件循环去处理。
坑四：精简版 Docker 镜像里的“底层渗透”
表现： 让 AI 代码里写 os.system('pip install websockets')，结果报 No module named pip。
真相： OpenClaw Kernel 是极度精简的生产环境，出厂直接阉割了 pip，AI 自己根本装不上第三方库。
解法（上帝指令）：
机房管理员必须亲自下场，动用宿主机的 root 权限，穿透容器底层，用操作系统的包管理器强行把环境补齐！
Bash
docker exec -u root -it openclaw_kernel apt-get update
docker exec -u root -it openclaw_kernel apt-get install -y python3-pip python3-websockets python3-aiohttp
坑五：OpenClaw 的安全机制与“幽灵进程”
表现： Agent 在 Telegram 里告诉你“我已经在后台运行了命令”，然后突然假死不回话；或者 QQ 收到多条重复的测试回复。
真相：
OpenClaw 的 preflight 安全机制严格禁止 Agent 运行类似 cd xxx && python3 xxx & 的复合/后台命令，导致其卡死。
你多次测试跑的代码，因为没有正确退出，变成了“幽灵进程”躲在后台抢答。
解法：
让 AI 只写代码，别运行。代码写好后，由宿主执行“清道夫+上帝点火”流程：
Bash
1. 强制杀掉旧容器里的幽灵进程
docker restart openclaw_kernel
2. 注入环境变量，带 -d 参数静默后台运行最终版大脑
docker exec -d -e DEEPSEEK_API_KEY="sk-你的真实密钥" openclaw_kernel python3 /home/node/qq_ears_brain.py
坑六：大模型 API 的“慢性脑缺血”
表现： QQ 端总是回复“思考超时，请稍后再试”，但日志没有明显报错。
真相： Agent 写的异常捕获太好，掩盖了真相。实际上是因为：
DeepSeek 官方 API 已经去掉了 /v1，地址写错。
aiohttp 的默认请求超时（Timeout）太短，大模型生成硬核长文（如电机算法推演）需要 10~30 秒，直接被掐断。
解法：
修改 Python 脚本，将 API URL 改为 https://api.deepseek.com/chat/completions，并将 aiohttp.ClientTimeout(total=90) 设置为 90 秒。同时放宽 max_message_length = 4000，防止硬核长文被无情截断。
💡 终极架构代码速览 (qq_ears_brain.py 核心逻辑)
如果你也想写一个连接大模型的桥接器，以下是最稳健的逻辑框架：
Python
import asyncio
import websockets
import aiohttp
import json
import os
1. 全局配置与环境注入
API_KEY = os.environ.get("DEEPSEEK_API_KEY")
WS_URL = "ws://172.18.0.1:3001" # NapCat 容器网关
async def main():
# 2. 初始化 90 秒超长的异步 HTTP 会话
session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=90))
# 3. 连接全双工 WebSocket
async with websockets.connect(WS_URL, ping_interval=20) as ws:while True:# 4. 彻底告别死循环，优雅挂起等待消息msg = await ws.recv()data = json.loads(msg)# 5. 过滤掉心跳，只处理私聊if data.get("post_type") == "message":user_msg = data.get("raw_message")# 6. 调用 LLM 大脑 (带上 System Prompt 人设)# ... 发送 HTTP 请求到 DeepSeek ...# 7. 通过同一条 WS 专线将回复发回 QQawait ws.send(json.dumps({"action": "send_private_msg","params": {"user_id": data["user_id"], "message": llm_reply}}))
🎉 结语
不要畏惧排错，所有的报错日志都是通往完美的引路石。
在这个过程中，见识到了大语言模型的倔强（手搓底层协议）以及愚蠢（死循环占满 CPU）。但只要你以造物主和架构师的视角，辅以 Docker 容器的上帝权限进行调优，最终会得到一个令人惊叹的、全平台无缝衔接的 AI 赛博生命体。
Stay Hungry, Stay Hardcore. 🦞