文档中心
费用中心控制台

接入 QQ 机器人 ​

连接 AI 助手

智能体开发服务平台（AgentWorks）的 QQ 渠道账号通过 WebSocket C2C 链路接收机器人单聊消息；当前配置入口不提供 Webhook 回调或群聊设置。

注意

需要人工审批时改用已完成验收的渠道

工具进入 HITL 时，QQ 会提示改用支持审批的渠道。需要人工确认的工具，请使用已经完成批准和拒绝验收的接入方式，例如飞书账号。

确认 QQ 机器人支持 WebSocket 接入 ​

在 QQ 开放平台确认目标机器人仍提供 WebSocket Gateway。只有同时满足以下条件时才继续：

  • QQ 开放平台中的目标机器人仍允许使用 WebSocket Gateway。
  • 该机器人可以订阅或接收 C2C_MESSAGE_CREATE 单聊事件。
  • 平台运行环境的出口 IP 已加入 QQ 开放平台为目标机器人配置的白名单。

如果新机器人只提供 Webhook 回调配置，AgentWorks QQ 渠道无法接入。不要把 Webhook 地址填写到其他字段，也不要把第三方 OneBot 接口当作本产品的 QQ 渠道。

准备 QQ 机器人 ​

确认机器人支持上述接入方式后，先在 QQ 开放平台准备凭证、测试成员和单聊事件，供后续配置和验证使用。

  1. 在 QQ 机器人开放平台创建机器人并取得 Bot AppID 和机器人密钥。
  2. 在上线前，把测试 QQ 账号加入机器人沙箱成员。
  3. 启用 C2C 单聊消息事件。
  4. 如果开放平台要求出口 IP 白名单，向 AgentWorks 平台管理员取得 AgentWorks 平台的稳定公网出口 IP 并加入白名单。
  5. 确认机器人在目标环境中已启用。

AgentWorks 不需要也不会显示 QQ 回调 URL。平台运行环境必须能够访问 QQ Gateway。

创建 QQ 渠道账号 ​

机器人准备好后，在 AgentWorks 中填写 QQ 应用凭证，选择要连接的智能体，并设置允许发送消息的用户。

  1. 打开 渠道账号。

    打开渠道账号

    也可以从控制台左侧导航进入 渠道账号。

  2. 选择 新建账号，在 渠道类型 中选择 QQ。

  3. 填写 账号名称、应用 ID（凭证）和应用密钥。

  4. 选择 绑定模式。

    • 实例绑定（agent_id 指向应用实例）：使用已有智能体实例；这里的“应用实例”就是智能体实例。
    • 模板绑定（agent_id 指向 Agent 模板，用户需 /init）：让渠道用户通过 /init 创建专属实例。

    两种方式的差异参见了解绑定模式：使用已有实例还是按用户创建。

  5. 设置谁可以与机器人单聊。

    QQ 渠道账号表单只提供单聊策略，不提供群聊设置。禁用单聊 决定是否接收单聊消息；只有未勾选时，单聊允许的发送者 ID 才决定允许哪些人发送消息。按希望的接收范围配置：

    单聊接收范围禁用单聊单聊允许的发送者 ID
    只允许指定人员不勾选填写这些人的发送者 ID；名单外的发送者会被拒绝
    不通过名单限制发送者不勾选留空
    不接收任何单聊消息勾选可以保留原名单，名单内的发送者也会被拒绝

    每行填写一个 ID，也可以用英文逗号分隔。生产账号应显式填写测试通过且经过批准的 QQ 发送者 ID。

    注意

    禁用单聊时，允许名单暂不生效

    勾选后，即使允许名单仍可编辑，创建或保存配置后也会拒绝所有单聊消息，包括 /init。原名单会保留；取消勾选并保存后，才重新按名单判断。名单为空时，不限制发送者。

    这些设置只控制当前渠道账号的单聊消息，不会绕过 QQ 自身的访问限制。需要正常提供 QQ 单聊服务时，不要勾选 禁用单聊。

  6. 保持 未命中的斜杠指令透传给 Agent 关闭。

    该选项默认关闭，未知 /command 返回 /help。只有明确希望模型接收未知斜杠文本，并已评估提示注入、工具权限和副作用风险时才开启。

  7. 选择 创建，然后选择 启用。

验证 QQ 单聊 ​

需要提供 QQ 单聊服务时，确认未勾选 禁用单聊 并已保存配置，再验证文本消息。图片、音频、视频或文件只有在目标机器人和租户中完成真实账号测试后，才能纳入业务验收。

  1. 确认渠道账号状态变为 在线。

  2. 使用沙箱成员或已获准的 QQ 用户向机器人发送文本消息。

  3. 确认机器人返回完整回复。

    按当前 QQ 渠道账号配置完成测试时，回复以非流式消息返回，不会像飞书流式卡片一样逐步更新回复内容。上线前请用目标机器人再次确认实际表现。

  4. 填写了单聊允许名单时，让未在允许列表中的 QQ 用户发送消息，确认被拒绝。

  5. 保持未知斜杠透传关闭，发送虚构未知命令，确认返回命令帮助。

    业务已批准开启时，只在没有副作用工具的测试智能体中确认该文本会作为 Agent 输入处理；测试后恢复账号原来的开关状态。

  6. 发送 /help，核对当前可用系统命令。

    命令含义和 /trust 风险参见管理渠道会话和斜杠命令。

消息往返验证成功后，需要核对绑定目标、定位渠道会话、检查用户路由或维护定时任务时，参见创建账号后继续管理消息、用户和任务。

收到自动重试通知时，平台仍在处理原任务，不需要重新发消息。等待最终回复，或发送 /stop 停止；需要调整超时和重试次数时，见配置自动重试。

验证模板绑定和 /init ​

按照以下步骤确认测试用户已经获得专属智能体实例：

  1. 使用尚未初始化的测试用户发送：

    language-text
    /init

  2. 如果机器人返回必填参数，使用 /init KEY=VALUE 补齐。

  3. 打开 AgentWorks 控制台的 渠道账号，进入目标 QQ 账号的 用户绑定。

    打开渠道账号

  4. 确认测试用户指向新创建的智能体实例。

  5. 让同一用户发送普通消息，确认后续单聊继续进入该实例。

/init 是 AgentWorks 渠道通用的模板绑定命令。KEY=VALUE 之间使用空格分隔，值本身不能包含空格；不要在消息中传递密码或访问令牌。实例绑定不需要初始化，直接使用已绑定的智能体实例。

轮换机器人密钥 ​

修改 QQ 凭证会停止旧 WebSocket 连接并使用新凭证重新连接，可能产生短暂中断。

  1. 在业务低峰期准备新机器人密钥。
  2. 选择 编辑，同时填写 应用 ID（凭证）和新的应用密钥。
  3. 选择 保存，等待账号重新上线。
  4. 使用沙箱成员完成一次消息往返和一次 /init 验证。
  5. 验证成功后再撤销旧密钥。

如果 QQ 开放平台不再允许该机器人使用 WebSocket，请停用 QQ 渠道账号，并改用已经配置并验证通过的飞书或 WebSocket 接入方式。

停用或删除 QQ 渠道账号 ​

临时停止或永久删除 QQ 渠道账号时，先选择 停用并确认状态已经变为 已停用。永久删除前，盘点用户绑定、模板绑定创建的智能体实例和仍在使用该机器人的外部用户，再选择 删除。

删除 AgentWorks 渠道账号会停止对应渠道连接并删除平台内账号记录，不会删除 QQ 开放平台中的机器人，也不会自动清理所有智能体实例和能力资源。