← 返回文档中心

Webhook 与事件订阅

OCTO 文档中心 · API 与集成

00-inbox/product-bot-answers/2026-09-22-P1-r2-Q9-BotAPI与消息类型全景回答.md（🔴Q9源码确认：HTTP长轮询/事件队列5写入源/payload结构/reaction不支持/App Bot过滤——BA-02核心纠偏）
00-inbox/product-bot-answers/2026-09-19-openclaw-channel-octo事件机制回答.md（events-poll、doc_comment_mention、card_action、bot_task、cursor/ACK策略，来源=openclaw-channel-octo@1.5.0源码核对）
00-inbox/product-bot-answers/2026-09-20-P0-API鉴权-Q2回答.md（bot_token/IM token双token模型，message_id=2101685396566872064）
00-inbox/product-bot-answers/2026-09-22-P1-round1-Q4-Docs文档协同深度回答.md（doc_comment_mention链路DC-02，源码确认级）
00-inbox/product-bot-answers/2026-09-22-P1-round1-Q1-Speech语音深度回答.md（语音STT/ASR转写，Q1.1-Q1.6）
00-inbox/product-bot-answers/2026-09-22-P1-round1-Q2-FleetLoop深度回答.md（FL-01出站SSRF、/internal/project-workspace-events、/v1/internal鉴权）
06-api-integration/Bot-API概览.md v0.4（/v1/bot/events长轮询、出站webhook端点列举）

Webhook 与事件订阅 v1.0

状态：`review` / v1.0（Q9 源码确认级，重大纠偏）

🔴🔴🔴 重大纠偏（售前/集成必读！）

以下三条为 Q9 源码级硬结论，任何售前材料/集成方案/旧文档若与此冲突，以本节为准。

🔴 Bot 收事件 = HTTP 长轮询，不是 WebSocket，不是 Webhook！

端点：POST /v1/bot/events，请求体带 wait 字段，单次 hold 上限 30 秒
底层实现：Redis sorted-set 事件队列 + doorbell BLPOP 通知机制
不存在"Bot 入站 Webhook 接收事件"的能力；不存在"Bot 直接订阅 WebSocket 事件流"的 Bot API

🔴 Bot 目前收不到以下事件（源码未找到向 Bot 事件队列投递的写入点；`MessageResp.Reactions` 字段被注释掉）——负向硬结论，不要承诺：

Reaction（表情回应）
群成员变动（加入/退出/被移除/角色变更）
Bot 被加入群/被移出群的"欢迎/告别"事件
网盘/Drive 文件分享事件

🔴 无独立 `in_reply_to` 字段——回复上下文嵌在 `payload` 内部（WuKongIM reply 结构），Bot 需自行从 payload 中解析引用关系，不能期望顶层有独立的 reply 字段。

本文覆盖范围

Bot 接收实时事件（🔴HTTP 长轮询 `POST /v1/bot/events`）——Bot 被@、文档@Bot、卡片回调、Bot 设置更新等；这是 Bot 收事件的唯一官方通道。
出站 Webhook（平台级/群入站 Webhook）——群入站 Webhook（外部系统→群消息）、平台级出站端点（`/v1/webhook` 等端点存在但 per-bot 自助订阅模型待确认）；
内部服务间事件（`/v1/internal/*`、`/internal/project-workspace-events`）——非外部 Bot API，仅作安全/架构边界说明。

1. 事件接收：HTTP 长轮询（唯一官方通道）

1.1 机制总览

Bot 服务端                     OCTO Server (octo-server)
   │                                │
   │── POST /v1/bot/events ────────▶│  （带 wait 参数，长轮询 hold 连接）
   │   {wait: 30, cursor?}          │
   │                                │  ┌─ Redis sorted-set 事件队列
   │                                │  │  (每个 Bot 一个队列)
   │                                │  └─ doorbell BLPOP 通知
   │                                │
   │◀── 200 OK {events:[...], ──────│  （有事件立即返回；无事件最多等 30s 返回空）
   │        next_cursor}            │
   │                                │
   │── 处理事件...                  │
   │── POST /v1/bot/events/:id/ack─▶│  （逐事件 ACK）
   │                                │
   │── 立即发起下一次 poll ─────────▶│  （at-least-once，需自行去重）

1.2 端点规范

项目	值
方法	POST（不是 GET）
路径	`/v1/bot/events`
鉴权	`Authorization: Bearer` （`bf_` 或 `app_` 前缀）
请求体	`{"wait": <秒数>, "cursor": "<可选游标>"}`
wait 上限	30 秒（单次连接 hold 最长时间；超时返回空 events 数组）
返回	`{"events": [...], "next_cursor": "..."}`
ACK 端点	`POST /v1/bot/events/:event_id/ack`
投递语义	at-least-once（Bot 必须基于 event_id 去重）
底层实现	Redis sorted-set（按 Bot 分队列）+ doorbell BLPOP（事件到达即时唤醒）

1.3 事件队列写入源（已确认 4/5，第 5 个待补全枚举）

#	写入源	event_type	触发场景
①	普通消息	`message`（类型名待枚举确认）	DM 私聊消息 / 群聊中 @Bot 消息
②	卡片动作回调	`card_action`	用户点击 Bot 发出的交互卡片（按钮/表单提交，v2 卡片 Action.Submit）
③	文档评论@Bot	`doc_comment_mention`	文档评论中 @Bot（含个人空间文档，不依赖群聊）
④	Bot 设置卡片事件	`bot_setting`（scope 值）	Bot 设置/Profile 更新（插件观测到 scope==="bot_setting"）
⑤	❓待补全	—	Q9 明确说 5 个写入源，第 5 个待源码完整枚举（可能是 bot_task 或其他内部桥接事件）

1.4 App Bot 事件过滤

App Bot（app_ 前缀 token）仅接收 DM（Person 频道）消息
服务端通过 filterAppBotEvents 过滤掉非 Person 频道（群聊/子区）的事件
即：App Bot 在群里被 @ 也不会收到事件——这是 App Bot 与 User Bot（bf_）的关键差异

1.5 已知拉取/补拉端点（插件实测）

端点	方法	用途	确认来源
`/v1/bot/events`	POST	长轮询拉取事件（带 wait/cursor）	Q9 BA-02 源码确认
`/v1/bot/events/:event_id/ack`	POST	确认已处理事件（逐事件 ACK）	插件实测
`/v1/bot/messages/sync`	POST	补拉历史消息（断线恢复场景）	插件实测，待 Q9 确认对外契约

1.6 cursor/ACK 策略建议（来自 openclaw-channel-octo@1.5.0 最佳实践）

⚠️ 以下为插件实现最佳实践，非服务端强制要求，但推荐所有 Bot SDK 遵循：

先持久化 cursor，再 ACK——崩溃至多重放一次，绝不 ACK 已遗忘的事件；
未识别事件：推进内存 cursor 但不 ACK，留服务端过期淘汰；
可重试 Bot Task：阻塞 cursor（bot_task_retry 指数退避），防止越过重试缺口；
长轮询循环：收到响应后立即发起下一次 poll，不要在两次 poll 之间 sleep（事件到达时 doorbell BLPOP 会立即唤醒，无事件时服务端 hold 30s）。

2. 事件 Payload 结构

2.1 通用信封（Q9 BA-02 源码确认）

{
  "message_id": "...",       // 消息/事件 ID（用于 ACK 和去重）
  "message_seq": 0,          // 消息序列号（WuKongIM 序号，用于排序/补拉）
  "from_uid": "u_...",       // 事件发起者 UID
  "timestamp": 1695000000000, // 事件时间戳（精度待确认：ms/s）
  "channel_id": "...",       // 频道 ID（群 ID / DM 会话 ID）
  "channel_type": 1|2|5,     // 1=DM(Person), 2=群, 5=子区/Thread
  "payload": { ... }         // 消息内容/WuKongIM 结构（含 reply 上下文）
  // typed 事件额外带：
  // "event_type": "card_action" | "doc_comment_mention" | "bot_setting" | ...
  // "event_data": { ... }     // typed 事件的结构化数据
}

2.2 重要字段说明

字段	说明
`payload`	消息主体内容。WuKongIM 消息结构，type 字段决定内容类型（见 §2.5）；回复引用关系嵌在此结构内，无顶层 in_reply_to
`event_type`	仅非普通消息事件携带（如 `card_action`、`doc_comment_mention`、`bot_setting`）；普通 DM/@消息无此字段或 type 为 message
`event_data`	typed 事件的结构化数据容器；普通消息事件无此字段
`message_seq`	WuKongIM 单调递增序号，可用于断线后按 seq 补拉（配合 `/v1/bot/messages/sync`）

2.3 🔴 关于回复引用（in_reply_to）

2.4 doc_comment_mention 事件（源码确认）

{
  "message_id": "...",
  "event_type": "doc_comment_mention",
  "event_data": {
    "doc_id": "...",              // 文档 ID（docs-backend Yjs 文档按 docId；html/ppt 按 slug 或其他）
    "comment_id": "...",          // 评论 ID
    "parent_id": "...",           // 父评论 ID（回复评论时存在）
    "from_uid": "u_...",          // @ 的发起者 UID
    "bot_uid": "u_bot_...",       // 被 @ 的 Bot UID
    "text": "...",                // 评论文本内容
    "url": "https://...",         // 文档 URL（Bot 可据此跳回文档）
    "space_id": "...",            // 所属空间 ID
    "doc_kind": "" | "html" | "ppt" // 文档类型；缺省=docs-backend/Yjs
  },
  "from_uid": "u_...",
  "timestamp": 1695000000000,
  "channel_id": "...",
  "channel_type": 1
}

不依赖群聊——个人空间文档同样能触发（链路：doc 评论 @ → octo-docs-backend 调 POST /v1/internal/bot-mentions → 进 bot event 队列）；
Bot 回复走 docs CLI/API 写回文档评论线程（不是发 IM 消息）：docs comments add --parentId --docId --text "..."；
有效 doc_kind：docs-backend 缺省（Yjs 文档，按 docId）、html（octo-doc，按 slug）、ppt；其余非缺省值进 unsupported_doc_kind，不分发不 ACK，留服务端过期。

2.5 普通消息事件 payload（消息内容类型枚举）

type	内容	type	内容
1	文本	11	合并转发
2	图片	12/13	lottie/emoji 贴图
3	GIF	14	富文本图文混排
4	语音	17	互动卡片（Adaptive Cards）
5	小视频	18	文档转发卡片
6	位置	20	截屏
7	名片	1002+	群系统消息
8	文件

OCTO 语音模块为纯 STT/ASR 服务（octo-speech，无 TTS），支持 Gemini/GPT/Qwen 三云引擎，可选本地 ASR；
Web 端"录音→转文字填入输入框"，发给 Bot 的语音消息 Bot 侧收到转写文字；
音频不进 MinIO/S3，只落本地 ASR 日志目录（默认保留 7 天）；
原始音频文件如需获取，通过 type=8 文件消息的 presigned URL 下载（是否对 Bot 开放待确认）。

2.6 card_action 事件（卡片回调）

type=17 互动卡片中 `Action.Submit` 触发，v2 卡片（octo/v2 profile）专属。

{
  "event_type": "card_action",
  "event_data": {
    "message_id": "...",        // 卡片消息 ID
    "channel_id": "...",        // 所在频道 ID
    "channel_type": 2,          // 1=DM, 2=群, 5=子区/Thread
    "action_id": "...",         // 按钮/动作 ID（卡片模板定义）
    "operator_uid": "u_...",    // 点击者 UID
    "inputs": { ... },          // 可选：表单提交的输入值（⚠️用户提交内容，业务侧须自校验！）
    "data": { ... },            // 可选：附加数据
    "space_id": "...",          // 可选：空间 ID
    "client_token": "...",      // 可选：客户端幂等 token
    "acted_at": 1695000000000   // 可选：动作发生时间
  }
  // 外层通用字段: message_id, from_uid, timestamp, channel_id, channel_type
}

两档 profile：octo/v1（纯展示）/ octo/v2（交互，支持 Action.Submit 和输入元素）；
展示元素白名单：TextBlock/RichTextBlock/Image/ImageSet/Container/ColumnSet/FactSet/Table/ActionSet；
输入元素（v2）：Input.Text/Toggle/ChoiceSet/Number/Date/Time；
动作：本地 OpenUrl/ToggleVisibility/CopyToClipboard；Action.Submit（回调服务端，v2 专属）；
❌不支持 Action.Execute / auto-refresh；
限制：payload ≤ 512KiB / body ≤ 2MiB / 节点 ≤ 200 / 深度 ≤ 16；
✅支持动态改卡：POST /v1/bot/message/edit + octo_message_card_revision 表 + card_seq CAS 并发控制。

2.7 bot_setting 事件

2.8 bot_task 事件（插件观测，待 Q9 确认对外稳定性）

⚠️ 以下字段来自 openclaw-channel-octo 插件解析（bot-task.ts），对外字段稳定性待 Q9 正式确认。

{
  "event_type": "bot_task",
  "event_data": {
    "source": "...",              // 业务系统标识（opaque）
    "task_type": "...",           // 任务类型（opaque）
    "idempotency_key": "...",     // 幂等键（业务系统必须保证唯一稳定）
    "session_key": "...",         // 会话键（必需非空）
    "context": { ... },           // 可选：任务上下文（opaque）
    "metadata": { ... }           // 可选：元数据（opaque）
  }
}

3. 事件类型清单

3.1 ✅ 已确认支持的事件

事件类型	触发场景	event_type 值	确认度	来源
DM 私聊消息	用户直接给 Bot 发私信	普通消息（无 event_type）	✅源码确认	Q9 BA-02
群聊 @Bot 消息	Bot 在群聊/子区中被 @	普通消息（无 event_type）	✅源码确认	Q9 BA-02 + 多源交叉
语音消息（自动转写）	用户发语音消息（DM/@）	伴随消息事件（type=4）	✅链路确认	P1-Q1 Speech
卡片动作回调	用户点击交互卡片按钮/提交表单	`card_action`	✅源码确认	Q9 BA-01/BA-02
文档评论@Bot	文档评论中 @Bot（含个人空间）	`doc_comment_mention`	✅源码确认	P1-Q4 DC-02
Bot 设置更新	Bot Profile/设置变更	`bot_setting`（scope）	⚠️插件观测	插件 + Q9 写入源④
Bot Task	业务系统向 Bot 下发任务	`bot_task`	⚠️插件观测	插件实测

App Bot 注意：App Bot（`app_`）仅收 DM，群聊@不会投递（`filterAppBotEvents`）。

3.2 🔴 确认不支持的事件（负向硬结论）

Q9 BA-02 源码确认：以下事件当前不会投递给 Bot，源码未找到向 Bot 事件队列投递的写入点，`MessageResp.Reactions` 字段被注释掉。售前/集成禁止承诺这些事件可用。

事件	状态	说明
Reaction（表情回应）	🔴不支持	`MessageResp.Reactions` 被注释掉，无投递点
群成员加入	🔴不支持	无向 Bot 队列投递的写入点
群成员退出/被移除	🔴不支持	同上
群角色变更（设管理员等）	🔴不支持	同上
Bot 被加入群（欢迎事件）	🔴不支持	同上
Bot 被移出群	🔴不支持	同上
网盘/Drive 文件分享	🔴不支持	同上

3.3 待确认事件

候选事件	待确认点
群聊普通消息（不@Bot）	Bot 默认是否接收？是否需要"监听全部消息"权限？
消息编辑/撤回	是否投递给 Bot、edit/recall 字段区别
Thread/子区创建/归档	子区生命周期事件是否对 Bot 开放
bot_task 事件	是否为第 5 个写入源？对外字段稳定性？

4. Webhook 相关

4.1 🔴 Bot 入站 Webhook：不支持

4.2 群入站 Webhook（外部系统→群消息）

Q9 BA-04 确认：Bot 可管理群入站 Webhook（创建/查询/删除群的入站 Webhook）
路径模式：/v1/groups/{g}/incoming-webhooks/*、/v1/.../{webhook_id}/{token}/...
方向：外部系统 → OCTO 群消息（推消息进群），不是 Bot 收事件
具体管理 API 端点/参数待 API 文档补全

4.3 平台级出站 Webhook 端点（存在但订阅模型待确认）

端点	用途	确认状态
`/v1/webhook`	平台级 IM 事件回调	⚠️端点存在，订阅方式/事件范围/签名/重试待确认
`/v2/webhook`	v2 版平台级 Webhook	⚠️同上，与 v1 差异待确认
`/v1/webhook/github`	GitHub 集成回调	⚠️用途推断存在，签名/事件待确认
`/v1/webhook/message/notify`	消息通知回调	⚠️待确认

⚠️ 这些端点目前是路由表级别确认存在，但外部 Bot 如何订阅、签名机制、重试策略均待进一步确认。不排除这些是平台内部/管理后台配置的出站回调，而非 per-bot 自助 API。

4.4 Webhook 签名（待确认）

签名算法是否统一为 HMAC-SHA256？
签名 Header 名称（如 X-Octo-Signature）？
签名密钥如何颁发/轮换？
签名字符串是否包含 timestamp（防重放）？
时间戳新鲜度校验窗口？

4.5 Webhook 重试与幂等（待确认）

回调失败（超时/5xx/网络错误）重试策略（次数/退避曲线）待确认；
dead-letter queue（DLQ）是否存在待确认；
幂等 ID Header 名称待确认；
成功响应状态码要求（仅 2xx？）待确认。

5. WebSocket 说明（WuKongIM 底层，非 Bot API）

5.1 IM Token 与 WuKongIM 连接（基础设施说明）

bot_token（bf_/app_ 前缀，opaque，长期身份凭据）→ 换 IM token（短期 WuKongIM 连接凭证）
换票端点：POST /v1/bot/register（用 bot_token 换 IM token）
保活：POST /v1/bot/heartbeat（Redis key bot:heartbeat:，TTL 60s）

⚠️ 上述 IM token/register/heartbeat 是 OCTO IM 底层基础设施，Bot 事件接收走 HTTP 长轮询（§1），不需要 Bot 开发者直接操作 WebSocket 连接。如果 SDK 内部使用 WebSocket，那是 SDK 封装行为，不是 Bot API 契约。

5.2 v0.1 文档修正记录

6. 内部事件端点（服务间调用，非外部 Bot API）

⚠️ 本节所列端点均为 OCTO 内部服务间调用，使用独立的 `X-Internal-Token` 鉴权，不对外部 Bot/第三方应用开放。 列出仅用于说明"服务端内部事件流"与"Bot 对外事件 API"的边界，外部集成者不应尝试直接调用这些端点。

6.1 `/internal/project-workspace-events`（server → Fleet）

方向：octo-server 出站到 Fleet/daemon
方法：POST
事件范围：5 类项目生命周期事件：create（创建）、archive（归档）、restore（恢复）、rename（重命名）、member-revoke（成员撤销）
数据流特性：主数据流是 Fleet/daemon → 拉取 octo-server；server 仅经 outbox 推这 5 类事件给 Fleet；server 从不主动推命令给 daemon
SSRF 防护：出站地址由 runtime-onboarding 推导，不接受调用方自定义 URL

6.2 `/v1/internal/bot-mentions`（docs-backend → octo-server）

方向：octo-docs-backend → octo-server
方法：POST
触发：文档评论中 @Bot
产出：octo-server 收到后生成独立的 doc_comment_mention Bot 事件，进入 bot event 队列（Redis sorted-set），供 Bot 经 POST /v1/bot/events 长轮询消费
这是内部桥接端点，外部不直接调用。

6.3 `/v1/internal/*` 鉴权模型

机制	实现
`X-Internal-Token` Header	独立内部 token，常量时间比较（防 timing attack）
Token 长度下限	过短 token 直接拒绝
Body 上限	限制请求体大小
按 IP 限流	`StrictIPRateLimitMiddleware`，无 uid，禁挂 SharedUIDRateLimiter 防 fail-open
IP 白名单	未找到显式 IP 白名单证据（待确认）

7. 安全注意事项

7.1 出站 Webhook SSRF 防护

平台级出站（server→Fleet）SSRF 面小：出站地址由 onboarding 推导，不接受自定义 URL；
环境变量 DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS——控制是否允许出站 Webhook 访问私网地址（127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16 等）；
待确认：
该配置项默认值（true/false）；
URL 协议白名单（仅 https？）、端口白名单；
DNS rebinding 防护（解析后 IP 再校验）。

7.2 事件消费安全最佳实践

bot_token 绝不能嵌入前端/客户端代码——`bf_`/`app_` token 是 Bot 全部权限凭证，泄露可冒充发消息/读事件；
基于 event_id 去重——长轮询投递语义是 at-least-once，Bot 侧必须幂等处理；
校验 inputs/data 等用户提交字段——卡片回调的 `inputs` 来自用户提交，业务侧须自校验（"不信任表单值"原则）；
ACK 前先持久化——防止崩溃导致事件丢失（cursor 先落盘再 ACK）；
长轮询不要加额外 sleep——收到响应立即发起下一次 poll，无事件时服务端 hold 30s。

7.3 Token 与限流（Q9 BA-03 确认）

项目	值
Token 前缀	User Bot `bf_` / App Bot `app_` / User API Key `uk_`（不是 bt_/sk_）
Token 格式	`bf_` + 16 随机字节 hex（共 35 字符：3 + 32 hex），crypto/rand 生成
HTTP 鉴权	`Authorization: Bearer {token}`
限流三桶	business / heartbeat / register，per-bot（key=robotID）
IP 底线	register 100rps、heartbeat 500rps；business 桶动态配置无硬编码
Token 重置	Botfather `/revoke`（需输入"Yes, revoke it"确认），旧 token 立即失效
OBO 代发	三重防循环：①自发不回放 ②grantor outbound 不 fan 给其 bot ③`__obo_processed__` 标记幂等短路

8. 代码示例

8.1 HTTP 长轮询接收事件（推荐模式）

const BOT_TOKEN = process.env.OCTO_BOT_TOKEN; // bf_xxx 或 app_xxx
const BASE = "https:///v1/bot";

let cursor = null; // 首次拉取不带 cursor，服务端从最新开始

async function pollLoop() {
  while (true) {
    try {
      const res = await fetch(`${BASE}/events`, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${BOT_TOKEN}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          wait: 30,        // 长轮询 hold 时间，上限 30s
          cursor: cursor   // 可选：断点续传游标
        }),
      });

      if (res.status === 200) {
        const { events, next_cursor } = await res.json();
        for (const evt of events) {
          await handleEvent(evt);           // 业务处理
          await ackEvent(evt.message_id);   // 逐事件 ACK
        }
        cursor = next_cursor;
        // 立即发起下一次 poll，不要 sleep
      } else if (res.status === 429) {
        await sleep(1000); // 限流退避
      } else if (res.status === 401) {
        console.error("token invalid, exiting poll loop");
        break; // token 失效需走管理后台重新颁发
      }
    } catch (err) {
      console.error("poll error:", err);
      await sleep(3000); // 网络错误退避重试
    }
  }
}

async function ackEvent(eventId) {
  await fetch(`${BASE}/events/${eventId}/ack`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${BOT_TOKEN}` },
  });
}

8.2 事件处理分派

async function handleEvent(evt) {
  const et = evt.event_type;

  // typed 事件
  if (et === "card_action") {
    const { action_id, operator_uid, inputs, message_id } = evt.event_data;
    console.log(`[card] ${operator_uid} clicked ${action_id} on msg ${message_id}`);
    // 处理卡片按钮/表单回调
    return;
  }

  if (et === "doc_comment_mention") {
    const { doc_id, comment_id, from_uid, text, url } = evt.event_data;
    console.log(`[doc@] ${from_uid} 在文档 ${url} 评论: ${text}`);
    // 回复走 docs API 写回评论线程，不是 IM 消息
    return;
  }

  // 普通消息（DM / 群聊@）
  if (!et || et === "message") {
    const { from_uid, channel_id, channel_type, payload } = evt;
    const { type: contentType, content } = payload;
    // ⚠️ 回复引用在 payload 内（WuKongIM reply 结构），无顶层 in_reply_to
    // ⚠️ App Bot 仅收 channel_type=1（DM/Person）
    console.log(`[msg${contentType}] ${from_uid}: ${content}`);
    return;
  }

  console.warn("unknown event_type:", et, evt);
}

9. 待确认项清单（v1.0 剩余）

v1.0 已由 Q9 BA-02 源码确认核心通道/负向结论/payload 结构。以下为剩余待确认项。

9.1 通道与 Payload 细节

#	问题	优先级
V10-01	事件队列第 5 个写入源是什么？bot_task 是否在内？	中
V10-02	普通消息事件的 event_type 字段值（是 undefined、"message"还是其他常量）？	中
V10-03	timestamp 精度（秒/毫秒）？event_id/message_id 格式规范？	低
V10-04	payload 内 WuKongIM reply 结构的具体字段路径/格式（替代 in_reply_to）？	中
V10-05	`/v1/bot/messages/sync` 补拉端点的对外契约（参数/响应格式）？	低
V10-06	语音消息转写文字在 payload 中的具体字段位置（content 平铺 vs 独立 transcript 字段）？原始音频是否对 Bot 开放下载？	中

9.2 出站 Webhook

#	问题	优先级
V10-07	平台级出站 Webhook（`/v1/webhook` 等）的订阅配置方式（管理后台/API）、签名算法（HMAC-SHA256？）、Header 名称、重试策略？	中
V10-08	`DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS` 默认值？	低
V10-09	群入站 Webhook 管理 API（BA-04 确认 Bot 可管理）的具体端点/参数？	中

9.3 限流与配额

#	问题	优先级
V10-10	business 桶具体 RPS 限制（system_setting 动态配置，无硬编码值，需运行时 config 确认）？日配额是否存在？	低

附录 A：变更记录

版本	日期	变更	作者
v1.0	2026-09-22	重大纠偏升级。🔴核心纠偏：Bot 收事件=HTTP长轮询（非WebSocket/Webhook）；🔴reaction/群成员变动/加入退出/网盘分享不支持（负向硬结论）；🔴无独立in_reply_to字段。新增：事件队列写入源、App Bot DM-only过滤、payload结构确认（Q9 BA-02）、消息类型枚举（Q9 BA-01）、卡片type=17约束、Token格式/限流确认（Q9 BA-03）、群入站Webhook管理（Q9 BA-04）。删除/修正：WebSocket从"Bot接入候选通道"改为"WuKongIM底层架构说明"；Bot入站Webhook明确标注"不支持"。confidence从low升至medium-high。	twb-knowledge-octo
v0.1	2026-09-22	初版框架。已确认doc_comment_mention、群聊@Bot、语音转写、card_action、bot_task、bot_setting_updated事件（插件观测级）；长轮询端点/内部事件/SSRF面/IM双token模型已写入；WebSocket/Webhook/签名/重试/完整事件枚举待Q9确认。	twb-knowledge-octo

附录 B：引用来源索引

00-inbox/product-bot-answers/2026-09-22-P1-r2-Q9-BotAPI与消息类型全景回答.md（message_id≈2102216162673594368）——🔴Q9核心纠偏：HTTP长轮询/事件队列5写入源/payload{message_id,message_seq,from_uid,timestamp,channel_id,channel_type,payload}/无in_reply_to/reaction不支持/App Bot DM-only/消息类型枚举/卡片约束/Token格式限流/OBO防循环
00-inbox/product-bot-answers/2026-09-19-openclaw-channel-octo事件机制回答.md（message_id=2101009604581167104）——events-poll实现、card_action字段、doc_comment_mention doc_kind、bot_task、cursor/ACK最佳实践、bot_setting_updated
00-inbox/product-bot-answers/2026-09-20-P0-API鉴权-Q2回答.md（message_id=2101685396566872064）——bot_token/IM token双token、register/heartbeat、限流三桶
00-inbox/product-bot-answers/2026-09-22-P1-round1-Q4-Docs文档协同深度回答.md（DC-02）——doc_comment_mention完整链路、/v1/internal/bot-mentions、个人空间支持、Bot回复写回评论
00-inbox/product-bot-answers/2026-09-22-P1-round1-Q1-Speech语音深度回答.md（Q1.1-Q1.6）——纯STT/ASR、三云引擎、音频保留7天、Web端"录音→转文字"
00-inbox/product-bot-answers/2026-09-22-P1-round1-Q2-FleetLoop深度回答.md（FL-01）——/internal/project-workspace-events 5类事件、出站SSRF、/v1/internal鉴权四要素、DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS
06-api-integration/Bot-API概览.md v0.4——/v1/bot/events长轮询端点、出站webhook端点列表（/v1/webhook, /v2/webhook, /v1/webhook/github, /v1/webhook/message/notify）