---
title: "配置自动化"
description: "OpenClaw cron、tasks、task flow、standing orders、hooks 和 heartbeat 的选择边界。"
verifiedAt: "2026-05-06"
---

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

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

> [!NOTE]
> **这一章用 15 分钟换什么**：你会知道什么时候用 cron，什么时候用 heartbeat，什么时候必须让任务进入 tasks / Task Flow，而不是把所有自动化都写进一个 prompt。

## 1. 快速判断

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

```mermaid
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` | 编排多步骤任务并追踪整体进度 | 替代每个底层 task 的日志 |
| `standing orders` | 定义长期职责、授权和升级规则 | 替代具体触发器 |
| `hooks` | Gateway 事件发生时运行脚本 | 替代业务流程编排 |
| `heartbeat` | 主 session 周期性检查上下文 | 精确计时、后台任务账本 |

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

> [!IMPORTANT]
> **先选机制，再写配置**：如果机制选错，prompt 写得再细也会变成难排障的后台行为。

## 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 类型：

| 类型 | CLI 参数 | 适合场景 |
| --- | --- | --- |
| 一次性 | `--at` | 延后提醒、指定时间执行一次 |
| 固定间隔 | `--every` | 每隔一段时间重复 |
| cron 表达式 | `--cron` | 工作日、每月、复杂日期规则 |

一个一次性提醒：

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

一个独立后台任务：

```bash
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"
```

核心参数先理解这几个：

| 参数 | 作用 |
| --- | --- |
| `--session main` | 把系统事件送进主 session，常用于提醒 |
| `--session isolated` | 每次用独立 session 执行，常用于后台报告 |
| `--session current` | 绑定创建任务时的当前 session |
| `--session session:ops` | 使用持久命名 session，适合累积上下文的周期任务 |
| `--announce` | 如果 agent 没有主动发消息，runner 把最终结果投递出去 |
| `--channel` / `--to` | 指定投递渠道和目标 |
| `--model` / `--thinking` | 给这个 cron job 单独指定模型和思考档位 |

常用管理命令：

```bash
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。

> [!TIP]
> **cron 只回答“什么时候启动”**：执行规则、授权边界和多步骤状态，不应该塞进每个 cron prompt。

## 3. Tasks

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

会创建 task record 的场景包括：

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

不会创建 task record 的场景：

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

常用命令：

```bash
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
```

任务状态大致经历：

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

| 状态 | 含义 |
| --- | --- |
| `queued` | 已创建，等待开始 |
| `running` | 正在执行 |
| `succeeded` | 正常完成 |
| `failed` | 执行报错 |
| `timed_out` | 超过 timeout |
| `cancelled` | 被操作者取消 |
| `lost` | 运行时支撑状态消失，超过宽限期后标记丢失 |

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

> [!TIP]
> **长任务必须可观察**：只要任务会跑很久、会重试、会投递结果或会失败，就应该能在 tasks 里看到记录。

## 4. Task Flow

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

适用场景：

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

常用命令：

```bash
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 里塞满流程细节。

> [!IMPORTANT]
> **流程不要藏在定时任务里**：多步骤工作用 Task Flow 表达，cron 只负责把它按时间拉起来。

## 5. Standing Orders

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

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

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

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

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

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

> [!WARNING]
> **长期授权必须写清批准门槛**：自动化可以直接做什么、什么时候必须问人、失败后怎么升级，这三件事不能靠模型临场猜。

## 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。

常用命令：

```bash
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，否则事件脚本会变成不可观察的后台黑箱。

> [!CAUTION]
> **hooks 不是后台任务系统**：事件脚本应该短、可审计、可失败；需要长时间执行的工作进入 tasks 或 flow。

## 7. Heartbeat

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

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

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

常见配置：

```json5
{
  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` 可以这样写：

```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 上下文，越长越贵，也越容易让心跳变成噪音。

> [!TIP]
> **heartbeat 是感知，不是闹钟**：需要准点就用 cron；需要带主上下文轻量巡检，才用 heartbeat。

## 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、审计日志。

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

> [!IMPORTANT]
> **稳定自动化是组合，不是堆配置**：授权、触发、执行记录、投递和事件审计应该分层表达。

## 9. 自检清单

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

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

## 10. 排错顺序

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

```bash
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。

> [!TIP]
> **自动化排错先看运行时，再看提示词**：Gateway、cron、tasks、heartbeat 和 hooks 的状态没确认前，先不要改 prompt。

## 11. 接下来去哪

<Cards>
  <Card href="/docs/openclaw/official/01-gateway-runtime/security-remote" title="远程与安全" description="继续核对自动化之外的 Gateway 暴露、认证、远程访问和安全边界。" />
  <Card href="/docs/openclaw/understanding/08-session-heartbeat" title="08 · Session 与 Heartbeat" description="从理解篇看 heartbeat、cron、session 和 tasks 的运行心智模型。" />
  <Card href="/docs/openclaw/official/01-gateway-runtime/gateway-configuration" title="Gateway 配置" description="回到 Gateway 配置页，检查 automation 相关配置如何落到运行时。" />
</Cards>

## 12. 官方来源

- [Automation & Tasks](https://docs.openclaw.ai/automation)
- [Scheduled Tasks](https://docs.openclaw.ai/automation/cron-jobs)
- [Background Tasks](https://docs.openclaw.ai/automation/tasks)
- [Task Flow](https://docs.openclaw.ai/automation/taskflow)
- [Standing Orders](https://docs.openclaw.ai/automation/standing-orders)
- [Hooks](https://docs.openclaw.ai/automation/hooks)
- [Heartbeat](https://docs.openclaw.ai/gateway/heartbeat)
