OpenClaw 异步通知：Agent Turn 与 Wake 选型指南

为什么需要这个链接到标题

AI Agent 经常需要执行耗时较长的异步任务（视频剪辑、字幕生成、模型推理等）。任务完成后，如何通知用户？

有三种常见实现方式：

方式	过程	优点	缺点
同步等待	发起任务 → 一直等到完成 → 返回结果	实现简单	长时间阻塞，用户体验差
异步轮询	发起任务 → 拿到 job_id → 不断查询 → 完成	不阻塞	对话不能断开，浪费 token
异步+通知	发起任务 → 返回"已提交" → 完成后主动推送	体验最好，资源最优	需要服务端支持回调

OpenClaw 的独特优势在于它拥有 Webhook/Hook 机制，可以作为服务端接收外部回调，主动推送消息到飞书。

对比其他 AI 工具：

OpenCode / Claude Code：纯 CLI 工具，只有"触发→等待→返回"的模式，没有回调机制
OpenClaw：内置 Gateway 服务，支持 /hooks/* 端点，天然适合异步回调

所以 “异步+通知” 是 OpenClaw 的场景的最优解。

整体架构链接到标题

sequenceDiagram participant U as 用户（飞书） participant O as OpenClaw Agent participant W as Windmill / 外部系统 participant H as OpenClaw Hook U->>O: 发消息处理这个视频 O->>W: API 调用（异步） O-->>U: 任务已提交 Note over W: 几分钟后... W-->>H: POST /hooks/agent H->>H: 创建 Agent Turn H->>U: 飞书消息（带下载链接）

Agent Turn 与 Wake 链接到标题

OpenClaw 提供了两种代码触发的消息通知方式，它们都通过 Gateway 的 /hooks/* 端点实现。

Agent Turn（action: “agent”）链接到标题

创建一个 隔离的 Agent 执行回合，Agent 可调用工具、执行命令、使用 message 工具发送消息到指定的飞书用户。

sequenceDiagram participant E as 外部系统 participant G as OpenClaw Gateway participant A as Agent Turn participant F as 飞书 E->>G: POST /hooks/agent { message, channel, to } G-->>E: { ok: true, runId } G->>A: 创建隔离 Agent 回合 Note over A: Agent 收到原始数据，可做格式化处理 A->>A: LLM 分析数据、格式化消息 A->>F: message tool → 飞书 Note over F: 用户收到消息（不保存在会话历史中）

Wake（action: “wake”）链接到标题

向 主会话 注入一条系统事件，Agent 在主会话中处理这条消息并回复。

sequenceDiagram participant E as 外部系统 participant G as OpenClaw Gateway participant S as 主会话 participant F as 飞书 E->>G: POST /hooks/wake { text, mode } G-->>E: { ok: true, mode } G->>S: 向主会话注入系统事件 Note over S: Agent 在主会话中处理事件 S->>F: 回复到主会话对话 Note over F: 消息保存在主会话历史中

对比链接到标题

维度	Agent Turn	Wake
创建方式	`POST /hooks/agent`	`POST /hooks/wake`
执行环境	隔离的 Agent 回合	主会话
目标用户	可指定任意飞书用户	仅主会话
消息存储	不入会话历史	保存在会话历史中
消息再处理	✅ Agent 可理解、格式化、增强数据	❌ 原样转交
权限要求	基础 Hook 配置即可	需要额外配置 session key

Agent Turn 适用场景：

需要将消息推送到特定用户（不是主会话的发起者）
需要对原始数据进行格式化/增强（如生成预签名 URL、计算耗时、加 emoji）
通知和主会话解耦，适合独立通知

Wake 适用场景：

消息需要保留在用户会话历史中
简单的系统提醒
通知触发后用户可以在同一对话中继续追问

前置条件链接到标题

基础配置链接到标题

在 ~/.openclaw/openclaw.json 中：

{
  "hooks": {
    "enabled": true,
    "token": "whk_oClAw_xxxxxxxxxxxx",
    "path": "/hooks"
  }
}

Wake 额外配置链接到标题

Wake 要指定目标会话，需要额外开启两个配置：

{
  "hooks": {
    "allowRequestSessionKey": true,
    "allowedSessionKeyPrefixes": ["feishu:", "hook:"]
  }
}

curl 代码示例链接到标题

Agent Turn——发送消息到指定用户链接到标题

# 基础路径
HOOK_URL="http://YOUR_HOST:18789/hooks/agent"
HOOK_TOKEN="your_hook_token"

curl -X POST "$HOOK_URL" \
  -H "Authorization: Bearer $HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "🎬 视频处理完成！\n\n📥 [点击下载](https://STORAGE_SERVER/...)\n\n⏱ 有效期：7天",
    "name": "视频处理通知",
    "channel": "feishu",
    "to": "feishu:user:ou_xxxxxxx"
  }'

Agent Turn——触发后让 Agent 自行格式化链接到标题

curl -X POST "$HOOK_URL" \
  -H "Authorization: Bearer $HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "视频流水线已结束。\n状态: success\n耗时: 323秒\nS3路径: BUCKET_NAME/.../output.mp4\n\n请格式化这条消息，生成预签名下载链接，发给 feishu:user:ou_xxxxxxx",
    "name": "视频处理通知"
  }'

Wake——发送到主会话链接到标题

WAKE_URL="http://YOUR_HOST:18789/hooks/wake"

curl -X POST "$WAKE_URL" \
  -H "Authorization: Bearer $HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "🔔 视频处理完成，请查看结果",
    "mode": "now"
  }'

参数说明链接到标题

Hook Token 链接到标题

从 ~/.openclaw/openclaw.json 中的 hooks.token 字段获取。这是外部系统调用 Hook 端口的认证凭证，通过 Authorization: Bearer 头传递。

feishu_target（Agent Turn）链接到标题

飞书消息的目标地址，格式为：

场景	格式
单聊	`feishu:user:ou_xxxxxxx`
群聊	`feishu:chat:oc_xxxxxxx`

这个值从 Agent 的聊天上下文中获取，或者通过飞书开放平台查询。Windmill 等外部系统回调时需要原样透传。

Session Key（Wake）链接到标题

Wake 方式的会话标识，格式通常为 feishu:ou_xxxxxxx（对应飞书用户 ID）。需要在 openclaw.json 中开启 allowRequestSessionKey: true 才允许外部传入。

实际案例：视频处理流水线链接到标题

完整的异步视频处理流程：

flowchart TD A["用户发消息：将 xxx/video.mov 生成带字幕视频"] B["Agent：提取 S3 key，调用 Windmill API"] C["Agent：回复‘已提交任务’"] D["Windmill 处理视频（几分钟）"] E["Windmill 完成 → POST /hooks/agent"] F["Agent Turn：生成预签名 URL"] G["Agent 格式化消息"] H["飞书推送通知到用户"] I["用户：点击下载"] A --> B B --> C C --> D D --> E E --> F F --> G G --> H H --> I style C fill:#e1f5fe style H fill:#e8f5e9 style I fill:#fff3e0

这种模式用户无需等待，处理完成会自动收到飞书通知。

总结链接到标题

OpenClaw 的 Hook 机制使其成为唯一能实现 “异步触发+主动通知” 的 AI Agent 工具
Agent Turn 适合定向通知、消息再处理，用途更广
Wake 适合回到主会话的简单提醒
选择哪种方式取决于是否需要指定目标用户和消息是否要入会话历史

为什么需要这个 链接到标题

整体架构 链接到标题

Agent Turn 与 Wake 链接到标题

Agent Turn（action: “agent”） 链接到标题

Wake（action: “wake”） 链接到标题

对比 链接到标题

前置条件 链接到标题

基础配置 链接到标题

Wake 额外配置 链接到标题

curl 代码示例 链接到标题

Agent Turn——发送消息到指定用户 链接到标题

Agent Turn——触发后让 Agent 自行格式化 链接到标题

Wake——发送到主会话 链接到标题

参数说明 链接到标题