1. 从单机 Agent 到 QQ 双端接管卡在哪一步OpenClaw Agent 本身跑起来不难Docker 一条命令就能把内核拉起来真正让人抓头的是「让它接管 QQ」这一段。OpenClaw 是一个带长期记忆、系统人设和本地工具链的 Agent 内核你可以把它理解成一个有脑子的管家而 QQ 只是它的一个新「耳朵和嘴巴」。问题在于QQ 不会说 Agent 的原生语言中间必须有一个协议翻译层把 QQ 的消息转成 Agent 能吃的输入再把 Agent 的输出塞回 QQ。我这次的目标很明确在一台 Linux 服务器上用 Docker 同时跑 OpenClaw Kernel 和 NapCatQQ通过 WebSocket 把两端接起来并且所有模型调用统一走 TaoToken 的 Key/API 通道不再手搓各家厂商的 API。适合谁看已经能把 OpenClaw 单机跑通、想让 QQ 也接进来的朋友或者你正在用 NapCatQQ 做机器人但发现消息发出去 Agent 不回、回了又是失忆复读机。整篇会交付三样东西一份可复制的config.toml骨架、一段 CC Switch 配置片段、以及连接验证和消息回环测试的具体动作。踩过的坑我也会按顺序列出来尤其是「文件覆盖陷阱」和「幽灵假死」这两个基本每个人都会遇到一次。2. TaoToken 前置统一 Key 与 API 通道在动手接 QQ 之前先把模型通道理顺。OpenClaw 的 Agent 能力依赖大模型如果你在桥接脚本里直接写死某家 API后面换模型、加并发、做多端共享都会很痛苦。TaoToken 在这里的角色就是统一网关一个 Key、一个 API 地址OpenClaw 和后续任何端都走同一条通道。你需要先拿到两样东西API Key在控制台的 API Keys 页面创建复制出来只显示一次建议直接写进环境变量而不是硬编码进脚本。API 地址https://taotoken.net/api注意这个地址不带任何查询参数配置里原样填。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite如果你还没决定用哪个模型可以先在模型对话页面试几条消息确认返回格式和延迟符合预期再写进配置模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite对于长期跑 Agent、要做编码或自动化任务的场景Coding Plan 更划算额度模型和按量计费不一样适合 24 小时挂着的管家型 AgentCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite接入文档建议开着配置字段对不上时随时查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite把 Key 写进环境变量后面 Docker 启动时注入export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api这样做的意义是OpenClaw Kernel 容器、桥接脚本、以后可能加的 Telegram 端全都读同一组环境变量换 Key 只改一处。3. 可复制配置config.toml 骨架与 CC Switch 片段3.1 Docker 网络与容器编排先建一个隔离但互通的网络NapCatQQ 和 OpenClaw Kernel 都挂上去容器之间用服务名互相访问不用记 IP。sudo docker network create openclaw-net # NapCatQQ 容器暴露 OneBot v11 的 WebSocket 端口 sudo docker run -d \ --name napcatqq \ --network openclaw-net \ -p 3001:3001 \ -v /root/napcat/config:/app/napcat/config \ --restart unless-stopped \ mlikiowa/napcatqq:latest # OpenClaw Kernel 容器 sudo docker run -d \ --name openclaw_kernel \ --network openclaw-net \ -e TAOTOKEN_API_KEY$TAOTOKEN_API_KEY \ -e TAOTOKEN_BASE_URL$TAOTOKEN_BASE_URL \ -v /root/openclaw/config:/home/node/.config/openclaw \ -v /root/openclaw/scripts:/home/node/scripts \ --restart unless-stopped \ openclaw/kernel:latest注意挂载点宿主机/root/openclaw/scripts对应容器内/home/node/scripts。这一点后面排障会重点讲因为很多人改了宿主机文件却忘了同步进容器。3.2 config.toml 骨架OpenClaw 的主配置放在/home/node/.config/openclaw/config.toml也就是宿主机/root/openclaw/config/config.toml。下面这份骨架可以直接抄字段按你的实际情况改[agent] name qq-butler persona 你是一个沉稳、简洁、带点冷幽默的私人管家回答尽量短。 memory_enabled true memory_path /home/node/.config/openclaw/memory.db max_context_tokens 32000 [model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 temperature 0.6 timeout_seconds 120 [channel.qq] enabled true protocol onebot-v11 ws_url ws://napcatqq:3001 access_token reconnect_interval 5 heartbeat_interval 30 self_id 0 [channel.qq.filter] private_enabled true group_enabled false group_at_only true [tools] shell_enabled true shell_workdir /home/node/scripts几个关键点解释一下。base_url填 TaoToken 的 API 地址api_key_env指向环境变量名而不是明文这样配置可以进版本管理。ws_url用的是 Docker 服务名napcatqq因为两个容器在同一网络里DNS 直接解析。self_id先留 0等 NapCat 登录后拿到真实 QQ 号再回填。3.3 CC Switch 配置片段CC Switch 用来在多个模型通道之间切换比如日常对话走一个模型、编码任务走另一个。它的配置文件通常和主配置同级片段如下[[cc_switch.profiles]] name default provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 [[cc_switch.profiles]] name coding provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 extra_headers { X-Task-Type coding } [cc_switch] active default fallback default两个 profile 都指向同一个 TaoToken 地址区别只在模型和附加头。切换时改active字段或者用命令行参数覆盖。这样 QQ 端和 Telegram 端可以共享同一套 profile人设和记忆自然就统一了。4. 验证请求与消息回环测试配置写完不代表通了必须做两步验证先确认模型通道能通再确认 QQ 消息能回环。4.1 模型通道验证先进容器用 curl 直接打 TaoToken 的接口确认 Key 和地址没问题sudo docker exec -it openclaw_kernel sh curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复两个字在线}] }返回里能看到choices[0].message.content是「在线」说明通道没问题。如果返回 401检查 Key 有没有正确注入容器返回 404检查base_url是不是多写了斜杠或路径。4.2 WebSocket 连接验证在容器里用 Python 快速测一下 NapCat 的 WebSocket 是否可达import asyncio, websockets, json async def probe(): uri ws://napcatqq:3001 async with websockets.connect(uri) as ws: print(WS connected) await ws.send(json.dumps({ action: get_login_info, params: {}, echo: probe-1 })) resp await asyncio.wait_for(ws.recv(), timeout10) print(resp:, resp) asyncio.run(probe())打印出WS connected并且 resp 里带user_id说明 NapCat 在线且协议正常。如果连接被拒检查 NapCat 容器是否真的在跑、3001 端口有没有被占用。4.3 消息回环测试最后一步用你的大号 QQ 给小号发一条消息观察桥接脚本的日志。桥接脚本的核心逻辑是收到 OneBot 事件 → 调用openclaw agent→ 把输出发回 QQ。关键代码片段import asyncio, json, websockets async def handle_message(event): user_msg event[raw_message] proc await asyncio.create_subprocess_exec( openclaw, --no-color, agent, --input, user_msg, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE ) stdout, stderr await proc.communicate() reply stdout.decode().strip() return reply async def main(): async with websockets.connect(ws://napcatqq:3001) as ws: while True: raw await ws.recv() event json.loads(raw) if event.get(post_type) message: reply await handle_message(event) await ws.send(json.dumps({ action: send_private_msg, params: { user_id: event[user_id], message: reply } })) asyncio.run(main())注意openclaw,--no-color,agent这个参数顺序--no-color必须紧跟在主程序后面、子命令之前位置错了会报unknown option。跑起来后大号发「你好」小号应该回一句带人设的回复日志里能看到完整的调用链。5. 本篇常见错排查5.1 改了脚本却不生效文件覆盖陷阱这是最高频的坑。你在宿主机/root/openclaw/scripts/下改了桥接脚本保存了重启容器结果跑的还是旧代码。原因是 Docker 容器是封闭的宿主机文件不会自动同步进容器除非你用挂载卷。即使挂了卷如果脚本路径写的是容器内另一个目录照样读不到。解法是每次改完执行「三件套」# 1. 把宿主机新文件塞进容器 sudo docker cp /root/openclaw/scripts/qq_ears_brain.py \ openclaw_kernel:/home/node/scripts/qq_ears_brain.py # 2. 重启容器清理旧进程 sudo docker restart openclaw_kernel # 3. 前台运行看日志确认没问题再放后台 sudo docker exec -it openclaw_kernel \ python3 /home/node/scripts/qq_ears_brain.py如果你用的是挂载卷而不是docker cp确认挂载路径和脚本实际读取路径完全一致大小写、斜杠都不能差。5.2 Agent 不回话参数顺序与安全机制表现是 Agent 假死日志里没有明显报错。两个原因一是openclaw命令的参数顺序错了--no-color放到了agent后面二是 OpenClaw 禁止 Agent 运行复合后台命令比如cmd1 cmd2 这种会被安全机制拦掉。解法参数严格按openclaw --no-color agent --input ...排列桥接脚本里不要拼 shell 复合命令用asyncio.create_subprocess_exec直接调可执行文件参数分开传。5.3 QQ 掉线「幽灵假死」终端打印了上线通知代码无报错但大号发消息小号不回。这是 NapCat 的本地 Token 还没过期所以不弹二维码也不报错但实际连接已经断了。解法是给桥接脚本加心跳检测超过heartbeat_interval没收到 pong 就主动重连async def heartbeat(ws): while True: await asyncio.sleep(30) try: await ws.send(json.dumps({action: get_status, params: {}})) except Exception: print(heartbeat failed, reconnecting...) return同时在 NapCat 配置里把reconnect_interval设短一点5 秒左右掉线后能快速恢复。5.4 模型返回 401 或超时401 一般是 Key 没注入容器用docker exec openclaw_kernel env | grep TAOTOKEN确认。超时则是timeout_seconds设太短长文本思考场景建议 120 秒起步。如果频繁超时检查是不是走了错误的base_urlTaoToken 的地址是https://taotoken.net/api不要多加/v1之外的路径。6. 接入与排障的下一步到这里OpenClaw Agent 接管 QQ 的链路应该已经跑通了Docker 网络隔离互通、NapCat 负责 QQ 协议、桥接脚本做翻译、TaoToken 统一模型通道。接下来如果你要扩展方向无非是加群聊、加多账号、或者把 Telegram 端也接进来共享同一份记忆。排障和接入相关的入口我集中放一下配置对不上时直接查文档最快API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你还在验证模型阶段先用模型对话跑几条真实消息确认返回稳定再写进config.toml模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite长期挂着做编码或自动化任务的Coding Plan 的额度模型更适合 24 小时 AgentCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后提醒一句桥接脚本里所有模型调用都走环境变量里的 TaoToken 地址不要图省事硬编码 Key 进脚本容器重建时你会感谢自己。
