OpenClaw Moves Auth and Exec Approvals to SQLite: Run Doctor Before the Cutover

OpenClaw merged two related storage cutovers into main on 26 July: authentication profiles now have a SQLite-only runtime, and exec-approval policy moves from ~/.openclaw/exec-approvals.json into the shared state database.

Both changes deliberately reject silent compatibility fallback. If legacy state is still present, affected runtime paths fail closed and direct the operator to run openclaw doctor --fix. That makes this an upgrade procedure, not merely an internal refactor.

These changes were merged after the releases explicitly mentioned in the auth pull request, including v2026.7.2-beta.5. A merge into main does not prove that any particular installed package contains them. Confirm the release notes or exact source revision before applying this guidance.

Operator decision

Do not delete or rename the old files to get past the gate. Their presence is the evidence Doctor uses to perform and verify the migration.

Authentication becomes agent-owned SQLite state

PR #114033 removes steady-state reads from four legacy credential sources. The canonical owner is the per-agent SQLite auth store; runtime auth, secret-handling paths, ownership lookups and session auth storage use that owner instead of falling back to JSON.

Doctor now performs a locked, idempotent import. Upstream says it verifies the SQLite target before timestamped archival, records receipts for crash recovery, can resume interrupted archive finalization and does not delete credential bytes during import. An unmigrated or unreadable owner produces the redacted AUTH_PROFILE_MIGRATION_REQUIRED diagnostic rather than silently switching to environment or configuration credentials.

That last point matters operationally. A fallback can make an upgrade appear healthy while authenticating with a different credential than the operator intended. Failing closed is noisier, but it preserves ownership and makes incomplete migration visible.

The Plugin SDK transition is also explicit. AuthStorage.forAgent(agentDir) is the supported API. AuthStorage.create(path) and FileAuthStorageBackend remain compatibility adapters backed by SQLite, with removal eligibility documented after 1 October 2026. Existing deprecated-path files fail closed without being read; plugins that intentionally maintain nonstandard file-backed auth need to migrate during that window.

Exec approvals leave the file-lock era

PR #114063 makes the reserved exec_approvals_config singleton row in state/openclaw.sqlite authoritative on both the TypeScript and native macOS runtimes.

The old JSON store depended on separate synchronous and asynchronous lock paths, stale-lock heuristics and filesystem compare-and-swap checks. Upstream links that architecture to intermittent fabricated deny policy under same-process lock contention. The new implementation uses SQLite transactions and rechecks compare-and-swap state inside the write transaction while preserving the existing CLI, RPC and web-interface contracts.

The fail-closed behaviour is now split correctly:

• enforcement reads use deny policy when the database is unavailable or malformed and emit a rate-limited warning;
• snapshot and mutation paths throw a typed unavailable error rather than pretending a synthetic deny document is authoritative; and
• while the legacy JSON or an in-progress migration claim exists, both runtimes refuse approval-dependent operations with a Doctor instruction.

Doctor claims the source, rejects symlink and hard-link surprises, verifies the imported row inside the transaction, records migration receipts and removes the source only after commit. Malformed legacy bytes are preserved for recovery rather than imported as an empty deny document.

The user-visible location therefore changes from a standalone JSON file to:

state/openclaw.sqlite#exec_approvals_config

Continue using openclaw approvals and the supported control surfaces. Do not edit the SQLite row directly.

Safe migration sequence

1. Confirm the containing build. Match PRs #114033 and #114063 to the release or source SHA you intend to deploy.

2. Stop competing writers. Arrange a maintenance window so Gateway, native clients and automation are not changing auth or approval state during backup and migration.

3. Take a restorable state backup. Preserve the complete OpenClaw state directory and the full SQLite database family, not only a workspace or one .sqlite file.

4. Record policy without exposing secrets. Capture profile names, expected providers, approval defaults, per-agent policy and allowlist counts. Do not print tokens or raw credential records.

5. Run the supported migration:

   openclaw doctor --fix

6. Verify authentication. Exercise each configured provider through its normal supported flow, including OAuth refresh where applicable.

7. Verify approvals. Run openclaw approvals get; compare defaults, per-agent rules and allowlist entries with the pre-migration record.

8. Exercise both outcomes. Confirm an expected allowed command still follows policy and an unapproved command still denies or prompts as designed.

9. Keep recovery evidence. Retain the pre-upgrade backup and Doctor archives until normal agent, auth-refresh and approval behaviour has survived a restart.

If Doctor reports malformed or unreadable legacy state, stop. Preserve the source, database family, receipts and redacted diagnostics. Do not replace the policy with a permissive document merely to restore service.

Evidence and limits

The auth pull request reports 511 focused tests and a packaged upgrade-survivor scenario from [email protected] through a candidate build, including Doctor, Gateway startup and readiness checks. The exec-approval pull request includes an isolated live CLI migration, focused TypeScript and Swift suites, native schema checks and post-migration per-agent policy reads.

OpenClaw Academy reviewed the official merged pull-request records, landed commit chronology and upstream evidence stored by the publication’s collector. We did not migrate a production credential store or execute a live host approval flow. Test outcomes above are attributed to upstream; the backup, maintenance-window and acceptance guidance is our operator interpretation.

Bottom line

OpenClaw is consolidating two sensitive authorities into SQLite and refusing to keep ambiguous file fallbacks alive. That is the right security direction, but it turns upgrades with legacy state into an explicit migration boundary.

Back up the whole state boundary, use a build containing both reviewed cutovers, let Doctor own the import, and verify real provider plus approval behaviour before deleting any recovery evidence.