openclaw backup CLI reference: archives and SQLite snapshots

openclaw backup

Generate a local backup archive that captures OpenClaw state, configuration, authentication profiles, channel and provider credentials, sessions, and optionally workspaces.

openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz
openclaw backup sqlite create --global --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite create --agent main --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite list --repository ~/Backups/openclaw-sqlite
openclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id>
openclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id> --scratch ~/Private/openclaw-scratch
openclaw backup sqlite restore ~/Backups/openclaw-sqlite/<snapshot-id> --target ./restored/openclaw.sqlite

Notes

• The archive contains a manifest.json that records the resolved source paths and the archive's internal layout.
• By default, the output is a timestamped .tar.gz archive placed in the current working directory. Timestamps in filenames reflect your machine's local time and include the UTC offset. If the current working directory falls within a source tree being backed up, OpenClaw defaults to your home directory instead.
• Existing archive files are never overwritten. Output paths that reside inside the source state or workspace trees are blocked to prevent the archive from including itself.
• openclaw backup verify <archive> verifies that the archive holds exactly one root manifest, rejects traversal-style archive paths and SQLite sidecar files, confirms every file declared in the manifest exists, validates the file shape of each SQLite snapshot, and performs full integrity and role checks on canonical OpenClaw databases. Plugin-specific schemas are left opaque because they may depend on SQLite capabilities defined by the plugin's owner. openclaw backup create --verify executes this validation immediately after the archive is written.
• openclaw backup create --only-config backs up only the active JSON configuration file.

SQLite snapshots

Use openclaw backup sqlite when you need a portable artifact for a single OpenClaw-owned SQLite database rather than a full state archive.

A snapshot command accepts exactly one named source:

Each committed snapshot occupies its own directory in the repository. Every snapshot directory contains exactly:

• manifest.json
• database.sqlite

When creating a snapshot, OpenClaw checks the live database's integrity before reading, uses SQLite's online backup API to capture committed WAL state without holding a long read transaction, closes the live database, compacts the private copy with VACUUM, verifies the resulting database again, and writes the completed directory without overwriting any existing paths. Global snapshots remove transient delivery queue rows before compaction so that deleted queue payloads do not linger in free pages.

Do not copy live .sqlite, -wal, -shm, or -journal files as a portable artifact. Only copy completed snapshot directories.

SQLite snapshots may contain authentication profiles, session state, plugin data, and other sensitive information. Protect snapshot repositories with the same permissions, encryption, retention policies, and destination restrictions you apply to the live OpenClaw state directory.

Verify and restore

openclaw backup sqlite verify <snapshot-directory>
openclaw backup sqlite restore <snapshot-directory> --target <new-database-path>

Verification checks the manifest's strict structure, artifact size and SHA-256 hash, SQLite integrity, foreign key constraints, schema version, database role and owner, and OpenClaw-owned index definitions.

Verification operates on a private content-pinned copy so that pathname races cannot substitute bytes while SQLite inspects them. By default, this temporary copy is created next to the snapshot repository and removed before the command finishes. The staging root and every ancestor directory must prevent other users from replacing it. On POSIX systems, roots must be owned by the current user and must not be group or world writable; sticky directories such as /tmp are acceptable as long as the child is user-owned. macOS ACL grants that expose the staging area or allow it to be replaced are rejected. On Windows, roots and all ancestors must be owned by the current user or a trusted OS principal, with ACLs that deny untrusted staging access. For read-only mounts or network shares, pass --scratch <existing-private-directory> on storage that provides equivalent encryption and destination controls.

Before staging or publishing database bytes, snapshot creation applies the same ownership, ACL, ancestor, and path identity checks to the repository.

Restore repeats verification and writes only to a fresh target. It refuses an existing target, -wal, -shm, or -journal sidecar, and never performs an in-place replacement of a live OpenClaw database. The target's parent directory must meet the same path security requirements as the verification scratch space. Activating a restored database remains an explicit offline operator step.

Snapshot repositories are local directories. Scheduling, uploading, retention, incremental WAL bundles, failover, and restore-on-boot behavior are intentionally outside this command's scope.

What gets backed up

openclaw backup create discovers sources from your local OpenClaw installation:

• The state directory (typically ~/.openclaw)
• The active configuration file path
• The resolved credentials/ directory when it exists outside the state directory
• Workspace directories found in the current configuration, unless you supply --no-include-workspace

Authentication profiles and other per-agent runtime state reside in SQLite under the state directory (agents/<agentId>/agent/openclaw-agent.sqlite), so the state backup entry automatically covers them.

--only-config bypasses state, credentials directory, and workspace discovery, archiving only the active configuration file path.

OpenClaw canonicalizes paths before building the archive: if the configuration file, credentials directory, or a workspace already lives inside the state directory, they are not duplicated as separate top-level backup sources. Missing paths are silently skipped.

During archive creation, OpenClaw excludes paths known to be undergoing live mutation before tar reads them. This prevents races between a file's recorded size and concurrent writes. The filter applies these state-relative rules under each backed-up state directory:

These rules do not filter workspace files located outside the state directory. They also skip completed transcript and log files that match the table, so retain those records separately when needed. The JSON result's skippedVolatileCount field reports how many files were intentionally omitted.

SQLite databases under the state directory are captured using SQLite's online backup API and compacted offline with VACUUM so that deleted page remnants do not enter the archive, and live WAL or SHM files are not copied. A plugin-owned database that requires unavailable owner-defined SQLite capabilities fails closed rather than falling back to a direct file copy. SQLite files included through workspace backups are copied as workspace files and are not covered by the compaction guarantee.

Plugin source files and manifest files located under the extensions/ subtree inside the state directory are included in the backup. Their nested node_modules/ dependency trees are omitted because they are rebuildable install artifacts. After an archive is restored, run openclaw plugins update <id> or reinstall with openclaw plugins install <spec> --force if a restored plugin reports that dependencies are missing.

Rebuildable runtime roots managed by the installer under the state directory are also excluded: dev/, git/, npm/, legacy npm-runtime/, and tools/. These contain managed checkouts, package trees, and downloaded runtimes rather than authoritative user state. Reinstall or update the relevant runtime or plugin after restoring. A config file, credentials directory, or workspace that is explicitly configured inside one of these roots is still included.

Invalid config behavior

openclaw backup skips the normal config preflight so it can assist during recovery. Workspace discovery requires a valid config, so openclaw backup create fails quickly when the config file exists but is invalid and workspace backup remains enabled.

For a partial backup in this scenario, rerun with --no-include-workspace. This keeps state, config, and the external credentials directory in scope while completely skipping workspace discovery.

--only-config also works when the config is malformed, because it does not parse the config for workspace discovery.

Size and performance

OpenClaw does not enforce a built-in maximum backup size or per-file size limit. If an archive write produces no data for five minutes, it fails and removes its partial temporary file rather than hanging indefinitely. Practical limits otherwise come from:

• Available space for the temporary archive write plus the final archive
• Time to walk large workspace trees and compress them into a .tar.gz
• Time to rescan the archive with --verify or openclaw backup verify
• Destination filesystem behavior: OpenClaw requires no-overwrite hard-link publication so a final archive path never exposes an in-progress copy. Unsupported filesystems fail with an actionable error

If final-directory durability confirmation fails after publication, the command reports failure but preserves the complete final entry rather than risk deleting a concurrent replacement.

Large workspaces are usually the main driver of archive size. Use --no-include-workspace for a smaller and faster backup, or --only-config for the smallest archive.

Related

• CLI reference