OpenClaw从入门到应用——自动化故障排除：cron 与 heartbeat 失效的排查路径

1. OpenClaw 自动化任务不触发？先分清 cron 与 heartbeat 两条链路

OpenClaw 的自动化能力，本质上由两条独立的链路支撑：一条是 cron 调度器，负责在指定时间点唤醒任务；另一条是 heartbeat 心跳，负责在空闲周期里主动检查有没有待办事项。很多人本地部署完 OpenClaw 之后，发现"任务该跑的时候没跑""心跳日志突然断了"，第一反应是去翻业务代码，其实绝大多数问题都出在这两条链路的配置或状态上，跟业务逻辑没关系。

这篇内容面向的是已经在本地把 OpenClaw 跑起来、但自动化流程时好时坏的人。如果你还没部署，建议先把 gateway 跑通再回来看。下面我会按"先看全局状态 → 再查 cron → 再查 heartbeat → 最后核对时区"的顺序，把每一步的命令、正常输出长什么样、异常特征怎么读，全部拆开讲清楚。你可以直接复制命令跟着敲，边敲边对照自己的输出。

需要先建立一个认知：cron 和 heartbeat 是解耦的。cron 到点触发一次任务，heartbeat 按间隔轮询一次状态。cron 没触发不代表 heartbeat 坏了，heartbeat 被跳过也不代表 cron 停了。排查时一定要分开定位，否则很容易在错误的方向上浪费时间。我见过有人因为 heartbeat 日志里出现 skipped，就去改 cron 表达式，结果越改越乱。

另外提醒一句，OpenClaw 的很多"没反应"其实是"静默跳过"——任务确实被调度了，但因为交付模式是 none、或者目标通道没连上，所以外部看不到任何消息。这种情况日志里往往有明确原因，只是你没去看。所以排查的核心动作只有一个：让日志说话。下面所有步骤都围绕这个原则展开。

2. TaoToken 前置准备：把模型调用链路先打通

在深入排查 cron 和 heartbeat 之前，有一个容易被忽略的前提：OpenClaw 的自动化任务在触发后，往往需要调用大模型来完成实际工作（比如总结、生成、判断）。如果模型调用链路本身是断的，你会看到任务"触发了但没结果"，误以为是调度问题。所以建议先把模型接入这一层确认好。

我自己的做法是统一走 TaoToken 的 API 网关来管理模型调用，这样 Base URL、Key、Model ID 三件套集中配置，排查时只需要确认一处。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api （这个不加 UTM）。注册后在控制台生成 Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

拿到 Key 之后，OpenClaw 的模型配置通常写在 settings 或环境变量里。以常见的 JSON 配置为例，你需要保证三个字段对齐：

{ "model": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "modelId": "claude-sonnet-4-5" } }

这里有个坑：baseUrl 结尾不要多加/v1，也不要漏掉协议头。很多人复制的时候带上了多余路径，导致请求 404，然后误判成 cron 没触发。Model ID 要和你实际想用的模型一致，写错了会返回 model not found。如果你用的是 Claude Code 这类工具做编码辅助，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的 Base URL + Key + Model ID 对照。

配置改完记得重启 gateway，否则旧配置还在内存里。重启命令一般是：

openclaw gateway restart openclaw status

openclaw status输出里如果能看到 gateway 处于 running、模型 provider 显示已加载，说明前置链路没问题，可以进入下一步排查调度器了。如果这一步就报错，先解决模型接入，别往下走。

3. 可复制配置：cron 与 heartbeat 的关键字段怎么写

排查之前，先把配置写对。OpenClaw 的 cron 和 heartbeat 配置分散在几个地方，我整理了一份可以直接抄的片段，你对照自己的配置文件改。

cron 作业的配置一般长这样，注意schedule、timezone、delivery三个字段：

[[cron.jobs]] id = "daily-report" enabled = true schedule = "0 9 * * *" timezone = "Asia/Shanghai" command = "report.generate" delivery = "channel" channel = "feishu" to = "ops-group"

schedule是标准五段式 cron 表达式，timezone不写就默认用网关主机时区。delivery = "none"表示只内部执行不外发，如果你期望收到消息却写了 none，那就是"触发了但没交付"的典型原因。channel和to必须和实际通道配置对得上，写错了会静默跳过外发。

heartbeat 的配置在 agents.defaults 下面：

[agents.defaults.heartbeat] enabled = true interval = "30m" activeHours = "09:00-22:00" activeHours.timezone = "Asia/Shanghai"

interval不能为 0，为 0 等于关闭。activeHours之外的时间心跳会被跳过，日志里会写reason=quiet-hours。如果你希望 24 小时都跑，就把 activeHours 去掉或者设成00:00-23:59。

时区这块单独强调一下，因为它是最高频的坑。agents.defaults.userTimezone如果没设置，心跳会回退到主机时区；cron 不带--tz时也用网关主机时区；而 cron 的at计划里如果写了不带时区的 ISO 时间戳，会被当成 UTC 处理。这三条规则不一致，就会出现"我明明设了 9 点，结果下午 5 点才跑"的现象。建议显式写死activeHours.timezone和 cron 的timezone，别依赖默认值。

配置改完，用openclaw config get逐项确认，别只看文件：

openclaw config get agents.defaults.heartbeat openclaw config get agents.defaults.heartbeat.activeHours openclaw config get agents.defaults.heartbeat.activeHours.timezone openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"

最后一条如果输出Config path not found: agents.defaults.userTimezone，说明这个键没设，属于正常提示，不是报错，心跳会走回退逻辑。

4. 验证请求：用命令阶梯确认 cron 与 heartbeat 真的在跑

配置写对只是第一步，接下来要用命令验证运行时状态。我习惯按一个固定阶梯走，从全局到局部，避免漏项。

先看全局：

openclaw status openclaw gateway status openclaw doctor openclaw channels status --probe

openclaw doctor会做一轮自检，把明显的问题直接列出来，比如配置缺失、通道未连接。channels status --probe会实际探测通道连通性，这一步很关键，因为交付失败往往卡在通道上。

然后专门查 cron：

openclaw cron status openclaw cron list openclaw cron runs --id daily-report --limit 20 openclaw logs --follow

cron status正常应该报告 scheduler 已启用，并且有一个未来的nextWakeAtMs。如果看到cron: scheduler disabled; jobs will not run automatically，说明 cron 在配置或环境里被禁用了，去检查cron.enabled相关字段。如果看到cron: timer tick failed，那是调度器滴答崩溃，要翻它前后的堆栈日志。cron runs里每条记录应该是ok，或者有明确的跳过原因，比如reason: not-due——这表示你手动触发了但作业还没到期，加--force才能强制执行。

再查 heartbeat：

openclaw system heartbeat last openclaw logs --follow

正常输出里心跳应该是ran，或者跳过原因你能看懂。常见的跳过原因有四个：quiet-hours表示超出 activeHours；requests-in-flight表示主通道忙、心跳被推迟；empty-heartbeat-file表示 HEARTBEAT.md 没有可操作内容且没有排队的标记事件；alerts-disabled表示可见性设置把外发消息压掉了。这四个都不是故障，是设计行为，理解清楚就不会误判。

验证模型调用是否通，可以顺手在模型对话页发一条测试消息，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，能正常返回就说明模型链路没问题，问题一定在调度或交付层。

5. 本篇常见错排查：401、local proxy failed、reading choices 逐个击破

排查过程中你会遇到一些具体报错，我把最高频的几个列出来，对照处理。

401 Unauthorized / missing_scope / Forbidden：这类是通道认证或模型 Key 的问题。先确认 TaoToken 的 Key 有没有过期、额度是否充足，再去openclaw channels status --probe看通道凭据。通道的 token 和模型的 Key 是两套东西，别搞混。401 出现在模型调用里，就去 api-keys 页面重新生成；出现在通道交付里，就去通道配置里更新凭据。

local proxy failed：这个通常出现在网络出口配置上。检查你的 gateway 是否能正常访问外部 API，openclaw doctor一般会给出提示。如果是本地代理配置问题，确认代理地址和端口写对，且代理服务本身在运行。注意不要配置来源不明的网络工具，用合规的网络环境即可。

reading choices 相关报错：这多半是模型返回结构不符合预期，常见于 Model ID 写错、或者用了不兼容的 provider 格式。回到第 2 节的 JSON 配置，确认provider是openai-compatible、baseUrl是https://taotoken.net/api、modelId拼写正确。改完重启 gateway 再试。

OAuth 相关报错：如果你用的是需要 OAuth 的通道（比如某些协作平台），token 过期会报这个。重新走一遍授权流程，把新的 token 写回配置。OAuth 的 refresh token 也要一并更新，只换 access token 过一会儿又会失效。

Codex auth.json 相关：如果你在用 Codex 类工具，认证信息写在 auth.json 里，格式错了会直接失败。确保里面同时有 Base URL、Key、Model ID 三件套，缺一不可。文件路径要和工具默认读取路径一致，放错位置等于没配。

CC Switch / Cline MCP 场景：这两个工具接入时同样要写全三件套。CC Switch 的配置里 Base URL 填https://taotoken.net/api，Key 填你的 Key，Model ID 填你要用的模型。Cline 的 MCP 配置也是同理，三个字段对齐才能通。少任何一个都会表现为"连不上"或"调用失败"。

排查时养成一个习惯：每改一处配置，就重启 gateway 并用openclaw logs --follow盯一会儿日志。日志里的时间戳、错误码、堆栈上下文，比任何猜测都可靠。

6. 长期跑自动化：把 Coding Plan 和接入文档用起来

如果你只是偶尔跑一两个定时任务，上面的排查够用了。但如果你打算长期跑自动化流程，比如每天定时生成报告、定时巡检、定时同步数据，那建议把模型调用和调度都规划好，避免频繁出问题。

长期编码和 Agent 类场景，可以看 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合需要稳定模型供给的自动化任务。接入细节和参数说明都在文档里，https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到配置问题先翻文档，大部分字段含义都有解释。

最后给一个实用技巧：把openclaw cron status、openclaw system heartbeat last、openclaw channels status --probe这三条命令写成一个巡检脚本，每天跑一次，输出存到日志文件。这样你不用等到任务失败才发现问题，提前就能看到nextWakeAtMs是不是空的、心跳是不是连续 skipped、通道是不是掉线了。自动化系统的稳定性，靠的不是出问题后救火，而是平时把状态盯住。