《OpenClaw架构与源码解读》· 第 12 章 Cron、Webhooks 与事件驱动自动化

第 12 章 Cron、Webhooks 与事件驱动自动化前面第 8–10 章介绍的消息处理链路都是被动响应式的用户先说话OpenClaw 才行动。但 OpenClaw 更有价值的地方之一恰恰是它可以主动出击——在你没有发消息的时候悄悄把事情做了再来汇报。本章介绍三种让 OpenClaw「自己动起来」的机制Cron 定时任务、Webhooks 外部触发、以及类 Gmail Pub/Sub 的长链路事件源。12.1 Cron Jobs让 OpenClaw「记住」该做什么12.1.1 什么是 Cron JobsCron Jobs 就是定时任务在指定时间或时间间隔触发一段操作。在 OpenClaw 里你可以用 Cron Jobs 让它每天早上 8 点给你发今日简报天气、日历、收件箱摘要每 2 小时检查一次 CI/CD 状态有失败时主动告警每周一整理一次你的 GitHub Issue 积压或者每晚 11 点发一条「今天的未完成 Todo」。12.1.2 Cron 配置在~/.openclaw/openclaw.json中Cron Jobs 的配置格式大致如下// ~/.openclaw/openclaw.json宽松 JSON{cron:[{id:morning-briefing,name:早晨简报,schedule:0 8 * * *,// 每天 8:00message:给我一个今天的早晨简报天气、日历安排、未读邮件摘要。,enabled:true},{id:ci-check,name:CI 状态检查,schedule:0 */2 * * *,// 每 2 小时message:检查最近 2 小时的 CI/CD 状态有失败的通知我。,enabled:true}]}schedule字段使用标准的 cron 表达式分 时 日 月 星期表达式含义0 8 * * *每天 8:000 */2 * * *每 2 小时整点*/15 * * * *每 15 分钟0 9 * * 1每周一 9:0012.1.3 Cron 任务的触发流程// src/cron/cron-engine.ts伪代码classCronEngine{privatejobs:Mapstring,CronJobnewMap();asyncinit(configs:CronConfig[],agentPool:AgentPool){for(constconfigofconfigs){if(!config.enabled)continue;constjobschedule.createJob(config.schedule,async(){awaitthis.triggerJob(config,agentPool);});this.jobs.set(config.id,job);}}privateasynctriggerJob(config:CronConfig,agentPool:AgentPool){constsyntheticMsg:InboundMessage{id:cron:${config.id}:${Date.now()},channel:internal:cron,peerId:system,chatId:config.sessionId,text:config.message,timestamp:newDate(),raw:{triggerType:cron,jobId:config.id},};awaitgateway.dispatchInbound(syntheticMsg);}}关键设计点在于Cron 触发的「消息」走的是和用户消息完全一样的分发链路。这意味着 Cron 任务也会经过 Session 解析、Agent 路由、Agent Runtime、Skill 调用、回复生成最终把结果发回你的 Slack/iMessage。这种「统一入口」设计极大地简化了代码避免了 Cron 路径和用户消息路径之间的逻辑重复。12.1.4 管理 Cron Jobs# 列出所有 Cron Jobsopenclawcronlist# 启用/禁用某个 Jobopenclawcronenablemorning-briefing openclawcrondisable ci-check# 立刻手动触发一次不等到下次调度时间openclawcrontrigger morning-briefing# 新增一个 Cron Jobopenclawcronadd--idnightly-todo--schedule0 23 * * *\--message给我一个今天的未完成 Todo 总结--agentpersonal-assistant12.2 Webhooks让外部系统「推」给 OpenClaw12.2.1 Webhook 的使用场景Cron 是「定时触发」Webhook 是「事件触发」。GitHub 合并了一个 PR 可以触发 OpenClaw 发一条通知Sentry 检测到线上报错可以触发 OpenClaw 通知你并自动尝试诊断Stripe 收到一笔付款可以触发收款通知某个爬虫任务完成后可以触发 OpenClaw 处理数据并发送摘要。Webhook 的核心优势是近实时——事件发生后几秒内就能触发而不是像 Cron 那样要等到下一个轮询周期才知道。12.2.2 Webhook 端点的注册与配置Gateway 会暴露一个统一的 Webhook 端点POST http://localhost:18789/webhook/{webhookId}在~/.openclaw/openclaw.json里注册一个 Webhook{webhooks:[{id:github-pr-merged,name:GitHub PR 合并通知,secret:my-secret-token,messageTemplate:GitHub 上有一个 PR 被合并了{payload.pull_request.title}仓库{payload.repository.full_name},enabled:true}]}然后在 GitHub 的 Webhook 设置里填入对应的 Payload URL、Secret 和 Content type。12.2.3 Webhook 处理流程// src/gateway/server-webhook.ts伪代码app.post(/webhook/:webhookId,async(req,res){constconfigwebhookRegistry.get(req.params.webhookId);if(!config||!config.enabled){res.status(404).end();return;}// 1. 验证签名防止伪造请求constsignaturereq.headers[x-hub-signature-256]asstring;constisValidverifySignature(req.rawBody,config.secret,signature);if(!isValid){res.status(401).end();return;}// 2. 立即返回 200让发起方尽快确认接收避免超时重发res.status(200).end();// 3. 异步处理 Webhook 内容setImmediate(async(){constpayloadreq.body;constmessageTextrenderTemplate(config.messageTemplate,{payload});constsyntheticMsg:InboundMessage{id:webhook:${config.id}:${Date.now()},channel:internal:webhook,peerId:system,chatId:config.sessionId,text:messageText,timestamp:newDate(),raw:{triggerType:webhook,webhookId:config.id,payload},};awaitgateway.dispatchInbound(syntheticMsg);});});注意第 2 步先返回 200再异步处理。这是 Webhook 处理的最佳实践——大多数发起方GitHub、Stripe 等要求在 5 到 10 秒内收到响应如果处理逻辑太慢就会触发重发。先回 200 确认收到再慢慢处理是标准做法。12.2.4 幂等性重复触发的防护由于网络或发送方重试同一个 Webhook 事件可能被发送多次。为了避免重复触发 AgentGateway 需要做幂等去重constdeliveryIdreq.headers[x-github-delivery]asstring;if(deliveryId){constisDuplicateawaitidempotencyStore.check(deliveryId);if(isDuplicate){res.status(200).end();return;}awaitidempotencyStore.mark(deliveryId,TTL_24H);}12.3 Gmail Pub/Sub长链路事件源处理对于邮件这类特殊场景既不适合 Cron延迟较高也没有可靠的 Webhook 推送Gmail 提供了一套基于 Google Cloud Pub/Sub 的实时通知机制。你授权 Gmail 把邮件变更事件推送到某个 Google Cloud Pub/Sub 主题OpenClaw 订阅该主题收到通知后拉取最新邮件变更然后根据规则决定是否触发 Agent例如「有新的 GitHub 通知邮件时」。// src/gateway/gmail-pubsub.ts伪代码asyncfunctionstartGmailWatch(config:GmailPubSubConfig){constclientawaitgetGmailClient(config.userId);awaitclient.users.watch({userId:me,requestBody:{topicName:config.pubsubTopicName,labelIds:[INBOX],},});constpubsubnewPubSub({projectId:config.gcpProjectId});constsubscriptionpubsub.subscription(config.subscriptionName);subscription.on(message,async(message){message.ack();constnotificationJSON.parse(Buffer.from(message.dataasstring,base64).toString());awaitprocessGmailHistory(notification.historyId,config);});}asyncfunctionprocessGmailHistory(historyId:string,config:GmailPubSubConfig){constclientawaitgetGmailClient(config.userId);consthistoryawaitclient.users.history.list({userId:me,startHistoryId:historyId,historyTypes:[messageAdded],});constnewMessageshistory.data.history?.flatMap(hh.messagesAdded??[])??[];for(const{message}ofnewMessages){if(matchesRule(message,config.rules)){constsyntheticMsg:InboundMessage{id:gmail-pubsub:${message.id},channel:internal:gmail-pubsub,peerId:system,chatId:config.sessionId,text:收到一封新邮件ID:${message.id}。请检查并根据规则处理。,timestamp:newDate(),raw:{messageId:message.id,historyId},};awaitgateway.dispatchInbound(syntheticMsg);}}}12.4 事件总线统一的异步事件分发除了上面三种机制Gateway 内部还有一个轻量级的事件总线EventBus用于在各模块之间发布和订阅事件避免直接耦合// 发布事件eventBus.emit(skill:gmail:archive_completed,{sessionId:main,count:17,timestamp:newDate(),});// 订阅事件eventBus.on(skill:gmail:archive_completed,async(data){awaitdashboard.updateStats({type:archive,count:data.count});});EventBus 让不同模块Skills、Nodes、Automation Engine、Web UI可以松散地相互感知而不需要直接调用对方的接口。12.5 源码走读导向在阅读自动化相关代码时可以沿以下路径。Cron Engine 在src/cron/中关注如何把 cron 表达式转化为定时器以及如何构造合成消息触发 Gateway。Webhook Handler 在src/gateway/中与 webhook 相关的文件如server-webhook.ts以及src/plugin-sdk/webhook-request-guards.ts签名验证和src/plugin-sdk/persistent-dedupe.ts幂等去重。Gmail Pub/Sub 相关代码可能分布在 Skills 或src/gateway/的特定模块中关注 Watch 注册和 Pub/Sub 消息解析。EventBus 在src/gateway/中事件相关模块。12.6 小结本章介绍了 OpenClaw 的三种主动触发机制。Cron 定时触发构造合成消息走标准分发链路配置简单直观。Webhook 是外部事件推送先 200 再异步处理注意签名验证和幂等去重。Gmail Pub/Sub 专为邮件类实时通知设计依赖 GCP 基础设施。三种机制的共同点是都最终收敛到 Gateway 的dispatchInbound这同一个入口这让自动化任务和用户主动触发的任务在处理逻辑上保持完全一致。下一章我们进入本书的「动手实战」章节从零开始一步步构建你自己的 Skill。