QQ 机器人接入

使用 QQ 官方机器人 Agent 通道。CyberCode 主动连接官方 WebSocket Gateway，不需要公网回调。

1. 扫码绑定（推荐）

1. 打开 设置 -> IM 接入 -> QQ。
2. 点击「扫码连接」。
3. 使用手机 QQ 扫描二维码，按手机页面完成机器人绑定。
4. CyberCode 收到官方返回的 AppID/Secret 后，会写入仅本机使用的配置，在 UI/API 中脱敏显示，并自动启动通道。

扫码账号会自动配对，无需再输入 6 位配对码。

2. AppID/Secret 手动兜底

扫码功能不可用时：

1. 打开 QQ 开放平台，创建并配置官方机器人。
2. 在 CyberCode QQ 面板的「或手动填写官方凭据」中输入 App ID 和 App Secret。
3. 点击保存。首次填写完整凭据时，通道会自动启用。
4. 在桌面端生成配对码，然后通过 QQ 私聊发送给机器人。

3. 私聊与群聊

• 私聊默认可用。
• 「响应 QQ 群消息」默认开启，只处理 QQ 官方 Gateway 推送给机器人的群消息。
• 不需要配置 HTTP 回调 URL，也不需要穿透本机端口。

4. 权限与附件

CyberCode 需要执行受控工具时，QQ 会显示「允许一次 / 始终允许 / 拒绝」按钮。按钮不可用时也可以回复 /allow <编号> 或 /deny <编号>。

QQ 推送的图片会作为图片附件发给当前模型；其他文件会下载到 ~/.cyber/im-downloads/qq/ 后以本地路径交给 Agent。语音有官方 ASR 文本时会一并传入会话。

常见问题

凭据保存后没有回复

先在 QQ 中发送 /status。如果仍无回复，检查开放平台中机器人是否已发布，App Secret 是否有效，以及当前 QQ OpenID 是否已配对。

群里不响应

确认「响应 QQ 群消息」已开启，机器人已加入目标群，并且官方平台已为该机器人开通相应事件权限。