定时任务

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 分钟，脚本载荷默认为 5 分钟。
• Gateway 网关启动时，逾期的隔离式智能体轮次任务会被重新调度，而不是立即重放，从而避免模型/工具的引导工作占用渠道连接窗口。
• 如果你通过系统 Cron 或其他外部调度器驱动 openclaw agent，即使 CLI 已处理 SIGTERM/SIGINT，也要用硬终止升级机制封装它。由 Gateway 网关支持的运行会请求 Gateway 网关中止已接受的运行；--local 运行也会收到相同的中止信号。对于 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 调度）。

Heartbeat 任务迁移

旧版 Heartbeat 临时配置支持结构化的 tasks: 块。升级后运行 openclaw doctor --fix，可将每个条目转换为普通的、可编辑的主会话 Cron 任务。Doctor 会保留时间间隔和上次运行时间，先创建任务再移除该块，并且重新运行时会安全地收敛相同的声明键。

这些迁移后的任务携带公开的 systemEvent 载荷，因此 openclaw cron list、get、edit 和 remove 以及 Cron 工具可以像管理其他任务一样管理它们。它们的执行使用受保护的 Heartbeat 任务唤醒机制：活动时段、最小间隔、防洪控制和忙碌重试仍然适用，而 Cron 负责每项任务的独立节奏。在同一合并窗口内到期的任务可以共享一个 Heartbeat 轮次。若计划执行时间位于 Heartbeat 活动时段之外，则会跳过该次执行，并在任务下一次到期时重试。

Heartbeat 临时配置现在仅作为监控说明文本。运行时 Heartbeat 不会将 tasks: 文本解析为调度；请使用 Cron 创建新的重复任务。

流数据源

流调度会在 Gateway 网关下持续运行由操作员编写的 argv 命令，并根据其 stdout 和 stderr 输出行触发任务。流调度由事件驱动，绝不会按时间到期触发，并且需要 cron.triggers.enabled: true，因为长期运行的命令与触发器脚本属于相同的无人值守信任类别。禁用或移除任务会停止该进程；Gateway 网关关闭时会等待进程树完成拆卸。快速失败会按照 Cron 的内置错误退避机制重启。若连续 5 次运行均短于 60 秒，任务将保持错误状态并使用常规失败提醒路径；手动重新启用任务可清除重启上限。

openclaw cron add \  --name "Build event stream" \  --stream-command '["node","scripts/build-events.mjs"]' \  --stream-mode match \  --stream-match '^(failed|recovered):' \  --stream-batch-ms 250 \  --session isolated \  --message "Investigate these build events."

mode: "line"（默认值）接受每一行。mode: "match" 仅接受与已编译的 match 正则表达式匹配的行。批次会在静默达到 batchMs 后关闭（默认 250 毫秒，限制在 50–5000 之间），或在达到 maxBatchBytes 时关闭（默认 16384，限制在 1024–65536 之间）。达到字节上限时，批次会以 [truncated] 结束。匹配模式始终根据完整文本计算完整的行，即使超过 maxBatchBytes 也是如此（只有交付的批次会被截断）；在有界原始输入上限处被截断的行只是一个前缀，因此会被视为不匹配，避免让以结尾锚定的模式在截断内容上触发。批次会追加到系统事件文本或智能体轮次消息中。流调度会拒绝命令载荷，因为源命令和载荷命令的进程所有权会产生歧义。

每项任务只保留一次载荷触发和一个有界待处理批次。载荷运行期间到达的行，或在内置的 30 秒触发间隔结束前到达的行，会合并到该待处理批次中，而不会形成无界队列。单一串行所有者会在 streamDroppedBatches 中记录门控丢弃、载荷错误和非运行状态的调度；有界合并会递增 streamCoalescedBatches。失败的载荷不会重试，因为它们可能不具备幂等性。逻辑源身份在受监管的子进程重启期间保持稳定，但在源被禁用、移除或替换时会轮换，因此即使进行 A 到 B 再到 A 的编辑，已退役源的排队批次也无法触发。停止完成后，旧子进程的延迟回调将不再生效。V1 不包含原生 WebSocket 数据源；可使用 argv 命令（例如 websocat wss://example.invalid/events）进行桥接。

当流任务还包含 trigger.script 时，门控会对每个已关闭的批次运行一次。当前批次作为深度冻结的 trigger.streamBatch 字符串与 trigger.state 一起提供。fire: false 会在持久化门控状态后丢弃该批次。fire: true 会保留现有的触发器消息语义，然后将该批次追加到生成的载荷中。流任务也可以改用不带条件门控的脚本载荷；该脚本通过相同的 trigger.streamBatch 值接收批次。脚本载荷不能与条件门控组合使用，因为二者都会占用持久化的 trigger.state 槽位。

动态节奏（速率控制）

重复任务可以将 pacing.min 和/或 pacing.max 设置为类似 15m 或 4h 的时长字符串；必须至少设置一个边界。将 --pacing-min 和 --pacing-max 与 cron add|edit 一起使用（--clear-pacing 会移除两个边界）。

在隔离运行期间，节奏调度任务可以使用 action: "next_check" 和 in: "30m" 调用 cron 工具。该提议仅适用于当前正在运行的任务，并从运行成功完成时开始计时。OpenClaw 会静默地将其限制在配置的边界内。

未提供提议的节奏调度不会更改正常计划。失败、超时和跳过的运行会丢弃该提议，因此现有的重试和错误退避行为优先。手动强制运行定时任务属于带外操作，会保留其待执行的自然或节奏调度时段。对于条件触发的任务，即使提议要求更早检查，内置最小间隔仍是下限。

月中日期和星期使用 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 或 stream 计划添加无界面条件脚本。时间计划会在到期时对其求值；流计划会对每个已关闭的批次进行求值。仅当脚本返回 fire: true 时，Cron 才运行正常载荷：

{  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 形式提供；流门控还会通过 trigger.streamBatch 接收当前批次。返回新的 state 值以将其持久化。状态上限为 16 KB。当触发结果包含 message 时，Cron 会在执行前将其附加到系统事件文本或智能体轮次消息中。once: true 会在首次成功执行已触发载荷后禁用该任务。

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

应围绕可操作状态编写监视器，而不应只关注成功：如果检查失败或超时时监视器悄无声息，它在故障时看起来仍然正常。将观察结果与 trigger.state 比较，并返回最新状态以进行去重；不要依赖模型或进程内存。触发时，应确保 message 自包含，因为它会成为已触发运行的完整事件上下文。

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

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

载荷

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

另有一种载荷类型 heartbeat 由系统所有：Gateway 网关会为每个启用了 Heartbeat 的智能体收敛为一个 Heartbeat 监控任务（参见 Heartbeat）。它会显示在 cron list --all 中，但无法通过 CLI 或 API 创建或编辑。启动、配置重新加载或执行 openclaw doctor --fix 时，Heartbeat 配置会直写到持久化的监控计划中。当 Cron 被禁用时，监控器不会触发，也不会运行备用 Heartbeat 计时器。

智能体轮次选项

能够运行工具的新任务始终存储显式工具策略。由智能体创建的任务 仅能使用创建该任务的轮次可用的工具，且智能体无法扩大 已存储的列表。由经过身份验证且未使用 --tools 的操作员创建的任务会存储 不受限制的 * 策略；cron edit --clear-tools 会恢复该显式不受限制 策略。早于显式工具策略而存在的任务会保留其当前行为， 直到显式编辑其工具策略或重新创建该任务。

--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 用于控制进程环境、标准输入和输出限制。

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

脚本载荷

脚本载荷会在与触发器脚本相同的代码模式执行器中以无头方式运行，不会启动对话式智能体轮次。创建或运行它们之前，请启用 cron.triggers.enabled；这一危险自动化门控同时涵盖触发器脚本和脚本载荷。脚本任务仅支持 main 和 isolated 会话目标。

openclaw cron create "0 * * * *" \  --name "Hourly queue check" \  --script ./automation/check-queue.js \  --script-timeout-seconds 300 \  --script-tool-budget 50 \  --session isolated \  --announce

使用 --script <file|-> 从文件或标准输入读取 JavaScript。超时时间默认为 300 秒，上限为 900 秒；工具预算默认为 50 次调用，上限为 200 次。这些载荷预算与更小的触发器门控评估预算相互独立。

脚本可以返回包含以下可选字段的对象：

• notify：通过任务的 announce、webhook 或 none 交付模式交付的文本。如果省略，则不交付任何内容。对于 main 任务，该文本会成为系统事件。
• wake："now" 请求在将 notify（或精简的完成事件）加入队列后立即触发一次 Heartbeat；"next-heartbeat" 则将该事件加入队列，供下一次 Heartbeat 处理。
• state：JSON 状态，上限为 16 KB，并且仅在成功运行后持久化。下一次运行会以 trigger.state 的形式接收其冻结副本，与触发器脚本一致。由于该命名空间只有一个持久化所有者，因此同一任务中的脚本载荷不能与条件触发器结合使用。
• nextCheck：持续时间，例如 "15m"。它仅适用于启用了节奏控制的任务，并使用与智能体轮次提案相同的节奏限制。

抛出异常、超时、工具预算耗尽、无效结果，以及未启用节奏控制时返回 nextCheck，都属于正常的定时任务运行错误：它们会进入运行历史记录、退避和失败警报处理流程，且不会持久化返回的状态。

执行方式

交付和输出

使用 --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 区分大小写；请使用 Matrix 提供的确切房间 ID 或 room:!room:server 形式。

当公告交付使用 channel: "last" 或省略 channel 时，像 telegram:123 这样的提供商前缀目标可以在定时任务回退到会话历史记录或唯一已配置渠道之前选择渠道。只有已加载插件声明的前缀才是提供商选择器。如果显式指定了 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 使任务或全局定时任务警报策略选择接收重复的已跳过运行警报。已跳过的运行使用单独的连续跳过计数器，因此不会影响执行错误退避。
• 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。

输出语言

定时任务不会根据渠道、区域设置或先前消息推断回复语言。请将语言规则写入定时消息或模板：

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

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

CLI 示例

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

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --tz "America/Los_Angeles" \  --session isolated \  --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

openclaw cron create "0 18 * * 1-5" \  "Summarize today's deploys as JSON." \  --name "Deploy digest" \  --webhook "https://example.invalid/openclaw/cron"

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

管理任务

# 列出已启用的任务openclaw cron list # 包含已禁用的任务openclaw cron list --all # 以 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:<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",    triggers: {      enabled: false,    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",  },}

webhookToken 会在 cron webhook POST 中作为 Authorization: Bearer <token> 发送。

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

相关内容

• 自动化 — 快速了解所有自动化机制
• 后台任务 — 定时任务执行的任务账本
• Heartbeat — 周期性的主会话轮次
• 时区 — 时区配置