OpenClawDocs
On this page

On this page

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Automation

Automation troubleshooting

A command ladder and the common failure shapes for scheduled jobs. Part of the Automations guide.

Troubleshooting

Command ladder

bash
openclaw statusopenclaw gateway statusopenclaw automations statusopenclaw automations listopenclaw automations runs <jobId> --limit 20openclaw automations show <jobId>openclaw logs --followopenclaw doctor
Automations not firing
  • Check the cron.enabled config setting and OPENCLAW_SKIP_CRON in the Gateway's launch environment. Either can disable automatic runs; clear both disable settings and restart the Gateway to enable scheduling.
  • Confirm the Gateway is running continuously.
  • Use openclaw automations list --all to find disabled jobs and openclaw doctor to inspect recorded auto-disable reasons, including terminal one-shot execution failures. Fix the cause before running openclaw automations enable <jobId>. Operator cancellations and restart interruptions remain visible in run history, but do not increase consecutive failures, trigger failure alerts or automatic repair, or record an auto-disable. A job failure completed before webhook delivery was interrupted still counts. Enabled, unchanged time-scheduled agent-turn jobs interrupted before delivery retry once through cron, including one-shots. Other interrupted one-shots stay disabled to avoid replaying uncertain work; inspect their history before continuing manually.
  • For cron schedules, verify timezone (--tz) vs the host timezone.
  • reason: not-due in run output means the manual run was checked with openclaw automations run <jobId> --due and the job was not due yet.
  • If the job's execution agent cannot be resolved, automatic and manual attempts record a failed task and a skipped run-history entry with the reason. Select an agent with openclaw automations edit <jobId> --agent <id>.
  • Automation has no recorded inference account means an older job has not adopted a stored account yet. Run openclaw doctor --fix: it backs up cron state and records the account the job's run would use (an explicit selection, or the first account in the normal account order) without pinning inherited models or changing fallbacks. When several accounts are eligible, Doctor names the others; if the account is unavailable or personal, Doctor names the job and the required action. An authorized operator can explicitly select the intended profile with openclaw automations edit <jobId> --model <provider/model>@<profileId>. A job on an environment or provider-config key keeps that key and needs no adoption; it stops instead of switching once a stored account becomes eligible. The refusal ends the run without trying fallback models. CLI-native login and configured credentialless inference do not require adopting a host profile; an unbound CLI job cannot select or automatically borrow one. Doctor does not infer historical account ownership from the last model in run history.
  • Automation candidate is incompatible with its recorded inference account and route means the selected model uses a different provider, or its runtime uses a CLI login that cannot replace the job's stored account. Model/default changes preserve account ownership. Select a model and host-managed runtime compatible with that account, or deliberately adopt another stored account with openclaw automations edit <jobId> --model <provider/model>@<profileId>. A profile selection does not transfer ownership to a CLI login. Doctor leaves existing bindings unchanged; repeating doctor --fix does not repair this mismatch. See Inference account continuity.
  • A run can finish ok after an exec call fails and the agent replies. Check diagnostic: in openclaw automations show <jobId> or diagnostics in run history; unresolved exec failures produce a warning without exposing command arguments.
  • Automation migration is incomplete; run openclaw doctor --fix means a converted monitor still has pending migration work. Complete Doctor's reported repair before running it.
  • If a capped job's stored named creator account is unavailable, the run fails before model/tool execution. Job details, run history, and warning logs name the account. Re-add it to the channel configuration, or recreate the automation from the intended account; changing the delivery --account does not change creator authority. Legacy jobs without account metadata keep their existing execution policy.
Job fired but no delivery
  • A session queue capacity error means the target cannot admit another turn. Let its existing work settle before retrying. Main-session system events stay running until their turn settles; a restart before adoption records one interrupted error without replaying the reminder.
  • Delivery mode none means no runner fallback send is expected. The agent can still send directly with the message tool when a chat route is available.
  • Delivery target missing/invalid (channel/to) means outbound was skipped.
  • For Matrix, copied or legacy jobs with lowercased delivery.to room IDs can fail because Matrix room IDs are case-sensitive. Edit the job to the exact !room:server or room:!room:server value from Matrix.
  • Channel auth errors (unauthorized, Forbidden) mean delivery was blocked by credentials.
  • When the dispatcher records intentional suppression, job state, run history, and finished events include deliverySuppressionReason (empty, silent, heartbeat, or channel_transform). This is separate from lastDeliveryError / deliveryError; required delivery failures also log an error when they happen.
  • For text-only isolated announcements, only a completed final that trims to uppercase NO_REPLY suppresses the text and fallback queued summary. Lowercase, wrapped forms, and trailing tokens remain visible. See Silent token suppression for the leading-line form and media behavior.
  • If the agent should message the user itself, check that the job has a usable route (channel: "last" with a previous chat, or an explicit channel/target).
  • With delivery.target: "owner", no resolved owner DM means delivery is unavailable; it does not skip execution or fall back to the last group conversation. delivery.directPolicy: "block" intentionally suppresses DM delivery. Inspect and edit the job's delivery settings.
Automations or heartbeat appear to prevent /new-style rollover
  • Daily and idle reset freshness is not based on updatedAt; see Session management.
  • Automation wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may update the session row for routing/status, but they do not extend sessionStartedAt or lastInteractionAt.
  • For legacy rows created before those fields existed, OpenClaw can recover sessionStartedAt from the transcript JSONL session header when the file is still available. Legacy idle rows without lastInteractionAt use that recovered start time as their idle baseline.
Timezone gotchas
  • Cron expressions without --tz use the gateway host timezone.
  • at schedules without timezone are treated as UTC.
  • Job activeHours has its own timezone (user, local, or an IANA zone), independent of the cron expression's --tz.
Was this useful?