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_49****41.json。将network字段补全必须将host设置为0.0.0.0允许 Docker 跨容器访问。坑二Docker 的“铜墙铁壁”放弃 HTTP拥抱 WS表现配置文件已经改了 0.0.0.03001(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 asynciowebsockets把阻塞和心跳保活全权交给操作系统底层的事件循环去处理。坑四精简版 Docker 镜像里的“底层渗透”表现让 AI 代码里写os.system(pip install websockets)结果报No module named pip。真相OpenClaw Kernel 是极度精简的生产环境出厂直接阉割了pipAI 自己根本装不上第三方库。解法上帝指令机房管理员必须亲自下场动用宿主机的root权限穿透容器底层用操作系统的包管理器强行把环境补齐Bashdocker 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_KEYsk-你的真实密钥 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(total90)设置为 90 秒。同时放宽max_message_length 4000防止硬核长文被无情截断。 终极架构代码速览 (qq_ears_brain.py 核心逻辑)如果你也想写一个连接大模型的桥接器以下是最稳健的逻辑框架Pythonimport 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(timeoutaiohttp.ClientTimeout(total90)) # 3. 连接全双工 WebSocket async with websockets.connect(WS_URL, ping_interval20) 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 专线将回复发回 QQ await ws.send(json.dumps({ action: send_private_msg, params: {user_id: data[user_id], message: llm_reply} }))
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_49****41.json。将network字段补全必须将host设置为0.0.0.0允许 Docker 跨容器访问。坑二Docker 的“铜墙铁壁”放弃 HTTP拥抱 WS表现配置文件已经改了 0.0.0.03001(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 asynciowebsockets把阻塞和心跳保活全权交给操作系统底层的事件循环去处理。坑四精简版 Docker 镜像里的“底层渗透”表现让 AI 代码里写os.system(pip install websockets)结果报No module named pip。真相OpenClaw Kernel 是极度精简的生产环境出厂直接阉割了pipAI 自己根本装不上第三方库。解法上帝指令机房管理员必须亲自下场动用宿主机的root权限穿透容器底层用操作系统的包管理器强行把环境补齐Bashdocker 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_KEYsk-你的真实密钥 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(total90)设置为 90 秒。同时放宽max_message_length 4000防止硬核长文被无情截断。 终极架构代码速览 (qq_ears_brain.py 核心逻辑)如果你也想写一个连接大模型的桥接器以下是最稳健的逻辑框架Pythonimport 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(timeoutaiohttp.ClientTimeout(total90)) # 3. 连接全双工 WebSocket async with websockets.connect(WS_URL, ping_interval20) 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 专线将回复发回 QQ await ws.send(json.dumps({ action: send_private_msg, params: {user_id: data[user_id], message: llm_reply} }))
