OpenClaw 定时任务完全教程｜Cron + Heartbeat 双机制实现 7×24 小时自动化

1. 为什么你的 OpenClaw 定时任务总是“差一口气”很多人第一次接触 OpenClaw 的自动化能力都是冲着“让 AI 自己干活”来的。但真正跑起来才发现事情没那么简单想让 AI 每天早上九点准时发日报结果它要么没动静要么在错误的时间点触发想让它每隔几分钟检查一次服务状态结果它在你发消息的时候才“顺便”看一眼。问题的根源在于OpenClaw 其实提供了两套完全不同的主动任务机制——Cron 定时任务和 Heartbeat 心跳机制它们各自解决不同的问题但很多人只用了其中一套或者把两套混在一起用错了场景。这篇教程要解决的就是这个问题。我会从零开始把 Cron 和 Heartbeat 的配置路径、触发逻辑、验证方法、排障手段全部拆开讲清楚最后给出一套可以直接复制的 config.toml 骨架以及通过 TaoToken 统一 Key 接入模型通道的配置方式。适合谁看如果你需要让 OpenClaw 在无人值守的情况下持续运行定时任务比如每天定时推送、周期性巡检、延迟提醒那这篇就是为你写的。读完你至少能做到三件事第一搞清楚什么任务该用 Cron、什么任务该用 Heartbeat第二写出可运行的配置文件并验证触发第三遇到任务不执行时知道从哪里查起。2. TaoToken 前置先把模型通道和 Key 准备好在配置定时任务之前有一个容易被忽略但非常关键的前置步骤模型通道。OpenClaw 的 Cron 和 Heartbeat 在执行任务时本质上都是调用 Agent 去完成某个动作而 Agent 需要模型来推理和生成内容。如果你的模型通道不稳定定时任务就会时灵时不灵排查起来非常痛苦。我建议的做法是把 OpenClaw 的模型调用统一走 TaoToken 的 API 通道。这样做的好处是一个 Key 可以覆盖多个模型不用在配置文件里到处填不同厂商的密钥而且通道本身做了兼容处理OpenClaw 的 OpenAI 兼容接口可以直接对接。具体操作分两步。第一步去 TaoToken 控制台创建一个 API Key。打开 https://taotoken.net/api-keys 这个地址登录后新建一个 Key复制出来备用。注意 Key 只在创建时显示一次记得先存到安全的地方。第二步在 OpenClaw 的配置里把模型通道指向 TaoToken。OpenClaw 的模型配置通常写在~/.openclaw/openclaw.json或者你自定义的 config.toml 里。核心是设置base_url和api_key两个字段。base_url 填https://taotoken.net/apiapi_key 填你刚才创建的那个 Key。模型名称按 TaoToken 文档里支持的写比如claude-sonnet-4-20250514或者gpt-4o这类。这里有个细节要注意OpenClaw 的 Cron 任务在触发时如果模型通道返回 401 或 429任务会直接失败而且默认不重试。所以建议在正式配置定时任务之前先用openclaw agent run手动跑一次确认模型通道是通的。手动跑通之后再挂到 Cron 或 Heartbeat 上能省掉很多“任务不执行”的误判。如果你还没有 TaoToken 账号可以从官网入口进去注册https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册完成后API Key 的管理页面在控制台里路径是 https://taotoken.net/console 。3. 可复制配置Cron Heartbeat 双机制 config.toml 骨架下面这份配置骨架是我在实际项目里反复调整后留下来的版本你可以直接复制到自己的 config.toml 里然后按需改任务名和命令。为了让你看得清楚我把 Cron 和 Heartbeat 分成两个区块来写。# ~/.openclaw/config.toml # OpenClaw 定时任务配置骨架 # 模型通道统一走 TaoToken [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 default_model claude-sonnet-4-20250514 # ---------- Cron 定时任务 ---------- [[cron]] id daily_report schedule 0 1 * * * # UTC 1:00 北京时间 9:00 command openclaw agent run reporter --message 生成今日日报并推送 enabled true timeout 120 [[cron]] id hourly_health_check schedule 0 * * * * # 每小时整点 command openclaw agent run ops --message 检查服务健康状态 enabled true timeout 60 [[cron]] id weekly_cleanup schedule 0 2 * * 0 # 每周日 UTC 2:00 command openclaw agent run ops --message 清理临时文件和过期日志 enabled true timeout 300 # ---------- Heartbeat 心跳机制 ---------- [agents.monitor.heartbeat] every 10m # 每 10 分钟一次 target last # 结果发回最近会话 task openclaw agent run monitor --message 检查服务器负载超过阈值则告警 timeout 30s onError log [agents.assistant.heartbeat] every 30m target none # 只执行不主动发消息 task openclaw agent run assistant --message 同步外部数据到记忆系统 timeout 20s onError ignore这份配置里有几个点需要你特别注意。第一Cron 的 schedule 字段用的是 UTC 时间不是本地时间。如果你在北京想让它早上 9 点执行表达式要写0 1 * * *因为北京时间减 8 小时就是 UTC 1:00。第二Heartbeat 的every字段支持5m、30m、1h这种写法但不要写0.5h它不认小数。第三target last表示把心跳任务的结果发回最近一次跟这个 Agent 对话的渠道如果你不想让它主动发消息就设成none。改完配置后需要重启 Gateway 让 Cron 任务生效openclaw gateway restartHeartbeat 的配置是跟着 Agent 走的重启后会自动加载。你可以用openclaw cron list确认 Cron 任务已经注册进去。4. 验证请求怎么确认双机制真的在跑配置写完不代表任务就在跑。我见过太多人改完配置就等着收消息结果等了一天什么都没发生。下面这套验证流程建议你每次新增任务后都走一遍。4.1 验证 Cron 任务是否注册成功openclaw cron list正常输出会列出所有已注册的 Cron 任务包括 id、schedule、状态。如果你看到某个任务状态是disabled说明配置里的enabled没写对或者被之前的 disable 命令关掉了。用openclaw cron enable task-id重新打开。4.2 手动触发一次 Cron 任务不要等实际时间点直接用 run 命令立即执行openclaw cron run daily_report这条命令会立刻触发一次daily_report任务相当于跳过时间判断直接跑。如果任务本身有问题比如模型通道不通、命令写错这里就会报出来。跑通之后再等真实时间点验证。4.3 查看 Cron 执行历史openclaw cron history输出里会显示每个任务最近一次执行的时间和状态。如果状态是Failed后面通常会跟一个原因比如timeout或者model_error。这一步是排查定时任务最直接的入口。4.4 验证 Heartbeat 是否触发Heartbeat 没有像 Cron 那样的 history 命令它的执行记录写在 Gateway 日志里。你可以这样过滤openclaw logs --agent monitor | grep heartbeat如果看到类似heartbeat task executed的日志行说明心跳在正常跑。如果日志里完全没有 heartbeat 相关记录检查两个地方一是 Agent 是否处于空闲状态如果一直有用户消息进来心跳会被推迟二是idleTimeout配置是否太短导致 Agent 在心跳触发前就休眠了。4.5 端到端验证让任务真的产生结果最可靠的验证方式是让任务产生一个你能看到的结果。比如把daily_report的 command 临时改成openclaw agent run reporter --message 回复定时任务测试成功然后手动 run 一次看目标渠道有没有收到这条消息。收到就说明整条链路是通的再把 command 改回正式内容。5. 本篇常见错排查任务不执行、重复执行、时间不对5.1 Cron 任务到点没执行先查时区。OpenClaw 的 Cron 默认用 UTC如果你按本地时间写了表达式就会差 8 小时。比如你想北京时间 9 点跑写了0 9 * * *实际会在北京时间 17 点才触发。解决办法是把表达式改成0 1 * * *或者在命令内部做时间转换。再查 Gateway 是否在运行。Cron 任务依赖 Gateway 进程如果 Gateway 挂了任务自然不会触发。用openclaw gateway status确认进程状态。最后查任务是否被禁用。openclaw cron list里看状态如果是 disabled用 enable 命令打开。5.2 Heartbeat 不触发或者触发间隔不对Heartbeat 的触发依赖 Agent 进入空闲循环。如果你一直在跟这个 Agent 对话它永远不空闲心跳就不会执行。这是设计如此不是 bug。解决办法是给心跳任务单独分配一个 Agent不要跟日常对话的 Agent 混用。另一个常见原因是every字段格式写错。它只接受5m、30m、1h这种整数加单位的形式写0.5h或者30min都可能不生效。统一用m和h两个单位。5.3 任务重复执行如果你在 config.toml 和 CLI 里都加了同一个任务或者配置文件里有两个相同 id 的 Cron 条目就会出现重复执行。检查cron数组确保每个 id 唯一。CLI 添加的任务和配置文件里的任务会合并所以不要两边都写。5.4 执行结果没收到Cron 任务本身不负责发消息它只是执行 command。如果你的 command 是openclaw agent run xxx --message ...那消息能不能发出去取决于 Agent 的 target 配置。Heartbeat 的target如果设成none就只执行不发消息。检查 target 设置确认目标渠道可用。5.5 模型通道报错导致任务失败如果openclaw cron history里看到model_error或者401说明 TaoToken 的 Key 有问题。检查 Key 是否过期、额度是否用完、base_url 是否写成了https://taotoken.net/api注意不要多加斜杠或者路径。可以在 https://taotoken.net/api-keys 重新生成一个 Key 替换上去。6. 语义一致 CTA把通道和任务管理收拢到一处定时任务跑起来之后你会发现真正需要长期维护的其实是两件事模型通道的稳定性和任务本身的管理。模型通道这边我建议把 TaoToken 的 Key 和接入配置固定下来不要频繁换。OpenClaw 的接入文档在 https://taotoken.net/doc 里有完整的参数说明包括 base_url、模型名称映射、错误码含义遇到通道问题时先查文档比盲目试错快得多。任务管理这边Cron 适合精确时间点Heartbeat 适合固定间隔循环两者混用的时候注意不要让同一个 Agent 同时承担高频心跳和日常对话否则心跳会被消息打断。如果你后面要跑长期编码或者 Agent 类的任务可以考虑用 Coding Plan 把模型调用和任务编排放在一起管理入口在 https://taotoken.net/coding-plan 。验证模型是否正常响应可以直接在模型对话页面发一条测试消息地址是 https://taotoken.net/chat 。最后说一个我自己的习惯每次新增定时任务先手动 run 一次确认输出符合预期再挂到 Cron 或 Heartbeat 上。这个动作花不了两分钟但能帮你避开绝大多数“任务不执行”的坑。