OpenClaw系列第19课:Webhook/Hooks – 外部事件触发 AI

这是「OpenClaw 教程课程」第 19 课。 第 18 课我们讲了 Cron：按时间触发 AI。今天换一个角度：不是到点触发，而是有外部事件发生时触发 AI。

图：Cron 是按时间触发；Webhook / Hooks 是按事件触发。外部系统、消息、命令、Gateway 生命周期事件，都可以成为自动化入口。

上一课我们解决的是：

“能不能每天早上 8 点自动做一件事？”

这类问题适合 Cron。

但还有另一类自动化问题：

“能不能有事情发生时，马上让 AI 处理？”

比如：

• GitHub Actions 跑完后，让 OpenClaw 总结结果
• n8n / Zapier 工作流触发 OpenClaw
• Gmail 收到新邮件后，让 OpenClaw 处理
• 外部监控报警时，让 OpenClaw 分析告警
• 用户发 /new 或 /reset 时，自动保存会话摘要
• Gateway 启动时，自动运行某个初始化逻辑

这些不是“固定时间”。

它们是“事件触发”。

这就是 Webhook / Hooks 的核心价值：

让 OpenClaw 从被动聊天，变成能响应外部事件和内部生命周期事件的自动化系统。

一、先区分两个词：Webhook 和 Hooks

这两个词很像，新手很容易混。

但在 OpenClaw 文档里，它们不是同一件事。

Webhook：外部系统通过 HTTP 调 OpenClaw

Webhook 更像一个对外入口。

外部系统发一个 HTTP POST 请求到 OpenClaw Gateway。

Gateway 收到请求后，唤醒主会话或启动一次 isolated agent run。

它回答的问题是：

外部系统怎么触发 OpenClaw？

例如：

• GitHub 发请求
• n8n 发请求
• 监控系统发请求
• Gmail Pub/Sub 发请求
• 你自己的脚本发 curl

Hooks：Gateway 内部事件触发脚本

Hooks 更像内部事件监听器。

它们在 Gateway 内部某些事件发生时运行。

它回答的问题是：

OpenClaw 自己发生某件事时，要不要自动跑一段逻辑？

例如：

• 用户发 /new
• 用户发 /reset
• 用户发 /stop
• Gateway 启动
• 消息收到
• 消息发送
• 会话压缩前后
• Agent bootstrap 前

所以一句话区分：

Webhook 是外部事件进来，Hooks 是内部事件发生。

图：Webhook 是外部系统通过 HTTP 触发 OpenClaw；Hooks 是 Gateway 内部事件触发脚本或插件逻辑。

二、Webhook / Hooks 和 Cron 有什么区别？

上一课讲 Cron，这一课讲 Webhook / Hooks。

这三个经常一起出现。

最简单的区分是：

也就是说：

• 按时间：用 Cron
• 外部系统通知你：用 Webhook
• OpenClaw 内部发生事件：用 Hooks

举个例子：

每天早上 8 点总结邮件

适合 Cron。

因为触发条件是时间。

有新邮件进来马上处理

适合 Webhook / Gmail PubSub。

因为触发条件是“新邮件事件”。

用户 /reset 时保存会话摘要

适合 Hooks。

因为触发条件是 OpenClaw 内部命令事件。

图：Cron 按时间触发，Webhook 按外部事件触发，Hooks 按 Gateway 内部事件触发。

三、Webhook 的基础配置

OpenClaw 文档里提到，Gateway 可以暴露 HTTP webhook endpoints，用于外部触发。

基础配置类似：

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",  },}

这里有三个关键点。

1）enabled

开启 hooks / webhook 入口。

enabled: true

2）token

共享密钥。

外部请求必须带这个 token。

不要用简单字符串。

也不要复用 Gateway 主认证 token。

最好用专门的强随机 token。

3）path

入口路径。

比如：

/hooks

文档里也提醒，不要把 hooks.path 放到 /，这是不安全的，OpenClaw 会拒绝。

路径应该是一个专门子路径。

四、Webhook 怎么认证？

文档里写得很明确：每个请求都必须带 hook token。

推荐方式是：

Authorization: Bearer <token>

也支持：

x-openclaw-token: <token>

但有一个很重要的安全点：

Query-string tokens are rejected.

也就是说，不要这样：

/hooks/agent?token=xxx

为什么？

因为 URL 很容易出现在：

• 浏览器历史
• 服务器日志
• 代理日志
• 错误报告
• 第三方监控

token 放在 URL 里很容易泄露。

所以正确做法是放 header。

五、/hooks/wake：唤醒主会话

OpenClaw 文档里列了一个基础 webhook endpoint：

POST /hooks/wake

它的作用是：

给 main session 加一个 system event，并唤醒处理。

示例：

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"New email received","mode":"now"}'

请求体里最重要的是：

• text：事件描述，必填
• mode：now 或 next-heartbeat

你可以把它理解成：

外部系统敲一下门，告诉主会话：有件事发生了。

它适合轻量触发。

比如：

• 外部系统通知“有新事件”
• 希望主会话在下一次 heartbeat 处理
• 不想为每次事件都开 isolated run

六、/hooks/agent：运行一次 isolated agent turn

另一个重要 endpoint 是：

POST /hooks/agent

它的作用是：

直接启动一次 isolated agent turn。

示例：

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'

常见字段包括：

• message：任务内容，必填
• name：任务名
• agentId：指定 Agent
• wakeMode
• deliver
• channel
• to
• model
• fallbacks
• thinking
• timeoutSeconds

你可以先简单理解成：

/hooks/agent 更像“外部系统直接派一个独立任务给 Agent”。

它适合：

• CI 完成后总结结果
• 外部监控报警后分析
• Gmail 新邮件触发一次整理
• 第三方工作流让 OpenClaw 执行明确任务

图：/hooks/wake 更像把事件放进主会话；/hooks/agent 更像启动一次独立 Agent run。

七、/hooks/wake 和 /hooks/agent 怎么选？

新手可以用这个判断。

选 /hooks/wake

如果你只是想：

• 通知主会话有事件发生
• 让主会话稍后处理
• 把事件作为系统提醒注入
• 不需要独立任务上下文

就用 wake。

比如：

New email received

这类事件可以先作为系统事件进入主会话。

选 /hooks/agent

如果你想：

• 立即跑一个明确任务
• 不污染主对话
• 每次事件独立处理
• 指定模型、thinking、timeout
• 处理完后直接投递结果

就用 agent。

比如：

Summarize this CI failure and suggest next steps.

这类任务更适合 isolated agent turn。

一句话：

wake 是通知主会话，agent 是启动独立任务。

八、Mapped hooks：把自定义路径映射成动作

文档里还提到：

POST /hooks/<name>

这些是 mapped hooks。

它们通过 hooks.mappings 配置，把自定义 payload 转成 wake 或 agent 动作。

为什么需要它？

因为外部系统发来的 JSON 格式经常不一样。

比如 GitHub、Stripe、n8n、监控系统，各有自己的 payload。

你不一定想让它们都按 OpenClaw 的标准格式发。

Mapped hooks 就可以做一层转换：

• 收到外部 payload
• 提取你关心的字段
• 生成一个 OpenClaw 能理解的 wake 或 agent request

新手先知道有这个能力即可。

实际配置时，要根据具体 payload 设计 mapping。

九、Hooks：内部事件触发脚本

讲完外部 Webhook，再讲内部 Hooks。

OpenClaw 文档里说：

Hooks are small scripts that run when something happens inside the Gateway.

也就是说，Hooks 是 Gateway 内部事件发生时运行的小脚本。

常见事件包括：

这类 Hooks 更适合做 OpenClaw 内部自动化。

比如：

• /new 时保存最近上下文
• Gateway 启动时运行 BOOT.md
• 命令执行时写审计日志
• 压缩会话前后给用户提示
• agent bootstrap 前注入额外文件

十、Hooks 的文件结构

如果你自己写一个内部 hook，文档里给了基本结构：

my-hook/├── HOOK.md└── handler.ts

HOOK.md

用于描述 hook 的元信息和文档。

示例结构：

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"] } }---# My HookDetailed documentation goes here.

handler.ts

是真正执行逻辑的代码。

示例：

consthandler = async (event) => {if (event.type !== "command" || event.action !== "new") {return;  }console.log(`[my-hook] New command triggered`);  event.messages.push("Hook executed!");};exportdefault handler;

这不是新手必须马上会写的内容。

但你要理解：

Hooks 是代码级扩展，不是普通聊天命令。  

写 hook 前，一定要明确它监听什么事件、做什么动作、有没有副作用。

十一、Hook 从哪里加载？

OpenClaw 文档里列了 hook discovery 顺序。

大致包括：

1. Bundled hooks：OpenClaw 自带
2. Plugin hooks：插件内置
3. Managed hooks：~/.openclaw/hooks/
4. Workspace hooks：<workspace>/hooks/

其中 workspace hooks 默认不会自动启用。

需要显式 enable。

这点很重要。

因为 workspace 里的代码更接近项目自定义逻辑，默认不启用更安全。

十二、常用 hooks 命令

OpenClaw 提供了 openclaw hooks CLI。

常用命令：

openclaw hooks listopenclaw hooks checkopenclaw hooks info <hook-name>openclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

list

查看可用 hooks。

openclaw hooks list

check

检查 hooks 是否 ready。

openclaw hooks check

info

查看某个 hook 的详细信息。

openclaw hooks info session-memory

enable / disable

启用或禁用 hook。

openclaw hooks enable session-memoryopenclaw hooks disable command-logger

文档里也提醒：启用或禁用后，需要重启 Gateway，让 hooks 重新加载。

十三、OpenClaw 自带哪些 bundled hooks？

文档里列了一些 bundled hooks。

例如：

这些 hooks 很适合帮助你理解内部 hooks 的价值：

• 有的是记忆增强
• 有的是审计日志
• 有的是用户体验提示
• 有的是启动自动化

它们都不是外部 HTTP 触发。

它们是 OpenClaw 自己事件触发。

图：内部 Hooks 监听 Gateway 内部事件，例如命令、消息、启动、关闭、会话压缩和 Agent bootstrap。

十四、插件 Webhooks：更高级的外部自动化入口

除了基础 /hooks/wake 和 /hooks/agent，OpenClaw 还有 Webhooks plugin。

文档里说，这个插件提供：

authenticated HTTP routes that bind external automation to OpenClaw TaskFlows.

简单说：

它让外部系统通过认证 HTTP route 创建和驱动 TaskFlow。

适合这些场景：

• Zapier 触发一个 managed TaskFlow
• n8n 驱动一个多步任务
• 内部系统创建一个 flow
• CI 系统触发一个可追踪的工作流

配置大概像这样：

{  plugins: {    entries: {      webhooks: {        enabled: true,        config: {          routes: {            zapier: {              path: "/plugins/webhooks/zapier",              sessionKey: "agent:main:main",              secret: {                source: "env",                provider: "default",                id: "OPENCLAW_WEBHOOK_SECRET",              },              controllerId: "webhooks/zapier",              description: "Zapier TaskFlow bridge",            },          },        },      },    },  },}

这个比基础 webhook 更偏进阶。

新手先理解：

• 基础 /hooks/wake：通知主会话
• 基础 /hooks/agent：跑一次 isolated Agent
• Webhooks plugin：让外部系统创建和驱动 TaskFlow

不要一开始就上最复杂的。

十五、安全边界：Webhook 是入口，入口就必须管住

Webhook 最大的问题不是“怎么触发”。

而是：

谁可以触发？触发后能做什么？

文档里有一段 warning 很重要。

建议包括：

• hook endpoints 放在 loopback、tailnet 或可信反代后面
• 使用专用 hook token
• 不要复用 gateway auth token
• hooks.path 使用专门子路径，不要用 /
• 设置 hooks.allowedAgentIds 限制显式 agentId 路由
• 保持 hooks.allowRequestSessionKey=false，除非确实需要
• 如果允许请求指定 sessionKey，也要设置 allowedSessionKeyPrefixes
• hook payload 默认会被安全边界包裹

这些建议背后的原因很简单：

Webhook 是让外部系统喊醒 AI 的门。门不能随便开。  

尤其是 /hooks/agent 这类入口，如果被滥用，外部请求就能不断启动 Agent run。

所以一定要控制：

• 谁能调用
• 调用什么路径
• token 是否够强
• 是否暴露公网
• 能否指定 agentId
• 能否指定 sessionKey
• 能否投递到外部渠道

图：Webhook 是外部事件进入 OpenClaw 的入口，必须用 token、路径、网络边界、agent allowlist 和 session 限制来保护。

十六、Gmail Pub/Sub：一个典型 Webhook 场景

OpenClaw 文档里把 Gmail Pub/Sub 作为 Webhook 集成的典型例子。

场景是：

Gmail 收到新邮件，通过 Google Pub/Sub 推送事件，最终触发 OpenClaw。  

OpenClaw 提供了辅助命令：

openclaw webhooks gmail setup --account openclaw@gmail.com

这个命令会配置 Gmail watch、Pub/Sub 和 OpenClaw webhook delivery。

文档也提到，通常需要：

• gcloud CLI
• gog / gogcli
• OpenClaw hooks enabled
• Tailscale 用于公开 HTTPS endpoint

如果你只是学习 Webhook，不必一上来就接 Gmail。

但它很好地说明了 Webhook 的价值：

事件发生在外部系统，OpenClaw 被动接收事件，然后启动 AI 处理。  

十七、一个最小 Webhook 测试流程

如果你只是想验证 Webhook 能不能通，可以从 /hooks/wake 开始。

第一步：启用 hooks

配置：

{  hooks: {    enabled: true,    token: "replace-with-strong-secret",    path: "/hooks",  },}

第二步：重启 Gateway

配置变更后，重启 Gateway。

第三步：本机 curl 测试

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer replace-with-strong-secret' \  -H 'Content-Type: application/json' \  -d '{"text":"Webhook test event","mode":"now"}'

第四步：观察主会话是否被唤醒

如果成功，主会话会收到系统事件。

如果没成功，先检查：

• Gateway 是否运行
• hooks.enabled 是否为 true
• path 是否正确
• token 是否一致
• 请求是否走了正确端口
• 是否被网络、防火墙、反代拦截

十八、一个 /hooks/agent 测试流程

如果你想测试 isolated agent run，可以用：

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer replace-with-strong-secret' \  -H 'Content-Type: application/json' \  -d '{    "name":"Webhook Test",    "message":"请用 3 条以内总结：Webhook 已经成功触发 OpenClaw。",    "deliver": false,    "timeoutSeconds": 120  }'

这里我建议测试时先：

"deliver":false

也就是先不主动投递到外部渠道。

等确认流程稳定后，再考虑 delivery。

这是一种安全习惯：

先本机验证，再开放网络；先不投递，再启用投递。  

十九、什么时候用基础 Webhook，什么时候用 Webhooks plugin？

可以这样选。

用基础 Webhook

如果你只是想：

• 通知 OpenClaw 有事件发生
• 让 OpenClaw 跑一次明确任务
• 外部系统只需要简单触发
• 不需要复杂状态管理

用 /hooks/wake 或 /hooks/agent 就够了。

用 Webhooks plugin

如果你需要：

• 外部系统创建 TaskFlow
• 多步工作流
• 等待 / 恢复 / 完成 / 失败状态
• n8n / Zapier 之类工作流系统长期驱动 OpenClaw
• 更明确的 managed flow 控制

再考虑 Webhooks plugin。

不要一开始就把简单触发做复杂。

二十、适合新手的 Webhook / Hooks 提问模板

下面这些句式可以直接复制。

1）解释现有 hooks 状态

请帮我检查当前 OpenClaw hooks 是否启用，并列出可用 hooks。不要修改配置。

2）设计一个 Webhook 触发方案

我想让外部监控报警时触发 OpenClaw 分析告警。请帮我设计 /hooks/agent 的 payload、token 安全建议和投递方式，先不要修改配置。

3）创建安全测试计划

请给我一个本机 loopback 测试 /hooks/wake 的步骤，使用 header token，不要使用 query token。

4）区分 Cron 和 Webhook

这个任务是按时间触发还是按外部事件触发？请帮我判断应该用 Cron、Webhook 还是内部 Hooks。

5）内部 hook 场景

我想在用户执行 /reset 时自动保存上下文。请先解释应该用哪个 bundled hook，启用前需要检查什么。

6）安全审查

请帮我审查这个 webhook 设计：入口是否暴露过大、token 是否独立、是否允许外部指定 agentId 或 sessionKey、是否会主动发外部消息。

这些模板的重点是：

先设计边界，再开放入口。

二十一、常见坑

坑 1：把 Webhook 和 Hooks 混成一件事

Webhook 是外部 HTTP 入口。

Hooks 是 Gateway 内部事件脚本。

先分清楚再设计。

坑 2：用 query 参数传 token

错误：

/hooks/agent?token=xxx

正确：

Authorization: Bearer xxx

坑 3：把 webhook 暴露到公网但没有保护

Webhook 入口要放在 loopback、tailnet 或可信反代后面。

如果必须公网访问，token、路径、速率限制、反代安全都要做好。

坑 4：让外部 payload 直接决定 agentId 或 sessionKey

这很危险。

默认应该限制 allowedAgentIds，并保持 allowRequestSessionKey=false。

坑 5：一开始就让 webhook 主动发消息

测试阶段建议先 deliver: false。

确认触发和任务内容没问题后，再启用投递。

坑 6：内部 hook 写了太重的逻辑

内部 hook 发生在 Gateway 生命周期或消息流程里。

如果 hook 太慢、太重、容易失败，可能影响正常体验。

hook 应该小、快、明确。

坑 7：启用 hook 后忘了重启 Gateway

hooks enable / disable 后，通常需要重启 Gateway 让配置生效。

二十二、Webhook / Hooks 的安全原则

我建议记住这 7 条。

1. Webhook 是入口，必须有强 token。
2. token 放 header，不放 URL。
3. 入口优先放 loopback / tailnet / trusted proxy 后面。
4. 不要让外部请求随便指定 agentId 或 sessionKey。
5. 测试阶段先 deliver:false。
6. 内部 Hooks 要轻量，不要阻塞 Gateway 关键流程。
7. 简单触发用基础 Webhook，复杂工作流再用 Webhooks plugin。

二十三、这一课最值得记住的一句话

如果今天只记一句话，我建议你记这句：

Cron 按时间触发，Webhook 按外部事件触发，Hooks 按 OpenClaw 内部事件触发。

再补一句安全原则：

先关好入口，再让 AI 响应事件。

二十四、总结

今天这节课，我们讲清楚了 OpenClaw 的 Webhook / Hooks：

1. Webhook 是外部系统通过 HTTP 触发 OpenClaw。
2. Hooks 是 Gateway 内部事件触发脚本或插件逻辑。
3. Cron 按时间触发，Webhook 按外部事件触发，Hooks 按内部事件触发。
4. /hooks/wake 用来给主会话注入 system event 并唤醒。
5. /hooks/agent 用来运行一次 isolated agent turn。
6. Mapped hooks 可以把自定义路径和 payload 转成 wake 或 agent 动作。
7. 内部 hooks 可以响应 /new、/reset、message、gateway startup 等事件。
8. OpenClaw 提供 openclaw hooks list/check/info/enable/disable 管理内部 hooks。
9. Webhooks plugin 适合更复杂的 TaskFlow 外部驱动场景。
10. Webhook 是入口，必须重视 token、路径、网络暴露和权限边界。

学会 Webhook / Hooks 后，OpenClaw 的自动化就不再只依赖时间。

它可以响应真实世界里的事件：邮件、CI、监控、第三方工作流、内部命令和 Gateway 生命周期。

这就是从“定时自动化”走向“事件驱动自动化”的关键一步。

下一课预告

下一课我们会讲：

第 20 课：Heartbeat——保持 Agent 活跃的机制

也就是：

• Heartbeat 是什么
• 它和 Cron 有什么区别
• 为什么后台事件需要 heartbeat 唤醒
• HEARTBEAT.md 怎么用
• 怎么避免 heartbeat 变成打扰

🦞 本文由八条撰写，持续更新中。