若WorkBuddy接入QQ后无响应，需依次检查：一、回调地址配置与验证状态；二、事件订阅是否包含MESSAGE_CREATE等基础类型；三、QQ账号与WorkBuddy绑定关系是否生效；四、本地端口占用及通信阻断；五、强制刷新Token与Webhook密钥。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您已成功将WorkBuddy接入QQ，但未收到任何消息或指令无响应，则可能是由于回调配置异常、事件订阅缺失、网络验证失败或权限未生效所致。以下是解决此问题的步骤：
一、检查QQ机器人回调地址配置与验证状态
WorkBuddy依赖QQ开放平台通过HTTPS回调地址向本地服务推送事件（如用户发消息、加好友、拉群等），若回调地址未正确配置或未通过签名验证，所有消息将无法抵达WorkBuddy进程。
1、登录QQ机器人开放平台，进入对应机器人的管理页。
2、在“机器人设置”中确认已填写有效的HTTPS回调地址，且端口为80、443、8080或8443之一。
3、点击“验证回调地址”，确保平台返回“验证成功”；若失败，需检查本地服务是否运行、SSL证书是否有效、防火墙是否放行对应端口。
4、确认回调请求头中包含X-Union-Appid与X-Signature字段，且WorkBuddy服务端已启用签名验签逻辑。
二、核对已订阅的事件类型是否覆盖基础交互
QQ仅向开发者推送明确勾选的事件类型，若未订阅MESSAGE_CREATE（私聊/群聊消息）或AT_MESSAGE_CREATE（@机器人消息），WorkBuddy将完全收不到用户输入。
1、在QQ开放平台机器人管理页，进入“事件订阅”模块。
2、勾选以下必需事件：MESSAGE_CREATE、AT_MESSAGE_CREATE、GUILD_MEMBER_ADD（如需群内欢迎语）。
3、保存后点击“启用事件订阅”，等待平台显示“已启用”状态。
4、在WorkBuddy日志中观察是否出现t: "MESSAGE_CREATE"或t: "AT_MESSAGE_CREATE"的原始payload接收记录。
三、验证QQ账号与WorkBuddy绑定关系是否生效
一个QQ号最多可创建5个机器人，但每个机器人必须独立绑定至OpenClaw运行环境；若绑定未完成或绑定ID错配，消息路由将中断。
1、打开WorkBuddy客户端，点击右上角头像，进入“Claw Settings”。
2、在QQ配置项中，确认已填入与QQ开放平台一致的App ID和App Secret。
3、检查“绑定状态”是否显示为已连接；若为“未授权”或“令牌过期”，需重新触发OAuth2.0授权流程。
4、在QQ中向该机器人发送任意文字（如“你好”），观察WorkBuddy界面右下角是否弹出实时任务提示。
四、排查本地服务端口占用与跨域通信阻断
WorkBuddy默认监听本地回环地址（127.0.0.1）的指定端口用于接收QQ回调；若端口被占用、系统代理拦截或安全软件阻止，会导致HTTP请求静默丢弃。
1、在命令行执行netstat -ano | findstr :8080（假设使用8080端口），确认无其他进程占用该端口。
2、临时关闭Windows Defender防火墙或第三方安全软件，测试消息是否恢复。
3、检查WorkBuddy启动日志中是否存在Server started on http://127.0.0.1:8080及后续Received POST /callback记录。
4、若使用Nginx或frp做反向代理，需确保Content-Type: application/json头未被篡改，且Transfer-Encoding: chunked兼容正常。
五、强制刷新QQ侧机器人Token与重置Webhook密钥
QQ平台会定期轮换Webhook签名密钥，且Token存在有效期；若长期未操作，旧凭证可能失效，导致回调被拒绝。
1、在QQ开放平台机器人管理页，进入“密钥管理”模块。
2、点击“重新生成密钥”，获取新的Webhook Secret，并同步更新至WorkBuddy的Claw Settings中。
3、在“机器人凭证”区域，点击“刷新Access Token”，复制新Token粘贴至WorkBuddy配置项对应字段。
4、重启WorkBuddy客户端，观察初始化日志中是否打印Token refreshed与Webhook secret loaded标识。
