1. OpenClaw 里 Heartbeat 和 Cron 到底差在哪OpenClaw 的自动化能力本质上由两个文件驱动Cron.md和Heartbeat.md。很多人第一次接触会懵觉得都是定时执行随便挑一个用不就行了结果要么日报发得不准时要么报警邮件轰炸到想关掉。问题不在工具在于没搞清两者的触发模型完全不同。一句话概括Cron 是闹钟到点就响不管有没有事Heartbeat 是巡逻保安每隔一段时间出来转一圈看看有没有需要处理的事没事就回去继续睡。这个比喻我试过讲给好几个刚上手的朋友基本一遍就懂。Cron 属于时间驱动。你在Cron.md里写死一个时间表达式比如*/10 * * * *它就会雷打不动地每 10 分钟执行一次你指定的指令。它不关心当前系统状态、不关心有没有数据、不关心这件事现在做合不合适时间到了就干。这种死板恰恰是它的价值——需要精确准时的任务就得靠它。Heartbeat 属于周期检查加条件驱动。你在Heartbeat.md里定义检查频率比如every 30m再写一段判断逻辑。它每 30 分钟醒一次先看状态、看待办、看日志判断现在有没有事要做。有事才干活没事就跳过。它保证的是响应及时而不是执行准时。适合谁用如果你要搭的是固定时间的报表推送、定时备份、周期性内容生成Cron 是首选。如果你要的是服务保活、异常监控、待办队列处理、主动感知变化Heartbeat 更合适。两者不是替代关系而是配合关系Heartbeat 负责兜底保命和智能巡逻Cron 负责准时打卡。下面这张对照表可以先存下来选型时对着看特性Cron定时任务Heartbeat心跳检测触发机制时间驱动严格遵守时间表周期检查 条件驱动执行逻辑时间到 → 强制执行指令时间到 → 检查状态 → 有事才做配置文件Cron.mdHeartbeat.md典型比喻闹钟设了 7 点必响保安巡逻发现门没关才报警适用场景固定报表、备份、定时推送监控异常、处理积压、保活精确性精确到分钟级不保证精确时刻只保证周期内响应理解了这张表后面的配置和排障就顺了。接下来先讲前置准备再给可复制的配置片段。2. 前置准备TaoToken 接入与 OpenClaw 环境确认OpenClaw 的自动化任务里很多动作需要调用大模型比如生成故事、总结日志、判断异常。所以你得先有一个稳定的模型接入通道。我用的是 TaoToken它的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的调用方式配置起来不折腾。第一步拿到 API Key。打开https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_heartbeat_cronutm_campaignrewrite在控制台里创建一个新的 Key复制保存好。这个 Key 后面要写进 OpenClaw 的配置里别弄丢。第二步确认你要用的模型 ID。TaoToken 支持多种模型具体在模型对话页面能看到当前可用的列表https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_heartbeat_cronutm_campaignrewrite。选一个你常用的比如claude-sonnet-4-5或者gpt-4o记下它的 Model ID。第三步确认 OpenClaw 的安装目录。通常配置文件在项目根目录下的config/或者直接放在根目录。你要找到Cron.md和Heartbeat.md这两个文件的位置。如果还没有就手动创建。第四步把 TaoToken 的接入信息写进 OpenClaw 的环境配置。一般是在.env文件或者settings.json里。下面是一个可复制的 JSON 片段路径按你实际项目调整{ openclaw: { model_provider: { base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model_id: claude-sonnet-4-5 }, automation: { cron_file: ./Cron.md, heartbeat_file: ./Heartbeat.md, log_dir: ./logs } } }注意base_url后面不要加多余的斜杠api_key用你刚创建的那串。model_id必须和 TaoToken 控制台里显示的完全一致大小写敏感。如果你用的是 TOML 格式的配置等价写法是这样[openclaw.model_provider] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model_id claude-sonnet-4-5 [openclaw.automation] cron_file ./Cron.md heartbeat_file ./Heartbeat.md log_dir ./logs配置写完后先别急着跑自动化任务。用一条最简单的请求验证接入是否通。打开终端执行curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 OK}] }如果返回里能看到choices字段和正常的回复内容说明接入没问题。如果报 401说明 Key 不对或者没带上如果报 model not found说明 Model ID 写错了。这两个错误后面排障章节会细讲。环境通了之后就可以开始写具体的自动化配置了。3. 可复制配置Cron.md 与 Heartbeat.md 写法这一节直接给能用的配置片段。你复制过去改改参数就能跑。先说Cron.md。它的核心是时间表达式加执行指令。OpenClaw 用的是标准 cron 语法五个字段分别代表分、时、日、月、周。下面是一个每 10 分钟生成一个故事并发邮件的配置# Cron.md ## 任务每10分钟生成故事并发送 - schedule: */10 * * * * - action: generate_story_and_send - prompt: | 请生成一个 200 字以内的短篇故事主题随机 风格轻松。生成后调用 send_email 工具发送到 storyexample.com。 - enabled: trueschedule就是时间表达式*/10 * * * *表示每 10 分钟。action是任务标识prompt是具体指令。enabled控制开关调试时可以设成 false 先不跑。再给一个每天凌晨 3 点备份数据库的配置# Cron.md ## 任务每日数据库备份 - schedule: 0 3 * * * - action: backup_database - command: | mysqldump -u root -p mydb /backup/mydb_$(date %Y%m%d).sql - enabled: true注意0 3 * * *表示每天 3:00 整执行。这种固定时间的任务Cron 是最合适的。然后是Heartbeat.md。它的核心是检查频率加判断逻辑。下面是一个每 30 分钟检查错误日志、有新错误才通知的配置# Heartbeat.md ## 检查错误日志监控 - interval: 30m - check: | 读取 /logs/error.log 的最后 100 行 对比上次检查的位置判断是否有新增的 ERROR 级别日志。 - condition: 存在新增 ERROR 日志 - action: | 调用 send_notification 工具把新增的错误内容 发送到运维群。 - enabled: trueinterval是检查周期check是检查逻辑condition是触发条件action是满足条件后执行的动作。如果条件不满足这次心跳就什么都不做直接结束。再给一个服务保活的配置# Heartbeat.md ## 检查AI 服务保活 - interval: 5m - check: | 执行 ps aux | grep ai_service检查进程是否存在。 - condition: 进程不存在 - action: | 执行 systemctl restart ai_service 并发送通知告知已重启。 - enabled: true这个每 5 分钟检查一次进程在就跳过不在就重启。这就是 Heartbeat 最原始也最实用的功能。如果你用的是 Cline MCP 或者 Codex 的auth.json方式接入配置结构会略有不同但核心三件套不变Base URL 填https://taotoken.net/apiKey 填你的 TaoToken 密钥Model ID 填控制台里选的模型。这三样缺一不可写错任何一个都会导致调用失败。配置写完后保存文件重启 OpenClaw 的自动化服务让它重新加载配置。接下来就是验证行为差异。4. 验证请求用日志和执行记录看两者行为差异配置写完不代表就对了得用日志验证。OpenClaw 会把每次 Cron 和 Heartbeat 的执行记录写到logs/目录下通常是cron.log和heartbeat.log两个文件。先看 Cron 的日志。执行tail -f logs/cron.log你会看到类似这样的输出[2025-01-15 09:00:00] CRON taskgenerate_story_and_send statusstarted [2025-01-15 09:00:03] CRON taskgenerate_story_and_send statuscompleted duration3.2s [2025-01-15 09:10:00] CRON taskgenerate_story_and_send statusstarted [2025-01-15 09:10:04] CRON taskgenerate_story_and_send statuscompleted duration4.1s注意时间戳每次都是整 10 分钟09:00、09:10、09:20非常规律。不管有没有新数据它都会执行。这就是时间驱动的特征。再看 Heartbeat 的日志tail -f logs/heartbeat.log输出会是这样[2025-01-15 09:00:00] HEARTBEAT checkerror_log_monitor statuschecking [2025-01-15 09:00:01] HEARTBEAT checkerror_log_monitor resultno_new_error actionskipped [2025-01-15 09:30:00] HEARTBEAT checkerror_log_monitor statuschecking [2025-01-15 09:30:02] HEARTBEAT checkerror_log_monitor resultnew_error_found actionexecuted [2025-01-15 09:30:05] HEARTBEAT checkerror_log_monitor statusnotification_sent关键看result和action字段。09:00 那次检查结果是no_new_error动作是skipped也就是什么都没做。09:30 那次发现了新错误动作是executed然后发了通知。这就是条件驱动的特征——不是每次都干活而是判断后才决定。你可以故意制造一个错误来验证。往/logs/error.log里追加一行echo [ERROR] test error at $(date) /logs/error.log然后等下一个心跳周期看日志里是否出现new_error_found和notification_sent。如果出现了说明 Heartbeat 的判断逻辑正常工作。再验证 Cron 的准时性。把Cron.md里的 schedule 改成*/1 * * * *也就是每分钟执行一次然后观察cron.log的时间戳是否严格每分钟一次。这个测试能直观感受到 Cron 的死板。两个日志对比着看差异就非常明显了Cron 的日志是等间隔的、每次都执行Heartbeat 的日志是等间隔检查、但执行与否取决于条件。5. 常见错误排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易撞上几个报错。这一节按真实报错信息来排查。401 Unauthorized。这个最常见通常是 API Key 的问题。检查三处一是settings.json或.env里的api_key是否填了完整的 Key有没有多余空格二是请求头里Authorization: Bearer sk-xxx格式对不对Bearer和 Key 之间有一个空格三是 Key 是否被禁用或过期去 TaoToken 控制台确认一下。如果 Key 没问题检查base_url是不是写成了https://taotoken.net/api/带了尾部斜杠有些客户端会因此拼出双斜杠导致鉴权失败。local proxy failed。这个报错说明 OpenClaw 在尝试走本地代理但代理没起来或者端口不对。检查你的环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个不存在的本地端口。如果有临时取消掉unset HTTP_PROXY unset HTTPS_PROXY然后重启 OpenClaw。另外确认base_url直接写的是https://taotoken.net/api不要经过任何中间层。reading choices 相关报错比如cannot read property choices of undefined或者reading choices failed。这通常说明请求发出去了但返回体结构不对解析不到choices字段。原因可能是 Model ID 写错了服务端返回了错误信息而不是正常的 completion 结构。去 TaoToken 的模型对话页面确认当前可用的 Model ID然后改配置里的model_id。还有一种可能是请求体格式不对比如messages数组为空或者model字段拼写错误。OAuth 相关报错比如OAuth token expired或invalid_grant。如果你用的是 Claude Code 或者 Codex 的 OAuth 方式接入token 过期是正常的需要重新授权。但如果你用的是 TaoToken 的 API Key 方式就不应该出现 OAuth 报错。检查配置里是不是混用了两种鉴权方式把 OAuth 相关的字段删掉统一用api_key。排查时有个通用技巧把 OpenClaw 的日志级别调到 debug能看到完整的请求和响应体。在配置里加{ openclaw: { log_level: debug } }然后重新跑一次任务看日志里打印的请求 URL、请求头、请求体、响应体。大部分问题看一眼请求 URL 和响应体就能定位。还有一个容易忽略的点Cron 和 Heartbeat 的配置文件路径。如果cron_file或heartbeat_file指向的路径不对OpenClaw 会静默跳过日志里什么都不写。确认路径是相对于项目根目录的或者用绝对路径。6. 选型建议与接入入口回到最初的问题什么时候用 Cron什么时候用 Heartbeat。我的判断标准很简单——问自己一句这件事需不需要判断。不需要判断、时间到了就必须干的用 Cron。日报推送、定时备份、周期性内容生成、会议提醒这些都是。它们的共同点是执行动作本身就是目的不需要前置条件。需要判断、有事才干的用 Heartbeat。服务保活、异常监控、待办处理、主动感知这些都是。它们的共同点是检查状态是前置步骤只有满足条件才触发动作。最容易踩的坑有两个。一是用 Heartbeat 做每天 9 点发日报结果它可能 9:00 检查也可能 9:30 检查发出来的时间不固定。二是用 Cron 做CPU 高了就报警结果它不管 CPU 高不高每到时间就发一封造成信息轰炸。记住Cron 负责准时打卡Heartbeat 负责智能巡逻和兜底保命。最佳实践是两者配合。Heartbeat 确保服务活着、异常能被发现Cron 确保固定任务准时跑。比如你可以用 Heartbeat 每 5 分钟检查 AI 服务进程挂了就重启同时用 Cron 每天 9 点推送昨日总结。两个文件各管一摊互不干扰。如果你还没接入模型通道先去 TaoToken 拿 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_heartbeat_cronutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_heartbeat_cronutm_campaignrewrite里面有各语言的调用示例。想先试试模型效果可以去模型对话页面直接聊两句https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_heartbeat_cronutm_campaignrewrite。如果你要长期跑编码类或 Agent 类任务Coding Plan 会更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_heartbeat_cronutm_campaignrewrite。配置写完后先跑一轮验证看日志确认行为符合预期再放开enabled正式启用。这样能避免配置错误导致的任务堆积或误报。