定时任务

Cron 是 Gateway 网关的内置调度器。它会持久化任务、在适当的时间唤醒智能体，并可将输出发送到聊天渠道、Webhook，或不发送到任何位置。

快速开始

openclaw cron create "2027-02-01T16:00:00Z" \  --name "Reminder" \  --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 网关进程内部运行，而不是在模型内部运行。Gateway 网关必须保持运行，计划任务才能触发。
• 任务定义、运行时状态和运行历史记录持久化在 OpenClaw 的共享 SQLite 状态数据库中，因此重启不会丢失计划任务。
• 每次 Cron 执行都会创建一条后台任务记录。
• 一次性任务（--at）默认在成功后自动删除；传入 --keep-after-run 可将其保留。
• 每次运行的实际时间预算：设置时使用 --timeout-seconds。否则，隔离/分离的智能体轮次任务由 Cron 自身的 60 分钟看门狗限制，它会在底层智能体轮次超时（agents.defaults.timeoutSeconds，默认 48 小时）生效前触发；命令任务默认为 10 分钟。
• Gateway 网关启动时，逾期的隔离智能体轮次任务会被重新调度，而不是立即重放，从而避免模型/工具引导工作占用渠道连接时间窗口。
• 如果你通过系统 Cron 或其他外部调度器驱动 openclaw agent，即使 CLI 已处理 SIGTERM/SIGINT，也应使用强制终止升级机制将其封装。由 Gateway 网关支持的运行会请求 Gateway 网关中止已接受的运行；本地和嵌入式回退运行会收到相同的中止信号。对于 GNU timeout，应优先使用 timeout -k 60 600 openclaw agent ...，而不是普通的 timeout 600 ...——如果进程无法及时完成清理退出，-k 值将作为最后保障。对于 systemd 单元，请使用 SIGTERM 停止信号，并在最终终止前设置宽限时间窗口（TimeoutStopSec）。如果原始 Gateway 网关运行仍处于活动状态时复用 --run-id，系统会将重复请求报告为正在运行，而不会启动第二次运行。

计划类型

没有时区的时间戳将按 UTC 处理。添加 --tz America/New_York，可在该 IANA 时区中解释不带时区偏移量的 --at 日期时间，或计算 Cron 表达式。未使用 --tz 的 Cron 表达式采用 Gateway 网关主机的时区。--tz 不能与 --every 或 --on-exit 一起使用。

整点重复表达式（分钟字段为 0，小时字段为通配符）会自动错开最多 5 分钟，以减少负载峰值。使用 --exact 可强制精确定时，或使用 --stagger 30s 设置显式时间窗口（仅适用于 Cron 计划）。

月中日期和星期字段使用 OR 逻辑

Cron 表达式由 croner 解析。当月中日期字段和星期字段都不是通配符时，只要任一字段匹配，croner 就会判定匹配，而不是要求两者同时匹配。这是标准的 Vixie Cron 行为。

# 预期：“每月 15 日上午 9 点，但仅当当天是星期一”# 实际：“每月 15 日上午 9 点，以及每个星期一上午 9 点”0 9 15 * 1

这会导致每月大约触发 5-6 次，而不是每月 0-1 次。若要求两个条件同时满足，请使用 croner 的 + 星期修饰符（0 9 15 * +1），或基于其中一个字段进行调度，并在任务提示或命令中检查另一个字段。

事件触发器（条件观察器）

事件触发器会向 every 或 cron 计划添加一个无头条件脚本。Cron 会在任务到期时计算该脚本，并且仅当脚本返回 fire: true 时才运行正常载荷：

{  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // 仅当观察到的状态与上次计算不同时触发。    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",    once: false,  },  payload: { kind: "agentTurn", message: "Investigate the CI status change." },}

脚本必须返回 { fire, message?, state? }。之前的 JSON 状态可通过深度冻结的 trigger.state 获取；返回新的 state 值即可将其持久化。状态上限为 16 KB。当触发结果包含 message 时，Cron 会在执行前将其追加到系统事件文本或智能体轮次消息中。once: true 会在首次成功执行已触发载荷后禁用该任务。

fire: false 会持久化计算状态和计数器，然后重新调度，且不创建运行历史记录。如果已触发的载荷运行失败，返回的 state 将不会持久化——下一次计算会看到之前的状态，并可再次触发，因此应将脚本编写为只读检查，并将操作保留在载荷中。触发器计划具有可配置的最小间隔（默认为 30 秒）。每次计算都有 30 秒的实际时间预算，最多可调用 5 次工具。

从本地脚本文件创建观察器（- 从标准输入读取脚本）：

openclaw cron add \  --name "PR CI watcher" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "Respond to the CI status change" \  --session isolated

载荷

每个任务都恰好携带一种通过标志选择的载荷类型：

智能体轮次选项

--model 设置任务的主模型；它不会取代会话的 /model 覆盖，因此已配置的回退链仍会在其基础上生效。无法解析或不允许使用的模型会导致运行失败并显示明确的验证错误，而不是静默回退到默认模型。如果任务有 --model，但没有显式或已配置的回退列表，OpenClaw 会传递空的回退覆盖，而不是静默追加 Agent 主模型作为隐藏的重试目标。

隔离任务的模型选择优先级从高到低如下：

1. 每个任务载荷中的 model（显式配置；不允许使用的模型会导致运行失败）
2. Gmail 钩子的模型覆盖（仅当运行来自 Gmail 且允许使用该覆盖时）
3. 用户选择并存储的 cron 会话模型覆盖
4. Agent/默认模型选择

快速模式遵循解析后的实时选择。如果所选模型配置包含 params.fastMode，隔离 cron 默认使用该值；存储的会话 fastMode 覆盖（其次是 Agent 的 fastModeDefault）仍会在任一方向上优先于模型配置。自动模式使用模型的 params.fastAutoOnSeconds 阈值，默认为 60 秒。

如果运行触发实时模型切换交接，cron 会使用切换后的提供商/模型重试，并为当前运行持久化该选择（以及任何新的身份验证配置文件）。重试次数有限：首次尝试加上 2 次切换重试后，cron 会中止，而不是继续循环。

隔离运行开始前，OpenClaw 会检查已配置的 api: "ollama" 和 api: "openai-completions" 提供商中可访问的本地端点，这些提供商的 baseUrl 为回环地址、私有网络地址或 .local。此预检会遍历任务已配置的回退链，并且仅在所有候选项均无法访问时才将运行标记为 skipped；--fallbacks "" 会使遍历严格限定为仅检查主模型。端点不可用时，运行会记录为 skipped 并附带清晰错误，而不会发起模型调用。结果按端点缓存 5 分钟（而非按任务或模型缓存），因此许多到期任务共用一个失效的本地 Ollama/vLLM/SGLang/LM Studio 服务器时，只需进行一次探测，而不会引发请求风暴。因预检跳过的运行不会增加执行错误退避；设置 failureAlert.includeSkipped 可选择接收重复的跳过提醒。

命令载荷

命令载荷会在 Gateway 网关调度器内运行确定性脚本，而不会启动由模型支持的轮次。它们在 Gateway 网关主机上执行，捕获 stdout/stderr，将运行记录到 cron 历史记录中，并复用与 Agent 轮次任务相同的 announce、webhook 和 none 交付模式。

openclaw cron create "*/15 * * * *" \  --name "队列深度探测" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> 存储 argv: ["sh", "-lc", <shell>]。如需不经过 shell 解析的精确 argv 执行，请使用 --command-argv '["node","scripts/report.mjs"]'。可选的 --command-env KEY=VALUE（可重复使用）、--command-input、--timeout-seconds（默认 10 分钟）、--no-output-timeout-seconds 和 --output-max-bytes 控制进程环境、stdin 和输出限制。

交付的文本源自进程输出：非空 stdout 优先；如果 stdout 为空且 stderr 非空，则交付 stderr；如果二者均存在，cron 会发送一个简短的 stdout: / stderr: 块。退出代码 0 会将运行记录为 ok；非零退出、信号、超时或无输出超时会记录为 error，并可能触发失败提醒。仅输出 NO_REPLY 的命令会使用常规 cron 静默令牌抑制机制，不向聊天发回任何内容。

执行方式

交付和输出

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

当公告交付使用 channel: "last" 或省略 channel 时，cron 回退到会话历史记录或唯一已配置渠道之前，可以通过 telegram:123 等提供商前缀目标选择渠道。只有已加载插件公布的前缀才是提供商选择器。如果显式指定了 delivery.channel，目标前缀必须指定同一提供商；channel: "whatsapp" 与 to: "telegram:123" 的组合会被拒绝，而不会让 WhatsApp 将 Telegram ID 解释为电话号码。目标类型和服务前缀（channel:<id>、user:<id>、imessage:<handle>、sms:<number>）仍是渠道所有的目标语法，而不是提供商选择器。

对于隔离任务，聊天交付是共享的：如果存在聊天路由，即使使用 --no-deliver，Agent 也可以使用 message 工具。如果 Agent 发送到已配置/当前目标，OpenClaw 会跳过回退公告。否则，announce、webhook 和 none 仅控制 Agent 轮次结束后运行器如何处理最终回复。

当 Agent 从活动聊天创建隔离提醒时，OpenClaw 会存储保留的实时交付目标，用作回退公告路由。内部会话键可能为小写；如果当前聊天上下文可用，则不会根据这些键重新构建提供商交付目标。

隐式公告交付使用已配置的渠道允许列表来验证过时目标并重新路由。私信配对存储中的审批对象不是回退自动化接收方；如果计划任务应主动发送到私信，请设置 delivery.to 或配置渠道的 allowFrom 条目。

失败通知

失败通知使用单独的目标路径：

• cron.failureDestination 设置失败通知的全局默认目标。
• job.delivery.failureDestination 按任务覆盖该目标。
• 如果二者均未设置，且任务已通过 announce 交付，则失败通知会回退到该主公告目标。
• delivery.failureDestination 仅支持 sessionTarget="isolated" 任务，除非主交付模式为 webhook。
• failureAlert.includeSkipped: true 可让任务或全局 cron 提醒策略选择接收重复的运行跳过提醒。跳过的运行会使用单独的连续跳过计数器，因此不会影响执行错误退避。
• openclaw cron edit 提供按任务配置的提醒调整选项：--failure-alert/--no-failure-alert、--failure-alert-after <n>、--failure-alert-channel、--failure-alert-to、--failure-alert-cooldown、--failure-alert-include-skipped/--failure-alert-exclude-skipped、--failure-alert-mode 和 --failure-alert-account-id。

输出语言

Cron 任务不会根据渠道、区域设置或以前的消息推断回复语言。请将语言规则写入计划消息或模板中：

openclaw cron edit <jobId> \  --message "总结更新。使用中文回复；保持 URL、代码和产品名称不变。"

对于模板文件，请在渲染后的提示中保留语言指令，并在任务运行前确认 {{language}} 等占位符已填充。如果输出混合了多种语言，请明确说明规则，例如：“叙述性文本使用中文，技术术语保持英文。”

CLI 示例

openclaw cron add \  --name "日历检查" \  --at "20m" \  --session main \  --system-event "下次 Heartbeat：检查日历。" \  --wake now

openclaw cron create "0 7 * * *" \  "汇总夜间更新。" \  --name "晨间简报" \  --tz "America/Los_Angeles" \  --session isolated \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "深度分析" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "每周深入分析项目进展。" \  --model "opus" \  --thinking high \  --announce

openclaw cron create "0 18 * * 1-5" \  "以 JSON 格式汇总今天的部署。" \  --name "部署摘要" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "队列深度探测" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

管理任务

# 列出所有任务openclaw cron list # 以 JSON 格式获取一个已存储的任务openclaw cron get <jobId> # 显示一个任务，包括解析后的投递路由openclaw cron show <jobId> # 在不删除的情况下启用/禁用openclaw cron enable <jobId>openclaw cron disable <jobId> # 编辑任务openclaw cron edit <jobId> --message "更新后的提示词" --model "opus" # 立即强制运行任务openclaw cron run <jobId> # 立即强制运行任务并等待其最终状态openclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # 仅在到期时运行openclaw cron run <jobId> --due # 查看运行历史openclaw cron runs --id <jobId> --limit 50 # 查看一次特定运行openclaw cron runs --id <jobId> --run-id <runId> # 删除任务openclaw cron remove <jobId> # 选择智能体（多智能体设置）openclaw cron create "0 6 * * *" "检查运维队列" --name "运维巡检" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

归档会话（通过 Control UI，或由操作员管理员调用方调用 sessions.patch { archived: true }）会禁用绑定到该会话的所有已启用 cron 任务：包括其隔离的 cron:<jobId> 会话、session:<key> 目标，或投递/唤醒 sessionKey 通道。恢复会话不会重新启用这些任务；请使用 openclaw cron enable <jobId>。绑定了已启用任务的会话会在 Control UI 侧边栏中显示时钟徽标。

openclaw cron run <jobId> 会在手动运行入队后返回。对于关闭钩子、维护脚本或其他必须阻塞至队列中的运行完成的自动化，请使用 --wait；它会轮询返回的 runId（默认超时为 10m，轮询间隔为 2s），状态为 ok 时以 0 退出，状态为 error、skipped 或等待超时时以非零值退出。

智能体的 cron 工具通过 cron(action: "list") 返回精简任务摘要（id、name、enabled、nextRunAtMs、scheduleKind、lastRunStatus）；使用 cron(action: "get", jobId: "...") 获取一个任务的完整定义。直接调用 Gateway 网关的调用方可以向 cron.list 传递 compact: true；省略该参数则保留包含投递预览的完整响应。

openclaw cron create 是 openclaw cron add 的别名。新任务可以使用位置式计划（"0 9 * * 1"、"every 1h"、"20m" 或 ISO 时间戳），后跟位置式智能体提示词。在 cron add|create 或 cron edit 上使用 --webhook <url>，可将已完成运行的载荷 POST 到 HTTP 端点；Webhook 投递不能与聊天投递标志（--announce、--channel、--to、--thread-id、--account）组合使用。在 cron edit 上，--clear-channel、--clear-to、--clear-thread-id 和 --clear-account 会分别清除对应的路由字段（每个标志均不能与其对应的设置标志同时使用）——这与 --no-deliver 不同，后者只禁用运行器的回退投递。

Webhooks

Gateway 网关可以公开 HTTP Webhook 端点供外部触发器使用。在配置中启用：

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

身份验证

每个请求都必须通过请求头包含钩子令牌：

• 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":"收到新邮件","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"汇总收件箱","name":"电子邮件","model":"openai/gpt-5.6-sol"}'

Gmail Pub/Sub 集成

通过 Google Pub/Sub 将 Gmail 收件箱触发器连接到 OpenClaw。

向导设置（推荐）

openclaw webhooks gmail setup --account openclaw@gmail.com

此命令会写入 hooks.gmail 配置、启用 Gmail 预设，并默认使用 Tailscale Funnel 作为推送端点（--tailscale funnel|serve|off）。

Gateway 网关自动启动

当设置了 hooks.enabled=true 和 hooks.gmail.account 时，Gateway 网关会在启动时运行 gog gmail watch serve，并自动续订监视。设置 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:gmail-api-push@system.gserviceaccount.com \  --role=roles/pubsub.publisher

gog gmail watch start \  --account openclaw@gmail.com \  --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",    },  },}

配置

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

上述 retry 值为默认值：最多重试 3 次，退避时间为 30s/60s/5m，并对全部五类暂时性错误进行重试。cron Webhook POST 请求会将 webhookToken 作为 Authorization: Bearer <token> 发送。

maxConcurrentRuns 同时限制计划 cron 调度和隔离智能体轮次执行，默认值为 8。隔离的 cron 智能体轮次在内部使用队列专用的 cron-nested 执行通道，因此提高此值可以让相互独立的 cron LLM 运行并行推进，而不是仅启动其外层 cron 包装器。此设置不会扩大共享的非 cron nested 通道。

cron.store 是逻辑存储键和 Doctor 迁移路径，不是可手动编辑的实时 JSON 文件。任务数据存储在 SQLite 中；请使用 CLI 或 Gateway 网关 API 进行更改。

禁用 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 — 主会话的周期性轮次
• 时区 — 时区配置