OpenClaw 自动化入门：cron、hooks、webhook 什么时候用

为什么这篇值得先看

OpenClaw 一旦从“聊天助手”进入“长期助手”，自动化就会变成刚需。但很多人第一反应是：既然要自动化，那就写 cron。

这一步很容易走偏。cron 只解决“按时间触发”的问题，它不解决内部事件、外部回调、插件策略、失败可见性和权限治理。把所有任务都塞进 cron，最后会得到一堆难排查、难停止、难追责的后台行为。

这篇帮你做一个更稳的判断：这个任务到底应该由时间触发、Gateway 内部事件触发、外部系统 HTTP 推送，还是插件运行时策略触发。

先抓住这 3 个关键点

• cron 是 Gateway 内置调度器，适合提醒、报告、周期检查和后台 chores。
• hooks 是 Gateway 内部事件后的自动化表面，适合 /new、/reset、message:sent、gateway:startup 这类事件副作用。
• webhook 是外部系统把事件推给 OpenClaw 的入口，必须重点处理 token、路径、agent 范围和网络暴露边界。

一句话记住：触发方式决定自动化形态，风险等级决定能不能后台运行。

先用这张决策表

你想做什么	优先选择	为什么
每天 9 点发提醒或检查报告	cron / Scheduled tasks	时间驱动，Gateway 负责持久化和运行历史
每 15 分钟跑一次队列探针	cron command payload	确定性脚本，不必启动模型对话
/new 后保存上下文或写日志	internal hooks	Gateway 内部命令事件触发
消息发送后同步一份审计日志	internal hooks	message:sent 属于内部事件
阻止某个工具调用或改写提示	plugin hooks	需要运行时策略、优先级和拦截语义
Gmail、GitHub、监控系统推送事件	webhook / mapped hooks	外部系统主动发 HTTP 请求
浏览器网页登录后做周期检查	cron + Browser	但必须先处理登录态和人工边界

如果你只能先记一条：定时用 cron，内部副作用用 hooks，外部推送用 webhook，运行时拦截用 plugin hooks。

cron 适合什么

官方 Scheduled tasks 文档把 cron 描述为 Gateway 内置调度器。它会持久化 jobs、运行状态和历史记录；重启后不会因为内存丢失而忘记任务。

适合 cron 的任务：

• 每天汇总站点数据、工单、告警或日志。
• 每小时检查一个公开状态页或队列长度。
• 在固定时间提醒用户处理审批。
• 周期性运行一个确定性脚本，并把结果发到聊天渠道或 webhook endpoint。
• 给长期助手一个固定节奏的后台检查。

不适合 cron 的任务：

• 外部事件一发生就要立刻响应。
• 需要拦截工具调用、阻止消息或修改运行时策略。
• 每次都依赖人工登录、验证码或不可预测网页状态。
• 失败后无法被看到，也没人负责处理。

示例：确定性队列探针更适合 command payload，而不是模型对话。

openclaw cron create "*/15 * * * *" \
  --name "Queue depth probe" \
  --command "scripts/check-queue.sh" \
  --command-cwd "/srv/app" \
  --announce \
  --channel telegram \
  --to "-1001234567890"

这个任务回答的是“每 15 分钟执行脚本并回报结果”。如果你把它写成“让 Agent 想办法看看队列”，反而更不稳定。

hooks 适合什么

官方 hooks 文档把 internal hooks 定义为 Gateway 内部发生某些事件时运行的小脚本。典型事件包括：

• command:new
• command:reset
• command:stop
• session:compact:before
• session:compact:after
• agent:bootstrap
• gateway:startup
• gateway:shutdown
• gateway:pre-restart
• message:received
• message:transcribed
• message:preprocessed
• message:sent

它适合做“事件后的副作用”，例如：

• /new 后保存一份 session 摘要。
• /reset 后写审计日志。
• gateway:pre-restart 时给当前会话发短通知。
• message:sent 后同步一份轻量 telemetry。
• agent:bootstrap 前注入工作区额外文件。

internal hooks 不适合做复杂策略拦截。如果你要重写 prompt、阻止工具、取消外发消息或加 middleware，应看 plugin hooks，而不是把逻辑塞进文件式 hook。

webhook 适合什么

webhook 适合“外部系统知道发生了什么，并希望通知 OpenClaw”。

常见例子：

• GitHub issue / PR 事件推送给 OpenClaw。
• 监控系统发现异常，请 OpenClaw 生成排查摘要。
• Gmail PubSub 触发 inbox 检查。
• 自有业务系统把订单、工单、告警推给 OpenClaw。

官方 Scheduled tasks 文档里的 hook endpoint 设计强调了几条安全边界：

• 请求应带 Authorization: Bearer <token> 或 x-openclaw-token。
• query-string token 会被拒绝。
• hook endpoint 应放在 loopback、tailnet 或可信反向代理后面。
• 使用专用 hook token，不要复用 Gateway auth token。
• 限制 hooks path、allowed agent IDs 和 session key 形态。
• payload 默认需要安全边界包装。

这说明 webhook 的重点不是“能不能接 HTTP”，而是“谁能触发、能触发哪个 agent、触发后能影响什么”。

/hooks/wake 和 /hooks/agent 怎么理解

官方文档把外部触发分成两个常见方向：

endpoint	适合场景	结果
POST /hooks/wake	给 main session 放入一个系统事件	像提醒或轻量通知，进入主会话 wake 流
POST /hooks/agent	运行一个 isolated agent turn	更适合外部系统触发一次独立任务

如果只是“新邮件到了，请提醒我看”，wake 更自然。如果是“监控告警来了，请单独分析这条告警并回传结果”，agent 更像合适入口。

最小请求形态可以这样理解：

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"}'

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"}'

这只是示意。生产环境里还要处理网络边界、token 轮换、agent 限制、timeout、失败通知和日志。

和 Browser 自动化怎么组合

Browser 很容易和 automation 结合，但也最容易出事故。

适合后台化的 Browser 任务：

• 打开公开状态页，截图留证。
• 进入测试账号后台，读取只读指标。
• 检查文档站、价格页、页面可用性。
• 运行一个不涉及登录态的网页 smoke check。

不适合直接后台化的 Browser 任务：

• 每次都需要验证码或 2FA。
• 依赖个人真实 session，且运行时无人值守。
• 会发布、删除、付款、导出客户数据。
• 失败后会重复提交表单或触发风控。

如果你的任务依赖 Browser，先看 OpenClaw Browser 工具 和 Browser 登录流，再决定是否进入 cron。

上线前安全清单

每条自动化上线前，至少检查这些项：

• 触发源：时间、内部事件、外部 HTTP、插件策略，是否选对。
• 权限范围：能触发哪个 agent、哪个 session、哪些工具、哪些网页。
• 认证方式：hook token 是否专用，是否避免 query token，是否有轮换方式。
• 网络边界：endpoint 是否只在 loopback、tailnet 或可信代理后面。
• 失败可见性：错误会发到哪里，谁看到，多久处理。
• 停止方式：如何 disable job、remove hook、撤销 token 或关闭入口。
• 回滚策略：自动化做错时，业务侧如何恢复。
• 审计记录：谁创建，为什么创建，最后一次验证是什么时候。

自动化越靠近生产环境，越要像运维系统一样管理，而不是像临时 prompt 一样管理。

常见坑

• 把所有任务都塞进 cron，导致事件来了也只能等下一轮轮询。
• 把 internal hooks 当成 plugin policy hook，用错拦截面。
• webhook endpoint 暴露到公网，却没有可信代理、专用 token 或 agent 限制。
• query string 里放 token，泄露到日志和浏览器历史。
• cron 失败没有通知，长期以为任务在正常运行。
• 后台 Browser 任务依赖个人登录态，但执行时无人处理验证码和风控。
• 自动化没有 owner，出问题时没人知道该停哪一条 job。

排错顺序

自动化不按预期运行时，按这个顺序排查：

1. 触发是否发生：cron 是否 due，hook 事件是否被 Gateway 看到，webhook 请求是否到达。
2. 入口是否启用：hooks 是否 enabled，cron job 是否 enabled，plugin hook 是否安装并加载。
3. 认证是否通过：token、path、allowedAgentIds、session key 限制是否挡住了请求。
4. 运行上下文是否正确：main、isolated、current、custom session 是否符合任务需求。
5. 执行结果是否可见：run history、background task、chat delivery 或 webhook delivery 是否有记录。
6. 业务动作是否越界：如果自动化卡在 Browser、审批或外部 API，可能是风险边界设计正确地把它挡住了。

完成检查

• 你能根据任务特征选择 cron、internal hooks、plugin hooks 或 webhook。
• 每条自动化都有 owner、触发源、权限范围和停止方式。
• webhook endpoint 不裸露给不可信网络，token 不出现在 query string。
• cron 任务的运行历史、失败通知和回滚路径都能被找到。
• Browser 相关自动化已经处理登录态、验证码和敏感动作边界。

下一步

• 如果你还没有 Gateway 心智模型，先看 OpenClaw Gateway 架构。
• 如果你的自动化要读网页或复用登录态，继续看 OpenClaw Browser 工具。
• 如果你想把渠道、Browser、webhook 串成真实场景，继续看 OpenClaw 多渠道助手案例。

为什么建议把这篇收藏起来

• 自动化是 OpenClaw 从“会聊天”走向“会长期工作”的分水岭。
• cron、hooks、webhook 名字相近，但背后的运行边界完全不同。
• 不要先问“怎么触发”，先问“这个任务该不该无人值守”。