跳转至

工作原理

Gateway 调度器如何运行任务、在多次运行之间保留什么,以及重复请求如何成为已存储的调度。属于自动化指南的一部分。

自动化如何工作

  • 自动化运行在 Gateway 进程内部,而不是模型内部。Gateway 必须处于运行状态,调度才会触发。
  • 任务定义、运行时状态和运行历史持久化在 OpenClaw 的共享 SQLite 状态数据库中,因此重启不会丢失调度。
  • 自动化运行会记录在 cron 运行历史中。
  • 从会话创建的隔离 agent-turn 任务会保留自己的运行会话。当默认 announce 投递没有显式或已记住的外部路由时,完成时会把最终可见结果提交到创建它的会话。该提交会验证其创建时的会话代际,并按任务/运行身份去重;已删除或已重置的会话会导致投递失败。参见自动化投递。
  • 一次性任务(--at)在成功完成后自动删除:投递已确认、未请求、被有意抑制,或明确为尽力而为。失败或未知状态的必需投递会保留任务并禁用,以便检查,而不会重放负载。传入 --keep-after-run 也可保留成功任务。
  • 每次运行的实际时间预算:设置时使用 --timeout-seconds。否则,隔离/分离的 agent-turn 任务会先受调度器自身的 60 分钟看门狗限制,然后才可能应用底层 agent-turn 超时(agents.defaults.timeoutSeconds,默认 48 小时);命令任务默认为 10 分钟,脚本负载默认为 5 分钟。
  • Gateway 启动时,逾期的 agent-turn 任务和等待心跳的任务会被重新调度,而不是立即重放,从而避免在调度器启动时执行模型/工具。这包括心跳监视器、迁移的心跳任务,以及具有立即唤醒的主会话系统事件。启动追赶延迟会在标签或负载内容对账以及另一次重启后保留;更改调度会开始新的调度决策。
  • 当运行中的 Gateway 在截止时间后唤醒时,调度器会合并错过的定时器滴答。Cron 会使用其存储的截止时间和运行回执重新检查符合条件的任务。共享的Gateway 调度器负责定时器启用和关闭等待;cron 负责执行、追赶策略和持久化结果。
  • 如果你通过系统 cron 或其他外部调度器驱动 openclaw agent,即使 CLI 已经处理 SIGTERM/SIGINT,也要用强制终止升级来包装它。Gateway 支持的运行会请求 Gateway 中止已接受的运行;--local 运行会收到相同的中止信号。对于 GNU timeout,优先使用 timeout -k 60 600 openclaw agent ...,而不是普通的 timeout 600 ... —— -k 值是当进程无法及时排空时的兜底。对于 systemd 单元,使用带宽限窗口(TimeoutStopSec)的 SIGTERM 停止信号,然后再执行最终终止。在原始 Gateway 运行仍然活跃时重用 --run-id,会将重复项报告为进行中,而不是启动第二个运行。
隔离运行加固
  • 计划运行拥有自己的执行生命周期,从准入到结果持久化和清理。定时器滴答、启动追赶和事件源监视器不会继承创建或更新它们的会话的请求状态。手动运行保留其调用方权限。
  • 隔离运行在完成后会尽力关闭其 cron:<jobId> 会话所跟踪的浏览器标签页/进程,并通过主会话和自定义会话运行所使用的同一共享拆除路径,处置为该任务创建的任何捆绑 MCP 运行时实例。清理失败会被忽略,因此运行结果仍然优先。
  • 在后代子代理正在运行或其完成投递仍待处理时,包括在保留扫描期间,运行的延续会话会保持可用,因此清理不会使其结果被搁置。
  • 具有窄自动化自清理权限的隔离运行可以读取调度器状态、仅包含其自身任务的自过滤列表,以及该任务的运行历史,并且只能删除其自身的任务。
  • 隔离运行会防范过时的确认回复:如果第一个结果只是临时状态更新(on it、pulling everything together 以及类似提示),并且没有后代子代理仍负责最终答案,OpenClaw 会在投递前重新提示一次以获取实际结果。运行总计包括两个已完成的提示,并按各自模型计价;会话上下文用量仍反映最终模型请求。
  • 结构化执行拒绝元数据(包括嵌套错误以 SYSTEM_RUN_DENIED 或 INVALID_REQUEST 开头的节点主机 UNAVAILABLE 包装器)会被识别,因此被阻止的命令不会被报告为绿色运行,而普通助手文本也不会被误认为拒绝。
  • 运行级 agent 失败即使没有回复负载也会计为任务错误,因此模型/提供商失败会增加错误计数器并触发失败通知,而不是将任务清除为成功。
  • 当任务达到 timeoutSeconds 时,调度器会中止运行并给予一个短暂的清理窗口。如果它无法排空,Gateway 拥有的清理会在调度器记录超时之前强制清除该运行的会话所有权,因此排队的聊天工作不会卡在过时的处理会话后面。
  • 设置/启动停滞会有阶段特定的超时(例如 cron: isolated agent setup timed out before runner start 或 cron: isolated agent run stalled before execution start (last phase: context-engine))。这些看门狗覆盖嵌入式和 CLI 支持的提供商,即使在其外部 CLI 进程启动之前也是如此,并且独立于较长的 timeoutSeconds 值设置上限,以便冷启动/身份验证/上下文失败能够快速暴露。
运行对账

Cron 负责其自身运行的恢复和历史;空的客户端进程并不是 Gateway 运行已停止的证据。

重启恢复将已定稿结果匹配到运行标识,而不仅仅是恰好相同的开始时间。已验证的存活进程会保留其运行回执。如果存在外部进程,但其启动标识无法验证,其回执在排队或运行开始超过两小时后变为可恢复。恢复流程在接纳另一个运行之前会撤销该回执;它无法撤销已在途的外部副作用。在 Gateway 启动时,一个在最终运行结果之前被中断的已启用一次性任务,仅当其运行回执证明完成投递尚未开始时,才会通过正常的错过任务补跑恢复,无论其逾期多久。在移交完成状态或写入消息之前,运行会记录一次持久化投递尝试。带有该记录的中断一次性任务保持禁用,投递状态为 Unknown,包括进程在记录尝试和发送之间停止的情况。没有可靠投递尝试证据的旧版中断一次性任务也保持禁用,状态为 Unknown;手动重试前请检查接收方。此围栏覆盖计划消息写入(包括中间消息),但不会使任意命令、脚本或其他工具副作用恰好一次。在正常运行期间回收已死的运行所有者会记录中断,而不会重放已消耗的一次性任务;单独重新调度的触发仍然符合条件。补跑限制和延迟会控制恢复节奏,但不会使其过期。待处理恢复会在另一次重启后保留,包括在 agent-turn 延迟期间。最终结果会在不重放该运行的情况下恢复,并且 deleteAfterRun 仅在完成状态为 succeeded 时删除任务。

如果已完成运行的历史已保存,但其任务更新失败,之后被确认的调度或节奏编辑会在恢复过程中保留其下一次检查。恢复会保留已完成历史,并结算旧运行,而不会再次执行其负载。保存未更改的调度不会改变该已完成运行的恢复方式。

中断的运行无论是在启动期间恢复,还是由运行中的 Gateway 恢复,都会以失败形式出现在运行历史中。再次恢复同一中断不会添加另一条历史记录。

将重复任务提升为自动化

大多数自动化应始于 agent 已经做过的工作。当你多次要求基本相同的任务时,agent 会建议将其转为调度,而不是仅仅再运行一次。提升优于从零开始构建任务,因为该提案继承了一个你已经阅读过的运行:在输出开始按计划到达之前,你就知道输出是什么样子的。

没有重复检测引擎,也没有新的存储历史。agent 从对话本身识别重复,并在提出新任务之前检查 automations(action: "list") 中是否已有任务,因此你已创建的例行任务不会被重复。驱动此行为的提示受 automations 工具门控,因此没有该工具的 agent 永远不会提供其无法创建的例行任务。

在创建任何内容之前,确认会用通俗语言重述调度和任务,例如:"每个工作日 07:00(Europe/Vienna),我会总结夜间更新并在此发布。" 请确认那句话,而不是 cron 表达式。

确认后,agent:

  1. 创建任务,投递默认为你提问所在的对话:其频道和线程,或者在没有外部路由时的对话提交。
  2. 立即以 force 模式使用 run 运行一次,作为可见测试,并投递到同一对话,以便你在首次计划触发之前就能看到真实输出。
  3. 如果该测试失败,则删除任务并告知你。

任务以 enabled 状态创建,而不是禁用-待批准,这是一个刻意的安全选择。调度器监督已启用的任务:失败的任务会触发失败通知,并在重复出错后自动禁用,同时记录原因并通知所有者。没有任何机制监督已禁用的任务。一个被留作禁用、等待永远不会到来的确认的任务,对所有保护机制都不可见,会从默认 automations list 中隐藏,并且永远不会触发或解释自身——这是一种静默无结果,比一个运行并明显抱怨的任务更糟糕。

你的确认仍然控制创建,因此不会在你不知情下安排任何内容,并且测试运行是带有真实投递的真实运行,而不是渲染预览:你批准的内容正是调度将产生的内容。

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