OpenClaw Retires Heartbeat tasks: Blocks—Back Up Before Running Doctor

OpenClaw merged the deferred final step of its heartbeat migration on 23 July 2026: structured tasks: entries in heartbeat monitor scratch are no longer runtime schedules. Each valid entry is now converted by openclaw doctor --fix into an independent cron job.

That is the useful feature. The operational warning arrived around it. Two adjacent fixes repaired a lossy Doctor auth migration and a schema upgrade that could prevent the Gateway from starting on supported Node versions. A further SQLite hardening merge closed maintenance and scratch-lifecycle races. Together, these changes make one decision clear: do not run a random mid-migration source snapshot against your only copy of OpenClaw state.

Operator decision

• Packaged installations: wait for release notes that explicitly include these commits. The latest stable GitHub release at verification time was v2026.7.1, published before all four merges discussed here.
• Source builds: take a restorable copy of the complete OpenClaw state directory and agent databases before running Doctor. Use a revision that includes the task migration and the later fixes, not an earlier 23 July snapshot.
• Existing heartbeat tasks: users: do not leave the block for runtime to interpret after adopting the new code. The runtime parser has been removed; unmigrated task text becomes ordinary prompt prose.
• Auth users with legacy JSON: preserve the legacy file and any migration backup until provider authentication has been verified. Do not treat the mere presence of profile IDs as proof that every credential field survived.
• Schema-v13 database users: do not repeatedly restart or manually rewrite the database after the session_windows.session_key startup error. Restore from backup if necessary and move to a revision containing PR #113151.

This guidance applies to the unreleased main-branch transition described by the cited commits. It is not a claim that the current stable package contains every affected migration path.

What changes for heartbeat tasks

Before PR #113165, the heartbeat runner parsed a YAML-like tasks: block from monitor scratch. Every task could declare an interval, but due work still waited for the base heartbeat tick and due tasks were batched into a heartbeat turn.

The merged implementation removes that parser. Doctor now turns each valid task into a cron row with its own schedule, payload, enabled state and run history. The surrounding scratch remains prose. Operators can manage the resulting jobs with the ordinary cron CLI and tools instead of editing scheduler syntax inside scratch.

The timing semantics also change:

1. Each task has an independent cron cadence rather than being capped by the base heartbeat interval.
2. Tasks due within the same coalescing window may still share a heartbeat turn.
3. Heartbeat active hours, minimum spacing, flood controls and busy retries still apply.
4. An occurrence outside active hours is skipped and considered again at the task’s next cron occurrence.

That fourth point deserves attention. Independent scheduling does not mean an overdue occurrence is guaranteed to run immediately when active hours resume.

Doctor owns the conversion

The migration is designed as one SQLite transaction. According to the merged PR and its tests, Doctor pins the scratch revision, creates or updates the task jobs, and strips the tasks: block atomically. A concurrent change causes the losing migration to abort without partially rewriting scratch. Invalid intervals, incomplete entries and orphan task fields produce a finding rather than silently deleting text.

Doctor also carries forward the previous task timing when available. Duplicate task names receive per-occurrence identities so both continue to run. Re-running the migration converges on the same declaration keys rather than creating another set of jobs.

After upgrading to a build containing the required fixes, the supported migration command is:

openclaw doctor --fix

Do not copy task rows into SQLite by hand. The transaction, scratch revision check, declaration identity and legacy timing cleanup are part of the migration contract.

Why the backup warning is not boilerplate

PR #97881, merged early on 24 July, found that both legacy auth migration writers rebuilt credentials from incomplete field lists. The auth.json path could discard keyRef, tokenRef and OAuth fields including clientId, idToken and chatgptPlanType. The flat auth-profiles.json path could lose the same fields and reject a credential backed only by a secret reference.

Upstream’s most concerning finding was about detection: post-migration verification checked profile IDs, not the full credential. Doctor could therefore accept the migration, back up and remove the legacy JSON, while leaving an OAuth credential unable to refresh or a secret-reference credential unusable. The fix reuses the canonical credential parser and preserves the already parsed credential instead of constructing a lossy copy.

Upstream demonstrated the field loss before the patch and preservation afterward through the production migration entry points and a real SQLite store. It did not make live provider requests, and the PR explicitly leaves the historical real-world blast radius as an open question. We therefore treat the code defect as verified without inventing an affected-install count.

A separate database upgrade failure

PR #113151 fixed another migration boundary. An existing schema-v13 agent database upgrading to v14 could fail to open on supported Node 22.22.3 and 24.15.0, whose embedded SQLite 3.51.3 rejected a correlated ORDER BY reference. The reported error was:

no such column: session_windows.session_key

The fix moves the legacy window-owner join inside each scalar lookup. Upstream tested a synthetic v13 database through Gateway startup and the production sessions.patch path, then reported schema v14 and a successful SQLite integrity check. Fresh databases and databases already at v14 were not affected by that specific defect.

Finally, PR #113216 tightened the same state layer after these migrations landed. It keeps quarantine intact when compaction fails, makes manual transcript compaction expose one consistent generation, prevents destructive maintenance from following filesystem aliases, and stops a late heartbeat from recreating scratch after its cron job was deleted.

Interpretation: none of those later fixes invalidate the move to SQLite. They show that migration and maintenance are the risk boundary. The database is now the authority for more OpenClaw state, so a workspace-only backup is increasingly inadequate.

Safe verification after migration

After Doctor completes, verify outcomes rather than trusting a zero exit code:

1. Run openclaw cron list --all and confirm that every former heartbeat task has one expected job.
2. Compare each job’s interval, enabled state and payload with the old block.
3. Inspect monitor scratch and confirm the tasks: scheduler block is gone while unrelated prose remains.
4. Check subsequent cron history and active-hours behaviour; do not assume the first due occurrence will bypass heartbeat guards.
5. Confirm each configured provider can authenticate or refresh through its normal supported workflow.
6. Keep the pre-migration state copy and Doctor-created backups until those checks pass.

Avoid printing raw auth databases or credential JSON into tickets, chat or CI logs. Verification should establish that references and provider flows work, not disclose their secret values.

The practical upgrade floor

For source-build operators planning this migration, the task conversion commit alone is not a sensible floor. The snapshot should also include the auth-preservation fix, the v13-to-v14 compatibility fix and the later SQLite maintenance hardening. At verification time, commit 2b7622d9 was the newest of those cited merges on main.

That SHA is evidence of the reviewed chronology, not a permanent recommendation to pin forever. Packaged operators should use the eventual release and its upgrade notes. Source-build operators should record the exact revision they deploy, back up the whole state boundary, run the supported migration once, and verify cron, scratch, sessions and authentication before deleting recovery evidence.

Verification note: OpenClaw Academy inspected the merged pull requests, merge commits, changed documentation and patches through the GitHub API on 24 July 2026. We did not execute unreleased OpenClaw against a live operator state directory or provider account. Behavioural tests and migration outcomes are attributed to upstream; the operator guidance and risk interpretation are ours.