openclaw cron 是 OpenClaw Gateway 的定时任务管理命令，适合需要周期性任务投递和运行排查的用户。支持独立 session 隔离、指数退避重试和失败通知，还准备了常用诊断命令方便验证。--at 一次性任务默认成功后自动删除，--model 必须是被允许的模型，否则任务会直接失败。

OpenClaw cron 定时任务配置与投递排查

管理 Gateway 调度器的定时任务（cron jobs）。

运行 openclaw cron --help 查看完整命令列表。概念指南见 Cron jobs。

怎么配置 session（会话）

--session 接受以下值：main、isolated、current、session:<id>。

键	说明
main	绑定到智能体的主会话。
isolated	每次运行创建全新的转写内容和会话 ID。
current	绑定到创建时的活跃会话。
session:<id>	固定到显式的持久会话键。

独立会话的语义：独立运行的上下文环境会被重置。频道和群组路由、发送/队列策略、权限提升、来源和 ACP 运行时绑定在每次新运行时都会重置。安全的偏好和用户显式选择的模型或认证覆盖可以跨运行携带。

投递配置与故障排查

openclaw cron list 和 openclaw cron show <job-id> 可以预览解析后的投递路径。对于 channel: "last"，预览会显示路径是从主会话还是当前会话解析的，或者是否会关闭失败。

使用前缀限定目标可以消除未明确声明的 announce 频道的歧义。例如，to: "telegram:123" 在 delivery.channel 省略或为 last 时会选择 Telegram。只有已加载插件声明的前缀才是 provider 选择器。如果 delivery.channel 是显式的，前缀必须匹配该频道；channel: "whatsapp" 配合 to: "telegram:123" 会被拒绝。Service 前缀如 imessage: 和 sms: 仍然属于频道拥有的目标语法。

默认投递行为：独立 cron add 任务默认使用 --announce 投递。使用 --no-deliver 让输出保留在内部。--deliver 是 --announce 的废弃别名，仍支持。

投递归属

独立 cron 聊天的投递在智能体和 runner 之间共享：

• 如果存在聊天路径，智能体可以直接使用 message 工具发送。
• announce 仅在智能体未直接发送到已解析的目标时，回退投递最终回复。
• webhook 将完成的载荷发布到 URL。
• none 禁用 runner 回退投递。

--announce 是 runner 对最终回复的回退投递。--no-deliver 禁用该回退，但不会移除智能体的 message 工具（如果存在聊天路径）。

从活跃聊天创建的提醒会保留实时聊天投递目标，用于回退 announce 投递。内部会话键可能是小写；不要将其用作大小写敏感的 provider ID（如 Matrix 房间 ID）的事实来源。

失败投递解析

失败通知按以下顺序解析：

1. 任务上的 delivery.failureDestination。
2. 全局 cron.failureDestination。
3. 任务的主 announce 目标（未设置显式失败目标时）。

主会话任务限制：主会话任务仅在主投递模式为 webhook 时，才可以使用 delivery.failureDestination。独立任务在所有模式下都接受。

注意：独立 cron 运行将运行级别的智能体失败视为任务错误，即使没有产生回复载荷。因此模型/提供者失败仍会递增错误计数并触发失败通知。

如果独立运行在第一个模型请求之前超时，openclaw cron show 和 openclaw cron runs 会包含阶段特定错误，如 setup timed out before runner start 或 stalled before first model call (last phase: context-engine)。对于 CLI 支持的提供者，预模型监视程序会一直保持活跃直到外部 CLI 轮到开始，因此会话查找、hook、认证、提示和 CLI 设置的停滞都会被报告为预模型 cron 失败。

调度配置

一次性任务

--at <datetime> 调度一次性运行。没有时区偏移的日期时间视为 UTC，除非同时传入 --tz <iana>，这会将挂钟时间解释为指定时区。

一次性任务成功执行后默认自动删除。使用 --keep-after-run 可保留。

周期性任务

周期性任务在连续出错后使用指数退避重试：30 秒、1 分钟、5 分钟、15 分钟、60 分钟。下一次成功运行后恢复正常调度。

跳过的运行与执行错误分开跟踪。它们不会影响重试退避，但 openclaw cron edit <job-id> --failure-alert-include-skipped 可以设置失败告警重复跳过运行通知。

对于目标为本地已配置模型提供者的独立作业，cron 在启动智能体轮次之前运行轻量级提供者预检。回环、私有网络和 .local 的 api: "ollama" 提供者在 /api/tags 探测；本地 OpenAI 兼容提供者（如 vLLM、SGLang、LM Studio）在 /models 探测。如果端点不可达，运行被记录为 skipped 并在后续调度中重试；匹配的死亡端点会缓存 5 分钟，避免多个作业频繁请求同一本地服务器。

注意：cron 任务定义存在 jobs.json 中，待定运行时状态存在 jobs-state.json 中。如果 jobs.json 被外部编辑，Gateway 会重新加载更改的调度并清除旧的待定槽位；仅格式重写不会清除待定槽位。

手动运行

openclaw cron run <job-id> 默认强制运行，并在手动运行入队后立即返回。成功响应包含 { ok: true, enqueued: true, runId }。使用返回的 runId 检查后续结果：

openclaw cron run <job-id>
openclaw cron runs --id <job-id> --run-id <run-id>

如果脚本需要阻塞直到该特定队列的运行记录终端状态，添加 --wait：

openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s

使用 --wait 时，CLI 仍然先调用 cron.run，然后轮询 cron.runs 获取返回的 runId。仅当运行以状态 ok 完成时，命令退出码为 0。如果运行以 error 或 skipped 完成、Gateway 响应不包含 runId、或 --wait-timeout 超时，则退出码非零。--poll-interval 必须大于零。

使用 --due 让手动命令仅在任务当前到期时运行。如果 --due --wait 未入队运行，命令返回正常的非运行响应，而不是轮询。

怎么配置模型

cron add|edit --model <ref> 为任务选择允许的模型。

模型验证：如果模型不允许或无法解析，cron 会以显式验证错误使运行失败，而不是回退到任务的智能体或默认模型选择。

Cron --model 是任务主模型，不是聊天会话的 /model 覆盖。这意味着：

• 当选定的任务模型失败时，已配置的模型回退仍然适用。
• 每个任务载荷中的 fallbacks 会替换已配置的回退列表（如果存在）。
• 空的每个任务回退列表（fallbacks: [] 在任务载荷/API 中）使 cron 运行变得严格。
• 当任务有 --model 但未配置回退列表时，OpenClaw 会传递一个显式的空回退覆盖，这样智能体主模型就不会被添加为隐藏的重试目标。

openclaw doctor 报告已设置 payload.model 的任务，包括提供者命名空间计数和与 agents.defaults.model 的不匹配。当认证、提供者或计费行为在实时聊天和定时任务之间表现不同时，使用此检查。

独立 cron 模型优先级

独立 cron 按以下顺序解析活跃模型：

1. Gmail-hook 覆盖。
2. 每个任务的 --model。
3. 存储的 cron 会话模型覆盖（当用户选择了一个时）。
4. 智能体或默认模型选择。

快速模式

独立 cron 快速模式遵循已解析的实时模型选择。模型配置中的 params.fastMode 默认应用，但存储的会话 fastMode 覆盖仍然优先于配置。

实时模型切换重试

如果独立运行抛出 LiveSessionModelSwitchError，cron 在重试之前会持久化已切换的提供者和模型（以及切换的认证配置文件覆盖，如果存在）用于活跃运行。外部重试循环限制在初始尝试后最多两次切换重试，然后中止，而不是无限循环。

运行输出和拒绝

过时确认抑制

独立 cron 抑制过时的纯确认回复。如果第一个结果只是临时状态更新，且没有子智能体运行负责最终答案，cron 会在投递前重新提示一次以获取真实结果。

静默 token 抑制

如果独立 cron 运行只返回静默 token（NO_REPLY 或 no_reply），cron 同时抑制直接出站投递和回退的排队摘要路径，因此不会向聊天发布任何内容。

结构化拒绝

独立 cron 运行使用嵌入运行的结构化执行拒绝元数据作为权威拒绝信号。当嵌套的结构化错误消息以 SYSTEM_RUN_DENIED 或 INVALID_REQUEST 开头时，它们也接受节点主机的 UNAVAILABLE 包装器。

Cron 不会将最终输出散文或看起来像是批准的拒绝短语分类为拒绝，除非嵌入的运行也提供结构化拒绝元数据。因此普通的助手文本不会被当作被阻止的命令。

cron list 和运行历史会显示拒绝原因，而不是将阻止的命令报告为 ok。

保留策略

保留和清理由配置控制：

• cron.sessionRetention（默认 24h）：清理已完成的独立运行会话。
• cron.runLog.maxBytes 和 cron.runLog.keepLines：清理 ~/.openclaw/cron/runs/<jobId>.jsonl。

迁移旧任务

如果你有旧版 cron 任务（早于当前投递和存储格式），运行 openclaw doctor --fix。Doctor 会规范化遗留 cron 字段（jobId、schedule.cron、顶层投递字段包括遗留 threadId、载荷 provider 投递别名），并在 cron.webhook 已配置时将简单的 notify: true webhook 回退任务迁移到显式 webhook 投递。

常见编辑操作

更新投递设置而不修改消息内容：

openclaw cron edit <job-id> --announce --channel telegram --to "123456789"

禁用独立任务的投递：

openclaw cron edit <job-id> --no-deliver

为独立任务启用轻量引导上下文：

openclaw cron edit <job-id> --light-context

向指定频道发布通知：

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"

发送到 Telegram 论坛主题：

openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

创建带轻量引导上下文的独立任务：

openclaw cron add \
  --name "Lightweight morning brief" \
  --cron "0 7 * * *" \
  --session isolated \
  --message "Summarize overnight updates." \
  --light-context \
  --no-deliver

--light-context 仅适用于独立智能体轮次任务。在 cron 运行中，轻量模式保持引导上下文为空，而不是注入完整的工作区引导集。

常见管理命令

手动运行和检查：

openclaw cron list
openclaw cron list --agent ops
openclaw cron get <job-id>
openclaw cron show <job-id>
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron run <job-id> --wait --wait-timeout 10m
openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s
openclaw cron runs --id <job-id> --limit 50
openclaw cron runs --id <job-id> --run-id <run-id>

openclaw cron list 默认显示所有匹配的任务。传递 --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。这镜像了可读状态列，以便外部工具无需重新推导即可读取任务状态。

cron runs 条目包含投递诊断信息：预期的 cron 目标、已解析的目标、消息工具发送、回退使用和投递状态。

智能体和会话重定向：

openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"

openclaw cron add 在智能体轮次任务上省略 --agent 时会发出警告，并回退到默认智能体（main）。在创建时传递 --agent <id> 以固定特定智能体。

投递调整：

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver

常见问题

定时任务到点了但没有触发，怎么排查？

先运行 openclaw gateway status 确认 Gateway 在线。然后用 openclaw cron runs --id <job-id> 查看运行日志。如果日志为空，检查 cron 表达式是否有误（可用 crontab.guru 验证），以及 Gateway 是否在任务触发时段内持续运行。另外检查 ~/.openclaw/cron/jobs-state.json 中是否有待定槽位被意外清除。

--no-deliver 和 --announce 有什么区别？

--announce 将任务结果投递到指定频道（如 Telegram/Slack），--no-deliver 则只在内部执行不发送任何消息。独立任务默认 --announce。注意 --no-deliver 不会阻止智能体的 message 工具直接发送，它只禁用 runner 的回退投递。

如何让某个 cron 任务只运行一次？

在 cron add 时使用 --at 指定未来时间，例如 --at "2026-05-01T09:00:00"。任务成功运行后会自动删除。若希望保留任务记录，加上 --keep-after-run。

相关文档

• CLI reference
• Scheduled tasks