第6课：自动化体系 — Hooks、Cron、Heartbeat、TaskFlow 配 TaoToken 的 settings.json 骨架

1. 从一次“自动化翻车”说起为什么需要 settings.json 骨架你可能已经写过不少自动化脚本定时跑个任务、收到消息触发一段逻辑、每隔几分钟检查一次状态。单个脚本跑起来没问题但一旦把它们放进同一个 AI 工具链里问题就来了——Key 散落在各个脚本里、触发时机互相打架、定时任务和心跳检测重复调用、任务流跑到一半断了不知道从哪续。我试过最原始的做法每个脚本单独读环境变量结果换一次 Key 要改七八个文件还漏了一个导致半夜任务全挂。后来才意识到自动化体系真正需要的不是“更多脚本”而是一份统一的配置骨架把 Key/API 通道、触发时机、调度策略、心跳检测、任务编排全部收口到一个settings.json里。这篇就围绕 Hooks、Cron、Heartbeat、TaskFlow 四条线索给你一份可以直接复制的settings.json骨架并逐项验证每个自动化环节是否按预期生效。适合已经在用 AI 工具做日常自动化、但配置开始变得混乱的开发者也适合刚接触这套体系、想一次性把结构搭对的新手。核心检索词就四个Hooks 管事件触发Cron 管定时调度Heartbeat 管批量心跳检测TaskFlow 管多步骤任务编排——它们共用同一个 API 通道配置。2. 前置准备用 TaoToken 统一 Key 与 API 通道在写settings.json之前先把 API 通道这件事解决掉。自动化体系最怕的就是每个环节各配一套 KeyHooks 用一个、Cron 用一个、TaskFlow 又用一个排查问题时根本不知道是哪个环节的凭证失效了。TaoToken 在这里的作用是提供一个统一的 API 入口让 Hooks、Cron、Heartbeat、TaskFlow 四类场景共用同一套 Key 和 base URL。这样你只需要在settings.json里维护一份凭证所有自动化环节都从这里读取。具体操作先到控制台创建 API Key然后确认你的接入文档里 base URL 的写法。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入文档参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite API 基础地址是 https://taotoken.net/api 这个不加 UTM直接作为配置值写入。拿到 Key 之后不要急着写进各个脚本。我们把它作为settings.json里的一个顶层provider节点后面所有自动化模块通过引用这个节点来获取通道。这样做的直接好处是换 Key 只改一处排查通道问题只看一个地方。注意Key 不要硬编码进会提交到版本库的文件。骨架里我们用占位符${TAOTOKEN_API_KEY}实际运行时从环境变量注入。3. 可复制配置settings.json 完整骨架下面这份骨架把四类自动化场景拆成四个顶层节点共用provider通道。你可以直接复制把占位符替换成自己的值。{ provider: { name: taotoken, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, defaultModel: claude-sonnet, timeoutMs: 60000, retry: { maxAttempts: 3, backoffMs: 2000 } }, hooks: { internal: { enabled: true, entries: { command-logger: { enabled: true }, session-memory: { enabled: true }, boot-md: { enabled: true }, bootstrap-extra-files: { enabled: true } } }, custom: [ { event: command:new, handler: ./hooks/snapshot.ts, enabled: true }, { event: message:received, handler: ./hooks/audit.ts, enabled: true }, { event: gateway:startup, handler: ./hooks/init-check.ts, enabled: true } ] }, cron: { enabled: true, timezone: Asia/Shanghai, jobs: [ { name: daily-report, schedule: { type: cron, expr: 0 9 * * * }, session: isolated, message: 生成昨日使用报告, announce: true, deleteAfterRun: false }, { name: health-check, schedule: { type: every, intervalMs: 1800000 }, session: isolated, message: 检查系统状态并报告, announce: true } ], failureAlert: { after: 3, channel: webchat, mode: announce, cooldownMs: 3600000 } }, heartbeat: { enabled: true, intervalMs: 300000, taskFile: ./HEARTBEAT.md, silentToken: HEARTBEAT_OK, announceOnChange: true, checks: [ { name: inbox, type: email }, { name: calendar, type: calendar }, { name: notifications, type: webhook } ] }, taskflow: { enabled: true, maxConcurrent: 2, defaultTimeoutMs: 600000, flows: [ { name: research-report, steps: [ { id: search, action: agent, prompt: 搜索主题相关资料 }, { id: analyze, action: agent, dependsOn: [search] }, { id: compose, action: agent, dependsOn: [analyze] } ], onFailure: retry, maxRetries: 2 } ] } }这份骨架的关键设计点provider是唯一通道来源四个自动化节点都隐式继承它hooks.custom用数组而不是对象方便按顺序执行cron.jobs里每个任务显式声明session类型避免默认值带来的上下文污染heartbeat.checks把多个检查合并到一次心跳里这正是 Heartbeat 相对 Cron 的核心优势。4. 逐项验证确认每个自动化环节生效配置写完不代表生效。下面按 Hooks、Cron、Heartbeat、TaskFlow 顺序给出可执行的验证动作。4.1 验证 Hooks 事件触发Hooks 的本质是事件触发的小脚本。验证思路是触发一个已知事件看 handler 是否被调用、副作用是否产生。先确认内置 Hook 加载成功。启动 Gateway 后查看日志应该能看到command-logger、session-memory等条目被注册。然后手动触发command:new# 触发 /new 命令观察 snapshot handler 是否执行 openclaw command new --verbose如果./hooks/snapshot.ts里写了日志输出你应该能在终端看到对应记录。再触发message:received检查audit.ts是否写入了审计日志文件。两个事件都通过说明 Hooks 链路正常。4.2 验证 Cron 定时任务Cron 验证分两步先确认调度器识别了任务再确认任务真的会执行。# 列出当前注册的所有 cron 任务 openclaw cron list # 手动触发一次不等定时 openclaw cron run daily-report --nowcron list应该输出daily-report和health-check两条且 schedule 类型正确。--now手动触发后检查isolatedsession 是否被创建、报告是否生成。如果配置了announce: true你应该在 webchat 频道收到消息。失败告警也要验证故意让任务失败比如把 message 指向一个不存在的资源连续失败 3 次后检查 webchat 是否收到告警。冷却时间cooldownMs设为 1 小时意味着 1 小时内不会重复告警。4.3 验证 Heartbeat 心跳检测Heartbeat 的验证重点是“批量合并”和“静默完成”两个行为。# 查看心跳当前状态和下次触发时间 openclaw heartbeat status # 手动触发一次心跳 openclaw heartbeat trigger手动触发后观察HEARTBEAT.md里列出的检查项是否被批量执行。如果所有检查都无更新输出应该是HEARTBEAT_OK且不发送任何消息——这就是静默完成。如果某个检查有更新比如模拟一封新邮件应该生成报告并发送到配置的频道。这里有个容易踩的坑intervalMs设得太短比如低于 5 分钟会导致 API 调用过于频繁。骨架里设的是 300000 毫秒也就是 5 分钟这是比较稳妥的下限。4.4 验证 TaskFlow 任务编排TaskFlow 验证要看步骤依赖和失败重试是否正确。# 启动一个 taskflow 实例 openclaw taskflow start research-report # 查看执行状态 openclaw taskflow status research-reportstatus应该显示search步骤先执行完成后analyze才开始最后是compose。如果中间某步失败onFailure: retry和maxRetries: 2应该生效最多重试两次。你可以故意在analyze步骤注入一个错误观察重试行为。5. 本篇常见错排查配置骨架跑不起来大概率是下面几个问题。Key 读取失败${TAOTOKEN_API_KEY}没有被正确注入。检查环境变量是否导出以及settings.json的加载器是否支持变量替换。有些加载器只支持${VAR}语法不支持$VAR。Hooks 不触发先确认事件名拼写正确。command:new和command.new是两回事。再确认 handler 路径是相对settings.json所在目录而不是相对当前工作目录。Cron 任务不执行最常见的是时区问题。timezone字段如果没设默认用系统时区容器环境里经常是 UTC导致你以为的“每天 9 点”实际是北京时间 17 点。另一个原因是session类型选错current类型在创建时的 session 已关闭后无法执行。Heartbeat 一直发消息说明silentToken没匹配上。检查你的检查脚本在无更新时是否真的输出了HEARTBEAT_OK大小写和空格都要一致。TaskFlow 卡住dependsOn引用了不存在的步骤 id或者步骤之间形成了循环依赖。用taskflow status看哪个步骤一直处于 pending 状态基本就能定位。API 调用超时provider.timeoutMs设得太短或者retry.maxAttempts不够。长任务比如 TaskFlow 里的分析步骤建议单独调大超时不要用全局默认值。6. 把通道和编排分开维护这套骨架跑通之后日常维护其实很轻。我的习惯是provider节点只在换 Key 或调超时的时候动四个自动化节点各自独立演进。Hooks 加新事件不影响 CronHeartbeat 调频率不影响 TaskFlow。如果你还在验证阶段想先确认模型通道本身是通的可以直接用模型对话页面发一条测试消息https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。通道确认没问题再回到settings.json里调自动化参数。长期跑编码类或 Agent 类自动化任务的话Coding Plan 会比按次调用更省心配置方式在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入过程中如果遇到通道报错先翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 大部分错误码都有对应说明。最后留一个实用技巧把settings.json里的failureAlert.cooldownMs设成比你最长任务执行时间稍长一点。比如 TaskFlow 最长跑 10 分钟冷却就设 15 分钟以上避免任务还在重试就触发告警白白消耗通知额度。