跳转至

故障排除

定时任务的命令阶梯以及常见故障形态。属于 Automations 指南的一部分。

故障排除

命令阶梯

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> 选择一个代理。
  • 即使 exec 调用失败且代理回复,运行也可能以 ok 结束。检查 openclaw automations show <jobId> 中的 diagnostic: 或运行历史中的 diagnostics;未解决的 exec 失败会生成警告,但不会暴露命令参数。
  • handler-unavailable 表示心跳服务未注册,或在等待期间停止。该尝试会被记录为跳过。在重试任务之前,请检查 Gateway 启动和 sidecar 错误。
  • 如果受限任务中存储的命名创建者账户不可用,运行会在模型/工具执行之前失败。任务详情、运行历史和警告日志会指明该账户。将其重新添加到通道配置中,或从预期账户重新创建自动化;更改投递 --account 不会更改创建者权限。没有账户元数据的旧任务会保留其现有执行策略。
任务已触发但未投递
  • System event queue is full 表示会话已有 20 个待处理事件。OpenClaw 会保留这些已接受的事件,并将溢出的提醒记录为失败运行,而不是丢弃较早的提醒。让会话处理其待处理事件,然后使用 openclaw automations run <jobId> 重试失败的提醒。如果心跳已暂停,请使用 openclaw system heartbeat enable 启用它们。待处理系统事件是进程本地的,不是跨 Gateway 重启的持久投递回执。
  • 投递模式 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 或以末尾静默 token 结尾的回复会抑制整个文本以及回退排队摘要。示例和媒体行为参见 静默 token 抑制。
  • 如果代理应自行向用户发送消息,请检查任务是否有可用路由(带有先前聊天的 channel: "last",或显式通道/目标)。
自动化或心跳似乎阻止 /new-style 滚动
  • 每日和空闲重置的新鲜度不基于 updatedAt;参见 会话管理。
  • 自动化唤醒、心跳运行、exec 通知和 gateway 簿记可能会更新会话行以用于路由/状态,但不会延长 sessionStartedAt 或 lastInteractionAt。
  • 对于在这些字段存在之前创建的旧行,OpenClaw 可以在文件仍可用时从 transcript JSONL 会话头中恢复 sessionStartedAt。没有 lastInteractionAt 的旧空闲行会使用恢复的启动时间作为其空闲基线。
时区陷阱
  • 不带 --tz 的 Cron 表达式使用 gateway 主机时区。
  • 不带时区的 at 计划被视为 UTC。
  • 心跳 activeHours 使用已配置的时区解析。

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