@captain-app/openclaw 2026.2.4

package/docs/zh-CN/automation/cron-jobs.md

@@ -0,0 +1,424 @@
+---
+read_when:
+  - 调度后台任务或唤醒
+  - 配置需要与心跳一起或并行运行的自动化
+  - 在心跳和定时任务之间做选择
+summary: Gateway网关调度器的定时任务与唤醒
+title: 定时任务
+x-i18n:
+  generated_at: "2026-02-01T19:37:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d43268b0029f1b13d0825ddcc9c06a354987ea17ce02f3b5428a9c68bf936676
+  source_path: automation/cron-jobs.md
+  workflow: 14
+---
+
+# 定时任务（Gateway网关调度器）
+
+> **定时任务还是心跳？** 请参阅[定时任务与心跳对比](/automation/cron-vs-heartbeat)了解何时使用哪种方式。
+
+定时任务是 Gateway网关内置的调度器。它持久化任务、在合适的时间唤醒智能体，并可选择将输出发送回聊天。
+
+如果你想要 _"每天早上运行"_ 或 _"20 分钟后提醒智能体"_，定时任务就是对应的机制。
+
+## 简要概述
+
+- 定时任务运行在 **Gateway网关内部**（而非模型内部）。
+- 任务持久化存储在 `~/.openclaw/cron/` 下，因此重启不会丢失计划。
+- 两种执行方式：
+  - **主会话**：入队一个系统事件，然后在下一次心跳时运行。
+  - **隔离式**：在 `cron:<jobId>` 中运行专用智能体轮次，可投递摘要（默认 announce）或不投递。
+- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳时"。
+
+## 快速开始（可操作）
+
+创建一个一次性提醒，验证其存在，然后立即运行：
+
+```bash
+openclaw cron add \
+  --name "Reminder" \
+  --at "2026-02-01T16:00:00Z" \
+  --session main \
+  --system-event "Reminder: check the cron docs draft" \
+  --wake now \
+  --delete-after-run
+
+openclaw cron list
+openclaw cron run <job-id> --force
+openclaw cron runs --id <job-id>
+```
+
+调度一个带投递功能的周期性隔离任务：
+
+```bash
+openclaw cron add \
+  --name "Morning brief" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --announce \
+  --channel slack \
+  --to "channel:C1234567890"
+```
+
+## 工具调用等价形式（Gateway网关定时任务工具）
+
+有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON 模式](/automation/cron-jobs#json-schema-for-tool-calls)。
+
+## 定时任务的存储位置
+
+定时任务默认持久化存储在 Gateway网关主机的 `~/.openclaw/cron/jobs.json` 中。Gateway网关将文件加载到内存中，并在更改时写回，因此仅在 Gateway网关停止时手动编辑才是安全的。请优先使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。
+
+## 新手友好概述
+
+将定时任务理解为：**何时**运行 + **做什么**。
+
+1. **选择调度计划**
+   - 一次性提醒 → `schedule.kind = "at"`（CLI：`--at`）
+   - 重复任务 → `schedule.kind = "every"` 或 `schedule.kind = "cron"`
+   - 如果你的 ISO 时间戳省略了时区，将被视为 **UTC**。
+
+2. **选择运行位置**
+   - `sessionTarget: "main"` → 在下一次心跳时使用主会话上下文运行。
+   - `sessionTarget: "isolated"` → 在 `cron:<jobId>` 中运行专用智能体轮次。
+
+3. **选择负载**
+   - 主会话 → `payload.kind = "systemEvent"`
+   - 隔离会话 → `payload.kind = "agentTurn"`
+
+可选：一次性任务（`schedule.kind = "at"`）默认会在成功运行后删除。设置
+`deleteAfterRun: false` 可保留它（成功后会禁用）。
+
+## 概念
+
+### 任务
+
+定时任务是一条存储记录，包含：
+
+- 一个**调度计划**（何时运行），
+- 一个**负载**（做什么），
+- 可选的**投递**（输出发送到哪里）。
+- 可选的**智能体绑定**（`agentId`）：在指定智能体下运行任务；如果缺失或未知，Gateway网关会回退到默认智能体。
+
+任务通过稳定的 `jobId` 标识（用于 CLI/Gateway网关 API）。
+在智能体工具调用中，`jobId` 是规范字段；旧版 `id` 仍可兼容使用。
+一次性任务默认会在成功运行后自动删除；设置 `deleteAfterRun: false` 可保留它。
+
+### 调度计划
+
+定时任务支持三种调度类型：
+
+- `at`：一次性时间戳（ISO 8601 字符串）。
+- `every`：固定间隔（毫秒）。
+- `cron`：5 字段 cron 表达式，可选 IANA 时区。
+
+Cron 表达式使用 `croner`。如果省略时区，将使用 Gateway网关主机的本地时区。
+
+### 主会话与隔离式执行
+
+#### 主会话任务（系统事件）
+
+主会话任务入队一个系统事件，并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。
+
+- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划心跳。
+- `wakeMode: "now"`：事件触发立即心跳运行。
+
+当你需要正常的心跳提示 + 主会话上下文时，这是最佳选择。参见[心跳](/gateway/heartbeat)。
+
+#### 隔离任务（专用定时会话）
+
+隔离任务在会话 `cron:<jobId>` 中运行专用智能体轮次。
+
+关键行为：
+
+- 提示以 `[cron:<jobId> <任务名称>]` 为前缀，便于追踪。
+- 每次运行都会启动一个**全新的会话 ID**（不继承之前的对话）。
+- 如果未指定 `delivery`，隔离任务会默认以“announce”方式投递摘要。
+- `delivery.mode` 可选 `announce`（投递摘要）或 `none`（内部运行）。
+
+对于嘈杂、频繁或"后台杂务"类任务，使用隔离任务可以避免污染你的主聊天记录。
+
+### 负载结构（运行内容）
+
+支持两种负载类型：
+
+- `systemEvent`：仅限主会话，通过心跳提示路由。
+- `agentTurn`：仅限隔离会话，运行专用智能体轮次。
+
+常用 `agentTurn` 字段：
+
+- `message`：必填文本提示。
+- `model` / `thinking`：可选覆盖（见下文）。
+- `timeoutSeconds`：可选超时覆盖。
+
+### 模型和思维覆盖
+
+隔离任务（`agentTurn`）可以覆盖模型和思维级别：
+
+- `model`：提供商/模型字符串（例如 `anthropic/claude-sonnet-4-20250514`）或别名（例如 `opus`）
+- `thinking`：思维级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型）
+
+注意：你也可以在主会话任务上设置 `model`，但这会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。
+
+优先级解析顺序：
+
+1. 任务负载覆盖（最高优先级）
+2. 钩子特定默认值（例如 `hooks.gmail.model`）
+3. 智能体配置默认值
+
+### 投递（渠道 + 目标）
+
+隔离任务可以通过顶层 `delivery` 配置投递输出：
+
+- `delivery.mode`：`announce`（投递摘要）或 `none`
+- `delivery.channel`：`whatsapp` / `telegram` / `discord` / `slack` / `mattermost`（插件）/ `signal` / `imessage` / `last`
+- `delivery.to`：渠道特定的接收目标
+- `delivery.bestEffort`：投递失败时避免任务失败
+
+当启用 announce 投递时，该轮次会抑制消息工具发送；请使用 `delivery.channel`/`delivery.to` 来指定目标。
+
+如果省略 `delivery.channel` 或 `delivery.to`，定时任务会回退到主会话的“最后路由”（智能体最后回复的位置）。
+
+目标格式提醒：
+
+- Slack/Discord/Mattermost（插件）目标应使用明确前缀（例如 `channel:<id>`、`user:<id>`）以避免歧义。
+- Telegram 主题应使用 `:topic:` 格式（见下文）。
+
+#### Telegram 投递目标（主题/论坛帖子）
+
+Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投递，你可以将主题/帖子编码到 `to` 字段中：
+
+- `-1001234567890`（仅聊天 ID）
+- `-1001234567890:topic:123`（推荐：明确的主题标记）
+- `-1001234567890:123`（简写：数字后缀）
+
+带前缀的目标如 `telegram:...` / `telegram:group:...` 也可接受：
+
+- `telegram:group:-1001234567890:topic:123`
+
+## 工具调用的 JSON 模式
+
+直接调用 Gateway网关 `cron.*` 工具（智能体工具调用或 RPC）时使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用应使用 ISO 8601 字符串作为 `schedule.at`，并使用毫秒作为 `schedule.everyMs`。
+
+### cron.add 参数
+
+一次性主会话任务（系统事件）：
+
+```json
+{
+  "name": "Reminder",
+  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
+  "sessionTarget": "main",
+  "wakeMode": "now",
+  "payload": { "kind": "systemEvent", "text": "Reminder text" },
+  "deleteAfterRun": true
+}
+```
+
+带投递的周期性隔离任务：
+
+```json
+{
+  "name": "Morning brief",
+  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
+  "sessionTarget": "isolated",
+  "wakeMode": "next-heartbeat",
+  "payload": {
+    "kind": "agentTurn",
+    "message": "Summarize overnight updates."
+  },
+  "delivery": {
+    "mode": "announce",
+    "channel": "slack",
+    "to": "channel:C1234567890",
+    "bestEffort": true
+  }
+}
+```
+
+说明：
+
+- `schedule.kind`：`at`（`at`）、`every`（`everyMs`）或 `cron`（`expr`，可选 `tz`）。
+- `schedule.at` 接受 ISO 8601（可省略时区；省略时按 UTC 处理）。
+- `everyMs` 为毫秒数。
+- `sessionTarget` 必须为 `"main"` 或 `"isolated"`，且必须与 `payload.kind` 匹配。
+- 可选字段：`agentId`、`description`、`enabled`、`deleteAfterRun`、`delivery`。
+- `wakeMode` 省略时默认为 `"next-heartbeat"`。
+
+### cron.update 参数
+
+```json
+{
+  "jobId": "job-123",
+  "patch": {
+    "enabled": false,
+    "schedule": { "kind": "every", "everyMs": 3600000 }
+  }
+}
+```
+
+说明：
+
+- `jobId` 是规范字段；`id` 可兼容使用。
+- 在补丁中使用 `agentId: null` 可清除智能体绑定。
+
+### cron.run 和 cron.remove 参数
+
+```json
+{ "jobId": "job-123", "mode": "force" }
+```
+
+```json
+{ "jobId": "job-123" }
+```
+
+## 存储与历史
+
+- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway网关管理的 JSON）。
+- 运行历史：`~/.openclaw/cron/runs/<jobId>.jsonl`（JSONL，自动清理）。
+- 覆盖存储路径：配置中的 `cron.store`。
+
+## 配置
+
+```json5
+{
+  cron: {
+    enabled: true, // 默认 true
+    store: "~/.openclaw/cron/jobs.json",
+    maxConcurrentRuns: 1, // 默认 1
+  },
+}
+```
+
+完全禁用定时任务：
+
+- `cron.enabled: false`（配置）
+- `OPENCLAW_SKIP_CRON=1`（环境变量）
+
+## CLI 快速开始
+
+一次性提醒（UTC ISO，成功后自动删除）：
+
+```bash
+openclaw cron add \
+  --name "Send reminder" \
+  --at "2026-01-12T18:00:00Z" \
+  --session main \
+  --system-event "Reminder: submit expense report." \
+  --wake now \
+  --delete-after-run
+```
+
+一次性提醒（主会话，立即唤醒）：
+
+```bash
+openclaw cron add \
+  --name "Calendar check" \
+  --at "20m" \
+  --session main \
+  --system-event "Next heartbeat: check calendar." \
+  --wake now
+```
+
+周期性隔离任务（投递到 WhatsApp）：
+
+```bash
+openclaw cron add \
+  --name "Morning status" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize inbox + calendar for today." \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+周期性隔离任务（投递到 Telegram 主题）：
+
+```bash
+openclaw cron add \
+  --name "Nightly summary (topic)" \
+  --cron "0 22 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize today; send to the nightly topic." \
+  --announce \
+  --channel telegram \
+  --to "-1001234567890:topic:123"
+```
+
+带模型和思维覆盖的隔离任务：
+
+```bash
+openclaw cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 1" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Weekly deep analysis of project progress." \
+  --model "opus" \
+  --thinking high \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+智能体选择（多智能体配置）：
+
+```bash
+# 将任务绑定到智能体 "ops"（如果该智能体不存在则回退到默认智能体）
+openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
+
+# 切换或清除现有任务的智能体
+openclaw cron edit <jobId> --agent ops
+openclaw cron edit <jobId> --clear-agent
+```
+
+手动运行（调试）：
+
+```bash
+openclaw cron run <jobId> --force
+```
+
+编辑现有任务（补丁字段）：
+
+```bash
+openclaw cron edit <jobId> \
+  --message "Updated prompt" \
+  --model "opus" \
+  --thinking low
+```
+
+运行历史：
+
+```bash
+openclaw cron runs --id <jobId> --limit 50
+```
+
+不创建任务直接发送系统事件：
+
+```bash
+openclaw system event --mode now --text "Next heartbeat: check battery."
+```
+
+## Gateway网关 API 接口
+
+- `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`
+- `cron.run`（强制或到期）、`cron.runs`
+  如需不创建任务直接发送系统事件，请使用 [`openclaw system event`](/cli/system)。
+
+## 故障排除
+
+### "没有任何任务运行"
+
+- 检查定时任务是否已启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。
+- 检查 Gateway网关是否持续运行（定时任务运行在 Gateway网关进程内部）。
+- 对于 `cron` 调度：确认时区（`--tz`）与主机时区的关系。
+
+### Telegram 投递到了错误的位置
+
+- 对于论坛主题，使用 `-100…:topic:<id>` 以确保明确无歧义。
+- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务投递接受这些前缀并仍能正确解析主题 ID。

package/docs/zh-CN/automation/cron-vs-heartbeat.md

@@ -0,0 +1,286 @@
+---
+read_when:
+  - 决定如何调度周期性任务
+  - 设置后台监控或通知
+  - 优化定期检查的 token 用量
+summary: 选择心跳还是定时任务进行自动化的指南
+title: 定时任务与心跳对比
+x-i18n:
+  generated_at: "2026-02-01T19:38:18Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 5f71a63181baa41b1c307eb7bfac561df7943d4627077dfa2861eb9f76ab086b
+  source_path: automation/cron-vs-heartbeat.md
+  workflow: 14
+---
+
+# 定时任务与心跳：何时使用哪种方式
+
+心跳和定时任务都可以按计划运行任务。本指南帮助你根据使用场景选择合适的机制。
+
+## 快速决策指南
+
+| 使用场景                  | 推荐方式                   | 原因                                     |
+| ------------------------- | -------------------------- | ---------------------------------------- |
+| 每 30 分钟检查收件箱      | 心跳                       | 可与其他检查批量处理，具备上下文感知能力 |
+| 每天上午 9 点准时发送报告 | 定时任务（隔离式）         | 需要精确定时                             |
+| 监控日历中即将到来的事件  | 心跳                       | 天然适合周期性感知                       |
+| 运行每周深度分析          | 定时任务（隔离式）         | 独立任务，可使用不同模型                 |
+| 20 分钟后提醒我           | 定时任务（主会话，`--at`） | 精确定时的一次性任务                     |
+| 后台项目健康检查          | 心跳                       | 搭载在现有周期上                         |
+
+## 心跳：周期性感知
+
+心跳在**主会话**中以固定间隔运行（默认：30 分钟）。它的设计目的是让智能体检查各种事项并呈现重要信息。
+
+### 何时使用心跳
+
+- **多个周期性检查**：与其设置 5 个独立的定时任务分别检查收件箱、日历、天气、通知和项目状态，不如用一次心跳批量处理所有内容。
+- **上下文感知决策**：智能体拥有完整的主会话上下文，因此可以智能判断哪些紧急、哪些可以等待。
+- **对话连续性**：心跳运行共享同一会话，因此智能体记得最近的对话，可以自然地进行后续跟进。
+- **低开销监控**：一次心跳替代多个小型轮询任务。
+
+### 心跳优势
+
+- **批量处理多项检查**：一次智能体轮次可以同时审查收件箱、日历和通知。
+- **减少 API 调用**：一次心跳比 5 个隔离式定时任务更经济。
+- **上下文感知**：智能体了解你一直在做什么，可以据此排定优先级。
+- **智能抑制**：如果没有需要关注的事项，智能体回复 `HEARTBEAT_OK`，不会投递任何消息。
+- **自然定时**：会根据队列负载略有漂移，但对大多数监控来说没有问题。
+
+### 心跳示例：HEARTBEAT.md 检查清单
+
+```md
+# Heartbeat checklist
+
+- Check email for urgent messages
+- Review calendar for events in next 2 hours
+- If a background task finished, summarize results
+- If idle for 8+ hours, send a brief check-in
+```
+
+智能体在每次心跳时读取此清单，并在一次轮次中处理所有项目。
+
+### 配置心跳
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m", // 间隔
+        target: "last", // 告警投递目标
+        activeHours: { start: "08:00", end: "22:00" }, // 可选
+      },
+    },
+  },
+}
+```
+
+完整配置请参阅[心跳](/gateway/heartbeat)。
+
+## 定时任务：精确调度
+
+定时任务在**精确时间**运行，可以在隔离会话中运行而不影响主会话上下文。
+
+### 何时使用定时任务
+
+- **需要精确定时**："每周一上午 9:00 发送"（而不是"大约 9 点左右"）。
+- **独立任务**：不需要对话上下文的任务。
+- **不同的模型/思维级别**：需要更强大模型的深度分析。
+- **一次性提醒**：使用 `--at` 实现"20 分钟后提醒我"。
+- **嘈杂/频繁的任务**：会把主会话历史搞得杂乱的任务。
+- **外部触发器**：无论智能体是否处于活跃状态都应独立运行的任务。
+
+### 定时任务优势
+
+- **精确定时**：支持带时区的 5 字段 cron 表达式。
+- **会话隔离**：在 `cron:<jobId>` 中运行，不会污染主会话历史。
+- **模型覆盖**：可按任务使用更便宜或更强大的模型。
+- **投递控制**：隔离任务默认以 `announce` 投递摘要，可选 `none` 仅内部运行。
+- **无需智能体上下文**：即使主会话空闲或已压缩，也能运行。
+- **一次性支持**：`--at` 用于精确的未来时间戳。
+
+### 定时任务示例：每日早间简报
+
+```bash
+openclaw cron add \
+  --name "Morning briefing" \
+  --cron "0 7 * * *" \
+  --tz "America/New_York" \
+  --session isolated \
+  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
+  --model opus \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+这会在纽约时间每天早上 7:00 准时运行，使用 Opus 保证质量，并直接投递到 WhatsApp。
+
+### 定时任务示例：一次性提醒
+
+```bash
+openclaw cron add \
+  --name "Meeting reminder" \
+  --at "20m" \
+  --session main \
+  --system-event "Reminder: standup meeting starts in 10 minutes." \
+  --wake now \
+  --delete-after-run
+```
+
+完整 CLI 参考请参阅[定时任务](/automation/cron-jobs)。
+
+## 决策流程图
+
+```
+任务是否需要在精确时间运行？
+  是 -> 使用定时任务
+  否 -> 继续...
+
+任务是否需要与主会话隔离？
+  是 -> 使用定时任务（隔离式）
+  否 -> 继续...
+
+此任务能否与其他周期性检查批量处理？
+  是 -> 使用心跳（添加到 HEARTBEAT.md）
+  否 -> 使用定时任务
+
+这是一次性提醒吗？
+  是 -> 使用定时任务配合 --at
+  否 -> 继续...
+
+是否需要不同的模型或思维级别？
+  是 -> 使用定时任务（隔离式）配合 --model/--thinking
+  否 -> 使用心跳
+```
+
+## 组合使用
+
+最高效的配置是**两者结合**：
+
+1. **心跳**处理常规监控（收件箱、日历、通知），每 30 分钟批量处理一次。
+2. **定时任务**处理精确调度（每日报告、每周回顾）和一次性提醒。
+
+### 示例：高效自动化配置
+
+**HEARTBEAT.md**（每 30 分钟检查一次）：
+
+```md
+# Heartbeat checklist
+
+- Scan inbox for urgent emails
+- Check calendar for events in next 2h
+- Review any pending tasks
+- Light check-in if quiet for 8+ hours
+```
+
+**定时任务**（精确定时）：
+
+```bash
+# 每天早上 7 点的早间简报
+openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce
+
+# 每周一上午 9 点的项目回顾
+openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
+
+# 一次性提醒
+openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
+```
+
+## Lobster：带审批的确定性工作流
+
+Lobster 是用于**多步骤工具管道**的工作流运行时，适用于需要确定性执行和明确审批的场景。当任务不只是单次智能体轮次，且你需要可恢复的带人工检查点的工作流时，使用它。
+
+### 何时适合使用 Lobster
+
+- **多步骤自动化**：你需要一个固定的工具调用管道，而不是一次性提示。
+- **审批关卡**：副作用应暂停直到你批准，然后继续执行。
+- **可恢复运行**：继续暂停的工作流而无需重新运行之前的步骤。
+
+### 如何与心跳和定时任务配合
+
+- **心跳/定时任务**决定*何时*运行。
+- **Lobster** 定义运行开始后*执行哪些步骤*。
+
+对于计划性工作流，使用定时任务或心跳触发一次调用 Lobster 的智能体轮次。对于临时工作流，直接调用 Lobster。
+
+### 操作说明（来自代码）
+
+- Lobster 以**本地子进程**（`lobster` CLI）在工具模式下运行，并返回 **JSON 信封**。
+- 如果工具返回 `needs_approval`，你需要使用 `resumeToken` 和 `approve` 标志来恢复。
+- 该工具是**可选插件**；建议通过 `tools.alsoAllow: ["lobster"]` 附加启用。
+- 如果传入 `lobsterPath`，必须是**绝对路径**。
+
+完整用法和示例请参阅 [Lobster](/tools/lobster)。
+
+## 主会话与隔离会话
+
+心跳和定时任务都可以与主会话交互，但方式不同：
+
+|        | 心跳                     | 定时任务（主会话）     | 定时任务（隔离式）    |
+| ------ | ------------------------ | ---------------------- | --------------------- |
+| 会话   | 主会话                   | 主会话（通过系统事件） | `cron:<jobId>`        |
+| 历史   | 共享                     | 共享                   | 每次运行全新          |
+| 上下文 | 完整                     | 完整                   | 无（从零开始）        |
+| 模型   | 主会话模型               | 主会话模型             | 可覆盖                |
+| 输出   | 非 `HEARTBEAT_OK` 时投递 | 心跳提示 + 事件        | announce 摘要（默认） |
+
+### 何时使用主会话定时任务
+
+当你需要以下场景时，使用 `--session main` 配合 `--system-event`：
+
+- 提醒/事件出现在主会话上下文中
+- 智能体在下一次心跳时带着完整上下文处理它
+- 不需要单独的隔离运行
+
+```bash
+openclaw cron add \
+  --name "Check project" \
+  --every "4h" \
+  --session main \
+  --system-event "Time for a project health check" \
+  --wake now
+```
+
+### 何时使用隔离式定时任务
+
+当你需要以下场景时，使用 `--session isolated`：
+
+- 无先前上下文的全新环境
+- 不同的模型或思维设置
+- 输出可通过 `announce` 直接投递摘要（或用 `none` 仅内部运行）
+- 不会把主会话搞得杂乱的历史记录
+
+```bash
+openclaw cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 0" \
+  --session isolated \
+  --message "Weekly codebase analysis..." \
+  --model opus \
+  --thinking high \
+  --announce
+```
+
+## 成本考量
+
+| 机制               | 成本特征                                       |
+| ------------------ | ---------------------------------------------- |
+| 心跳               | 每 N 分钟一次轮次；随 HEARTBEAT.md 大小扩展    |
+| 定时任务（主会话） | 将事件添加到下一次心跳（无隔离轮次）           |
+| 定时任务（隔离式） | 每个任务一次完整智能体轮次；可使用更便宜的模型 |
+
+**建议**：
+
+- 保持 `HEARTBEAT.md` 精简以减少 token 开销。
+- 将类似的检查批量放入心跳，而不是创建多个定时任务。
+- 如果只需要内部处理，在心跳上使用 `target: "none"`。
+- 对常规任务使用隔离式定时任务配合更便宜的模型。
+
+## 相关内容
+
+- [心跳](/gateway/heartbeat) - 完整的心跳配置
+- [定时任务](/automation/cron-jobs) - 完整的定时任务 CLI 和 API 参考
+- [系统](/cli/system) - 系统事件 + 心跳控制