跳转至

计划

任务触发时:五种计划类型、cron 表达式规则、动态频率和条件监视器。属于 Automations 指南的一部分。

计划类型

类型 CLI 标志 描述
at --at 一次性时间戳(ISO 8601 或相对值,如 20m)
every --every 固定间隔(10m、1h、1d)
cron --cron 5 字段或 6 字段 cron 表达式,可选 --tz
on-exit --on-exit 当被监视的命令退出时触发一次(事件触发;在回合拆除后仍保留;可选 --on-exit-cwd)
stream --stream-command 由受监督的长驻命令产生的批量行触发

这些计划标志同时适用于 openclaw automations add 和 openclaw automations edit <job-id>。例如,openclaw automations edit <job-id> --on-exit "./watch.sh" --on-exit-cwd /srv/app 会将现有任务转换为退出触发计划。

不带时区的时间戳按 UTC 处理。添加 --tz America/New_York 可在该 IANA 时区中解释不带偏移的 --at 日期时间,或评估 cron 表达式。不带 --tz 的 cron 表达式使用 Gateway 主机时区。--tz 不能与 --every 或 --on-exit 一起使用。

每小时整点的重复表达式(分钟为 0 且小时字段为通配符)会自动错开最多 5 分钟,以减少负载峰值。使用 --exact 强制精确计时,或使用 --stagger 30s 指定显式窗口(仅限 cron 计划)。

在 Control UI 中,启用 精确计时 可禁用错开。对于每小时整点的重复表达式,关闭它并清除 错开窗口 可恢复最多 5 分钟的默认窗口。对于其他表达式,清除已保存窗口而不更改表达式会禁用错开,并重新打开时启用 精确计时。具有空白窗口的新计划在其表达式更改时保持默认计时。

当 on-exit 任务的负载被排队执行时,该任务会禁用自身。重新启用任务即可再次监视;即使前一个负载仍在完成,这也有效。如果新命令在该负载完成前退出,其退出会等待前一次运行稳定,然后再禁用任务并启动下一个负载。这包括超时响应后仍在运行的清理。禁用或更改监视会取消其待处理的退出。重新启用时,可以更改被监视的命令或工作目录。

心跳任务迁移

在 v2026.8.1 之前,Heartbeat scratch 支持结构化的 tasks: 块。如果你从更早版本升级,请运行 openclaw doctor --fix,将每个条目转换为普通可编辑的主会话自动化任务。Doctor 会保留间隔和之前的上次运行时间,在删除该块之前创建任务,并在重新运行时安全地收敛相同的声明键。

这些迁移后的任务携带公开的 systemEvent 负载,因此 openclaw automations list、get、edit 和 remove 以及 automations 代理工具会像管理其他任务一样管理它们(该工具仍接受其旧版 cron 名称作为兼容性别名)。它们的执行使用受保护的心跳任务唤醒:活跃时段、最小间隔、洪泛控制和繁忙重试仍然适用,而调度器负责每个任务的独立节奏。在同一合并窗口内到期的任务可以共享一个心跳回合。在心跳活跃时段之外的计划触发会被跳过,并在任务的下次触发时重试。

Heartbeat scratch 仅用于监视文本。运行时心跳不会将 tasks: 文本解析为计划;请将新的重复工作创建为自动化。

流式来源

流式计划会在 Gateway 下保持一个由操作员编写的 argv 命令运行,并根据其 stdout 和 stderr 行触发任务。流式计划是事件驱动的,永远不会因时间到期,并且默认可用。设置 cron.triggers.enabled: false 可将其与条件触发脚本和脚本负载一起禁用。禁用或删除任务会停止进程;Gateway 关闭时会等待进程树拆除。快速失败会使用调度器内置的错误退避重启。连续五次运行时间少于 60 秒会使任务进入错误状态,并使用正常的失败告警路径;手动重新启用任务以清除重启上限。

openclaw automations add \
  --name "Build event stream" \
  --stream-command '["node","scripts/build-events.mjs"]' \
  --stream-mode match \
  --stream-match '^(failed|recovered):' \
  --stream-batch-ms 250 \
  --session isolated \
  --message "Investigate these build events."

mode: "line"(默认值)接受每一行。mode: "match" 仅接受与编译后的 match 正则表达式匹配的行。批次在 batchMs 的静默期后关闭(默认 250 ms,限制在 50–5000 之间),或在达到 maxBatchBytes 时关闭(默认 16384,限制在 1024–65536 之间)。达到字节上限时,批次以 [truncated] 结尾。匹配模式始终针对完整文本评估完整行,即使超过 maxBatchBytes(只有交付的批次会被截断);在受限的原始接收上限处被截断的行只是前缀,因此被视为不匹配,而不是让末尾锚定模式在截断处触发。批次会追加到系统事件文本或代理回合消息中。流式计划会拒绝命令负载,因为源命令和负载命令会导致进程所有权不明确。

匹配具有有界的处理预算和队列。如果任一限制被超过,源会停止并记录错误;请检查匹配表达式和 Gateway 负载,然后手动重新启用任务。

每个作业仅保留一次 payload 触发和一个有界待处理批次。在 payload 运行期间,或在内置 30 秒触发间隔尚未结束前到达的行,会合并到该待处理批次中,而不是构建无界队列。一个串行化所有者在 streamDroppedBatches 中记录 gate 丢弃、payload 错误和未运行调度;有界合并会增加 streamCoalescedBatches。失败的 payload 不会重试,因为它们可能不具有幂等性。逻辑源标识在受监督子进程重启之间保持稳定,但当源被禁用、移除或替换时会轮换,因此来自已退役源的排队批次即使在 A-to-B-to-A 编辑后也无法触发。停止完成后,来自旧子进程的迟到回调无效。没有原生 WebSocket 源;可以使用 argv 命令桥接一个,例如 websocat wss://example.invalid/events。

当作业繁忙时,批次截止时间和重试使用 Gateway 调度器。睡眠后,每个已过期的截止时间只运行一次。停止源会取消其待处理截止时间,并等待已启动的回调完成。

当 stream 作业还具有 trigger.script 时,gate 会为每个关闭的批次运行一次。当前批次作为深度冻结的 trigger.streamBatch 字符串与 trigger.state 一起可用。fire: false 会在持久化 gate 状态后丢弃该批次。fire: true 保留现有 trigger 消息语义,然后将批次追加到生成的 payload。stream 作业也可以不使用条件 gate,而改用 script payload;该 script 通过相同的 trigger.streamBatch 值接收批次。将 script payload 与条件 gate 组合会被拒绝,因为两者都会拥有持久化的 trigger.state 槽位。

动态节奏(pacing)

周期性作业可以将 pacing.min 和/或 pacing.max 设置为持续时间字符串,例如 15m 或 4h;至少需要一个边界。在 automations add|edit 中使用 --pacing-min 和 --pacing-max(--clear-pacing 会移除两个边界)。

Control UI 在复制周期性作业时保留 pacing 边界。将带 pacing 的作业或其副本更改为 Once 会移除 pacing;其他编辑保留现有边界。

在 agent-turn 运行期间,带 pacing 的作业可以调用 automations 工具,使用 action: "next_check" 和 in: "30m"。该提案仅适用于当前正在运行的作业,并从成功运行完成时开始计算。OpenClaw 会静默将其限制在配置的边界内。未来的 paced 截止时间在 Gateway 重启后仍为下一次计划检查。

没有提案的 pacing 保持正常计划不变。失败、超时和跳过的运行会丢弃提案,因此现有重试和错误退避行为优先。手动强制周期性作业属于带外操作,并保留其待处理的自然或 paced 槽位。对于条件触发的作业,即使提案请求更早检查,内置最小间隔仍为下限。

/loop 聊天快捷方式

在聊天中,仅限所有者的 /loop [interval] <prompt> 命令会创建一个绑定到该对话的周期性 agent-turn 作业。提供诸如 5m 的间隔以固定节奏,或省略它,让循环使用 next_check 在 1 分钟到 1 小时之间自我调节。使用 /loop status 列出绑定到对话的循环,使用 /loop stop [name] 移除它们。

每月日期和每周日期使用 OR 逻辑

Cron 表达式由 croner 解析。当月日期和周日期字段都非通配符时,croner 在任一字段匹配时即匹配,而不是两者都匹配。这是标准 Vixie cron 行为。

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

这大约每月触发 5-6 次,而不是每月 0-1 次。若要同时要求两个条件,请使用 croner 的 + 周日期修饰符(0 9 15 * +1),或在其中一个字段上调度,并在作业的 prompt 或命令中校验另一个字段。

事件触发器(条件监视器)

事件触发器会为 every、cron 或 stream 计划添加一个无头条件 script。时间计划在到期时评估它;stream 计划为每个关闭的批次评估它。调度器仅在 script 返回 fire: true 时运行正常 payload:

{
  schedule: { kind: "every", everyMs: 30000 },
  trigger: {
    // Fires only when the observed status differs from the last evaluation.
    script: "const res = await exec({ command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",
    once: false,
  },
  payload: { kind: "agentTurn", message: "Investigate the CI status change." },
}

强制手动运行会绕过此 gate:openclaw automations run <job-id>(默认强制)以及使用 action: "run", runMode: "force" 的 automations 工具会跳过 trigger.script 并直接执行 payload。即使 script 会返回 fire: false,agentTurn payload 也会唤醒模型。要测试 gate,请等待计划评估,或在作业到期时使用 openclaw automations run <job-id> --due。工具的默认 runMode: "due" 也遵循 gate;两种 due 模式都不会使作业提前到期。

openclaw doctor --fix 会转换调用 tools.call('exec', args) 并读取 .result.details 信封的已持久化 trigger script。Doctor 会保留自定义或模糊的 script 不变,并识别每个受影响的作业以便手动转换;独立 script payload 不会被转换。

script 必须返回 { fire, message?, state? }。之前的 JSON 状态作为深度冻结的 trigger.state 可用;stream gate 还会将当前批次作为 trigger.streamBatch 接收。返回新的 state 值以持久化它。State 上限为 16 KB。当触发结果包含 message 时,调度器会在执行前将其追加到系统事件文本或 agent-turn 消息中。once: true 会在其第一次成功触发 payload 后禁用该作业。

更改正在运行的监视器的条件或已保存状态会保护该编辑免受旧评估的状态更新和 once 完成的影响,包括在 Gateway 重启之后。已完成的负载仍保留其运行历史。未更改的监视器保持其通常的 once 行为;重命名它不会重置其条件。

fire: false 会持久化评估状态和计数器,然后重新调度而不创建运行历史。这些静默评估在重启追赶期间计为已完成发生次数。如果已触发的负载运行失败,返回的 state 不会被持久化——下一次评估会看到之前的状态并可能再次触发,因此请将脚本编写为只读检查,并将操作保留在负载中。触发计划具有内置的 30 秒最小间隔,该间隔在维护和 Gateway 重启期间保持不变。每次评估有 30 秒的挂钟时间预算和最多 5 次工具调用。

脚本通过交互式 Code Mode 使用的同一 MCP.<server>.<tool>({ ...input }) 命名空间调用已配置的 MCP 服务器工具。MCP 按服务器选择加入:脚本只能访问其作业的 toolsAllow(--tools)中带服务器前缀命名的服务器,可以是精确工具(如 wispr-flow__search_meetings)或服务器作用域通配符(如 wispr-flow__*)。通配符 *、缺失的 toolsAllow 或没有服务器前缀的通配符会使脚本没有 MCP 命名空间,并且不会启动任何服务器,因为评估可能每 30 秒运行一次。源代码从未提及 MCP 的脚本也不会启动服务器,即使 toolsAllow 为负载命名了一个服务器。在已命名的服务器内,拥有代理的工具策略仍然适用,与交互式运行一样。MCP 调用经过相同的工具调用前钩子和审批,并返回相同的不可信内容结果。每次评估仅为已命名的服务器启动自己的运行时,并在评估结束时将其退役;缓慢的服务器关闭会在 1 秒宽限后在后台完成。连接和列出工具计入 30 秒预算,每次 MCP 调用计入 5 次调用限制。启动失败的已命名服务器不会出现在 MCP 中;如果脚本随后失败,运行错误以 MCP server "<name>" is unavailable: <reason> 结尾。

从基于 MCP 的检查返回 fire: false 会在静默滴答时跳过负载及其模型调用:

const { structuredContent } = await MCP.wisprFlow.searchMeetings({
  since: trigger.state?.cursor,
});
const meetings = structuredContent?.meetings ?? [];
if (meetings.length === 0) return { fire: false };
return {
  fire: true,
  message: `${meetings.length} new meetings`,
  state: { cursor: meetings.at(-1).id },
};

在条件评估期间移除或禁用作业会取消其评估,使其负载无法启动。主会话负载将工作交给 heartbeat 后,该共享 heartbeat 保留其自身生命周期。

围绕可操作状态而非仅成功来编写监视器:当检查失败或超时时变安静的监视器在损坏时看起来仍然健康。将观察结果与 trigger.state 比较并返回新状态以去重;不要依赖模型或进程内存。触发时,使 message 自包含,因为它会成为已触发运行的完整事件上下文。

Warning

条件触发脚本和 script 负载默认无人值守运行,并拥有代理的完整工具策略,包括 exec。Stream 计划也会让操作员编写的命令无人值守运行。将这些入口视为具有该代理权限的无人值守代码执行。需要硬性停止的操作员可以设置 cron.triggers.enabled: false;删除它或将其设置为 true 以重新启用它们。

从本地脚本文件创建监视器(- 从 stdin 读取脚本)。CLI 保留文件路径中的前导和尾随空格;将路径引用为一个 shell 参数:

openclaw automations add \
  --name "PR CI watcher" \
  --every 30s \
  --trigger-script ./watch-pr-ci.js \
  --message "Respond to the CI status change" \
  --session isolated

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw