定时任务

Cron 是 Gateway 网关的内置调度器。它会持久保存任务，在正确的时间唤醒智能体，并可将输出传送到聊天渠道、webhook，或不传送到任何位置。

快速开始

openclaw cron create "2027-02-01T16:00:00Z" \  --name "Reminder" \  --session main \  --system-event "提醒：检查 cron 文档草稿" \  --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: "调查 CI 状态变化。" },}

脚本必须返回 { 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 "响应 CI 状态变化" \  --session isolated

载荷

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

智能体轮次选项

--model 设置任务的主模型；它不会替换会话的 /model 覆盖，因此已配置的后备链仍会在其基础上应用。无法解析或不允许使用的模型会使运行因明确的验证错误而失败，而不会静默回退到默认模型。如果任务具有 --model，但没有显式或已配置的后备列表，OpenClaw 会传入空的后备覆盖，而不会静默地将智能体主模型追加为隐藏的重试目标。

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

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

快速模式遵循解析后的实时选择。如果所选模型配置具有 params.fastMode，隔离 cron 默认使用该值；已存储的会话 fastMode 覆盖（其次是智能体 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 历史记录中记录运行，并复用与智能体轮次任务相同的 announce、webhook 和 none 交付模式。

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> 存储 argv: ["sh", "-lc", <shell>]。使用 --command-argv '["node","scripts/report.mjs"]' 可在不经 shell 解析的情况下精确执行 argv。可选的 --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 时，诸如 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、webhook 和 none 仅控制智能体轮次结束后运行器如何处理最终回复。

当智能体从活跃聊天创建隔离提醒时，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 网关的调用方可以将 compact: true 传给 cron.list；省略它会保留包含投递预览的完整响应。

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 PubSub 集成

通过 Google PubSub 将 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: "openai/gpt-5.6-sol",      thinking: "high",    },  },}

对于不受信任的收件箱，请使用提供商所提供的最新一代最高档模型。以上值仅为示例；该模型必须存在于已配置的目录和允许列表中。

配置

{  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",  },}

以上 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 — 定期执行的主会话轮次
• 时区 — 时区配置