OpenClaw’s June 2026 Cron SQLite Migration

OpenClaw’s cron system crossed an important operational boundary in June 2026. Scheduled jobs, runtime state and run history stopped living primarily in separate JSON and JSONL files and moved into OpenClaw’s shared SQLite state database.

That was more than a storage refactor. Cron runs inside the Gateway and can wake sessions, execute isolated agent turns, and send results to channels or webhook endpoints. Its persisted state is therefore production automation state. The migration made that state more coherent, but the first stable rollout also showed that a scheduler migration is an upgrade event operators must verify—not a routine package replacement.

The historical change

PR #88285 merged on 30 May 2026. Its stated scope was to move cron job definitions, runtime state and run logs from legacy JSON/JSONL files into the shared OpenClaw SQLite database.

The design addressed several real persistence problems. Valid legacy stores and logs were to be imported; old files were to be archived only after a durable SQLite import; malformed rows were to remain available for quarantine; and runtime-only updates were not supposed to overwrite concurrent configuration edits. The patch also included additive repair for early SQLite table shapes.

That work shipped in OpenClaw 2026.6.1, published on 3 June. The release described compatibility across legacy run-log tables, archived stores, diagnostic names, single-job history, startup retries and old one-shot deletion behaviour.

The tagged scheduled-tasks documentation made the new authority boundary explicit: cron runs inside the Gateway, while definitions, runtime state and history persist in the shared SQLite state database. It also warned that after import, editing ~/.openclaw/cron/jobs.json no longer changes active jobs. Operators had to use the cron CLI or Gateway RPC methods instead.

The rollout gap

The migration code and the ordinary upgrade path were not initially joined tightly enough.

On 4 June, the original report in issue #90072 described an upgrade from 2026.5.28 to 2026.6.1 in which openclaw cron list showed only one of 45 previously configured jobs after Gateway restart. The reporter also indicated that the old state had not been preserved for recovery. That is one operator’s incident report, not evidence that every upgrade lost jobs, and OpenClaw Academy did not independently reproduce it.

A later commenter described a different recovery situation: their legacy jobs.json was intact, and running openclaw doctor --fix recovered the jobs. That comment supports the repair path for that commenter’s preserved state; it must not be attributed to the original reporter or treated as proof that every affected installation retained its JSON file.

The root-cause account in the subsequent fix is more broadly useful. PR #90208 says the cron runtime read only the canonical SQLite store, while the existing doctor repair flow could import legacy files. Ordinary doctor configuration preflight, however, did not call that repair before startup or restart paths read runtime state. Legacy JSON could therefore still exist while SQLite was empty or incomplete.

The fix merged on 5 June. It moved migration into non-interactive doctor preflight, reused the same repair path as doctor --fix, let existing SQLite rows win duplicate IDs, normalized legacy shapes, and archived source files only after a successful database write.

This distinction matters: PR #88285 shipped the SQLite model in 2026.6.1; PR #90208 later repaired the automatic upgrade path. A merged fix was not protection for installed users until it appeared in a release.

What shipped next

OpenClaw 2026.6.5, published on 9 June, explicitly included the preflight migration fix. Its release notes say legacy cron JSON stores are migrated into SQLite before runtime reads.

Upstream’s PR proof used a temporary OpenClaw home containing three representative legacy jobs, split runtime state and one JSONL run-log row. The reported result was three SQLite job rows, one imported historical row, archived legacy files, and successful Gateway readback; an overdue recurring job then ran once. The PR also says it did not test a packaged real-user upgrade from 2026.5.28 or invoke a real service-manager restart.

A smaller observability loose end remained. cron.status still exposed the legacy jobs.json path even though SQLite was authoritative. PR #92144, merged on 11 June and listed in the 2026.6.8 release published on 16 June, added storage: "sqlite" and sqlitePath while retaining storePath as a deprecated compatibility field.

That sequence completed the operational story: migrate automatically, keep recovery semantics conservative, then make status output identify the real store.

Who this affected

The highest-risk group was operators upgrading a pre-SQLite installation with existing scheduled work. The risk was not limited to reminders. The historical docs already supported main-session wake events, isolated agent turns, recurring schedules, one-shot jobs, channel announcements and webhook delivery. Losing or overlooking a definition could therefore mean missing an external report, an event-triggered run or a background task.

Automation wrappers were affected too. Any script that treated cron.store or jobs.json as the live source of truth had to move to the CLI or Gateway API. Monitoring that parsed only the old storePath field could also describe the wrong authority after migration, even when jobs themselves were healthy.

Fresh installations without legacy files did not face the same import boundary. Nor does the single reported incident establish a universal data-loss rate or security impact.

What operators had to learn

The June transition produced a practical upgrade discipline:

1. Back up scheduler state before crossing a storage migration. The relevant asset became the whole OpenClaw state area, not merely a hand-edited cron JSON file.
2. Run the supported migration path. In the historical 2026.6.5 documentation, openclaw doctor --fix was the explicit repair/import route; the release also added automatic preflight migration.
3. Verify semantics, not just process health. After restart, compare job count, enabled state, schedule, delivery target and run history. A running Gateway does not prove every automation definition migrated.
4. Treat legacy files as evidence, not live configuration. Preserve them until migration is confirmed, but do not expect edits there to alter SQLite-backed jobs.
5. Check the authoritative status fields. From the 2026.6.8 lineage, storage and sqlitePath identify the database; deprecated storePath exists for compatibility.

What this history explains today

OpenClaw’s scheduler is a Gateway-owned automation service, not a thin wrapper around operating-system cron. Its jobs combine timing, session selection, model-backed execution, delivery routing and durable history. Consolidating that state in SQLite made transactional updates and shared operational inspection possible, but it also made database migration part of the scheduler lifecycle.

That is the lasting operator consequence. When OpenClaw changes where automation state lives, “the package installed” is only the first check. The real acceptance test is that jobs are present, correctly routed, historically traceable and able to run after the Gateway restarts.

Verification note: OpenClaw Academy checked the official release pages, merged pull requests, issue record and versioned documentation on 23 July 2026. Test outcomes and the reported upgrade incident are attributed to upstream sources. We did not install or reproduce the retired June versions, so this is historical source analysis rather than an independent migration test.