openclaw automations¶
管理 Gateway 调度器的自动化任务。该命令注册为 openclaw cron,别名是 openclaw automations。下面的每个子命令都可以用两种拼写之一运行。
Tip
运行 openclaw automations --help 查看完整的命令用法。概念指南参见 自动化。
Note
所有自动化变更操作(add/create、edit、remove、run)都需要 operator.admin。命令负载直接在 Gateway 进程中执行,而不是作为 agent 的 tools.exec 工具调用。tools.exec.* 和 exec 审批仍然管辖模型可见的 exec 工具。
每个自动化子命令都接受共享的 Gateway 连接选项。对于运行在非默认本地端口的 Gateway,使用 --port <port>;对于显式的 WebSocket URL,使用 --url <url>。不要同时使用它们。--port、--url 和 --token 等连接选项可以出现在子命令的前面或后面。
自动化命令需要正在运行的 Gateway。在使用 token、password 或 none 认证时,对已配置的本地 loopback Gateway 的调用不会打开共享状态数据库进行设备认证。远程与显式 URL 目标保留其设备认证和配对要求。
快速创建任务¶
openclaw automations create 是 openclaw automations add 的别名。对于新任务,先将调度放在前面,再将 prompt 放在后面:
openclaw automations create "0 7 * * *" \
"Summarize overnight updates." \
--name "Morning brief" \
--agent ops
对于 agent 或 command 任务,--timeout-seconds 接受非负整数秒。在 add/create 或 edit 上设置 --timeout-seconds 0 可禁用调度程序的墙钟时间上限。创建时省略该标志会保留默认超时;编辑时省略则会保持已存储的超时不变。Agent/provider 超时、启动看门狗和命令运行器限制仍然适用。系统事件任务拒绝 --timeout-seconds;脚本任务改用 --script-timeout-seconds。
当任务应把完成后的负载 POST 到指定地址而不是投递到聊天目标时,请使用 --webhook <url>:
openclaw automations create "0 18 * * 1-5" \
"Summarize today's deploys as JSON." \
--name "Deploy digest" \
--webhook "https://example.invalid/openclaw/cron"
如需运行确定性的 shell 风格任务(在 OpenClaw 调度器内部执行,不启动隔离的 agent/model 运行),请使用 --command:
openclaw automations create "*/15 * * * *" \
--name "Queue depth check" \
--command "scripts/check-queue.sh" \
--command-cwd "/srv/app" \
--announce \
--channel telegram \
--to "-1001234567890"
--command <shell> 会存储 argv: ["sh", "-lc", <shell>]。若要以精确的 argv 执行,请使用 --command-argv '["node","scripts/report.mjs"]'。命令任务会捕获 stdout/stderr,记录正常的运行历史,并通过与隔离任务相同的 announce、webhook 或 none 投递模式路由输出。只打印 NO_REPLY 的命令会被抑制。
当列表和详情视图应显示一个有别于自动化稳定名称的人类可读标签时,请使用 --display-name <name>。可通过 automations add|edit --display-name 设置或更新该标签。使用 automations edit <job-id> --clear-display-name 可移除标签并恢复列表和详情视图中的稳定名称。set 和 clear 选项不能同时使用。
调度类型¶
作为位置参数创建语法的替代方案,automations add|create 接受以下调度标志之一。automations edit 使用相同的标志替换任务的调度:
--at <when>根据 ISO 时间戳或持续时间(如20m)调度一次运行。除非提供--tz <iana>,否则无偏移的时间戳使用 UTC。--every <duration>设置循环间隔,例如10m、1h或1d。--cron <expression>设置五字段或六字段 cron 调度。使用--tz <iana>指定评估时区,使用--exact禁用错峰,或使用--stagger <duration>设置错峰窗口。--on-exit <shell>启动一个被监视的命令,并在其退出时触发一次任务。--on-exit-cwd <path>设置该命令的工作目录,且需要--on-exit。--stream-command <json>接受由非空字符串组成的非空 JSON 数组,作为受监督的长期运行命令的参数,并基于其批处理输出触发任务。--stream-cwd <path>设置来源的工作目录。--stream-mode line|match选择每一行或仅匹配的行。匹配模式需要--stream-match <regex>,该正则表达式在行模式下无效。--stream-batch-ms <n>设置静默窗口延迟(毫秒),--stream-max-batch-bytes <n>设置每个批次的最大 UTF-8 字节数。
--tz 适用于 cron 调度和无偏移的 --at 时间戳,而 --exact 和 --stagger 仅适用于 cron 调度。这三个标志均不能与 exit 或 stream 调度一起使用。有关流生命周期、批处理限制和触发细节,请参阅 自动化调度。
创建时,省略 --command-cwd、--on-exit-cwd 或 --stream-cwd 将使用默认工作目录。显式提供空字符串或仅包含空白的路径是错误的。编辑流任务时,--stream-cwd "" 仍会清除其已配置的工作目录。
会话¶
--session 接受 main、isolated、current 或 session:<id>。
当会话上下文可用时,agent 回合任务默认使用创建该任务的会话。如果没有会话密钥(包括普通 CLI 调用和省略该参数的 API 调用),目标将回退到 isolated。
从会话创建的隔离 agent 回合任务还会捕获该会话的生成结果用于投递。使用 announce 且没有显式或记忆中的外部路由时,其最终结果会提交到该会话中,而运行仍保持隔离。没有创建会话的普通 CLI 任务仍需要可解析的频道路由、webhook 投递或 --no-deliver。
会话密钥
main绑定到智能体的主会话。isolated为每次运行创建新的转录和会话 ID。current绑定到创建时处于活动状态的会话。session:<id>固定到显式的持久会话密钥。
隔离会话语义
隔离运行会重置环境对话上下文。对于新运行,频道和群组路由、发送/排队策略、提权、来源以及 ACP 运行时绑定都会被重置。安全偏好设置以及用户显式选择的模型或身份验证覆盖设置可以跨运行保留。
当操作员删除一个具有活动运行的自动化时,OpenClaw 会请求取消该运行。已获准的自动化可以删除其自身任务,而无需取消活动运行。当请求取消时,JSON 删除响应会包含 activeRunCancellationRequested: true。对于隔离自动化,可复用会话清理随后会等待活动运行停止,并在清理被延迟时报告 sessionCleanup: "pending"。运行历史会被保留。
如果会话清理失败,错误会被记录。没有活动运行的删除操作也会将清理错误返回给调用方。使用 openclaw sessions list --json 查找剩余会话,然后在 Gateway 或 worker 恢复后使用 openclaw sessions delete <key> --yes 重试清理。
投递¶
openclaw automations add、openclaw automations list 和 openclaw automations show <job-id> 会预览已解析的投递路由。对于 channel: "last",预览会显示一个会话提交、已解析的频道路由,或投递为何会失败关闭。
如果现有会话元数据存储无法读取或其模式尚未就绪,预览会保留请求的目标并报告其不可用的原因,而不会阻止任务创建或列表显示。不存在的数据库没有会话路由历史,并使用正常的投递回退。
带提供商前缀的目标可以消除未解析的 announce 频道的歧义。例如,当 delivery.channel 被省略或为 last 时,to: "telegram:123" 会选择 Telegram。只有已加载插件所通告的前缀才是提供商选择器。如果 delivery.channel 是显式的,前缀必须与该频道匹配。channel: "whatsapp" 与 to: "telegram:123" 会被拒绝。诸如 imessage: 和 sms: 之类的服务前缀仍然是频道拥有的目标语法。
Note
隔离的 automations add 任务默认使用 --announce 投递。使用 --no-deliver 可将输出保留在内部。--deliver 仍然是 --announce 的已弃用别名,后者在 2026.2.3 中取代了它。
投递所有权¶
隔离自动化的聊天投递由智能体和 runner 共同处理:
- 当聊天路由可用时,智能体可以使用
message工具直接发送。 - 只有当智能体未直接发送到已解析目标时,
announce才会回退投递最终回复。 webhook会将完成的负载发布到 URL。none禁用 runner 回退投递。
对于在创建时绑定到无路由会话的隔离智能体轮次任务,announce 会将最终可见结果提交到该会话。WebChat 会实时显示并在重新加载后显示它,重试提交不会导致重复。已删除或已重置的创建会话会记录一次投递失败。显式的频道、收件人、账户和线程设置保持正常的频道解析;webhook 和 none 保持不变。参见 自动化投递。
使用 automations add|create --webhook <url> 或 automations edit <job-id> --webhook <url> 设置 webhook 投递。不要将 --webhook 与聊天投递标志(如 --announce、--no-deliver、--channel、--to、--thread-id 或 --account)组合使用。
automations edit <job-id> 可以使用 --clear-channel、--clear-to、--clear-thread-id 和 --clear-account 取消设置单个投递路由字段(每个字段在与对应的设置标志组合使用时都会被拒绝)。与仅禁用 runner 回退投递的 --no-deliver 不同,这些操作会删除已存储的字段,使任务再次从默认值解析其路由的该部分。
--announce 是最终回复的 runner 回退投递。--no-deliver 会禁用该回退,但当聊天路由可用时,不会移除智能体的 message 工具。
从活动聊天创建的提醒会保留实时聊天投递目标,用于回退 announce 投递。内部会话密钥可能是小写的。不要将它们用作区分大小写的提供商 ID(如 Matrix 房间 ID)的权威来源。
失败投递¶
失败通知按以下顺序解析:
- 任务
failureAlert对象中的路由字段。 - 任务上的
delivery.failureDestination,它叠加在cron.failureAlert的全局目标字段(mode、channel、to、accountId)之上。已在 2026.8.1 中退役的cron.failureDestination块会由openclaw doctor --fix合并到这些字段中。 - 任务的主要 announce 目标(当上述两者都未解析到具体目标时)。
具有上述任一路由的任务默认在连续 2 次失败后触发执行失败告警,并带有 1 小时冷却时间。按任务或全局的 failureAlert 对象即使在没有现有路由的情况下也会显式启用/调整该策略。failureAlert: false 会禁用任务的执行和必需投递失败告警,但不会禁用自动禁用安全通知。全局 enabled: false 会禁用继承,除非任务拥有自己的 failureAlert 对象。delivery.bestEffort: true 会抑制继承的/默认的执行告警,但不会抑制显式的按任务策略。
具有相同原因的重复失败在 Gateway 重启期间仍会归并为一个事件。原因或目标发生变化后,可以在冷却时间后再次通知。成功完成会静默清除事件;恢复记录保留在自动化历史中。跳过的运行和未知的投递结果不计为恢复。如果脚本设置无法在插件重新加载后刷新工具,告警会说明在脚本运行之前自动恢复失败。
Note
主会话任务仅在主投递模式为 webhook 时才能使用 delivery.failureDestination。隔离任务在所有模式下都接受它。
聊天失败通知包含以代理配置的用户时区表示的运行开始时间。Webhook 消息文本保持稳定,并以 runAtMs 暴露该时刻。
隔离自动化运行将运行级代理失败视为任务错误,即使未生成回复负载。模型和提供商失败仍会增加错误计数器并触发失败通知。
命令任务不会启动隔离代理回合。零退出码记录为 ok。非零退出、信号、超时或无输出超时记录为 error,并可能触发相同的失败通知路径。
必需的完成投递是独立的:status: "ok" 且 completionStatus: "failed" 不会增加执行连续计数或退避。投递失败警报使用已解析的备用失败目标,且不带 after 阈值,并将重复失败归并为一个事件。针对失败变化的警报遵循共享的任务/全局 failureAlert.cooldownMs(默认 1 小时),包括执行警报后的首次投递失败。警报永远不会重试刚刚失败的主路由。
未解析的公告目标(例如未配置频道)在代理回合成功时仅为投递失败。其报告保留在运行历史中;再次运行任务前请配置目标。
如果隔离运行在首次模型请求前超时,openclaw automations show 和 openclaw automations runs 会包含特定阶段的错误。示例包括 setup timed out before runner start,或指明最后已知启动阶段(例如 context-engine)的停滞消息。对于基于 CLI 的提供商,模型前看门狗会保持激活,直到外部 CLI 回合开始。因此,会话查找、钩子、身份验证、提示词和 CLI 设置停滞会被报告为模型前自动化失败。
调度¶
一次性任务¶
--at <datetime> 安排一次性运行。无偏移量的日期时间按 UTC 处理,除非同时传入 --tz <iana>,后者会在给定时间区中解释墙上时间。
无效的 --tz 值会在保存任务前被拒绝;请使用 IANA 时区,例如
America/New_York。无效时间戳以及夏令时转换期间不存在的本地时间会作为 --at 错误单独报告。
Note
一次性任务仅在 completionStatus: "succeeded" 后删除。必需投递失败或完成状态未知会使任务保持禁用,且没有下次运行,因此重启不会重放负载副作用。有意静默以及显式 delivery.bestEffort: true 的成功执行会正常完成并删除。使用 --keep-after-run 也可保留成功任务。
周期性任务¶
配置的间隔和错峰窗口在人类可读输出中保留毫秒精度:--every 90s 显示为 every 1m 30s,--stagger 1001ms 显示为 stagger 1s 1ms。当列表列被截断时,使用 automations show <job-id> 查看完整时长。相对下次运行和上次运行标签仍会取整。
周期性任务在连续错误后使用指数重试退避:30s、1m、5m、15m、60m。下次成功运行后,调度恢复正常。
对于提供商网络故障、请求超时、过载、速率限制和服务器错误(不包括任务自身的执行超时),调度器会先在 30s、1m 和 5m 后重新运行任务(如果更早则在其下次计划运行时),并暂缓失败警报和所有者修复请求,直到这些重新运行也失败。
跳过的运行与执行错误分开跟踪。它们不影响重试退避,但 openclaw automations edit <job-id> --failure-alert-include-skipped 可以让失败警报选择接收重复的跳过运行通知。
本地配置的模型提供商具有位于回环、私有网络或 .local 上的基础 URL。对于目标为此类提供商的隔离任务,调度器会在启动代理回合前运行轻量级提供商预检。调度器在 /api/tags 检查 api: "ollama" 提供商。它在 /models 检查其他本地 OpenAI 兼容提供商(例如 api: "openai-completions",如 vLLM、SGLang 和 LM Studio)。如果端点不可达,调度器会将运行记录为 skipped,并在稍后的计划中重试。它按端点缓存可达性结果 5 分钟,因此针对同一本地服务器的许多任务不会发送重复检查。
自动化任务、待处理运行时状态和运行历史位于共享 SQLite 状态数据库中。它在 2026.6.1 中替换的文件存储已退役。如果仍保留 jobs.json、<name>-state.json 或 runs/*.jsonl 文件,请在升级到最新版本前安装 OpenClaw 2026.9.7 并运行 openclaw doctor --fix。当前 Doctor 会保留这些文件并报告中间升级要求。受支持的 jobs-quarantine.json 边车文件仍会被导入并以 .migrated 后缀归档。请使用 openclaw automations add|edit|remove 编辑调度,而不是编辑 JSON 文件。
手动运行¶
手动运行已禁用的任务不会启用其调度,也不会创建自动重试。使用 openclaw automations enable <job-id> 恢复计划运行。
openclaw automations run <job-id> 默认强制运行,并在 Gateway 持久化预留运行且将其接受到执行通道后返回。成功响应包含 { ok: true, enqueued: true, runId };任务可能仍在等待槽位。如果准入或调用方检查在队列接受前失败,请求会失败且不会报告已入队运行。如果 Gateway 在分发前退出,启动过程会在状态数据库中为该确切请求记录一个中断回执。此类分发前中断不会出现在已执行运行历史中。使用返回的 runId 检查已执行运行的结果:
强制运行会跳过任务的 trigger.script 条件门,并直接执行负载。因此,agentTurn 负载即使条件门会返回 fire: false,也会唤醒模型。当 automations 工具以 action: "run", runMode: "force" 调用时,也会跳过该门;其默认 runMode 为 "due"。
当脚本需要阻塞,直到该特定已入队运行记录到终态状态时,添加 --wait:
使用 --wait 时,CLI 会先调用 cron.run,然后针对返回的 runId 轮询持久的 cron.runs 行。它不会重新读取可变的任务投递设置。JSON 将负载执行报告为 status,将整个运行完成报告为 completionStatus。只有 completionStatus: "succeeded" 时命令才以 0 退出。failed、unknown、执行错误或跳过、缺失的 runId 以及超时到期都会以非零退出(默认 10m,默认每 2s 轮询一次)。--poll-interval 必须大于零。包括运行摘要在内的已完成 JSON 输出会在命令退出前刷新,因此可以管道到 JSON 读取器。
Note
使用 --due 可在任务当前已到期时测试条件门,或等待其计划评估。与强制运行不同,--due 会遵循 trigger.script;它不会让任务提前到期。如果 --due --wait 未入队运行,命令会返回正常的非运行响应,而不是轮询。被门跳过的已入队运行在 --wait 下会以非零退出。
模型¶
automations add|edit --model <ref> 为任务选择一个允许的模型。automations add|edit --fallbacks <list> 设置按任务的回退模型,例如 --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5。传入 --fallbacks "" 可执行无回退的严格运行。automations edit <job-id> --clear-fallbacks 移除按任务的回退覆盖。automations edit <job-id> --clear-model 移除按任务的模型覆盖。随后任务遵循正常的自动化模型选择优先级:如果存在已存储的自动化会话覆盖,则使用它;否则使用 agent 或默认模型。不能将其与 --model 组合使用。automations add|edit --thinking <level> 设置按任务的思考覆盖。automations edit <job-id> --clear-thinking 移除它,使任务遵循正常的自动化思考优先级。不能将其与 --thinking 组合使用。
Warning
如果模型不被允许或无法解析,调度器会以明确的验证错误使运行失败。它不会回退到任务的 agent 或默认模型选择。
自动化的 --model 是 任务主模型,而不是聊天会话的 /model 覆盖。这意味着:
- 当所选任务模型失败时,已配置的模型回退仍然适用。
- 当存在按任务负载的
fallbacks时,它会替换已配置的回退列表。 - 空的按任务回退列表(任务负载/API 中的
--fallbacks ""或fallbacks: [])会使运行变为严格模式。 - 当任务具有
--model但未配置回退列表时,OpenClaw 会传递一个显式的空回退覆盖。因此,agent 主模型不会被追加为隐藏的重试目标。 - 本地提供商预检在将运行标记为
skipped之前,会遍历已配置的回退。
openclaw doctor 会报告已经设置了 payload.model 的任务,包括提供商命名空间计数以及与 agents.defaults.model 的不匹配。当实时聊天和计划任务之间的身份验证、提供商或计费行为看起来不同时,请使用该检查。
隔离自动化模型优先级¶
隔离自动化运行按以下顺序解析活动模型:
- Gmail-hook 覆盖。
- 按任务的
--model。 - 已存储的自动化会话模型覆盖(当用户选择了某个模型时)。
- Agent 或默认模型选择。
快速模式¶
隔离自动化快速模式遵循解析后的实时模型选择。它依次解析已存储会话的 fastMode、按 agent 的 agents.entries.*.fastModeDefault、全局 agents.defaults.fastModeDefault,然后解析所选模型的 params.fastMode。当解析后的模式为 auto 时,该阈值使用所选模型的 params.fastAutoOnSeconds 值,默认为 60 秒。
实时模型切换重试¶
如果隔离运行抛出 LiveSessionModelSwitchError,调度器在重试前会为活动运行持久化已切换的提供商和模型。当存在已切换的身份验证配置文件覆盖时,它也会持久化该覆盖。外层重试循环在初始尝试之后限制为两次切换重试,然后中止,而不是无限循环。
运行输出与拒绝¶
过期确认抑制¶
隔离自动化轮次会抑制过期的仅确认回复。如果第一个结果只是临时状态更新,调度器会在投递前重新提示一次以获取真实结果。当某个后代子 agent 运行负责最终答案时,它不会重新提示。
静默 token 抑制¶
对于仅文本的隔离自动化公告,如果回复仅包含静默 token(NO_REPLY 或 no_reply),或以末尾静默 token 结尾,则会抑制直接出站投递和回退的排队摘要路径。前面的文本不会被投递。
例如,以下最终回复不会发送聊天消息:
不要将 NO_REPLY 追加到应送达用户的报告中。在句子中提到该 token,例如 Use NO_REPLY when nothing actionable changed.,不会触发此规则。对于媒体负载,可以移除静默说明,同时媒体仍会被投递。
人类可读的 automations list 和 automations show 会将成功的有意抑制标记为 ok (suppressed),而不是投递警告。automations show 包含 last delivery suppression,并带有记录的原因(empty、silent、heartbeat 或 channel_transform)。JSON 保留 deliveryStatus: "not-delivered" 以及单独的 deliverySuppressionReason。当执行成功时,没有有意原因的真正投递失败仍会显示 ok (not delivered)。
对于投递结果未确认的成功执行,会显示 delivery unknown,包括在收到响应头之前超时的 webhook 请求。该标签同时适用于必需投递和尽力投递;它并不表示投递失败。JSON 执行状态仍为 ok。
结构化拒绝¶
隔离自动化运行使用嵌入运行中的结构化执行拒绝元数据(编码为 SYSTEM_RUN_DENIED 或 INVALID_REQUEST 的致命 exec-tool 错误)作为权威的拒绝信号。它们也会接受节点主机围绕携带上述任一代码的嵌套结构化错误的 UNAVAILABLE 包装。
调度器仅当嵌入运行同时提供结构化拒绝元数据时,才将最终输出文本或看似审批的拒绝短语归类为拒绝。因此,普通助手文本不会被当作被阻止的命令。
automations list 和运行历史会显示拒绝原因,而不是将阻止的命令报告为 ok。
保留¶
保留行为:
cron.sessionRetention会清理已完成的隔离运行会话。默认值为24h。设置为false,或设置为零时长(例如"0h"),可禁用它。- 终态运行历史保留 7 天,
lost行保留 24 小时。额外的上限仅保留每个任务和每个历史类别中最新的 2000 行。
迁移旧任务¶
Note
如果你有早于当前投递和存储格式的自动化任务,请运行 openclaw doctor --fix。Doctor 会规范化旧版任务字段:jobId、schedule.cron、包括旧版 threadId 在内的顶层投递字段,以及 payload 的 provider 投递别名。它还会将 notify: true 的 webhook 回退任务从已弃用的原始 cron.webhook 值迁移到显式 webhook 投递。之后它会移除该配置键。已经向聊天发送通知的任务会保留该投递方式,并获得一个完成 webhook 目标。如果没有旧版 webhook,Doctor 会移除没有迁移目标的任务中无用的顶层 notify 标记。现有投递保持不变。因此,doctor --fix 不会再重复警告它们。
常见编辑¶
在不更改消息的情况下更新投递设置:
为隔离任务禁用投递:
为隔离任务启用轻量引导上下文:
向特定频道发送通知:
向 Telegram 论坛主题发送通知:
openclaw automations edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
创建具有轻量引导上下文的隔离任务:
openclaw automations create "0 7 * * *" \
"Summarize overnight updates." \
--name "Lightweight morning brief" \
--session isolated \
--light-context \
--no-deliver
--light-context 仅适用于隔离的代理轮次任务。对于自动化运行,轻量模式会保持引导上下文为空,而不是注入完整的工作区引导集。
创建具有精确 argv、cwd、env、stdin 和输出限制的命令任务:
openclaw automations create "*/30 * * * *" \
--name "Position export" \
--command-argv '["node","scripts/export-position.mjs"]' \
--command-cwd "/srv/app" \
--command-env "NODE_ENV=production" \
--command-input '{"mode":"summary"}' \
--timeout-seconds 120 \
--no-output-timeout-seconds 30 \
--output-max-bytes 65536 \
--webhook "https://example.invalid/openclaw/cron"
常见管理命令¶
手动运行和检查:
openclaw automations list
openclaw automations list --agent ops
openclaw automations list --all --agent ops --query backup --json
openclaw automations get <job-id>
openclaw automations get <job-id> --json
openclaw automations show <job-id>
openclaw automations run <job-id>
openclaw automations run <job-id> --due
openclaw automations run <job-id> --wait --wait-timeout 10m
openclaw automations run <job-id> --wait --wait-timeout 10m --poll-interval 2s
openclaw automations runs <job-id> --limit 50
openclaw automations runs <job-id> --limit 50 --json
openclaw automations runs <job-id> --run-id <run-id>
openclaw automations runs <job-id> --status error --query timeout
openclaw automations runs <job-id> --delivery-status not-delivered
openclaw automations runs <job-id> --sort asc --offset 200 --limit 50
automations runs 是首选拼写。cron runs 以及叶子本地的 --id <job-id> 形式仍作为受支持的兼容别名。
运行历史过滤器由 Gateway 在分页前应用。使用 --status 配合 all、ok、error 或 skipped;使用 --delivery-status 配合 delivered、not-delivered、unknown 或 not-requested。--query <text> 搜索运行摘要和错误。--sort asc|desc 选择最旧优先或最新优先顺序,--offset <n> 使用上一条命令返回的分页元数据在结果集中前进。
openclaw automations list 默认显示跨 agent 的已启用任务,包括无法解析所有者的任务。传入 --all 以包含已禁用任务,或传入 --agent <id> 按有效的规范化 agent ID 过滤。所有权解析顺序为:任务声明的 agent、其 agent 作用域会话键,然后是已配置的 system-agent 所有者。无法解析的任务不匹配 agent 过滤器。cron list 别名具有相同行为。
使用 --query <text> 搜索任务 ID、名称、描述、声明的 agent ID 和显示名称。匹配不区分大小写,并在分页前使用 Gateway 现有的清单过滤器;CLI 会使用相同查询读取每个有界的匹配页面。它可以与 --all、--agent 以及文本或 --json 输出组合使用。省略该标志或仅传入空白会保留现有列表。这搜索的是任务元数据,而不是消息或脚本 payload;请改用 automations runs <job-id> --query <text> 搜索运行摘要和错误。
人类可读的 Agent ID 列显示有效所有者。JSON 列表行保留声明的 agentId,并包含 effectiveAgentId;当所有权未解析时,该值为 null。
即使其 agent 不再是系统默认,现有的主会话任务仍可以重命名、禁用或重新安排。创建主会话任务,或显式设置其 agent、会话目标或 payload 类型,会重新验证当前的主会话规则。
未解析的所有者不会阻止调度器:该任务会被跳过,并在 state.lastError 中附带说明,其他任务继续运行。运行 openclaw doctor --fix 以修复未解析的多 agent 遗留所有权,设置 agents.defaults.systemAgent.agentId,或使用 openclaw cron edit <job-id> --agent <id> 修复该任务。运行时认可的单 agent 名册和遗留默认标记已经解析出所有者,无需迁移所有者。说明会保留在任务上。由于没有 agent 运行启动,因此不会创建 agent 运行历史条目。
--json 始终请求 JSON 输出。对于其输出已经是机器可读结果的命令,默认输出 JSON 结果:add/create、status、enable、disable、rm/remove/delete、run、edit、get 和 runs。它们接受 --json 作为显式的机器输出写法。openclaw automations get <job-id> 直接返回存储的任务 JSON。当你想要带投递路由预览的人类可读视图时,使用 automations show <job-id>。
list 和 show 默认使用人类可读输出,并可通过 --json 切换为 JSON。scratch 默认读取原始 scratch 内容。使用 --json 时,它会输出 scratch 以及修订元数据。Scratch 写入默认以 JSON 返回修订结果,并接受 --json 作为显式的机器输出写法。
automations show 也接受精确的任务名称,匹配时不区分大小写。任务 ID 优先。当多个任务匹配该名称时(包括已禁用的任务),命令会报告歧义,并包含匹配任务的完整 ID、名称、计划摘要、启用状态和状态。请使用预期的任务 ID 而不是名称重试同一命令。
使用 --json 时,失败信封会在 error.matches 中包含这些摘要。事件计划显示为 on-exit 或 stream,不包含其命令文本。
automations list --json 和 automations show <job-id> --json 会在每个任务中包含一个顶层 status 字段,该字段由 enabled、state.runningAtMs 和 state.lastRunStatus 计算得出。取值:disabled、running、ok、error、skipped 或 idle。JSON 状态保持规范且无装饰,因此外部工具可以直接读取任务状态,而无需重新推导。人类可读输出可能会为重复的 error 状态添加失败次数装饰。
automations runs 条目包含投递诊断信息,包括预期的自动化目标、解析后的目标、消息工具发送、回退使用情况和已投递状态。
每个任务的私有 scratch(心跳检查清单和类似的监控上下文):
openclaw automations scratch <job-id> # print current scratch content
openclaw automations scratch <job-id> --json # scratch plus revision metadata
openclaw automations scratch <job-id> --set "text" # replace scratch with exact text
openclaw automations scratch <job-id> --file notes.md # replace scratch from a file (- for stdin)
openclaw automations scratch <job-id> --unset # remove the scratch row
Scratch 存储在共享状态数据库中,上限为 256 KiB,并且永远不会包含在 automations list/automations get/automations runs 输出中。写入操作使用 compare-and-swap 保护,并与命令开始时读取的修订版本进行比对。也可以传入 --expected-revision <n> 以固定一个显式修订版本。有关心跳监控如何使用 scratch,请参阅 心跳。
Agent 与会话重定向:
openclaw automations edit <job-id> --agent ops
openclaw automations edit <job-id> --clear-agent
openclaw automations edit <job-id> --session current
openclaw automations edit <job-id> --session "session:daily-brief"
对于 agent-turn 任务,如果省略 --agent,openclaw automations add 会发出警告,并回退到默认 agent(main)。在创建时传入 --agent <id> 可以固定特定 agent。
投递调整:
openclaw automations edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw automations edit <job-id> --webhook "https://example.invalid/openclaw/cron"
openclaw automations edit <job-id> --best-effort-deliver
openclaw automations edit <job-id> --no-best-effort-deliver
openclaw automations edit <job-id> --no-deliver
跨自动化历史¶
使用 openclaw automations runs --all 查询现有 Gateway 历史,覆盖所有可见自动化,而无需查找每个任务 ID。筛选和分页适用于合并后的历史:
openclaw automations runs --all --status error --limit 20
openclaw automations runs --all --sort asc --offset 20 --limit 20
不要将 --all 与位置任务 ID 或 --id 组合使用。省略 --all 会保留现有的按任务查询。Gateway 权限和可见性规则不变。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw