1. 为什么我要把 OpenClaw 接到 QQ 上OpenClaw 是一个开源的本地 AI 助手网关它把大模型的推理能力和本机的文件读写、脚本执行、浏览器控制串在一起让你用聊天的方式指挥电脑干活。它默认自带 Web UI 面板也支持 Telegram、Discord 这类海外渠道但国内开发者最顺手的入口其实是 QQ——不用额外装客户端手机和桌面端都能收发消息群聊里 一下就能触发任务。所以「OpenClaw 接入 QQ」这件事本质上是给你的本地 Agent 换一个更贴近日常的遥控器。这篇内容适合三类人一是已经在本地跑通 OpenClaw、想让它在 QQ 里回消息的开发者二是想基于官方 QQ 机器人通道做插件化定制的团队三是 WebSocket 连接老断、想搞清楚重连和心跳怎么配的运维同学。我会从官方方案讲起再往下走到插件改造和连接优化每一步都给可复制的配置和验证命令。先说清楚 OpenClaw 的架构不然后面配置容易懵。它采用「网关-节点」解耦Gateway 是常驻的 WebSocket RPC 服务默认监听 18789 端口负责路由消息、管理并发会话、调用 LLM APIWeb UI 面板在 18790。Agent Runner 是执行引擎解析模型输出的指令去跑 Shell、开浏览器。Skills 是脚本形式的扩展模块Channels 就是多渠道集成层QQ 接入就是往这一层加一个 channel。我试过直接拿个人号协议去接短期能跑但稳定性完全看第三方框架脸色消息丢包和掉线是常态。所以下面主线走腾讯官方给 OpenClaw 开放的 QQ 机器人通道它用标准 WebSocket 长连接凭证走 AppID AppSecret合规性和稳定性都更可控。第三方方案我会在排障章节提一下差异方便你判断要不要换。2. 接入前的环境准备与 TaoToken 配置官方通道对运行环境有硬性要求先对齐版本再动手能省掉一半的玄学报错。OpenClaw 需要 2026.1.30 或更高版本Node.js 要 22 以上服务器得有公网 IP因为 QQ 开放平台要配 IP 白名单。QQ 号需要完成实名认证个人主体用身份证企业主体用营业执照。服务器我建议 2 核 4G、50G SSD 起步系统用 Ubuntu 22.04 LTS跑一个常驻网关加几个 Agent 会话足够。模型侧我走的是 TaoToken 的 API它兼容 OpenAI 风格的接口OpenClaw 里配置 base_url 和 key 就能用。官网在 https://taotoken.net API 入口是 https://taotoken.net/api 。你需要先去控制台建一个 API Key路径是 https://taotoken.net/console/api-keys 拿到 key 之后填进 OpenClaw 的模型配置。如果你还没决定用哪个模型可以先去模型对话页 https://taotoken.net/models 试一下响应风格再决定给 QQ 机器人挂哪个模型。这里有个容易踩的坑OpenClaw 的模型配置和渠道配置是两套东西。模型配置决定「谁来思考」渠道配置决定「消息从哪来」。很多人 QQ 那边配好了却收不到回复其实是模型 API 没通。所以先把模型跑通再配 QQ 渠道顺序别反。环境变量建议统一管理别把密钥硬编码进配置文件。可以在~/.openclaw/.env里写# ~/.openclaw/.env TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api QQ_APP_ID你的AppID QQ_APP_SECRET你的AppSecret然后在openclaw.json里用${TAOTOKEN_API_KEY}这种占位符引用。这样换 key 不用改主配置也方便做密钥轮换。Node 版本用node -v确认低于 22 的话用 nvm 升一下别用系统自带的旧版本插件安装阶段会报奇怪的语法错误。3. 可复制的 QQ 渠道配置与插件安装官方通道的接入分两步先在 QQ 开放平台建机器人拿凭证再在 OpenClaw 里装插件、加渠道。开放平台入口是 https://q.qq.com/qqbot/openclaw/login.html 用手机 QQ 扫码登录首次要完成实名和人脸核身。登录后在控制台点「创建机器人」填名称和功能描述回调地址留空——因为 OpenClaw 走的是 WebSocket 主动连接不需要 HTTP 回调。创建完拿到 AppID 和 AppSecretAppSecret 只显示一次务必先存进密码管理器。接着装插件。OpenClaw 的插件体系是 npm 包形式QQ 渠道插件包名是sliverp/qqbot# 安装 QQ 渠道插件 openclaw plugins install sliverp/qqbotlatest # 添加 QQ 渠道token 填 AppSecret openclaw channels add --channel qqbot --token $QQ_APP_SECRET # 重启网关让配置生效 openclaw gateway restart命令行方式适合快速验证但要做深度定制还是得改配置文件。编辑~/.openclaw/openclaw.json把 QQ 渠道的完整参数写进去{ channels: { qq: { enabled: true, appId: 你的QQ机器人AppID, appSecret: 你的QQ机器人AppSecret, token: 你的QQ机器人Token, sandbox: true, allowPrivateChat: true, allowGroupAt: true, reconnect: { enabled: true, maxRetries: 10, intervalMs: 5000 }, heartbeat: { enabled: true, intervalMs: 30000 } } }, models: { default: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: 你的模型ID } } }注意sandbox先设 true在沙箱环境里测通了再切生产。allowGroupAt控制群里是否需要 才响应建议先开着避免机器人在群里刷屏。reconnect和heartbeat是 WebSocket 保活的关键后面第五节会展开。配完还要去开放平台加 IP 白名单否则连接会被拒。拿公网 IPcurl ifconfig.me把结果填进机器人管理页的「开发管理 - IP 白名单」。然后测一下到 QQ 服务器的连通性telnet q.qq.com 443 sudo ufw status如果 telnet 不通先查防火墙和安全组443 出站必须放行。这一步做完基础接入就齐了。4. 验证请求与连接状态确认配置写完不代表通了得用日志和状态命令确认。OpenClaw 提供了logs和status两个命令前者看实时输出后者看渠道健康度# 实时看最近 100 行日志 openclaw logs --tail 100 # 查看 QQ 渠道连接状态 openclaw status --channel qq正常连上后日志里会出现 WebSocket 握手成功的记录类似qqbot channel connected, session established。如果卡在connecting或者反复reconnect多半是凭证或白名单问题对照第五节排查。沙箱测试阶段去开放平台的「开发管理 - 沙箱配置」选「在消息列表配置」把测试成员的 QQ 号加进去然后生成绑定二维码用测试号扫码添加机器人。当前沙箱主要支持私聊模式群聊要等正式发布后开。扫码成功后给机器人发一条消息比如「列出当前目录文件」看它能不能触发 Agent 执行并回消息。模型侧单独验证一下确认 TaoToken 的 key 和 base_url 没问题curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: ping}] }返回里有choices字段就说明模型通道正常。如果这里就报 401那 QQ 那边再怎么配也没用先把 key 和 base_url 对齐。验证顺序永远是模型 API 通 - 网关起来 - QQ 渠道连上 - 消息能触发 Agent。5. 常见报错排查401、local proxy failed 与连接断开排障这块我按真实报错来对你遇到哪个直接查哪个。401 Unauthorized出现在模型调用或 QQ 凭证校验。模型侧先确认TAOTOKEN_API_KEY有没有正确注入.env文件有没有被加载base_url 是不是https://taotoken.net/api而不是带/v1的变体。QQ 侧 401 通常是 AppSecret 填错或过期去开放平台重新生成再更新配置。注意 AppSecret 不支持明文保存改完记得重启网关。local proxy failed这个报错一般是 OpenClaw 尝试走本地代理转发但代理没起来或者环境变量里残留了HTTP_PROXY之类的设置。检查env | grep -i proxy把不需要的代理变量清掉。如果你在容器里跑确认容器网络能直连外网别让 DNS 解析卡住。reading choices 报错模型返回体里没有choices字段通常是 base_url 指错了端点或者模型 ID 写错。用第四节的 curl 单独测一次确认返回结构。如果 curl 正常但 OpenClaw 报这个错检查配置文件里modelId和baseUrl有没有被其他配置覆盖。OAuth 相关报错QQ 开放平台登录态过期或 scope 不足。重新扫码登录开放平台确认机器人权限里勾了消息收发。OpenClaw 侧如果用了 OAuth 流程检查 token 刷新逻辑别让过期 token 卡住连接。WebSocket 频繁断开先看心跳有没有开。QQ 服务端对空闲连接有超时限制heartbeat.intervalMs设 30000 比较稳。再看reconnect配置maxRetries给 10 次、间隔 5 秒避免网络抖动直接放弃。如果还是断检查服务器出口带宽和 NAT 超时云服务器默认 NAT 表可能几分钟就回收空闲连接心跳能有效对抗这个。插件安装失败多半是 Node 版本不对或 npm 源慢。确认node -v是 22然后换源重试npm config set registry https://registry.npmmirror.com openclaw plugins install sliverp/qqbotlatest如果还失败手动下载插件包解压到~/.openclaw/plugins/下再重启网关。消息发出但机器人不回先看openclaw logs里有没有收到消息事件。收到了但没回复是模型调用超时或 Agent 执行卡住调大超时时间、简化提示词。没收到消息事件是 QQ 侧推送没到检查沙箱成员配置和 IP 白名单。6. 插件化定制与 WebSocket 通信优化基础接入跑通后真正的价值在定制。OpenClaw 的 Skills 机制允许你用 Python、Node.js 或 Shell 写扩展脚本QQ 渠道收到消息后会按路由规则分发给对应 Skill。比如你想让机器人在群里被 时查天气、私聊时执行本地脚本可以写一个消息处理器// ~/.openclaw/skills/qq-router/index.js class QQMessageProcessor { constructor() { this.queue []; this.processing false; this.batchSize 10; this.timeout 100; } async processBatch(messages) { // 按消息类型分流群聊走轻量模型私聊走完整 Agent const grouped messages.reduce((acc, msg) { const key msg.isGroup ? group : private; (acc[key] acc[key] || []).push(msg); return acc; }, {}); return await openclaw.batchProcess(grouped); } }流式响应在 QQ 场景下体验提升明显长回答不用等整段生成完再发。在配置里开 streaming{ gateway: { streaming: { enabled: true, chunkSize: 1024, timeout: 30000 } } }WebSocket 连接池是稳定性的关键。单连接在高并发下容易排队用连接池管理多路复用const wsPool new WebSocketPool({ maxConnections: 10, idleTimeout: 30000, reconnectInterval: 5000 });安全侧建议开限流和密钥轮换。限流防止机器人被刷{ security: { rateLimit: { enabled: true, maxRequests: 100, windowMs: 60000 } } }密钥轮换用 cron 每月跑一次脚本更新 AppSecret更新后重启网关。监控方面OpenClaw 暴露/metrics端点Prometheus 抓一下就能看连接数、消息吞吐、模型延迟。日志用 Filebeat 收集到 ELK排障时按 session id 串起来看。如果你打算长期跑编码类或 Agent 类任务可以考虑 Coding Plan它在长会话和并发上更省心入口在 https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 里面有各渠道的完整参数说明。Claude Code 相关的接入配置也可以参考文档里的 Anthropic 兼容章节。最后给个实用建议把 QQ 渠道的配置和模型配置分开管理用环境变量注入密钥配置文件进版本控制但密钥不进。这样换服务器、做灰度、回滚都干净。连接稳定性上心跳和重连是底线别省这两个配置。