WorkBuddy接入QQ失败需按四步排查：一、刷新AppID/Token/Secret并重启服务；二、遇WebSocket错误4006需强制IDENTIFY；三、确认OpenClaw服务运行、端口18789开放且配置公网地址；四、在QQ平台启用GUILD_MESSAGES等必要Intent权限。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试将WorkBuddy接入QQ平台，但机器人连接失败或指令无响应，则可能是由于认证信息失效、WebSocket连接中断、协议配置错误或服务端未正确监听所致。以下是解决此问题的步骤：
一、检查并刷新QQ机器人认证凭证
QQ频道开放平台对机器人身份采用AppID、Token与Secret三元组校验，任一参数过期或不匹配均会导致接入失败。平台可能因安全策略自动轮换Token，旧配置将立即失效。
1、登录QQ频道开放平台开发者中心，进入对应机器人的管理页面。
2、在“机器人设置”或“基础信息”页中，查找“重新生成Token”按钮并点击执行。
3、复制新生成的AppID、Token和AppSecret，确保字符完整无空格、无换行。
4、在WorkBuddy配置文件（如config.yaml或环境变量）中，覆盖原有凭证字段。
5、保存配置后，必须重启WorkBuddy服务进程，否则新凭证不会加载。
二、验证WebSocket连接状态与重连机制
WorkBuddy通过WebSocket与QQ频道网关建立长连接，若遭遇4006（无效session id）、4009（连接过期）或4900–4913类内部错误，需触发主动重连流程，而非等待自动恢复。
1、在WorkBuddy日志中搜索关键词websocket error或opcode 4006，确认具体错误码。
2、若日志出现4006 invalid session id，说明resume失败，必须强制触发IDENTIFY流程，不可尝试resume。
3、检查WorkBuddy启动参数是否包含--force-identify或配置项connection.force_identify: true。
4、手动终止当前进程，添加该参数后重新启动。
5、观察日志是否输出IDENTIFY sent及后续READY received事件。
三、校验OpenClaw协议绑定与端口映射
WorkBuddy需通过OpenClaw协议与QQ机器人通信，若本地OpenClaw服务未运行或端口未暴露，QQ指令无法路由至WorkBuddy执行引擎。
1、在服务器终端执行systemctl status openclaw，确认服务状态为active (running)。
2、若服务未运行，执行systemctl start openclaw并启用开机自启：systemctl enable openclaw。
3、检查OpenClaw监听端口，默认为18789，运行netstat -tuln | grep 18789确认端口处于LISTEN状态。
4、若使用云服务器（如腾讯云Lighthouse），必须在安全组中放行18789端口的TCP入站规则。
5、在WorkBuddy配置中核对openclaw.endpoint地址，确保为可被QQ网关访问的公网IP或域名，而非localhost:18789。
四、排查QQ频道Intent权限与事件订阅
QQ机器人需显式声明所需接收的事件类型（即Intents），若缺失GUILD_MESSAGES或MESSAGE_CONTENT等关键Intent，将无法接收到用户指令。
1、返回QQ频道开放平台，在机器人“权限管理”页中，勾选接收消息内容、发送消息、管理频道三项基础权限。
2、在“事件订阅”配置页中，确保已启用消息事件、互动事件，并保存提交。
3、检查WorkBuddy初始化时传入的Intent数值，国内版应至少包含1 （对应GUILD_MESSAGES与MESSAGE_CONTENT）。
4、若使用低代码部署包，需确认安装包版本不低于v2026.3.8，此前版本默认禁用MESSAGE_CONTENT Intent。
5、完成配置后，在QQ频道中@机器人发送测试消息，观察WorkBuddy日志是否打印on_message_create事件。
五、隔离网络策略与DNS解析异常
部分企业网络或校园网存在SNI拦截、WebSocket协议阻断或DNS污染，导致WorkBuddy无法完成QQ网关的TLS握手或域名解析。
1、在服务器执行curl -v https://api.sgroup.qq.com，验证能否成功建立HTTPS连接并返回HTTP 200。
2、若超时或报错SSL connect error，尝试更换DNS为119.29.29.29或223.5.5.5并刷新解析缓存：systemd-resolve --flush-caches。
3、运行tcpdump -i any port 443 -w qq_debug.pcap抓包，过滤目标域名流量，确认是否有SYN发出但无SYN-ACK返回。
4、若确认网络层受限，临时切换至4G热点或家庭宽带环境进行对比测试，以排除本地策略干扰。
5、抓包确认连接正常后，再执行node_modules/.bin/openclaw doctor --fix运行自动化诊断脚本。
