接入 QQ 机器人
一体化智能体运行与协同平台（AgentWorks）的 QQ 渠道账号通过 WebSocket C2C 链路接收机器人单聊消息；当前配置入口不提供 Webhook 回调或群聊设置。
确认 QQ 机器人支持 WebSocket 接入
在 QQ 开放平台确认目标机器人仍提供 WebSocket Gateway。只有同时满足以下条件时才继续：
- QQ 开放平台中的目标机器人仍允许使用 WebSocket Gateway。
- 该机器人可以订阅或接收
C2C_MESSAGE_CREATE单聊事件。 - 平台运行环境的出口 IP 已加入 QQ 开放平台为目标机器人配置的白名单。
如果新机器人只提供 Webhook 回调配置，AgentWorks QQ 渠道无法接入。不要把 Webhook 地址填写到其他字段，也不要把第三方 OneBot 接口当作本产品的 QQ 渠道。
准备 QQ 机器人
- 在 QQ 机器人开放平台创建机器人并取得 Bot AppID 和机器人密钥。
- 在上线前，把测试 QQ 账号加入机器人沙箱成员。
- 启用 C2C 单聊消息事件。
- 如果开放平台要求出口 IP 白名单，向 AgentWorks 平台管理员取得 AgentWorks 平台的稳定公网出口 IP 并加入白名单。
- 确认机器人在目标环境中已启用。
AgentWorks 不需要也不会显示 QQ 回调 URL。平台运行环境必须能够访问 QQ Gateway。
创建 QQ 渠道账号
按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。
打开 渠道账号。
也可以从控制台左侧导航进入 渠道账号。
选择 新建账号，在 渠道类型 中选择 QQ。
填写 账号名称、应用 ID（凭证）和应用密钥。
在 绑定模式 中选择 实例绑定（agent_id 指向应用实例） 或 模板绑定（agent_id 指向 Agent 模板，用户需 /init）。其中，“应用实例”就是智能体实例。两种模式的差异参见选择渠道绑定模式。
需要接收 QQ 消息时，保持 禁用单聊 关闭。
填写 单聊允许的发送者 ID。
选择 创建，然后选择 启用。
QQ 渠道账号表单只提供单聊策略，不提供群聊设置。单聊允许列表为空时允许任意发送者；生产账号应显式填写测试通过且经过批准的发送者 ID。
禁用单聊优先于发送者允许名单。启用后，所有 QQ 消息都会被拒绝，即使发送者 ID 已在允许名单中。由于当前账号没有群聊设置，这个选项适合临时阻止消息接入，不适合保持正常服务时启用。
验证 QQ 单聊
- 确认渠道账号状态变为 在线。
- 使用沙箱成员或已获准的 QQ 用户向机器人发送文本消息。
- 确认机器人返回完整回复。
- 发送来自未在允许列表中的用户消息，确认被拒绝。
按当前 QQ 渠道账号配置完成测试时，回复以非流式消息返回，不会像飞书流式卡片一样逐步更新回复内容。上线前请用目标机器人再次确认实际表现。
本流程以文本消息为验收范围。图片、音频、视频或文件只有在目标机器人和租户中完成真实账号测试后，才能纳入业务验收。
验证模板绑定和 /init
使用尚未初始化的测试用户发送：
/init如果机器人返回必填参数，使用 /init KEY=VALUE 补齐。确认 AgentWorks 创建智能体实例和用户绑定，后续单聊进入该实例。/init 是 AgentWorks 渠道通用的模板绑定命令。
轮换机器人密钥
修改 QQ 凭证会停止旧 WebSocket 连接并使用新凭证重新连接，可能产生短暂中断。
- 在业务低峰期准备新机器人密钥。
- 选择 编辑，同时填写 应用 ID（凭证）和新的应用密钥。
- 选择 保存，等待账号重新上线。
- 使用沙箱成员完成一次消息往返和一次
/init验证。 - 验证成功后再撤销旧密钥。
如果 QQ 开放平台不再允许该机器人使用 WebSocket，请停用 QQ 渠道账号，并改用目标租户已开通且验证通过的飞书或 WebSocket 接入方式。
停用或删除 QQ 渠道账号
临时停止或永久删除 QQ 渠道账号时，先选择 停用并确认状态已经变为 已停用。永久删除前，盘点用户绑定、模板绑定创建的智能体实例和仍在使用该机器人的外部用户，再选择 删除。
删除 AgentWorks 渠道账号会停止对应渠道连接并删除平台内账号记录，不会删除 QQ 开放平台中的机器人，也不会自动清理所有智能体实例和能力资源。