mirror of
https://github.com/moltbot/moltbot.git
synced 2026-04-26 07:57:40 +00:00
feat(cron): enhance delivery modes and job configuration
- Updated isolated cron jobs to support new delivery modes: `announce` and `none`, improving output management. - Refactored job configuration to remove legacy fields and streamline delivery settings. - Enhanced the `CronJobEditor` UI to reflect changes in delivery options, including a new segmented control for delivery mode selection. - Updated documentation to clarify the new delivery configurations and their implications for job execution. - Improved tests to validate the new delivery behavior and ensure backward compatibility with legacy settings. This update provides users with greater flexibility in managing how isolated jobs deliver their outputs, enhancing overall usability and clarity in job configurations.
This commit is contained in:
Tyler Yust
committed by
Peter Steinberger
Peter Steinberger
parent
ab9f06f4ff
commit
3f82daefd8
@@ -23,7 +23,7 @@ cron is the mechanism.
|
||||
- Jobs persist under `~/.openclaw/cron/` so restarts don’t lose schedules.
|
||||
- Two execution styles:
|
||||
- **Main session**: enqueue a system event, then run on the next heartbeat.
|
||||
- **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with delivery (announce by default, full output or none; legacy main summary still supported).
|
||||
- **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with delivery (announce by default or none).
|
||||
- Wakeups are first-class: a job can request “wake now” vs “next heartbeat”.
|
||||
|
||||
## Quick start (actionable)
|
||||
@@ -97,7 +97,7 @@ A cron job is a stored record with:
|
||||
|
||||
- a **schedule** (when it should run),
|
||||
- a **payload** (what it should do),
|
||||
- optional **delivery mode** (announce, full output, or none).
|
||||
- optional **delivery mode** (announce or none).
|
||||
- optional **agent binding** (`agentId`): run the job under a specific agent; if
|
||||
missing or unknown, the gateway falls back to the default agent.
|
||||
|
||||
@@ -109,7 +109,7 @@ One-shot jobs auto-delete after success by default; set `deleteAfterRun: false`
|
||||
|
||||
Cron supports three schedule kinds:
|
||||
|
||||
- `at`: one-shot timestamp. Prefer ISO 8601 via `schedule.at`; `atMs` (epoch ms) is also accepted.
|
||||
- `at`: one-shot timestamp via `schedule.at` (ISO 8601).
|
||||
- `every`: fixed interval (ms).
|
||||
- `cron`: 5-field cron expression with optional IANA timezone.
|
||||
|
||||
@@ -137,13 +137,10 @@ Key behaviors:
|
||||
|
||||
- Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
|
||||
- Each run starts a **fresh session id** (no prior conversation carry-over).
|
||||
- Default behavior: if `delivery` is omitted, isolated jobs announce a summary immediately (`delivery.mode = "announce"`), unless legacy isolation settings or legacy payload delivery fields are provided.
|
||||
- Legacy behavior: jobs with legacy isolation settings, legacy payload delivery fields, or older stored jobs without `delivery` post a summary to the main session (prefix `Cron`, configurable).
|
||||
- `delivery.mode` (isolated-only) chooses what happens instead of the legacy summary:
|
||||
- Default behavior: if `delivery` is omitted, isolated jobs announce a summary immediately (`delivery.mode = "announce"`).
|
||||
- `delivery.mode` (isolated-only) chooses what happens:
|
||||
- `announce`: subagent-style summary delivered immediately to a chat.
|
||||
- `deliver`: full agent output delivered immediately to a chat.
|
||||
- `none`: internal only (no main summary, no delivery).
|
||||
- `wakeMode: "now"` only triggers an immediate heartbeat when using the legacy main-summary path.
|
||||
- `none`: internal only (no delivery).
|
||||
|
||||
Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam
|
||||
your main chat history.
|
||||
@@ -163,28 +160,15 @@ Common `agentTurn` fields:
|
||||
|
||||
Delivery config (isolated jobs only):
|
||||
|
||||
- `delivery.mode`: `none` | `announce` | `deliver`.
|
||||
- `delivery.mode`: `none` | `announce`.
|
||||
- `delivery.channel`: `last` or a specific channel.
|
||||
- `delivery.to`: channel-specific target (phone/chat/channel id).
|
||||
- `delivery.bestEffort`: avoid failing the job if delivery fails (deliver mode).
|
||||
- `delivery.bestEffort`: avoid failing the job if announce delivery fails.
|
||||
|
||||
If `delivery` is omitted for isolated jobs, OpenClaw defaults to `announce` unless legacy isolation
|
||||
settings are present.
|
||||
Announce delivery suppresses messaging tool sends for the run; use `delivery.channel`/`delivery.to`
|
||||
to target the chat instead.
|
||||
|
||||
Legacy delivery fields (still accepted when `delivery` is omitted):
|
||||
|
||||
- `payload.deliver`: `true` to send output to a channel target.
|
||||
- `payload.channel`: `last` or a specific channel.
|
||||
- `payload.to`: channel-specific target (phone/chat/channel id).
|
||||
- `payload.bestEffortDeliver`: avoid failing the job if delivery fails.
|
||||
|
||||
Isolation options (only for `session=isolated`):
|
||||
|
||||
- `postToMainPrefix` (CLI: `--post-prefix`): prefix for the system event in main.
|
||||
- `postToMainMode`: `summary` (default) or `full`.
|
||||
- `postToMainMaxChars`: max chars when `postToMainMode=full` (default 8000).
|
||||
|
||||
Note: setting isolation post-to-main options opts into the legacy main-summary path (no `delivery` field). If `delivery` is set, the legacy summary is skipped.
|
||||
If `delivery` is omitted for isolated jobs, OpenClaw defaults to `announce`.
|
||||
|
||||
### Model and thinking overrides
|
||||
|
||||
@@ -207,7 +191,7 @@ Resolution priority:
|
||||
|
||||
Isolated jobs can deliver output to a channel via the top-level `delivery` config:
|
||||
|
||||
- `delivery.mode`: `announce` (subagent-style summary) or `deliver` (full output).
|
||||
- `delivery.mode`: `announce` (subagent-style summary) or `none`.
|
||||
- `delivery.channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` (plugin) / `signal` / `imessage` / `last`.
|
||||
- `delivery.to`: channel-specific recipient target.
|
||||
|
||||
@@ -216,14 +200,6 @@ Delivery config is only valid for isolated jobs (`sessionTarget: "isolated"`).
|
||||
If `delivery.channel` or `delivery.to` is omitted, cron can fall back to the main session’s
|
||||
“last route” (the last place the agent replied).
|
||||
|
||||
Legacy behavior (no `delivery` field with legacy isolation settings or older jobs):
|
||||
|
||||
- If `payload.to` is set, cron auto-delivers the agent’s final output even if `payload.deliver` is omitted.
|
||||
- Use `payload.deliver: true` when you want last-route delivery without an explicit `to`.
|
||||
- Use `payload.deliver: false` to keep output internal even if a `to` is present.
|
||||
|
||||
If `delivery` is set, it overrides legacy payload delivery fields and skips the legacy main-session summary.
|
||||
|
||||
Target format reminders:
|
||||
|
||||
- Slack/Discord/Mattermost (plugin) targets should use explicit prefixes (e.g. `channel:<id>`, `user:<id>`) to avoid ambiguity.
|
||||
@@ -246,7 +222,7 @@ Prefixed targets like `telegram:...` / `telegram:group:...` are also accepted:
|
||||
|
||||
Use these shapes when calling Gateway `cron.*` tools directly (agent tool calls or RPC).
|
||||
CLI flags accept human durations like `20m`, but tool calls should use an ISO 8601 string
|
||||
for `schedule.at` (preferred) or epoch milliseconds for `atMs` and `everyMs`.
|
||||
for `schedule.at` and milliseconds for `schedule.everyMs`.
|
||||
|
||||
### cron.add params
|
||||
|
||||
@@ -286,12 +262,12 @@ Recurring, isolated job with delivery:
|
||||
|
||||
Notes:
|
||||
|
||||
- `schedule.kind`: `at` (`at` or `atMs`), `every` (`everyMs`), or `cron` (`expr`, optional `tz`).
|
||||
- `schedule.kind`: `at` (`at`), `every` (`everyMs`), or `cron` (`expr`, optional `tz`).
|
||||
- `schedule.at` accepts ISO 8601 (timezone optional; treated as UTC when omitted).
|
||||
- `atMs` and `everyMs` are epoch milliseconds.
|
||||
- `everyMs` is milliseconds.
|
||||
- `sessionTarget` must be `"main"` or `"isolated"` and must match `payload.kind`.
|
||||
- Optional fields: `agentId`, `description`, `enabled`, `deleteAfterRun` (defaults to true for `at`),
|
||||
`delivery`, `isolation`.
|
||||
`delivery`.
|
||||
- `wakeMode` defaults to `"next-heartbeat"` when omitted.
|
||||
|
||||
### cron.update params
|
||||
@@ -392,7 +368,7 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize today; send to the nightly topic." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel telegram \
|
||||
--to "-1001234567890:topic:123"
|
||||
```
|
||||
@@ -408,7 +384,7 @@ openclaw cron add \
|
||||
--message "Weekly deep analysis of project progress." \
|
||||
--model "opus" \
|
||||
--thinking high \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
|
||||
@@ -90,8 +90,8 @@ Cron jobs run at **exact times** and can run in isolated sessions without affect
|
||||
- **Exact timing**: 5-field cron expressions with timezone support.
|
||||
- **Session isolation**: Runs in `cron:<jobId>` without polluting main history.
|
||||
- **Model overrides**: Use a cheaper or more powerful model per job.
|
||||
- **Delivery control**: Isolated jobs default to `announce` (summary); choose `deliver` (full output) or `none` as needed. Legacy jobs still post a summary to main.
|
||||
- **Immediate delivery**: Announce/deliver modes post directly without waiting for heartbeat.
|
||||
- **Delivery control**: Isolated jobs default to `announce` (summary); choose `none` as needed.
|
||||
- **Immediate delivery**: Announce mode posts directly without waiting for heartbeat.
|
||||
- **No agent context needed**: Runs even if main session is idle or compacted.
|
||||
- **One-shot support**: `--at` for precise future timestamps.
|
||||
|
||||
@@ -246,7 +246,7 @@ Use `--session isolated` when you want:
|
||||
|
||||
- A clean slate without prior context
|
||||
- Different model or thinking settings
|
||||
- Announce summaries or deliver full output directly to a channel
|
||||
- Announce summaries directly to a channel
|
||||
- History that doesn't clutter main session
|
||||
|
||||
```bash
|
||||
|
||||
@@ -16,9 +16,8 @@ Related:
|
||||
|
||||
Tip: run `openclaw cron --help` for the full command surface.
|
||||
|
||||
Note: isolated `cron add` jobs default to `--announce` delivery. Use `--deliver` for full output
|
||||
or `--no-deliver` to keep output internal. To opt into the legacy main-summary path, pass
|
||||
`--post-prefix` (or other `--post-*` options) without delivery flags.
|
||||
Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
|
||||
output internal. `--deliver` remains as a deprecated alias for `--announce`.
|
||||
|
||||
Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
|
||||
|
||||
@@ -36,8 +35,8 @@ Disable delivery for an isolated job:
|
||||
openclaw cron edit <job-id> --no-deliver
|
||||
```
|
||||
|
||||
Deliver full output (instead of announce):
|
||||
Announce to a specific channel:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --deliver --channel slack --to "channel:C1234567890"
|
||||
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
```
|
||||
|
||||
@@ -81,8 +81,8 @@ you revoke it with `openclaw devices revoke --device <id> --role <role>`. See
|
||||
|
||||
Cron jobs panel notes:
|
||||
|
||||
- For isolated jobs, delivery defaults to announce summary. You can switch to legacy main summary, deliver full output, or none.
|
||||
- Channel/target fields appear when announce or deliver is selected.
|
||||
- For isolated jobs, delivery defaults to announce summary. You can switch to none if you want internal-only runs.
|
||||
- Channel/target fields appear when announce is selected.
|
||||
|
||||
## Chat behavior
|
||||
|
||||
|
||||
@@ -1,39 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- 调度后台任务或唤醒
|
||||
- 配置需要与心跳一起运行或配合运行的自动化任务
|
||||
- 决定计划任务使用心跳还是定时任务
|
||||
summary: Gateway 网关调度器的定时任务与唤醒机制
|
||||
- 配置需要与心跳一起或并行运行的自动化
|
||||
- 在心跳和定时任务之间做选择
|
||||
summary: Gateway网关调度器的定时任务与唤醒
|
||||
title: 定时任务
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:44:30Z"
|
||||
generated_at: "2026-02-01T19:37:32Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d43268b0029f1b13d0825ddcc9c06a354987ea17ce02f3b5428a9c68bf936676
|
||||
source_path: automation/cron-jobs.md
|
||||
workflow: 15
|
||||
workflow: 14
|
||||
---
|
||||
|
||||
# 定时任务（Gateway 网关调度器）
|
||||
# 定时任务（Gateway网关调度器）
|
||||
|
||||
> **定时任务还是心跳？** 请参阅[定时任务与心跳对比](/automation/cron-vs-heartbeat)了解何时使用哪种方式。
|
||||
|
||||
定时任务是 Gateway 网关内置的调度器。它持久化任务，在正确的时间唤醒智能体，并可选择将输出发送回聊天。
|
||||
定时任务是 Gateway网关内置的调度器。它持久化任务、在合适的时间唤醒智能体，并可选择将输出发送回聊天。
|
||||
|
||||
如果你需要"每天早上运行这个"或"20 分钟后触发智能体"，定时任务就是实现机制。
|
||||
如果你想要 _"每天早上运行"_ 或 _"20 分钟后提醒智能体"_，定时任务就是对应的机制。
|
||||
|
||||
## 简要概述
|
||||
|
||||
- 定时任务运行在 **Gateway 网关内部**（不是在模型内部）。
|
||||
- 定时任务运行在 **Gateway网关内部**（而非模型内部）。
|
||||
- 任务持久化存储在 `~/.openclaw/cron/` 下，因此重启不会丢失计划。
|
||||
- 两种执行方式：
|
||||
- **主会话**：将系统事件加入队列，然后在下一次心跳时运行。
|
||||
- **隔离**：在 `cron:<jobId>` 中运行专用的智能体回合，可选择发送输出。
|
||||
- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳"。
|
||||
- **主会话**：入队一个系统事件，然后在下一次心跳时运行。
|
||||
- **隔离式**：在 `cron:<jobId>` 中运行专用智能体轮次，可投递摘要（默认 announce）或不投递。
|
||||
- 唤醒是一等功能：任务可以请求"立即唤醒"或"下次心跳时"。
|
||||
|
||||
## 快速开始（可操作）
|
||||
|
||||
创建一个一次性提醒，验证它是否存在，然后立即运行：
|
||||
创建一个一次性提醒，验证其存在，然后立即运行：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -49,7 +49,7 @@ openclaw cron run <job-id> --force
|
||||
openclaw cron runs --id <job-id>
|
||||
```
|
||||
|
||||
调度一个带消息发送的循环隔离任务：
|
||||
调度一个带投递功能的周期性隔离任务：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -58,168 +58,158 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize overnight updates." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel slack \
|
||||
--to "channel:C1234567890"
|
||||
```
|
||||
|
||||
## 工具调用等效项（Gateway 网关定时任务工具）
|
||||
## 工具调用等价形式（Gateway网关定时任务工具）
|
||||
|
||||
有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON schema](/automation/cron-jobs#json-schema-for-tool-calls)。
|
||||
有关规范的 JSON 结构和示例，请参阅[工具调用的 JSON 模式](/automation/cron-jobs#json-schema-for-tool-calls)。
|
||||
|
||||
## 定时任务的存储位置
|
||||
|
||||
定时任务默认持久化存储在 Gateway 网关主机的 `~/.openclaw/cron/jobs.json`。Gateway 网关将文件加载到内存中，并在更改时写回，因此只有在 Gateway 网关停止时手动编辑才是安全的。建议使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。
|
||||
定时任务默认持久化存储在 Gateway网关主机的 `~/.openclaw/cron/jobs.json` 中。Gateway网关将文件加载到内存中，并在更改时写回，因此仅在 Gateway网关停止时手动编辑才是安全的。请优先使用 `openclaw cron add/edit` 或定时任务工具调用 API 进行更改。
|
||||
|
||||
## 新手友好概述
|
||||
|
||||
将定时任务理解为：**何时**运行 + **做什么**。
|
||||
|
||||
1. **选择计划**
|
||||
1. **选择调度计划**
|
||||
- 一次性提醒 → `schedule.kind = "at"`（CLI：`--at`）
|
||||
- 重复任务 → `schedule.kind = "every"` 或 `schedule.kind = "cron"`
|
||||
- 如果你的 ISO 时间戳省略了时区，它将被视为 **UTC**。
|
||||
- 如果你的 ISO 时间戳省略了时区，将被视为 **UTC**。
|
||||
|
||||
2. **选择运行位置**
|
||||
- `sessionTarget: "main"` → 在下一次心跳时使用主上下文运行。
|
||||
- `sessionTarget: "isolated"` → 在 `cron:<jobId>` 中运行专用的智能体回合。
|
||||
- `sessionTarget: "main"` → 在下一次心跳时使用主会话上下文运行。
|
||||
- `sessionTarget: "isolated"` → 在 `cron:<jobId>` 中运行专用智能体轮次。
|
||||
|
||||
3. **选择负载**
|
||||
- 主会话 → `payload.kind = "systemEvent"`
|
||||
- 隔离会话 → `payload.kind = "agentTurn"`
|
||||
|
||||
可选：`deleteAfterRun: true` 会在成功执行后从存储中删除一次性任务。
|
||||
可选：一次性任务（`schedule.kind = "at"`）默认会在成功运行后删除。设置
|
||||
`deleteAfterRun: false` 可保留它（成功后会禁用）。
|
||||
|
||||
## 概念
|
||||
|
||||
### 任务
|
||||
|
||||
定时任务是一个存储的记录，包含：
|
||||
定时任务是一条存储记录，包含：
|
||||
|
||||
- 一个**计划**（何时运行），
|
||||
- 一个**调度计划**（何时运行），
|
||||
- 一个**负载**（做什么），
|
||||
- 可选的**发送**（输出发送到哪里）。
|
||||
- 可选的**智能体绑定**（`agentId`）：在特定智能体下运行任务；如果缺失或未知，Gateway 网关会回退到默认智能体。
|
||||
- 可选的**投递**（输出发送到哪里）。
|
||||
- 可选的**智能体绑定**（`agentId`）：在指定智能体下运行任务；如果缺失或未知，Gateway网关会回退到默认智能体。
|
||||
|
||||
任务通过稳定的 `jobId` 标识（供 CLI/Gateway 网关 API 使用）。在智能体工具调用中，`jobId` 是规范名称；为了兼容性也接受旧版的 `id`。任务可以通过 `deleteAfterRun: true` 选择在一次性成功运行后自动删除。
|
||||
任务通过稳定的 `jobId` 标识（用于 CLI/Gateway网关 API）。
|
||||
在智能体工具调用中，`jobId` 是规范字段；旧版 `id` 仍可兼容使用。
|
||||
一次性任务默认会在成功运行后自动删除；设置 `deleteAfterRun: false` 可保留它。
|
||||
|
||||
### 计划
|
||||
### 调度计划
|
||||
|
||||
定时任务支持三种计划类型：
|
||||
定时任务支持三种调度类型：
|
||||
|
||||
- `at`：一次性时间戳（自纪元以来的毫秒数）。Gateway 网关接受 ISO 8601 并转换为 UTC。
|
||||
- `at`：一次性时间戳（ISO 8601 字符串）。
|
||||
- `every`：固定间隔（毫秒）。
|
||||
- `cron`：5 字段 cron 表达式，带可选的 IANA 时区。
|
||||
- `cron`：5 字段 cron 表达式，可选 IANA 时区。
|
||||
|
||||
Cron 表达式使用 `croner`。如果省略时区，则使用 Gateway 网关主机的本地时区。
|
||||
Cron 表达式使用 `croner`。如果省略时区，将使用 Gateway网关主机的本地时区。
|
||||
|
||||
### 主会话与隔离执行
|
||||
### 主会话与隔离式执行
|
||||
|
||||
#### 主会话任务（系统事件）
|
||||
|
||||
主任务将系统事件加入队列并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。
|
||||
主会话任务入队一个系统事件，并可选择唤醒心跳运行器。它们必须使用 `payload.kind = "systemEvent"`。
|
||||
|
||||
- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划的心跳。
|
||||
- `wakeMode: "next-heartbeat"`（默认）：事件等待下一次计划心跳。
|
||||
- `wakeMode: "now"`：事件触发立即心跳运行。
|
||||
|
||||
当你需要正常的心跳提示 + 主会话上下文时，这是最佳选择。参见[心跳](/gateway/heartbeat)。
|
||||
|
||||
#### 隔离任务（专用定时会话）
|
||||
|
||||
隔离任务在会话 `cron:<jobId>` 中运行专用的智能体回合。
|
||||
隔离任务在会话 `cron:<jobId>` 中运行专用智能体轮次。
|
||||
|
||||
关键行为：
|
||||
|
||||
- 提示以 `[cron:<jobId> <job name>]` 为前缀以便追踪。
|
||||
- 每次运行启动一个**新的会话 id**（没有先前的对话延续）。
|
||||
- 摘要会发布到主会话（前缀 `Cron`，可配置）。
|
||||
- `wakeMode: "now"` 在发布摘要后触发立即心跳。
|
||||
- 如果 `payload.deliver: true`，输出会发送到渠道；否则保持内部。
|
||||
- 提示以 `[cron:<jobId> <任务名称>]` 为前缀，便于追踪。
|
||||
- 每次运行都会启动一个**全新的会话 ID**（不继承之前的对话）。
|
||||
- 如果未指定 `delivery`，隔离任务会默认以“announce”方式投递摘要。
|
||||
- `delivery.mode` 可选 `announce`（投递摘要）或 `none`（内部运行）。
|
||||
|
||||
对于嘈杂、频繁或不应该刷屏主聊天历史的"后台杂务"，使用隔离任务。
|
||||
对于嘈杂、频繁或"后台杂务"类任务，使用隔离任务可以避免污染你的主聊天记录。
|
||||
|
||||
### 负载结构（运行什么）
|
||||
### 负载结构（运行内容）
|
||||
|
||||
支持两种负载类型：
|
||||
|
||||
- `systemEvent`：仅限主会话，通过心跳提示路由。
|
||||
- `agentTurn`：仅限隔离会话，运行专用的智能体回合。
|
||||
- `agentTurn`：仅限隔离会话，运行专用智能体轮次。
|
||||
|
||||
常见的 `agentTurn` 字段：
|
||||
常用 `agentTurn` 字段：
|
||||
|
||||
- `message`：必需的文本提示。
|
||||
- `message`：必填文本提示。
|
||||
- `model` / `thinking`：可选覆盖（见下文）。
|
||||
- `timeoutSeconds`：可选的超时覆盖。
|
||||
- `deliver`：`true` 则将输出发送到渠道目标。
|
||||
- `channel`：`last` 或特定渠道。
|
||||
- `to`：特定于渠道的目标（电话/聊天/频道 id）。
|
||||
- `bestEffortDeliver`：发送失败时避免任务失败。
|
||||
- `timeoutSeconds`：可选超时覆盖。
|
||||
|
||||
隔离选项（仅适用于 `session=isolated`）：
|
||||
### 模型和思维覆盖
|
||||
|
||||
- `postToMainPrefix`（CLI：`--post-prefix`）：主会话中系统事件的前缀。
|
||||
- `postToMainMode`：`summary`（默认）或 `full`。
|
||||
- `postToMainMaxChars`：当 `postToMainMode=full` 时的最大字符数（默认 8000）。
|
||||
|
||||
### 模型和思考覆盖
|
||||
|
||||
隔离任务（`agentTurn`）可以覆盖模型和思考级别：
|
||||
隔离任务（`agentTurn`）可以覆盖模型和思维级别：
|
||||
|
||||
- `model`：提供商/模型字符串（例如 `anthropic/claude-sonnet-4-20250514`）或别名（例如 `opus`）
|
||||
- `thinking`：思考级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型）
|
||||
- `thinking`：思维级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`；仅限 GPT-5.2 + Codex 模型）
|
||||
|
||||
注意：你也可以在主会话任务上设置 `model`，但它会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。
|
||||
注意：你也可以在主会话任务上设置 `model`，但这会更改共享的主会话模型。我们建议仅对隔离任务使用模型覆盖，以避免意外的上下文切换。
|
||||
|
||||
解析优先级：
|
||||
优先级解析顺序：
|
||||
|
||||
1. 任务负载覆盖（最高）
|
||||
1. 任务负载覆盖（最高优先级）
|
||||
2. 钩子特定默认值（例如 `hooks.gmail.model`）
|
||||
3. 智能体配置默认值
|
||||
|
||||
### 发送（渠道 + 目标）
|
||||
### 投递（渠道 + 目标）
|
||||
|
||||
隔离任务可以将输出发送到渠道。任务负载可以指定：
|
||||
隔离任务可以通过顶层 `delivery` 配置投递输出：
|
||||
|
||||
- `channel`：`whatsapp` / `telegram` / `discord` / `slack` / `mattermost`（插件）/ `signal` / `imessage` / `last`
|
||||
- `to`：特定于渠道的接收者目标
|
||||
- `delivery.mode`：`announce`（投递摘要）或 `none`
|
||||
- `delivery.channel`：`whatsapp` / `telegram` / `discord` / `slack` / `mattermost`（插件）/ `signal` / `imessage` / `last`
|
||||
- `delivery.to`：渠道特定的接收目标
|
||||
- `delivery.bestEffort`：投递失败时避免任务失败
|
||||
|
||||
如果省略 `channel` 或 `to`，定时任务可以回退到主会话的"最后路由"（智能体最后回复的位置）。
|
||||
当启用 announce 投递时，该轮次会抑制消息工具发送；请使用 `delivery.channel`/`delivery.to` 来指定目标。
|
||||
|
||||
发送说明：
|
||||
|
||||
- 如果设置了 `to`，即使省略了 `deliver`，定时任务也会自动发送智能体的最终输出。
|
||||
- 当你想要不带显式 `to` 的最后路由发送时，使用 `deliver: true`。
|
||||
- 使用 `deliver: false` 即使存在 `to` 也保持输出在内部。
|
||||
如果省略 `delivery.channel` 或 `delivery.to`，定时任务会回退到主会话的“最后路由”（智能体最后回复的位置）。
|
||||
|
||||
目标格式提醒：
|
||||
|
||||
- Slack/Discord/Mattermost（插件）目标应使用显式前缀（例如 `channel:<id>`、`user:<id>`）以避免歧义。
|
||||
- Telegram 话题应使用 `:topic:` 形式（见下文）。
|
||||
- Slack/Discord/Mattermost（插件）目标应使用明确前缀（例如 `channel:<id>`、`user:<id>`）以避免歧义。
|
||||
- Telegram 主题应使用 `:topic:` 格式（见下文）。
|
||||
|
||||
#### Telegram 发送目标（话题/论坛帖子）
|
||||
#### Telegram 投递目标（主题/论坛帖子）
|
||||
|
||||
Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发送，你可以将话题/帖子编码到 `to` 字段中：
|
||||
Telegram 通过 `message_thread_id` 支持论坛主题。对于定时任务投递，你可以将主题/帖子编码到 `to` 字段中：
|
||||
|
||||
- `-1001234567890`（仅聊天 id）
|
||||
- `-1001234567890:topic:123`（推荐：显式话题标记）
|
||||
- `-1001234567890`（仅聊天 ID）
|
||||
- `-1001234567890:topic:123`（推荐：明确的主题标记）
|
||||
- `-1001234567890:123`（简写：数字后缀）
|
||||
|
||||
带前缀的目标如 `telegram:...` / `telegram:group:...` 也被接受：
|
||||
带前缀的目标如 `telegram:...` / `telegram:group:...` 也可接受：
|
||||
|
||||
- `telegram:group:-1001234567890:topic:123`
|
||||
|
||||
## 工具调用的 JSON schema
|
||||
## 工具调用的 JSON 模式
|
||||
|
||||
直接调用 Gateway 网关 `cron.*` 工具时（智能体工具调用或 RPC）使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用对 `atMs` 和 `everyMs` 使用纪元毫秒（`at` 时间接受 ISO 时间戳）。
|
||||
直接调用 Gateway网关 `cron.*` 工具（智能体工具调用或 RPC）时使用这些结构。CLI 标志接受人类可读的时间格式如 `20m`，但工具调用应使用 ISO 8601 字符串作为 `schedule.at`，并使用毫秒作为 `schedule.everyMs`。
|
||||
|
||||
### cron.add 参数
|
||||
|
||||
一次性，主会话任务（系统事件）：
|
||||
一次性主会话任务（系统事件）：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Reminder",
|
||||
"schedule": { "kind": "at", "atMs": 1738262400000 },
|
||||
"schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
|
||||
"sessionTarget": "main",
|
||||
"wakeMode": "now",
|
||||
"payload": { "kind": "systemEvent", "text": "Reminder text" },
|
||||
@@ -227,7 +217,7 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
}
|
||||
```
|
||||
|
||||
循环，带发送的隔离任务：
|
||||
带投递的周期性隔离任务：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -237,22 +227,24 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
"wakeMode": "next-heartbeat",
|
||||
"payload": {
|
||||
"kind": "agentTurn",
|
||||
"message": "Summarize overnight updates.",
|
||||
"deliver": true,
|
||||
"message": "Summarize overnight updates."
|
||||
},
|
||||
"delivery": {
|
||||
"mode": "announce",
|
||||
"channel": "slack",
|
||||
"to": "channel:C1234567890",
|
||||
"bestEffortDeliver": true
|
||||
},
|
||||
"isolation": { "postToMainPrefix": "Cron", "postToMainMode": "summary" }
|
||||
"bestEffort": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `schedule.kind`：`at`（`atMs`）、`every`（`everyMs`）或 `cron`（`expr`，可选 `tz`）。
|
||||
- `atMs` 和 `everyMs` 是纪元毫秒。
|
||||
- `sessionTarget` 必须是 `"main"` 或 `"isolated"` 并且必须与 `payload.kind` 匹配。
|
||||
- 可选字段：`agentId`、`description`、`enabled`、`deleteAfterRun`、`isolation`。
|
||||
- `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 参数
|
||||
@@ -269,8 +261,8 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
|
||||
说明：
|
||||
|
||||
- `jobId` 是规范名称；为了兼容性也接受 `id`。
|
||||
- 在补丁中使用 `agentId: null` 来清除智能体绑定。
|
||||
- `jobId` 是规范字段；`id` 可兼容使用。
|
||||
- 在补丁中使用 `agentId: null` 可清除智能体绑定。
|
||||
|
||||
### cron.run 和 cron.remove 参数
|
||||
|
||||
@@ -282,9 +274,9 @@ Telegram 通过 `message_thread_id` 支持论坛话题。对于定时任务发
|
||||
{ "jobId": "job-123" }
|
||||
```
|
||||
|
||||
## 存储和历史
|
||||
## 存储与历史
|
||||
|
||||
- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway 网关管理的 JSON）。
|
||||
- 任务存储：`~/.openclaw/cron/jobs.json`（Gateway网关管理的 JSON）。
|
||||
- 运行历史：`~/.openclaw/cron/runs/<jobId>.jsonl`（JSONL，自动清理）。
|
||||
- 覆盖存储路径：配置中的 `cron.store`。
|
||||
|
||||
@@ -330,7 +322,7 @@ openclaw cron add \
|
||||
--wake now
|
||||
```
|
||||
|
||||
循环隔离任务（发送到 WhatsApp）：
|
||||
周期性隔离任务（投递到 WhatsApp）：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -339,12 +331,12 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize inbox + calendar for today." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
|
||||
循环隔离任务（发送到 Telegram 话题）：
|
||||
周期性隔离任务（投递到 Telegram 主题）：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -353,12 +345,12 @@ openclaw cron add \
|
||||
--tz "America/Los_Angeles" \
|
||||
--session isolated \
|
||||
--message "Summarize today; send to the nightly topic." \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel telegram \
|
||||
--to "-1001234567890:topic:123"
|
||||
```
|
||||
|
||||
带模型和思考覆盖的隔离任务：
|
||||
带模型和思维覆盖的隔离任务：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@@ -369,15 +361,15 @@ openclaw cron add \
|
||||
--message "Weekly deep analysis of project progress." \
|
||||
--model "opus" \
|
||||
--thinking high \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
|
||||
智能体选择（多智能体设置）：
|
||||
智能体选择（多智能体配置）：
|
||||
|
||||
```bash
|
||||
# 将任务绑定到智能体"ops"（如果该智能体不存在则回退到默认）
|
||||
# 将任务绑定到智能体 "ops"（如果该智能体不存在则回退到默认智能体）
|
||||
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
|
||||
|
||||
# 切换或清除现有任务的智能体
|
||||
@@ -406,27 +398,27 @@ openclaw cron edit <jobId> \
|
||||
openclaw cron runs --id <jobId> --limit 50
|
||||
```
|
||||
|
||||
不创建任务的立即系统事件：
|
||||
不创建任务直接发送系统事件：
|
||||
|
||||
```bash
|
||||
openclaw system event --mode now --text "Next heartbeat: check battery."
|
||||
```
|
||||
|
||||
## Gateway 网关 API 接口
|
||||
## Gateway网关 API 接口
|
||||
|
||||
- `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`
|
||||
- `cron.run`（强制或到期）、`cron.runs`
|
||||
对于不创建任务的立即系统事件，使用 [`openclaw system event`](/cli/system)。
|
||||
如需不创建任务直接发送系统事件，请使用 [`openclaw system event`](/cli/system)。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### "什么都不运行"
|
||||
### "没有任何任务运行"
|
||||
|
||||
- 检查定时任务是否启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。
|
||||
- 检查 Gateway 网关是否持续运行（定时任务在 Gateway 网关进程内运行）。
|
||||
- 对于 `cron` 计划：确认时区（`--tz`）与主机时区的关系。
|
||||
- 检查定时任务是否已启用：`cron.enabled` 和 `OPENCLAW_SKIP_CRON`。
|
||||
- 检查 Gateway网关是否持续运行（定时任务运行在 Gateway网关进程内部）。
|
||||
- 对于 `cron` 调度：确认时区（`--tz`）与主机时区的关系。
|
||||
|
||||
### Telegram 发送到错误的位置
|
||||
### Telegram 投递到了错误的位置
|
||||
|
||||
- 对于论坛话题，使用 `-100…:topic:<id>` 以确保明确无歧义。
|
||||
- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务发送接受它们并仍然正确解析话题 ID。
|
||||
- 对于论坛主题，使用 `-100…:topic:<id>` 以确保明确无歧义。
|
||||
- 如果你在日志或存储的"最后路由"目标中看到 `telegram:...` 前缀，这是正常的；定时任务投递接受这些前缀并仍能正确解析主题 ID。
|
||||
|
||||
@@ -97,7 +97,7 @@ x-i18n:
|
||||
- **精确定时**：支持带时区的 5 字段 cron 表达式。
|
||||
- **会话隔离**：在 `cron:<jobId>` 中运行，不会污染主会话历史。
|
||||
- **模型覆盖**：可按任务使用更便宜或更强大的模型。
|
||||
- **投递控制**：可直接投递到渠道；默认仍会向主会话发布摘要（可配置）。
|
||||
- **投递控制**：隔离任务默认以 `announce` 投递摘要，可选 `none` 仅内部运行。
|
||||
- **无需智能体上下文**：即使主会话空闲或已压缩，也能运行。
|
||||
- **一次性支持**：`--at` 用于精确的未来时间戳。
|
||||
|
||||
@@ -111,7 +111,7 @@ openclaw cron add \
|
||||
--session isolated \
|
||||
--message "Generate today's briefing: weather, calendar, top emails, news summary." \
|
||||
--model opus \
|
||||
--deliver \
|
||||
--announce \
|
||||
--channel whatsapp \
|
||||
--to "+15551234567"
|
||||
```
|
||||
@@ -180,7 +180,7 @@ openclaw cron add \
|
||||
|
||||
```bash
|
||||
# 每天早上 7 点的早间简报
|
||||
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver
|
||||
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
|
||||
@@ -219,13 +219,13 @@ Lobster 是用于**多步骤工具管道**的工作流运行时，适用于需
|
||||
|
||||
心跳和定时任务都可以与主会话交互，但方式不同：
|
||||
|
||||
| | 心跳 | 定时任务（主会话） | 定时任务（隔离式） |
|
||||
| ------ | ------------------------ | ---------------------- | ------------------ |
|
||||
| 会话 | 主会话 | 主会话（通过系统事件） | `cron:<jobId>` |
|
||||
| 历史 | 共享 | 共享 | 每次运行全新 |
|
||||
| 上下文 | 完整 | 完整 | 无（从零开始） |
|
||||
| 模型 | 主会话模型 | 主会话模型 | 可覆盖 |
|
||||
| 输出 | 非 `HEARTBEAT_OK` 时投递 | 心跳提示 + 事件 | 摘要发布到主会话 |
|
||||
| | 心跳 | 定时任务（主会话） | 定时任务（隔离式） |
|
||||
| ------ | ------------------------ | ---------------------- | --------------------- |
|
||||
| 会话 | 主会话 | 主会话（通过系统事件） | `cron:<jobId>` |
|
||||
| 历史 | 共享 | 共享 | 每次运行全新 |
|
||||
| 上下文 | 完整 | 完整 | 无（从零开始） |
|
||||
| 模型 | 主会话模型 | 主会话模型 | 可覆盖 |
|
||||
| 输出 | 非 `HEARTBEAT_OK` 时投递 | 心跳提示 + 事件 | announce 摘要（默认） |
|
||||
|
||||
### 何时使用主会话定时任务
|
||||
|
||||
@@ -250,7 +250,7 @@ openclaw cron add \
|
||||
|
||||
- 无先前上下文的全新环境
|
||||
- 不同的模型或思维设置
|
||||
- 输出直接投递到渠道（摘要默认仍会发布到主会话）
|
||||
- 输出可通过 `announce` 直接投递摘要（或用 `none` 仅内部运行）
|
||||
- 不会把主会话搞得杂乱的历史记录
|
||||
|
||||
```bash
|
||||
@@ -261,7 +261,7 @@ openclaw cron add \
|
||||
--message "Weekly codebase analysis..." \
|
||||
--model opus \
|
||||
--thinking high \
|
||||
--deliver
|
||||
--announce
|
||||
```
|
||||
|
||||
## 成本考量
|
||||
|
||||
@@ -23,12 +23,17 @@ x-i18n:
|
||||
|
||||
提示：运行 `openclaw cron --help` 查看完整的命令集。
|
||||
|
||||
## 常用编辑
|
||||
说明：隔离式 `cron add` 任务默认使用 `--announce` 投递摘要。使用 `--no-deliver` 仅内部运行。
|
||||
`--deliver` 仍作为 `--announce` 的弃用别名保留。
|
||||
|
||||
说明：一次性（`--at`）任务成功后默认删除。使用 `--keep-after-run` 保留。
|
||||
|
||||
## 常见编辑
|
||||
|
||||
更新投递设置而不更改消息：
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --deliver --channel telegram --to "123456789"
|
||||
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
|
||||
```
|
||||
|
||||
为隔离的作业禁用投递：
|
||||
|
||||
Reference in New Issue
Block a user