NanoClaw NapCat QQ：为 NanoClaw v2 接入 QQ 渠道

私聊与群聊接入#

支持 QQ 私聊和群聊消息，分别使用 private:<QQ号> 与 group:<群号> 标识会话。私聊与群聊沿用 NanoClaw 的渠道访问规则，未知发送者采用严格策略；群聊以真正 @ 机器人作为触发条件。

安装时可以将个人 QQ 绑定到指定 agent，并授予普通成员访问权限。群聊需要单独绑定，避免把机器人加入群聊后就直接开放访问。

图文消息与引用上下文#

将 OneBot 消息段转换为 NanoClaw 的文字、图片附件和引用信息，并把 agent 的输出转换回 QQ 消息：

• 识别文字、@、图片与引用消息。
• 下载并校验入站图片，支持 PNG、JPEG、GIF 和 WebP，限制单张图片大小为 20 MiB。
• 通过 get_msg 补充被引用消息的发送者和文字；查询失败时保留引用 ID。
• 图片读取失败时保留“图片不可用”提示，使同条消息的文字仍可继续处理。

文字选项交互#

将 NanoClaw 的选项问题转为带编号的文字消息，用户通过 /nc-answer <问题ID> <选项序号> 回复，再由适配器回传对应选项及会话信息。

对于卡片内容，优先使用文字回退。由于 OneBot 不提供文字消息编辑接口，终态更新会作为新消息发送。

自动安装与部署#

提供 setup 脚本，自动部署 NapCat Docker、生成连接配置并安装宿主渠道。已有 NapCat 的用户可以选择外部实例模式，复用现有部署。

NapCat 的登录状态和配置保存在宿主的 data/napcat/ 下。WebUI 默认仅允许本机访问；远程部署可以通过 SSH 端口转发完成扫码登录。项目同时提供中英文 README、环境变量示例与卸载说明。

连接与消息处理#

连接建立时校验 Bearer Token、机器人 QQ 号和客户端角色，并通过 get_login_info 再次确认账号。API 调用使用独立的 echo 关联请求与响应，待处理请求绑定到具体 WebSocket；连接断开或被替换时及时拒绝请求，避免旧连接的响应混入新会话。

入站消息按队列串行处理，设置队列长度上限，并在有限时间窗口内去重。连接层通过心跳检查存活状态，消息层则为图片下载设置超时、重定向次数和大小限制，控制异常消息带来的资源消耗。