定时任务

Cron 是 Gateway 网关的内置调度器。它会持久化作业，在正确时间唤醒智能体，并可将输出送回聊天渠道或 webhook 端点。

快速开始

openclaw cron add \  --name "Reminder" \  --at "2026-02-01T16:00:00Z" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --wake now \  --delete-after-run

openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

cron 的工作原理

• Cron 在 Gateway 网关进程内部运行（不在模型内部）。
• 作业定义会持久化到 ~/.openclaw/cron/jobs.json，因此重启不会丢失计划。
• 运行时执行状态会持久化到旁边的 ~/.openclaw/cron/jobs-state.json。如果你在 git 中跟踪 cron 定义，请跟踪 jobs.json，并将 jobs-state.json 加入 gitignore。
• 拆分后，旧版本 OpenClaw 可以读取 jobs.json，但可能会把作业视为全新作业，因为运行时字段现在位于 jobs-state.json 中。
• 当 Gateway 网关正在运行或已停止时编辑 jobs.json，OpenClaw 会将变更的计划字段与待处理运行时槽位元数据进行比较，并清除陈旧的 nextRunAtMs 值。纯格式化或仅键顺序重写会保留待处理槽位。
• 所有 cron 执行都会创建后台任务记录。
• 在 Gateway 网关启动时，逾期的隔离智能体轮次作业会被重新安排到渠道连接窗口之外，而不是立即重放，因此 Discord/Telegram 启动和原生命令设置在重启后仍能保持响应。
• 一次性作业（--at）默认在成功后自动删除。
• 隔离 cron 运行完成时，会尽力关闭其 cron:<jobId> 会话中跟踪的浏览器标签页/进程，因此分离的浏览器自动化不会留下孤立进程。
• 获得狭窄 cron 自清理授权的隔离 cron 运行，仍可以读取调度器状态、经过自过滤的当前作业列表以及该作业的运行历史，因此状态/Heartbeat 检查可以检查自身计划，而不会获得更广泛的 cron 修改权限。
• 隔离 cron 运行还会防范陈旧的确认回复。如果第一个结果只是临时状态更新（on it、pulling everything together 以及类似提示），并且没有后代子智能体运行仍负责最终答案，OpenClaw 会在交付前重新提示一次以获取实际结果。
• 隔离 cron 运行优先使用嵌入式运行中的结构化执行拒绝元数据，然后回退到已知的最终摘要/输出标记，例如 SYSTEM_RUN_DENIED 和 INVALID_REQUEST，因此被阻止的命令不会被报告为成功运行。
• 隔离 cron 运行还会将运行级智能体失败视为作业错误，即使没有生成回复载荷也是如此，因此模型/提供商失败会递增错误计数器并触发失败通知，而不是把作业清除为成功。
• 当隔离智能体轮次作业达到 timeoutSeconds 时，cron 会中止底层智能体运行，并给它一个短暂的清理窗口。如果运行没有排空，由 Gateway 网关拥有的清理会在 cron 记录超时前强制清除该运行的会话所有权，因此排队的聊天工作不会被留在陈旧的处理中会话后面。
• 如果隔离智能体轮次在运行器启动前或首次模型调用前停滞，cron 会记录特定阶段的超时，例如 setup timed out before runner start 或 stalled before first model call (last phase: context-engine)。这些 watchdog 会在外部 CLI 进程实际启动前覆盖嵌入式提供商和 CLI 支持的提供商，并且与较长的 timeoutSeconds 值独立封顶，因此冷启动/凭证/上下文失败会快速暴露，而不是等待完整作业预算。

计划类型

不带时区的时间戳会被视为 UTC。添加 --tz America/New_York 可按本地墙钟时间调度。

整点循环表达式会自动错开最多 5 分钟，以减少负载峰值。使用 --exact 强制精确计时，或使用 --stagger 30s 指定显式窗口。

月中日期和星期使用 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 次。OpenClaw 在这里使用 Croner 的默认 OR 行为。要要求两个条件都满足，请使用 Croner 的 + 星期修饰符（0 9 15 * +1），或在一个字段上调度，并在作业的提示或命令中保护另一个条件。

执行风格

隔离作业的载荷选项

--model 使用所选的允许模型作为该作业的主模型。它不同于聊天会话的 /model 覆盖：当作业主模型失败时，已配置的回退链仍然适用。如果请求的模型不被允许或无法解析，cron 会让运行失败，并给出明确的验证错误，而不是静默回退到作业的智能体/默认模型选择。

cron 作业也可以携带载荷级 fallbacks。如果存在，该列表会替换作业已配置的回退链。当你想要严格 cron 运行，仅尝试所选模型时，请在作业载荷/API 中使用 fallbacks: []。如果作业有 --model，但既没有载荷回退，也没有已配置回退，OpenClaw 会传递显式空回退覆盖，因此智能体主模型不会作为隐藏的额外重试目标追加进去。

隔离作业的模型选择优先级为：

1. Gmail 钩子模型覆盖（当运行来自 Gmail 且该覆盖被允许时）
2. 每作业载荷 model
3. 用户选择的已存储 cron 会话模型覆盖
4. 智能体/默认模型选择

Fast 模式也会跟随解析后的实时选择。如果所选模型配置具有 params.fastMode，隔离 cron 默认会使用它。已存储会话的 fastMode 覆盖仍会在任一方向上优先于配置。

如果隔离运行遇到实时模型切换移交，cron 会使用切换后的提供商/模型重试，并在重试前为活动运行持久化该实时选择。当切换还携带新的凭证配置文件时，cron 也会为活动运行持久化该凭证配置文件覆盖。重试是有界的：在初始尝试加 2 次切换重试之后，cron 会中止，而不是无限循环。

在隔离的 cron 运行进入智能体运行器之前，OpenClaw 会检查已配置的 api: "ollama" 和 api: "openai-completions" 提供商中可访问的本地提供商端点，这些端点的 baseUrl 为 local loopback、私有网络或 .local。如果该端点已停机，运行会被记录为 skipped，并给出明确的提供商/模型错误，而不是启动模型调用。端点结果会缓存 5 分钟，因此许多使用同一个已停机本地 Ollama、vLLM、SGLang 或 LM Studio 服务器的到期作业会共享一次小型探测，而不是制造请求风暴。跳过的提供商预检运行不会增加执行错误退避；当你想收到重复跳过通知时，请启用 failureAlert.includeSkipped。

投递和输出

使用 --announce --channel telegram --to "-1001234567890" 进行渠道投递。对于 Telegram 论坛主题，请使用 -1001234567890:topic:123；直接 RPC/配置调用方也可以将 delivery.threadId 作为字符串或数字传入。Slack/Discord/Mattermost 目标应使用显式前缀（channel:<id>、user:<id>）。Matrix 房间 ID 区分大小写；请使用精确的房间 ID，或使用来自 Matrix 的 room:!room:server 形式。

当 announce 投递使用 channel: "last" 或省略 channel 时，带提供商前缀的目标（例如 telegram:123）可以在 cron 回退到会话历史或单个已配置渠道之前选择渠道。只有已加载插件声明的前缀才是提供商选择器。如果 delivery.channel 是显式的，目标前缀必须命名同一个提供商；例如，channel: "whatsapp" 搭配 to: "telegram:123" 会被拒绝，而不是让 WhatsApp 将 Telegram ID 解释为电话号码。目标类型和服务前缀（例如 channel:<id>、user:<id>、imessage:<handle> 和 sms:<number>）仍然是渠道拥有的目标语法，而不是提供商选择器。

对于隔离作业，聊天投递是共享的。如果聊天路由可用，即使作业使用 --no-deliver，智能体也可以使用 message 工具。如果智能体发送到已配置/当前目标，OpenClaw 会跳过兜底 announce。否则，announce、webhook 和 none 只控制运行器在智能体轮次之后如何处理最终回复。

当智能体从活跃聊天创建隔离提醒时，OpenClaw 会存储保留的实时投递目标，用于兜底 announce 路由。内部会话键可以是小写；当当前聊天上下文可用时，不会从这些键重建提供商投递目标。

隐式 announce 投递会使用已配置的渠道 allowlist 来验证并重定向过期目标。私信配对存储批准不是兜底自动化收件人；当定时作业需要主动发送到私信时，请设置 delivery.to 或配置渠道 allowFrom 条目。

失败通知遵循单独的目标路径：

• cron.failureDestination 为失败通知设置全局默认值。
• job.delivery.failureDestination 按作业覆盖该值。
• 如果两者都未设置，并且作业已通过 announce 投递，失败通知现在会回退到该主要 announce 目标。
• delivery.failureDestination 仅支持 sessionTarget="isolated" 作业，除非主要投递模式是 webhook。
• failureAlert.includeSkipped: true 会让作业或全局 cron 告警策略选择接收重复的跳过运行告警。跳过的运行会保留单独的连续跳过计数器，因此不会影响执行错误退避。

CLI 示例

openclaw cron add \  --name "Calendar check" \  --at "20m" \  --session main \  --system-event "Next heartbeat: check calendar." \  --wake now

openclaw cron add \  --name "Morning brief" \  --cron "0 7 * * *" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Summarize overnight updates." \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "Deep analysis" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Weekly deep analysis of project progress." \  --model "opus" \  --thinking high \  --announce

Webhook

Gateway 网关 可以公开 HTTP webhook 端点，用于外部触发器。在配置中启用：

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",  },}

身份验证

每个请求都必须通过标头包含 hook 令牌：

• Authorization: Bearer <token>（推荐）
• x-openclaw-token: <token>

查询字符串令牌会被拒绝。

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'

Gmail PubSub 集成

通过 Google PubSub 将 Gmail 收件箱触发器接入 OpenClaw。

向导设置（推荐）

openclaw webhooks gmail setup --account [email protected]

这会写入 hooks.gmail 配置，启用 Gmail 预设，并使用 Tailscale Funnel 作为推送端点。

Gateway 网关 自动启动

当 hooks.enabled=true 且已设置 hooks.gmail.account 时，Gateway 网关 会在启动时启动 gog gmail watch serve 并自动续期 watch。设置 OPENCLAW_SKIP_GMAIL_WATCHER=1 可选择退出。

手动一次性设置

gcloud auth logingcloud config set project <project-id>gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:[email protected] \  --role=roles/pubsub.publisher

gog gmail watch start \  --account [email protected] \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

Gmail 模型覆盖

{  hooks: {    gmail: {      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

管理作业

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent opsopenclaw cron edit <jobId> --clear-agent

配置

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 1,    retry: {      maxAttempts: 3,      backoffMs: [60000, 120000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "server_error"],    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",    runLog: { maxBytes: "2mb", keepLines: 2000 },  },}

maxConcurrentRuns 同时限制定时 cron 调度和隔离智能体轮次执行。隔离 cron 智能体轮次在内部使用队列的专用 cron-nested 执行通道，因此提高该值会让独立的 cron LLM 运行并行推进，而不是只启动它们的外层 cron 包装器。共享的非 cron nested 通道不会被此设置拓宽。

运行时状态 sidecar 源自 cron.store：例如 ~/clawd/cron/jobs.json 这样的 .json 存储会使用 ~/clawd/cron/jobs-state.json，而没有 .json 后缀的存储路径会追加 -state.json。

如果你手动编辑 jobs.json，请不要将 jobs-state.json 纳入源代码控制。OpenClaw 使用该 sidecar 存放待处理槽位、活跃标记、上次运行元数据，以及告诉调度器外部编辑的作业何时需要新的 nextRunAtMs 的调度身份。

禁用 cron：cron.enabled: false 或 OPENCLAW_SKIP_CRON=1。

故障排除

命令阶梯

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

相关内容

• 自动化 — 概览所有自动化机制
• 后台任务 — Cron 执行的任务账本
• Heartbeat — 周期性的主会话轮次
• 时区 — 时区配置