OpenClaw cron validation fix: how to unblock job creation fast

Problem statement: you try to create a scheduled job in OpenClaw and cron add fails with a validation error instead of saving the job. This is especially frustrating because the payload often looks correct at first glance. In practice, these failures usually come from a small mismatch between schedule shape, payload kind, and session target rules.

Why this error matters more than it seems

Cron is not a nice-to-have feature in most serious OpenClaw setups. It is how teams run reminders, scheduled checks, daily summaries, and isolated maintenance flows without depending on someone being awake in chat at the right moment. When job creation breaks, the damage is not just one failed command. It blocks automation design, encourages risky manual workarounds, and often pushes operators toward editing JSON by hand under time pressure.

The good news is that validation failures are usually recoverable without guesswork. They rarely require a full reinstall. They usually require a precise reading of OpenClaw’s cron contract: what schedule kind you chose, what payload kind is allowed with that session target, and whether the job structure matches the schema exactly.

The failure pattern behind most cron validation errors

1. Wrong payload for the selected session target: main requires systemEvent, while isolated requires agentTurn.
2. Schedule shape mismatch: kind: "at" needs a valid ISO timestamp; kind: "every" needs everyMs; kind: "cron" needs expr.
3. Mixed top-level and nested fields: operators sometimes supply fields where the tool expects them inside job.schedule or job.payload.
4. Trying to create a main-session job with agent-style settings: model, timeout, and heavy agent-run fields belong to isolated jobs, not plain reminder events.
5. Copy-pasting examples without adapting them: a working snippet for one schedule or one delivery mode can fail if only half the structure is changed.

Step 1: verify what kind of job you actually need

Before touching the payload, decide whether the job is really a main-session reminder or an isolated agent run. This is the first branching decision, and getting it wrong causes a large share of validation failures.

• Use main + systemEvent for lightweight reminders that should appear as a message-like event.
• Use isolated + agentTurn for jobs that should run a model, perform a task, or generate a report independently.
• Do not mix them. If you need an agent run, do not try to force it into a main-session reminder shape.

Step 2: validate the schedule contract

Next, check the schedule block against the selected schedule type. OpenClaw’s schema is strict here, and it should be. A scheduler that accepts vague input becomes unreliable later.

For one-time jobs

Use kind: "at" with a valid ISO-8601 timestamp such as 2026-03-20T14:00:00Z. If the timezone is missing, interpretation can become ambiguous. Use UTC or provide an explicit timezone offset.

For repeating jobs

Use kind: "every" with everyMs and optionally anchorMs, or use kind: "cron" with a real cron expression. Do not pass cron syntax inside an every schedule or interval fields inside a cron schedule.

Step 3: compare the payload to the schema, field by field

This is where most recoveries happen. Ignore what the job was supposed to do for a minute and compare the exact object you are sending to the exact object OpenClaw expects.

• Does the job object wrap schedule, payload, and sessionTarget at the correct level?
• Is payload.kind allowed for that sessionTarget?
• Are you providing only fields that belong to that payload type?
• Did you accidentally place name, delivery, or timeout fields in the wrong block?
• Did you use an ISO timestamp with a valid timezone marker?

Safe known-good patterns you can reuse

One-time reminder in the main session

This is the cleanest pattern for reminders that should read naturally when they fire. Keep the message explicit and include enough context so it still makes sense later.

cron(action: "add", job: {
  name: "Follow up on deployment",
  schedule: { kind: "at", at: "2026-03-20T14:00:00Z" },
  sessionTarget: "main",
  payload: {
    kind: "systemEvent",
    text: "Reminder: check the OpenClaw deployment results from this morning and verify browser automation is healthy."
  }
})

Recurring isolated report job

cron(action: "add", job: {
  name: "Daily usage review",
  schedule: { kind: "cron", expr: "0 8 * * *", tz: "UTC" },
  sessionTarget: "isolated",
  payload: {
    kind: "agentTurn",
    message: "Review yesterday's usage metrics and summarize anomalies.",
    timeoutSeconds: 180
  }
})

Diagnostics runbook for production systems

1) Preserve the failing payload

Do not rewrite the command from memory. Save the exact payload that failed. Validation issues often hide in one tiny difference: an unexpected nesting level, a missing wrapper key, or a wrong payload kind.

2) Strip the job to the minimum valid shape

Start with the smallest possible job that should work for your use case. Once that passes, add optional fields back one at a time. This is much faster than debugging a fully loaded job object.

3) Test one schedule kind at a time

If you are unsure whether the problem is schedule-related, test a one-time at job first. It is easier to validate than a more complex recurring schedule.

4) Separate delivery concerns from execution concerns

A job can fail because the job schema is wrong, not because the thing you hope to receive later is wrong. First make the job structurally valid. Then refine delivery behavior, content, and frequency.

Edge cases that catch experienced operators too

• Timestamp without timezone: looks valid to a human, fails or behaves unexpectedly in scheduling logic.
• Copied reminder text without context: technically valid, operationally poor when it fires hours later.
• Using main-session delivery expectations on isolated jobs: different payload type, different execution path.
• Adding delivery config before the base job works: extra moving parts make root cause slower to isolate.
• Editing by hand during an incident: easy to save a malformed job and harder to roll back cleanly.

How to verify the fix before you trust it

1. Create one minimal job successfully.
2. Read it back with your cron listing flow or dashboard view.
3. Trigger a near-term test schedule and confirm it fires exactly once.
4. Check that the reminder or agent output lands where you expect.
5. Only then recreate more complex production jobs.

Typical mistakes that keep this broken

• Assuming the problem is “cron is broken” instead of “this payload is invalid.”
• Changing schedule, payload, and delivery all at once.
• Using a valid-looking JSON shape that does not match the tool contract.
• Mixing reminder use cases with long-running agent-run use cases.
• Skipping a real post-fix test because the create call finally returned success.

When to stop hand-building jobs and move to a managed workflow

If you only create a few jobs occasionally, hand-built cron payloads are fine. But if your team is running many reminders, maintenance jobs, or daily agent workflows, the bigger cost is not the scheduler itself. It is the operator time spent validating structures, recovering from drift, and checking whether jobs still behave as intended after changes.

Start by comparing your options on /compare/. If you want a hosted path with a cleaner control surface and easier import/migration flow, see /openclaw-cloud-hosting/ or go straight to import your current OpenClaw instance.

Fix once. Stop recurring cron validation failures.

If this keeps coming back, you can move your existing setup to managed OpenClaw cloud hosting instead of rebuilding the same stack. Import your current instance, keep your context, and move onto a runtime with lower ops overhead.

• Import flow in ~1 minute
• Keep your current instance context
• Run with managed security and reliability defaults

If you would rather compare options first, review OpenClaw cloud hosting or see the best OpenClaw hosting options before deciding.

Import your current OpenClaw instance in 1 click Keep self-hosted: apply fix checklist

Review the baseline OpenClaw setup guide

FAQ

Why would a simple reminder fail validation?

Because the scheduler validates structure, not intention. A reminder can still fail if the job object uses the wrong wrapper shape, the wrong payload kind, or a schedule format that does not match the declared schedule type.

Should I use main or isolated for most scheduled jobs?

Use main for lightweight reminders that should read like a prompt or nudge. Use isolated for jobs that should run an agent task independently, especially if they need model execution or their own timeout budget.

What if the job creates successfully but does not fire later?

Then you have moved past validation and into runtime troubleshooting. Check gateway health, cron execution logs, model availability for isolated jobs, and whether the schedule time or timezone is what you expected.