---
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="/zh-Hant/docs/openclaw/official/01-gateway-runtime/security-remote" title="遠端與安全" description="繼續核對自動化之外的 Gateway 暴露、認證、遠端訪問和安全邊界。" />
  <Card href="/zh-Hant/docs/openclaw/understanding/08-session-heartbeat" title="08 · Session 與 Heartbeat" description="從理解篇看 heartbeat、cron、session 和 tasks 的執行心智模型。" />
  <Card href="/zh-Hant/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)
