故障排除

用于定时任务的命令阶梯和常见故障形态。属于自动化指南的一部分。

故障排查¶

命令阶梯¶

openclaw status
openclaw gateway status
openclaw automations status
openclaw automations list
openclaw automations runs <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

自动化未触发

检查 cron.enabled 配置项以及 Gateway 启动环境中的 OPENCLAW_SKIP_CRON。两者都可能禁用自动运行；清除这两个禁用设置并重启 Gateway 以启用调度。
确认 Gateway 正在持续运行。
对于 cron 调度，请核对时区（--tz）与主机时区。
运行输出中的 reason: not-due 表示手动运行已通过 openclaw automations run <jobId> --due 检查，且任务尚未到期。
如果无法解析任务的执行代理，自动和手动尝试都会记录一个失败任务以及一条带有原因的运行历史跳过条目。使用 openclaw automations edit <jobId> --agent <id> 选择一个代理。
handler-unavailable 表示心跳服务未注册，或在等待期间停止。该尝试会被记录为跳过。在重试任务前，请检查 Gateway 启动和 sidecar 错误。
如果受限任务中存储的命名创建者账户不可用，运行会在模型/工具执行前失败。任务详情、运行历史和警告日志会指明该账户。请将其重新添加到通道配置中，或从预期账户重新创建自动化；更改投递 --account 不会更改创建者权限。没有账户元数据的旧任务会保留其现有执行策略。

任务已触发但未投递

投递模式 none 表示不预期 runner 回退发送。当聊天路由可用时，代理仍可使用 message 工具直接发送。
投递目标缺失或无效（channel/to）表示出站发送被跳过。
对于 Matrix，复制的或旧任务如果 delivery.to 房间 ID 被小写化，可能会失败，因为 Matrix 房间 ID 区分大小写。请将任务编辑为 Matrix 中确切的 !room:server 或 room:!room:server 值。
通道认证错误（unauthorized、Forbidden）表示投递被凭据阻止。
当分发器记录有意抑制时，任务状态、运行历史和完成事件会包含 deliverySuppressionReason（empty、silent、heartbeat 或 channel_transform）。这与 lastDeliveryError / deliveryError 是分开的；必需投递失败发生时也会记录错误。
如果隔离运行只返回静默令牌（NO_REPLY / no_reply），OpenClaw 会抑制直接出站投递和回退队列摘要路径，因此不会有任何内容发布回聊天。
如果应由代理自行向用户发送消息，请检查任务是否有可用路由（带有先前聊天的 channel: "last"，或显式通道/目标）。

自动化或心跳似乎阻止了 /new 式滚动

每日重置和空闲重置的新鲜度不基于 updatedAt；参见会话管理。
自动化唤醒、心跳运行、exec 通知和 Gateway 簿记可能会更新会话行以用于路由/状态，但它们不会延长 sessionStartedAt 或 lastInteractionAt。
对于在这些字段存在之前创建的旧行，OpenClaw 可以在文件仍可用时从 transcript JSONL 会话头中恢复 sessionStartedAt。没有 lastInteractionAt 的旧空闲行会使用恢复的启动时间作为其空闲基线。

时区陷阱

不带 --tz 的 Cron 表达式使用 Gateway 主机时区。
不带时区的 at 调度被视为 UTC。
心跳 activeHours 使用已配置的时区解析。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw