openclaw cron
管理 Gateway 网关调度器的定时任务。
所有定时任务变更操作（
add/create、update/edit、remove、run）都需要 operator.admin。命令载荷直接在 Gateway 网关进程中运行，而不是作为智能体的 tools.exec 工具调用；tools.exec.* 和 Exec 审批仍会管控模型可见的 Exec 工具。快速创建任务
openclaw cron create 是 openclaw cron add 的别名。创建新任务时，先放调度表达式，再放提示词：
--webhook <url>：
--command：
--command <shell> 存储 argv: ["sh", "-lc", <shell>]。如需精确执行 argv，请使用 --command-argv '["node","scripts/report.mjs"]'。命令任务会捕获 stdout/stderr、记录常规定时任务历史记录，并通过与隔离任务相同的 announce、webhook 或 none 投递模式路由输出。仅打印 NO_REPLY 的命令将被抑制。
会话
--session 接受 main、isolated、current 或 session:<id>。
会话键
会话键
main绑定到智能体的主会话。isolated为每次运行创建新的对话记录和会话 ID。current绑定到创建时的活动会话。session:<id>固定到明确指定的持久会话键。
隔离会话语义
隔离会话语义
隔离运行会重置环境对话上下文。渠道和群组路由、发送/排队策略、权限提升、来源以及 ACP 运行时绑定都会针对新运行重置。安全偏好设置以及用户明确选择的模型或身份验证覆盖项可以跨运行保留。
投递
openclaw cron list 和 openclaw cron show <job-id> 可预览解析后的投递路由。对于 channel: "last"，预览会显示路由是从主会话还是当前会话解析的，或者是否会以关闭方式失败。
带提供商前缀的目标可以消除未解析公告渠道的歧义。例如，当省略 delivery.channel 或其值为 last 时，to: "telegram:123" 会选择 Telegram。只有已加载插件声明的前缀才是提供商选择器。如果明确指定了 delivery.channel，前缀必须与该渠道匹配；将 channel: "whatsapp" 与 to: "telegram:123" 组合使用会被拒绝。imessage: 和 sms: 等服务前缀仍属于渠道自有的目标语法。
隔离的
cron add 任务默认使用 --announce 投递。使用 --no-deliver 可将输出保留在内部。--deliver 仍作为 --announce 的已弃用别名保留。投递所有权
隔离定时任务的聊天投递由智能体和运行器共同负责：- 当聊天路由可用时，智能体可以使用
message工具直接发送。 - 仅当智能体未直接发送到解析后的目标时，
announce才会回退投递最终回复。 webhook将最终载荷发布到 URL。none禁用运行器的回退投递。
cron add|create --webhook <url> 或 cron edit <job-id> --webhook <url> 设置 webhook 投递。不要将 --webhook 与 --announce、--no-deliver、--channel、--to、--thread-id 或 --account 等聊天投递标志组合使用。
cron edit <job-id> 可以使用 --clear-channel、--clear-to、--clear-thread-id 和 --clear-account 取消设置各个投递路由字段（每个选项与其对应的设置标志组合时都会被拒绝）。--no-deliver 仅禁用运行器回退投递，与之不同的是，这些选项会移除已存储的字段，使任务再次从默认值解析其路由的相应部分。
--announce 是最终回复的运行器回退投递。--no-deliver 会禁用该回退，但在聊天路由可用时不会移除智能体的 message 工具。
从活动聊天创建的提醒会保留实时聊天投递目标，用于回退公告投递。内部会话键可以是小写；不要将它们作为 Matrix 房间 ID 等区分大小写的提供商 ID 的事实依据。
失败投递
失败通知按以下顺序解析：- 任务上的
delivery.failureDestination。 - 全局
cron.failureDestination。 - 任务的主要公告目标（当上述两项均未解析为具体目的地时）。
仅当主要投递模式为
webhook 时，主会话任务才可以使用 delivery.failureDestination。隔离任务在所有模式下均接受它。ok；非零退出、信号、超时或无输出超时记录为 error，并且可以触发相同的失败通知路径。
如果隔离运行在首次模型请求前超时，openclaw cron show 和 openclaw cron runs 会包含特定于阶段的错误，例如 setup timed out before runner start，或者包含一条指出最后已知启动阶段的停滞消息（例如 context-engine）。对于基于 CLI 的提供商，预模型看门狗会保持活动状态，直到外部 CLI 轮次开始，因此会话查找、钩子、身份验证、提示词和 CLI 设置停滞都会被报告为预模型定时任务故障。
调度
单次任务
--at <datetime> 安排单次运行。没有偏移量的日期时间会被视为 UTC，除非你同时传入 --tz <iana>，它会按给定时区解释挂钟时间。
默认情况下，单次任务成功后会被删除。使用
--keep-after-run 可保留任务。重复任务
重复任务在连续发生错误后使用指数重试退避：30s、1m、5m、15m、60m。下一次运行成功后，调度恢复正常。 跳过的运行与执行错误分开跟踪。它们不会影响重试退避，但openclaw cron edit <job-id> --failure-alert-include-skipped 可以让失败警报包含重复的运行跳过通知。
对于以本地已配置模型提供商（基准 URL 位于环回地址、专用网络或 .local）为目标的隔离任务，定时任务会在启动智能体轮次前执行轻量级提供商预检：在 /api/tags 探测 api: "ollama" 提供商；在 /models 探测其他与 OpenAI 兼容的本地提供商（api: "openai-completions"，例如 vLLM、SGLang、LM Studio）。如果端点不可访问，该运行会记录为 skipped，并在后续调度时重试；每个端点的可达性结果会缓存 5 分钟，以免针对同一本地服务器的大量任务通过重复探测对其造成压力。
定时任务、待处理运行时状态和运行历史记录存储在共享 SQLite 状态数据库中。旧版 jobs.json、<name>-state.json 和 runs/*.jsonl 文件会被导入一次，并使用 .migrated 后缀重命名。导入后，请使用 openclaw cron add|edit|remove 编辑调度，而不是编辑 JSON 文件。
手动运行
openclaw cron run <job-id> 默认强制运行，并在手动运行进入队列后立即返回。成功响应包含 { ok: true, enqueued: true, runId }。使用返回的 runId 查看后续结果：
--wait：
--wait 时，CLI 仍会先调用 cron.run，然后针对返回的 runId 轮询 cron.runs。仅当运行以 ok 状态结束时，命令才以 0 退出。如果运行以 error 或 skipped 结束、Gateway 网关响应不包含 runId，或者 --wait-timeout 到期（默认为 10m，默认每 2s 轮询一次），命令将以非零状态退出。--poll-interval 必须大于零。
如果你只想在任务当前已到期时运行手动命令，请使用
--due。如果 --due --wait 未将运行加入队列，命令会返回常规的未运行响应，而不会进行轮询。Models
cron add|edit --model <ref> 为任务选择允许使用的模型。cron add|edit --fallbacks <list> 设置每个任务的回退模型，例如 --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5；传入 --fallbacks "" 可执行没有回退模型的严格运行。cron edit <job-id> --clear-fallbacks 移除每个任务的回退覆盖项。cron edit <job-id> --clear-model 移除每个任务的模型覆盖项，使任务遵循正常的定时任务模型选择优先级（优先使用已存储的定时任务会话覆盖项，否则使用智能体/默认模型）；它不能与 --model 组合使用。cron add|edit --thinking <level> 设置每个任务的思考覆盖项；cron edit <job-id> --clear-thinking 将其移除，使任务遵循正常的定时任务思考优先级，并且不能与 --thinking 组合使用。
定时任务的 --model 是任务主模型，而不是聊天会话的 /model 覆盖项。这意味着：
- 选定的任务模型失败时，已配置的模型回退仍然适用。
- 如果存在每个任务的载荷
fallbacks，它会替换已配置的回退列表。 - 空的每任务回退列表（任务载荷/API 中的
--fallbacks ""或fallbacks: []）会使定时任务严格运行。 - 当任务包含
--model但未配置回退列表时，OpenClaw 会传入明确的空回退覆盖项，避免将智能体主模型作为隐藏重试目标追加。 - 本地提供商预检会逐个检查已配置的回退项，然后才将定时任务运行标记为
skipped。
openclaw doctor 会报告已设置 payload.model 的任务，包括提供商命名空间计数以及与 agents.defaults.model 的不匹配项。当实时聊天与调度任务之间的身份验证、提供商或计费行为看起来不同时，请使用此检查。
隔离定时任务模型优先级
隔离定时任务按以下顺序解析活动模型：- Gmail 钩子覆盖项。
- 每个任务的
--model。 - 已存储的定时任务会话模型覆盖项（当用户选择过时）。
- 智能体或默认模型选择。
快速模式
隔离的定时任务快速模式遵循解析后的实时模型选择。默认应用模型配置params.fastMode，但存储的会话 fastMode 覆盖仍优先于配置。当解析后的模式为 auto 时，截止时间使用所选模型的 params.fastAutoOnSeconds 值，默认为 60 秒。
实时模型切换重试
如果隔离运行抛出LiveSessionModelSwitchError，定时任务会在重试前，为当前运行持久化切换后的提供商和模型（以及存在时切换后的身份验证配置文件覆盖）。外层重试循环在初次尝试后最多进行两次切换重试，随后中止，而不是无限循环。
运行输出和拒绝
抑制过时确认
隔离的定时任务轮次会抑制仅包含过时确认的回复。如果第一个结果只是临时状态更新，并且没有任何后代子智能体运行负责生成最终答案，定时任务会在交付前重新提示一次，以获取实际结果。抑制静默令牌
如果隔离的定时任务运行仅返回静默令牌（NO_REPLY 或 no_reply），定时任务会同时抑制直接出站交付和后备排队摘要路径，因此不会向聊天回发任何内容。
结构化拒绝
隔离的定时任务运行将嵌入式运行提供的结构化执行拒绝元数据（编码为SYSTEM_RUN_DENIED 或 INVALID_REQUEST 的致命 Exec 工具错误）用作权威拒绝信号。它们也会识别节点主机的 UNAVAILABLE 包装器，其中嵌套的结构化错误携带上述代码之一。
除非嵌入式运行也提供结构化拒绝元数据，否则定时任务不会将最终输出中的文字或看似要求审批的拒绝语句归类为拒绝，因此普通智能体文本不会被视为受阻命令。
cron list 和运行历史记录会显示拒绝原因，而不是将受阻命令报告为 ok。
保留
保留行为：cron.sessionRetention（默认值为24h，或设为false以禁用）会清理已完成的隔离运行会话。- 运行历史记录为每个定时任务保留最新的 2000 条终态记录。丢失的记录仍采用标准的 24 小时丢失任务清理窗口。
迁移旧任务
如果你的定时任务创建于当前交付和存储格式之前，请运行
openclaw doctor --fix。Doctor 会规范化旧版定时任务字段（jobId、schedule.cron、包括旧版 threadId 在内的顶层交付字段、有效负载 provider 交付别名），并在移除该配置键之前，将 notify: true Webhook 后备任务从已停用的原始 cron.webhook 值迁移为显式 Webhook 交付。已经向聊天发送通知的任务会保留该交付方式，并获得一个完成 Webhook 目标。若没有旧版 Webhook，对于没有迁移目标的任务，会移除不起作用的顶层 notify 标记（现有交付方式保持不变），因此 doctor --fix 不会再反复发出相关警告。常用编辑操作
在不更改消息的情况下更新交付设置：--light-context 仅适用于隔离的智能体轮次任务。对于定时任务运行，轻量级模式会保持引导上下文为空，而不是注入完整的工作区引导集合。
创建具有精确 argv、cwd、env、stdin 和输出限制的命令任务：
常用管理命令
手动运行和检查：openclaw cron list 默认显示已启用的任务。传入 --all 可包括已禁用的任务，或传入 --agent <id> 仅显示有效规范化智能体 ID 匹配的任务；未存储智能体 ID 的任务视为使用配置的默认智能体。
openclaw cron get <job-id> 直接返回存储的任务 JSON。如需包含交付路由预览的易读视图，请使用 cron show <job-id>。
cron list --json 和 cron show <job-id> --json 会在每个任务中包含一个顶层 status 字段，该字段根据 enabled、state.runningAtMs 和 state.lastRunStatus 计算。值包括：disabled、running、ok、error、skipped 或 idle。JSON 状态保持规范且不加修饰，以便外部工具无需重新推导即可读取任务状态；易读输出可以为重复的 error 状态附加失败次数。
cron runs 条目包含交付诊断信息，包括预期的定时任务目标、解析后的目标、消息工具发送情况、后备方案使用情况和已交付状态。
每个任务的私有暂存区（Heartbeat 检查清单和类似的监控上下文）：
cron list/cron get/cron runs 输出中。写入操作通过比较并交换机制，基于命令启动时读取的修订版本提供保护；也可以传入 --expected-revision <n> 来固定显式修订版本。有关 Heartbeat 监控器如何使用暂存区，请参阅 Heartbeat。
重新指定智能体和会话：
--agent 时，openclaw cron add 会发出警告，并回退到默认智能体（main）。创建时传入 --agent <id> 可固定特定智能体。
交付调整：