OpenClaw 接入 QQ 完全指南：TaoToken 统一 Key 配置与 NapCat WebSocket 验证

1. 为什么要在 QQ 里跑一个 AI 助手OpenClaw 是一个支持多渠道消息接入的 AI Agent 框架NapCat 是基于 NTQQ 的 QQ 机器人框架两者通过 WebSocket 对接后你的 QQ 私聊就能直接和 AI 对话。这套组合适合想搭建私人 AI 助手的开发者不用公网服务器、不用备案域名本地跑起来就能用。而模型调用这一层我用 TaoToken 的统一 Key 来收口——一个 Key 同时驱动对话模型和编码模型省得在 OpenClaw 的 config.toml 里塞好几家厂商的密钥。整条链路是这样的QQ 消息 → NapCatWebSocket 服务端→ OpenClaw 的 QQ 通道插件 → OpenClaw Gateway → AI Agent → 原路返回。本文按这条链路从 TaoToken 拿 Key 开始到 NapCat 反向 WS 配置、OpenClaw 的 config.toml 骨架最后用一条真实消息做端到端验证。全程命令可直接复制踩坑点我会单独标出来。2. TaoToken 前置统一 Key 与模型入口TaoToken 在这里的角色是模型网关。OpenClaw 的 Agent 需要调用大模型与其在配置里分别填 Anthropic、OpenAI 的地址和密钥不如统一走 TaoToken 的 API 端点一个 Key 管所有模型。对 QQ 助手这种场景很实用白天用对话模型陪聊晚上切编码模型帮你写脚本改的只是 config.toml 里一行 model 字段。先拿 Key。打开控制台登录后在 API Keys 页面创建一个新 Key复制出来只显示一次丢了就重建。地址是 https://taotoken.net/api 注意这个端点不带任何查询参数直接作为 base_url 用。模型选择上日常对话用 claude-sonnet 系列响应快、语气自然需要长上下文或复杂推理时换更强的型号。如果你打算让这个 QQ 助手长期挂着跑编码任务可以了解下 Coding Plan额度模型更适合高频调用。想先试试模型效果模型对话页面可以直接在线验证不用写代码。注意Key 属于敏感凭证别写进会提交到 Git 的配置文件里。下面 config.toml 里我用环境变量占位实际部署时用export注入。3. 可复制配置NapCat 反向 WS OpenClaw config.toml3.1 安装 QQ 通道插件OpenClaw 侧先装插件一条命令openclaw plugins install izhimu/qq装完确认版本OpenClaw 本体要求 2026.2.1 以上openclaw --version3.2 NapCat 开启 WebSocket 服务NapCat 的配置文件位置按系统区分# Linux ~/.config/NapCat/config/config.yml # Windows %APPDATA%\NapCat\config\config.yml编辑 config.yml启用 WS 服务并设置 token。这里配的是 NapCat 作为服务端监听OpenClaw 作为客户端连过来ws: servers: - url: ws://0.0.0.0:3001 token: your-napcat-token enableHeart: true0.0.0.0表示监听所有网卡本机自用改成127.0.0.1更安全。token 自己设一个随机串后面 OpenClaw 要填一样的值。改完重启 NapCat 生效。3.3 OpenClaw 的 config.toml 骨架OpenClaw 支持交互式配置但手动写 config.toml 更可控。完整骨架如下重点看 channels.qq 和 agents 两段[channels.qq] wsUrl ws://127.0.0.1:3001 accessToken your-napcat-token enabled true [agents.assistant] provider taotoken baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} model claude-sonnet-4-5-20250929 systemPrompt 你是一个友好专业的 AI 助手回答简洁准确语气自然。 [routing] qq:private:* assistant几个关键点wsUrl必须和 NapCat 里配的地址端口一致accessToken填 NapCat 那个 token两边不匹配会直接握手失败apiKey用${TAOTOKEN_API_KEY}引用环境变量启动前先export TAOTOKEN_API_KEY你的Keyrouting里qq:private:*把所有私聊消息路由到 assistant 这个 Agent。如果你更习惯向导式配置跑openclaw onboard按提示填也行生成的字段和上面一一对应。3.4 启动 Gatewayopenclaw gateway restart重启后 Gateway 会读取 config.toml主动去连 NapCat 的 WS 端口。4. 验证请求一条消息从 QQ 到 AI 回复配置写完别急着庆祝先做端到端验证。分三步。第一步确认 NapCat 的 WS 服务活着curl http://localhost:3001/get_status返回 JSON 里 status 为 ok 就说明服务端正常。第二步看 OpenClaw 的 QQ 通道有没有连上openclaw channels输出里 qq 通道状态应该是 connected。如果是 disconnected直接看日志openclaw logs --channel qq --verbose第三步真实发消息。用另一个 QQ 号给你的机器人发一条私聊比如「你好帮我算下 23 乘 47」。正常的话几秒内会收到 AI 回复。如果没反应用命令行主动发一条测试openclaw message send 测试消息 --to qq:private:123456789目标格式是qq:private:QQ号冒号别写错。带图片的消息加--media参数openclaw message send 看这张图 --to qq:private:123456789 --media https://example.com/image.jpg实测下来从 QQ 发出到收到回复本地链路延迟通常在 2 到 5 秒取决于模型响应速度。如果超过 30 秒没动静基本可以判定是连接或鉴权问题往下看排查。5. 本篇常见错排查连接类问题占九成。最常见的是 wsUrl 和 NapCat 配置对不上——NapCat 监听 3001OpenClaw 却连 3000握手直接失败。其次是 token 不匹配NapCat 设了 token 但 OpenClaw 的 accessToken 留空或者反过来。这两个字段必须完全一致。现象可能原因处理方式通道一直 disconnectedwsUrl 端口写错核对 NapCat config.yml 与 config.toml握手失败 401accessToken 不一致两边 token 改成同一个值消息发出无回复routing 未命中检查qq:private:*拼写模型报鉴权错误TaoToken Key 无效重新生成 Key 并 export图片发送失败URL 不可公网访问换可访问的图片地址模型侧报错单独说下。如果日志里出现 401 或 invalid api key是 TaoToken 的 Key 没生效确认环境变量在当前 shell 里echo $TAOTOKEN_API_KEY有值。如果报 model not found检查 model 字段拼写别把日期后缀写错。想快速确认 Key 和模型是否可用去模型对话页面发一条消息能正常回就说明 Key 没问题问题在 OpenClaw 配置侧。还有一个隐蔽的坑NapCat 重启后 token 如果重新生成OpenClaw 侧不会自动更新需要手动改 config.toml 再openclaw gateway restart。建议 token 设成固定值别用随机生成。6. 把 Key 和接入文档收进工具箱链路跑通后日常维护主要盯两件事NapCat 的 WS 连接状态和 TaoToken 的额度消耗。前者用openclaw channels一眼看后者在控制台看用量。如果你要把这个 QQ 助手长期挂着建议把 Key 管理、模型切换、额度监控都收口到 TaoToken 一处省得散落在多个配置文件里。接入过程中遇到鉴权或通道配置问题直接翻接入文档对照字段需要新建或轮换 Key去 API Keys 页面操作想先验证模型输出质量再决定用哪个型号模型对话页面最省事。长期跑编码类 Agent 的话Coding Plan 的额度模型比按次调用更划算。整套配置的核心就一句话NapCat 管 QQ 连接OpenClaw 管消息路由TaoToken 管模型调用三层各司其职出问题按层排查就不会乱。