OpenClaw 定时任务不执行？Cron、Heartbeat 与通知失败排查清单

本文按 2026-08-15 可见的官方英文文档复核。当前官方主术语和主命令是 Automations，openclaw cron 仍是同一命令面的兼容别名。操作前请同时核对 Automations、Heartbeat、Automations CLI 和 Sandboxing。命令、默认值和迁移方式可能随版本变化，以你安装版本的 --help 与官方文档为准。

先判断问题发生在哪一层

OpenClaw 的定时链路可以拆成三层：调度器决定何时到点，任务执行器负责真正运行，投递通道把结果送到聊天或 webhook。只看“手机没收到消息”无法判断是哪一层出错。

第一步：保存现场，再看任务和运行记录

先记录任务名称、任务 ID、预期触发时间、实际时区、最后一次正常时间和当前版本。然后只读查看任务定义、解析后的投递路由与运行历史。官方当前优先使用 openclaw automations；openclaw cron 仍是兼容别名。

openclaw status
openclaw gateway status
openclaw automations status
openclaw automations list
openclaw automations get <job-id>
openclaw automations show <job-id>
openclaw automations runs --id <job-id> --limit 20
openclaw system heartbeat last
openclaw automations --help

# 兼容别名仍可用
openclaw cron list

如果列表里有两个名字相似、时间相同的任务，重复推送可能来自重复配置；如果任务被禁用或时区与预期不同，先记录证据，再做单项修改。不要在尚未看清运行记录时删除任务，因为删除会让排错失去关键上下文。

第二步：确认 Gateway 与 Cron 调度器真的在运行

OpenClaw 的 Automations 调度器运行在 Gateway 进程中；Gateway 没有持续运行时，计划任务不会触发。计划 Heartbeat 的节拍也由 Automations 调度器管理：当 cron.enabled: false 或设置 OPENCLAW_SKIP_CRON=1 时，计划 Heartbeat 不会运行，且没有另一套独立计时器兜底；但手动唤醒和事件驱动唤醒仍可用。因此，“聊天页面还能打开”不能替代对 Gateway 与调度状态的检查。

• 确认 Gateway 在预期主机上运行，而不是只剩旧的浏览器页面。
• 确认 Cron 没被配置项或启动环境关闭。
• 确认任务启用状态、时区和下一次触发时间符合预期。
• 升级后如官方诊断提示迁移或修复，先阅读输出，再决定是否执行修复。

第三步：分清 Cron 与 Heartbeat

需要固定时间、独立启停状态或独立运行历史的工作，应创建为 Automation 任务。Heartbeat 更适合在主会话中执行周期检查；没有需要关注的事项时通常返回 HEARTBEAT_OK，这个确认默认不会向外显示。Heartbeat 的 monitor scratch 只是提示词上下文，不是调度器，运行时不会再把其中的 tasks: 文本解析为日程。旧版 scratch 含周期任务时，升级后应先阅读 openclaw doctor --fix 的迁移说明，再用任务列表确认它们已成为普通 Automation 任务。

第四步：有运行记录时，单独排查“执行”和“投递”

任务运行记录是分叉点。状态失败时，查看最早出现的错误，不要只看最后一行。常见原因包括数据源不可用、网络或沙箱限制、工具没有权限、提示词要求了不存在的文件，以及任务超过超时限制。状态成功但没有消息时，应转查投递模式、频道、收件人和路由诊断；Heartbeat 还可能只是返回了默认不展示的 HEARTBEAT_OK。

1. 确认任务的目标是主会话、隔离会话、指定频道还是 webhook。
2. 确认发送目标仍存在，机器人或账号仍有最小必要权限。
3. 用无敏感信息的测试内容做一次人工触发或等候下一次触发。
4. 把“任务执行成功”和“消息投递成功”分别记录，避免混为一谈。

第五步：检查 activeHours、忙碌队列与时间边界

Heartbeat 可通过 activeHours 限制运行窗口，并按配置的时区解析。窗口外的计划触发会被跳过，直到窗口内的下一个计划时刻。主队列或 Automation 工作繁忙、同一智能体正在回复或执行嵌入式运行，或者目标会话仍有活动或排队工作时，计划 Heartbeat 会被跳过并稍后重试。跨时区部署时，主机时区、用户时区和任务时区不一致，最容易制造“晚了八小时”的假故障。

第六步：检查沙箱与最小权限

OpenClaw 的工具沙箱默认关闭。启用后，exec、文件读写、编辑、进程等智能体工具，以及可选的沙箱浏览器，可以在配置的隔离后端中运行；workspaceAccess 决定工作区不可见、只读或读写，而 Gateway 进程本身仍留在主机上。需要特别区分：--session isolated 只隔离对话上下文，并不证明工具沙箱已启用；Automation 的 command payload 也直接在 Gateway 主机上执行。任务从交互会话移到隔离会话后若依赖未挂载文件或主机凭据，可能突然失败，但解决办法仍应是明确所需的最小数据和权限，而不是开放全盘访问。

• 优先读取公开数据；能不用账户 API 就不用。
• 需要凭据时使用可撤销、最小范围的凭据存储，不写入提示词。
• 通知任务不应同时拥有交易、提现或修改安全设置的权限。
• 官方文档警告条件触发脚本可在无人值守时执行代码；不理解权限影响时不要启用。

一套可重复的无资金验收

修复后不要立刻接入真实账户。建立一个仅使用公开数据的测试任务，并把触发间隔设为便于观察但不会刷屏的范围。验收时覆盖成功、失败、延迟和重复四种路径。

1. 创建带唯一标识的测试消息，记录任务 ID 和预期时间。
2. 等待正常触发，核对运行记录与收到的消息是否一一对应。
3. 临时使用一个明确无效的公开测试地址，确认失败被记录而不是静默吞掉。
4. 恢复有效地址，确认系统不会把旧失败无限补发。
5. 重启 Gateway 后再观察一次，确认任务和运行历史仍可追踪。
6. 最后删除测试数据前，先保留验收结果和必要截图。

排错记录模板

任务 ID：
任务类型：Cron / Heartbeat
预期时间与时区：
实际运行时间：
运行状态：
投递状态：
第一条错误：
本次只修改了什么：
复测结果：
是否可安全恢复：

常见问题

任务显示成功，为什么 Telegram 还是没消息？

成功可能只代表任务主体执行完成。继续查投递目标、机器人权限、目标会话和运行记录中的投递诊断，不要直接重建调度。

Heartbeat 没有每 30 分钟都发消息，是不是坏了？

不一定。正常情况下它可以在没有需要提醒的内容时保持安静；活跃时段、忙碌状态和目标设置也会影响可见消息。判断是否运行要看配置与记录，而不是只数聊天消息。

可以把间隔改成几秒来压测吗？

生产环境不建议。过密任务会制造队列、费用和刷屏风险，也会让重复与延迟更难判断。先在隔离的测试任务上选择温和间隔，并设定停止条件。

结论：先定位层级，再做单项修改

稳定的排错顺序是：保存现场 → 看任务定义 → 看运行记录 → 确认 Gateway 与 Cron → 区分执行和投递 → 核对 Heartbeat、时区和活跃时段 → 检查沙箱与权限 → 做无资金复测。每次只改一个变量，才能知道修复是否真的有效。

参考资料

• OpenClaw：Automations 与故障排查
• OpenClaw：Heartbeat
• OpenClaw：Automations CLI（Cron 兼容命令）
• OpenClaw：Sandboxing
• OpenClaw：Sandbox、Tool policy 与 Elevated 的区别
• 站内延伸：公告与链上异动分级预警
• 站内延伸：AI 输出复核方法

首次发布：2026 年 8 月 13 日 · 最近实质更新：2026 年 8 月 15 日 · 如官方机制更新，以官方文档为准。