〇、先搞懂几个词（小白必读）
-
工作流：你在画布里搭的那套自动流程（比如「收到文字 → AI 处理 → 回结果」）。
-
机器人 / Bot：一个能自动收发消息的 QQ 账号，由你在 QQ 开放平台创建，不是你的私人 QQ。
-
Webhook（回调地址）：一个网址。用户给机器人发消息时，QQ 会把这条消息**POST（推送）**到这个网址——也就是推给我们的服务器，从而触发你的工作流。你要做的就是把我们生成的网址，填到 QQ 后台。
-
AppID / AppSecret：机器人的「账号 + 密码」。AppID 是身份，AppSecret 是密钥（用来验证消息真伪、换取调用凭证）。AppSecret 要保密。
-
C2C / 群@：C2C = 用户和机器人的「单聊」；群@ = 在群里 @机器人 的消息。QQ 规定：群里只有 @机器人 的消息才会推给你，普通群聊不推。
一、前提
-
有一个 QQ 开放平台账号，并已创建机器人（https://q.qq.com）。
-
接入方式选 Webhook 模式（不是 WebSocket 长连接）。
-
已经在我们平台搭好一个工作流，且它的开始节点是「Webhook 开始」节点（不是普通「开始」节点）。
-
合规提醒：QQ 平台对 AIGC（AI 生成内容）类机器人有规则要求，上线前请阅读平台公告，确保合规。
二、你将得到的效果
-
用户私聊机器人发「你好」→ 机器人几秒后回复工作流的处理结果。
-
用户在群里 @机器人 发消息 → 机器人在群里回复（引用该消息）。
-
文字、图片都支持（取决于你的工作流有没有处理图片的节点）。
效果示意：在 QQ 会话里，你发出的消息下方会先出现机器人「正在处理」的反馈，几秒到几十秒后机器人引用你的原消息、回复工作流的处理结果（文字或图片）。
三、第一步：在 QQ 开放平台拿凭据
-
登录 QQ 开放平台，进入你的机器人。
-
左侧菜单找到「开发 → 开发设置」。
-
在这个页面能看到两个关键值，记下来（后面填到我们画布）：
| 字段 | 长什么样 | 在哪复制 | 用途 |
|---|---|---|---|
| 机器人 AppID | 一串数字，如 102xxxxxx | 开发设置页顶部 | 机器人身份标识 |
| AppSecret | 一串字母数字，如 naOC0oc...PG7 | 开发设置页（可能需点「重置/查看」） | 验证消息真伪 + 换调用凭证；保密 |
界面位置：登录 QQ 开放平台 → 进入你的机器人 → 左侧「开发 → 开发设置」。AppID 在页面顶部（一串数字），AppSecret 在同页稍下位置，首次查看可能要点「重置」生成后复制。
四、第二步：在画布填凭据，拿到 Webhook 地址
-
打开你的工作流画布，点中「Webhook 开始」节点（绿色入口节点）。
-
右侧配置面板里：
-
触发平台：下拉选「QQ 机器人」。选中后下方只显示 QQ 相关字段（其它平台字段自动隐藏）。
-
机器人 AppID：粘贴第一步的 AppID。
-
机器人 AppSecret：粘贴第一步的 AppSecret。
-
点画布保存（或工作流管理面板的「覆盖保存」），保存后工作流有唯一 ID（一长串 uuid）。
-
在「工作流管理 → 我的工作流」启用 webhook 后（见第六步），会显示 Webhook 地址：
https://api.openai.run/v1/workflow/webhook/qq/你的工作流ID
地址里
界面位置：这一步在我们的工作流画布里做，不在 QQ 后台。点中绿色的「Webhook 开始」节点后，右侧配置面板顶部有「触发平台」下拉，选「QQ 机器人」后下方会露出「机器人 AppID」「机器人 AppSecret」两个输入框，把第一步的值粘进去。
五、第三步：把 Webhook 地址填到 QQ 后台
-
QQ 开放平台 → 你的机器人 →「开发 → 开发设置」→ 找到「回调配置 / 回调地址（Webhook）」。
-
把第二步的 Webhook 地址填进「回调地址」。
-
保存的瞬间，QQ 会发一个验证请求（业内叫 op=13 握手）。我们后端用你填的 AppSecret 自动算签名应答，验证会自动通过，显示「验证成功 / 配置成功」即可。
-
在「事件订阅 / Intents」里勾选：
-
C2C 消息（用户私聊机器人）
-
群@消息（群里 @机器人）
界面位置：QQ 开放平台「开发 → 开发设置」页。「回调地址（Webhook）」是一个输入框，填入你的 Webhook 地址后保存即触发握手验证。事件订阅（Intents）在同页或相邻的「事件订阅」区，是一组可勾选项，勾上「C2C 消息」和「群@消息」两项。
六、第四步：在画布启用工作流
「工作流管理 → 我的工作流」找到该工作流：
-
触发方式设为 webhook。
-
点「启用」。
只有「已启用 + webhook 触发」才会被 QQ 消息触发。启用时系统校验 AppID/AppSecret，缺了会提示。
界面位置：在我们平台的「工作流管理 → 我的工作流」列表里找到该工作流，把它的「触发方式」切到 webhook，再点「启用」。启用后同一行会显示出可复制的 webhook 地址。
七、测试
-
私聊：QQ 里搜到机器人 → 发一句话（工作流期望的输入）。
-
群里：把机器人拉进群 → @机器人 + 一句话。
机器人会在几秒到几十秒后引用回复工作流结果。
八、排错（现象 → 原因 → 解决）
| 现象 | 可能原因 | 解决 |
|---|---|---|
| 保存回调地址「验证失败」 | AppSecret 填错 / 画布没保存 / 地址末尾 ID 不对 | 核对 AppSecret 两边一致；确认已保存；检查地址 |
| 私聊机器人没反应 | 没「启用 + webhook 触发」；没订阅 C2C 消息 | 画布启用；QQ 后台勾「C2C 消息」 |
| 群里不理 | 没 @机器人；或没订阅群@消息 | 群里必须 @机器人；勾「群@消息」 |
| 收到但不回复（日志报错） | 工作流执行失败 / 凭据失效 | 看 API 日志；核对 AppID/AppSecret |
| 发图报错 | 工作流没有处理图片的节点 | 纯文字工作流收纯图会因无文字输入失败，属正常 |
九、速查表（一页纸）
1. QQ 开放平台 → 开发设置 → 拿 AppID + AppSecret
2. 画布 webhook_start → 平台选「QQ 机器人」→ 填 AppID/AppSecret → 保存
3. 工作流管理 → 启用 webhook → 复制 webhook 地址
https://api.openai.run/v1/workflow/webhook/qq/<工作流ID>
4. QQ 开发设置 → 回调地址 填该地址（自动握手验证）
事件订阅：勾 C2C 消息 + 群@消息
5. QQ 私聊机器人 / 群里 @机器人 测试
─────────────────────────────────────────
群消息只响应 @机器人；签名 Ed25519 后端已实现，无需操心