配置自动化

OpenClaw 的自动化不是一个总开关，而是一组职责不同的机制。cron 负责准时触发，tasks 负责记录后台工作，Task Flow 负责多步骤编排，standing orders 负责长期授权，hooks 负责事件响应，heartbeat 负责周期感知。

这一篇的目标不是把所有命令背下来，而是先建立选择边界。边界清楚之后，你再配置定时任务、长期巡检、后台执行或事件脚本，就不会把所有问题都塞进 cron。

1. 快速判断

先问这个自动化到底解决什么问题：

flowchart TD
    A[要自动化的事] --> B{核心问题是什么}
    B -->|准点触发| C[cron]
    B -->|后台账本| D[tasks]
    B -->|多步骤流程| E[Task Flow]
    B -->|长期授权| F[standing orders]
    B -->|事件响应| G[hooks]
    B -->|周期感知| H[heartbeat]
    C --> I[每次执行都会产生 task record]
    E --> D
    H --> J[主 session turn 不产生 task record]

判断口诀很简单：cron 管时间，tasks 管账本，Task Flow 管流程，standing orders 管授权，hooks 管事件，heartbeat 管感知。

2. Cron

cron 是 Gateway 内置调度器，运行在 Gateway 进程里，不运行在模型里。它适合三类场景：

• 某个固定时间点执行一次，例如 20 分钟后提醒。
• 按固定间隔执行，例如每 6 小时跑一次检查。
• 按 cron 表达式执行，例如工作日早上 8 点生成摘要。

cron job 定义默认保存在 ~/.openclaw/cron/jobs.json。运行时状态保存在旁边的 ~/.openclaw/cron/jobs-state.json。如果你把 cron 配置纳入 git，只跟踪 jobs.json，不要跟踪 jobs-state.json。

常用 schedule 类型：

一个一次性提醒：

openclaw cron add \
  --name "calendar-check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

一个独立后台任务：

openclaw cron add \
  --name "morning-brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates according to the standing order." \
  --announce \
  --channel telegram \
  --to "123456789"

核心参数先理解这几个：

常用管理命令：

openclaw cron list
openclaw cron show {jobId}
openclaw cron run {jobId}
openclaw cron runs --id {jobId} --limit 20
openclaw cron edit {jobId} --message "Updated prompt"
openclaw cron remove {jobId}

几个容易踩坑的点：

• --at 一次性任务成功后默认自动删除。
• 所有 cron 执行都会创建 background task record，包括 main session 和 isolated。
• cron 表达式的 day-of-month 和 day-of-week 同时非通配时是 OR 逻辑，不是 AND。
• 没有 timezone 的 timestamp 按 UTC 处理；需要本地墙钟时间就加 --tz。
• --model 是这个 job 的 primary model，不等于聊天里的 /model override。
• 需要长期规则时，cron prompt 引用 standing order，不要把规则复制进每个 job。

3. Tasks

tasks 是后台工作账本，不是调度器。

会创建 task record 的场景包括：

• cron 执行。
• ACP runs。
• subagent spawns。
• CLI 发起的 agent 操作。

不会创建 task record 的场景：

• 普通交互对话。
• heartbeat turn。
• 直接 /command 响应。

常用命令：

openclaw tasks list
openclaw tasks list --status running
openclaw tasks list --runtime cron
openclaw tasks show {lookup}
openclaw tasks cancel {lookup}
openclaw tasks notify {lookup} state_changes
openclaw tasks audit
openclaw tasks maintenance

任务状态大致经历：

stateDiagram-v2
    [*] --> queued
    queued --> running
    running --> succeeded
    running --> failed
    running --> timed_out
    running --> cancelled
    queued --> lost
    running --> lost

tasks 的默认保留期是 7 天。日常排障先看 openclaw tasks list 和 openclaw tasks show {lookup}；怀疑后台任务积压、丢失或投递失败时，再跑 openclaw tasks audit。

4. Task Flow

Task Flow 是 tasks 之上的编排层。它适合多步骤、可恢复、需要整体进度状态的工作。

适用场景：

• A 然后 B 然后 C 的流水线。
• 周报：采集数据、生成报告、投递摘要。
• 长研究：检索、筛选、写作、复检。
• 多个外部任务组合成一个可追踪流程。

常用命令：

openclaw tasks flow list
openclaw tasks flow show {lookup}
openclaw tasks flow cancel {lookup}

managed 模式由 flow 创建和推进任务；mirrored 模式观察外部任务，把它们纳入同一个进度视图。

最容易混淆的是 Task Flow 和 cron：cron 解决“什么时候启动”，Task Flow 解决“启动后分几步、每一步状态如何、整体是否完成”。稳定做法是 cron 触发一个 flow，而不是让 cron prompt 里塞满流程细节。

5. Standing Orders

standing orders 是长期授权，不是定时器。它告诉 Agent：

• 什么事情归你负责。
• 什么触发条件下执行。
• 什么动作可以直接做。
• 哪些情况必须请求批准。
• 出现异常时如何升级。

最稳的位置是 AGENTS.md，因为它会自动进入 session bootstrap。大段规则可以放到独立文件，但要从 AGENTS.md 明确引用。

一个稳定的 standing order 至少写清五件事：职责范围，也就是这个 agent 负责哪类事；触发条件，也就是什么情况可以启动；可直接执行，也就是哪些动作不需要再问；批准门槛，也就是哪些动作必须先问；异常升级，也就是报错、权限不足、事实不确定时怎么处理。

比如周报任务要明确“可以汇总指标和生成报告”，也要写清“外发前是否需要批准”。自动化最危险的地方不是不会执行，而是授权边界不清楚。

cron prompt 应该引用 standing order，不要复制一大段规则。规则复制越多，漂移越快。

6. Hooks

hooks 是 Gateway 事件响应脚本，适合把运行时事件接到日志、审计、记忆或外部系统。它不是业务任务编排器。

常见事件类型包括 command、session、agent、gateway、message 几类。比如 command 覆盖 command:new、command:reset、command:stop，session 覆盖 compact 前后和 session patch，gateway 覆盖 startup、shutdown、pre-restart，message 覆盖 received、transcribed、preprocessed、sent。

常用命令：

openclaw hooks list
openclaw hooks check
openclaw hooks info {name}
openclaw hooks enable {name}

hooks 适合做这些事：

• session reset 前后写审计日志。
• Gateway 启动时做环境检查。
• message flow 中做轻量预处理或路由记录。
• agent bootstrap 时注入额外文件或检查规则。

不要用 hooks 承担长任务。长任务应该进入 cron、tasks 或 Task Flow，否则事件脚本会变成不可观察的后台黑箱。

7. Heartbeat

heartbeat 是主 session 的周期性 turn。默认间隔是 30m，Anthropic OAuth/token auth 等模式下可能是 1h。它适合做上下文相关的轻量检查：

• inbox 是否有新消息。
• 日历是否有近期事件。
• 通知是否需要汇总。
• 已完成任务是否需要提醒用户。

heartbeat 不创建 task record。它的优势是带主 session 上下文；代价是时间不如 cron 精确。cron 是“到点做事”，heartbeat 是“周期性看看有没有需要你知道的事”。

常见配置：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        directPolicy: "allow",
        lightContext: true,
        isolatedSession: true,
        skipWhenBusy: true,
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/Los_Angeles",
        },
      },
    },
  },
}

关键字段：

• every：心跳间隔；0m 表示关闭。
• target：结果投递位置，常用 last 或 none。
• directPolicy：是否允许 DM/direct 投递。
• lightContext：只注入轻量 bootstrap，降低 token 成本。
• isolatedSession：每次 heartbeat 用新 session，避免带完整历史。
• skipWhenBusy：子任务或嵌套工作繁忙时跳过。
• activeHours：只在指定时间窗口运行。

HEARTBEAT.md 应该短，只写稳定检查项。没有需要提醒时，heartbeat 应返回 HEARTBEAT_OK。OpenClaw 会把 OK-only 响应压掉，避免无意义通知。

一个克制的 HEARTBEAT.md 可以这样写：

- Check inbox, calendar, pending tasks and channel health.
- Report only urgent changes, blocked tasks or failed deliveries.
- If nothing needs attention, reply HEARTBEAT_OK.

不要把 secrets、长策略、临时任务堆进 HEARTBEAT.md。它会进入 prompt 上下文，越长越贵，也越容易让心跳变成噪音。

8. 组合方式

一个稳定的自动化通常是组合出来的：

1. AGENTS.md 写 standing order，定义授权和升级规则。
2. cron 负责准时触发。
3. task record 记录执行结果。
4. heartbeat 做轻量巡检和结果提醒。
5. hooks 处理 session reset、启动、审计、日志等事件。
6. task flow 管多步骤流程。

判断边界时只问一个问题：这是时间问题、状态记录问题、流程编排问题、长期授权问题、事件响应问题，还是周期感知问题？

例如“每天早上 8 点检查运营队列并发摘要”：standing order 定义运营队列职责、可处理范围、升级条件；cron 在工作日 8 点触发；Task Flow 拆成拉取、筛选、生成摘要、投递；tasks 记录每次后台执行和失败原因；heartbeat 后续提醒失败任务或需要人工处理的事项；hooks 记录 Gateway 重启、session reset、审计日志。

这样每层都有自己的边界，后面排障也知道该看哪里。

9. 自检清单

配置自动化前，先过一遍这几个问题：

• 这件事是否真的需要准点？需要就用 cron，不需要就考虑 heartbeat。
• 是否需要长期授权？需要就先写 standing order。
• 是否会跑很久？会就让它产生 task record，避免藏在普通对话里。
• 是否有多步骤和可恢复进度？有就用 Task Flow。
• 是否只是 Gateway 事件旁路处理？是就用 hooks。
• 是否需要向外投递？明确 channel、to、DM 策略和失败通知。
• 是否涉及密钥或账号？放进 config/env/凭据系统，不写进 prompt、HEARTBEAT.md 或 cron message。

10. 排错顺序

自动化出问题时，不要先改 prompt。先用命令确认运行状态：

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id {jobId} --limit 20
openclaw tasks list --status running
openclaw tasks audit
openclaw system heartbeat last
openclaw doctor

常见判断：

• cron 没触发：优先查 Gateway 是否常驻、cron.enabled、timezone、OPENCLAW_SKIP_CRON。
• cron 触发但没消息：优先查 announce、channel、to、投递凭据、channel allowlist。
• 后台任务一直 running：优先看 openclaw tasks show {lookup}、timeout、provider 错误。
• heartbeat 太吵：优先查 HEARTBEAT.md 是否过长、target、channel visibility。
• heartbeat 不运行：优先查 every、active hours、busy lanes、HEARTBEAT.md 是否空。
• hooks 没生效：优先查 openclaw hooks list、check、是否已 enable。

11. 接下来去哪

12. 官方来源

• Automation & Tasks
• Scheduled Tasks
• Background Tasks
• Task Flow
• Standing Orders
• Hooks
• Heartbeat