How to back up and restore OpenClaw’s state directory without treating copied secrets as safe

By OpenClawBlog Team

A failed laptop, a machine move, or a bad update can turn OpenClaw’s state directory into the most important folder on the host. It is also easy to handle it like an ordinary configuration directory: copy it while the Gateway is running, transfer the archive, and assume the job is finished.

That shortcut misses the harder question. What authority did the copy carry, who can read it now, and what happens when the restored files refer to the old machine?

OpenClaw’s migration guide places the default state directory at ~/.openclaw and lists configuration, authentication stores, sessions, channel state, and workspace material among the data involved in a move. The current backup CLI reference provides a supported archive and restore path. Its warning is the part worth keeping: backups can contain auth profiles, tokens, and provider credentials.

This tutorial follows that path. It distinguishes documented behavior from checks you should perform locally, and it treats the archive as a copy of potentially usable credentials. A compressed file is not automatically a safe secret store.

The short version

On the Gateway host, first confirm which state tree the running installation uses. Preview the archive, stop the Gateway, then create a verified archive:

openclaw status
openclaw backup create --dry-run --json
openclaw gateway stop
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

The expected result is a timestamped .tar.gz archive. Read the command output instead of checking only that a file appeared. The JSON report can identify skipped volatile entries, warnings, and links that point outside the selected tree.

On the recovery host, verify the archive and extract it into a new staging directory:

openclaw backup verify /protected/path/openclaw-backup.tar.gz
openclaw backup restore /protected/path/openclaw-backup.tar.gz --target ~/openclaw-restore-staging

The target must be new or empty. Restore does not activate files in place. Review the extracted manifest, correct paths and ownership, then activate the restored state as a separate offline step. Run Doctor before restarting the Gateway.

Know the boundary before you copy it

The phrase state directory sounds narrower than it is. OpenClaw plans a full archive from the installation’s configured sources. The CLI documentation lists the state directory, the active configuration file, credentials stored outside that directory, every configured agent directory, workspace directories, and durable resources declared by loadable plugins.

That matters when an agent root lives somewhere else. A custom agent directory can remain authoritative even when it is outside ~/.openclaw. Copying only the visible default directory can therefore leave the restored installation without its agent database or auth state.

Workspace files are another boundary. Full archives include configured workspaces by default. If the workspace contains repositories or large generated files, you can use --no-include-workspace and protect the workspace separately. This flag does not omit configured agent directories, including agent roots outside the state directory. Inspect the planned result before relying on it.

--only-config is smaller but incomplete. It archives the active JSON configuration file, not a full state tree. The CLI documentation also notes that this mode does not include configuration files referenced through modular include directives. It can be useful for a narrow configuration recovery, but it is not a substitute for the full archive.

Profiles make the path easy to misread. OpenClaw can use a profile-specific directory such as ~/.openclaw-<profile>/, or a location set through OPENCLAW_STATE_DIR. The migration guide recommends running openclaw status on the old machine to confirm the active path. If the user interface connects to a remote Gateway, the Gateway host owns the sessions and workspace. Backing up the laptop that displays the interface may capture nothing useful.

Why a live directory copy is not enough

Current OpenClaw state includes SQLite databases. The backup command captures OpenClaw-owned databases through SQLite’s online backup API, verifies them, and compacts private copies before archiving. The CLI reference explicitly says not to copy live .sqlite, -wal, -shm, or -journal files as a portability artifact.

A raw copy can catch the main database and its sidecars at different moments. That leaves the recovery tool with files that look complete but do not describe one usable state. Stopping the Gateway before the archive also keeps configuration, queues, and other files from changing while the backup is being assembled. This is a consistency measure, not a claim that every file in the archive forms one cross-file transaction.

The CLI documentation says configuration files are pinned before database capture and that later writes may not appear in the archive. Stopping the Gateway narrows that window. It does not turn the archive into an atomic snapshot of every configured workspace, plugin, and external file.

Create a useful archive

Use the dry run to inspect scope before the maintenance window. Look for custom agent roots, credentials directories outside the state directory, workspaces you did not intend to include, and external symbolic links. If the plan contains an unexpected path, resolve that first.

After stopping the Gateway, run the verified archive command from a protected destination. OpenClaw writes a manifest that records the archive layout and the resolved source paths. The verification pass checks the archive structure, manifest-declared payloads, and the SQLite snapshots included in the archive.

Some files are deliberately omitted because they are live or rebuildable. The documented filters include session and log files with selected extensions, delivery queue entries, process and socket files, browser singleton files, and generated sandbox skill workspaces. Completed transcript and log files that match those filters are omitted too. If those records are part of your retention requirement, preserve them through a separate process rather than assuming the state archive contains them.

Plugin dependencies need the same care. Installed plugin source and manifest files can be included, while nested node_modules trees are treated as rebuildable. After activation, a plugin that reports missing dependencies may need an update or reinstall. The generated plugin-skills/ symlink index is also rebuilt from plugin metadata.

Read the manifest and the report. A successful archive command proves that OpenClaw completed its archive operation and verification checks. It does not prove that your intended workspace was included, that excluded logs are acceptable, or that a provider will accept a restored session.

Protect the archive as a credential-bearing artifact

OpenClaw’s backups guide says that archives contain auth profiles, channel and provider credentials, session history, and other sensitive records. It recommends encrypted storage, restricted access, and the same destination controls used for the live state directory. The migration guide gives the same advice and says to rotate keys if exposure is suspected.

That warning changes the backup procedure. Store the archive in a private location. Keep its encryption key or passphrase separate from the archive. Do not paste it into an issue, upload it to a public repository, or leave an unprotected plaintext extraction in a temporary directory. These are operational controls, not features that OpenClaw can infer from the filename.

Encryption at rest limits who can read the file while the control is working. It does not change the meaning of a token after decryption. A person who obtains the archive and its key may have a usable copy of the same authority that the live installation holds.

For a versioned remote backup, OpenClaw documents a separate openclaw backup git path. Its redaction option omits documented credential-bearing tables and machine-state prefixes. A redacted history is not a full-fidelity restore: devices may need to be paired again and providers may need fresh authentication. Use that tradeoff deliberately. Do not describe a redacted Git snapshot and a credential-complete archive as equivalent artifacts.

Restore into a fresh staging directory

Install OpenClaw on the recovery host and keep its Gateway stopped. The migration guide allows a fresh default directory created during onboarding because the restored state is handled separately. Choose a new target that is not inside the live state directory or a configured live agent directory.

Run openclaw backup verify before extraction when the archive has crossed a machine or storage boundary. Verification checks structure and payload integrity, but the backup CLI warns that verification does not authenticate an archive or make untrusted content safe. Treat an archive from an unknown source as untrusted input even when its hashes and SQLite checks pass.

Then run openclaw backup restore against the fresh target. OpenClaw verifies the archive before writing, refuses a non-empty target, removes incomplete extraction output when extraction fails, and has no in-place or force mode. Those restrictions are useful because they keep the restore from silently merging old and new state.

Open the extracted manifest.json and use it as the map for the state, configuration, credentials, workspace, and agent assets. Review symbolic links before activation. OpenClaw preserves links as links and does not follow them to copy their targets. Absolute links retain their original target locations, so a restored link can still point at a path on the old host or at a separately backed-up credential file.

That is a real failure boundary, not a cosmetic warning. A link to an old path can make the restored Gateway appear incomplete. A link to a sensitive path can also reconnect the installation to data you did not intend to transfer. Correct the target or the configuration before starting the Gateway.

Activate the restored state offline

Activation is separate from extraction. With the destination Gateway stopped, either move the restored state asset into the location described by the manifest or point OPENCLAW_STATE_DIR at that restored asset. If the service uses an environment file or supervisor definition, make the same state-directory choice there. Setting the variable only in an interactive shell can leave the service reading the original empty directory.

Restore custom agent roots to the locations recorded in the manifest, or update the configuration to their new locations before startup. Confirm that the state tree and workspace are owned by the account that will run the Gateway. A copy made as root or restored under another user can leave credentials unreadable.

Run the documented checks in order:

openclaw doctor
openclaw gateway restart
openclaw status

Doctor can apply configuration migrations and report state or service problems. Status tells you whether the Gateway is using the expected installation. For an additional configuration check, run openclaw security audit. The security page presents that command as a way to detect security drift, not as proof that a backup archive was safe.

For a remote setup, run these checks on the Gateway host. A browser or chat client on another machine does not own the restored sessions.

Failure paths and limits

The archive refuses to publish

OpenClaw may refuse a state archive when it cannot resolve agent or plugin ownership. The CLI documentation says --no-include-workspace does not bypass that discovery requirement. Repair the configuration or the missing path, then retry. If you use --only-config as an emergency fallback, label the result clearly as a configuration-only artifact.

The restore is empty or channels appear logged out

Check the profile and state-directory selection before inspecting credentials. The migration guide says a mismatch can produce empty sessions and logged-out channels. Confirm that the service and the interactive CLI use the same profile and OPENCLAW_STATE_DIR value.

A channel does not reconnect after restore

Restoration is time travel. The backup reference warns that ratcheting channel credentials, especially WhatsApp state, can become desynchronized after rollback. Approvals and delivery or deduplication state also roll back. Re-pair or relink the channel according to its provider flow instead of repeatedly restoring the same archive.

A plugin starts without its dependencies

Reinstall or update the plugin after activation. Its dependency tree may have been omitted intentionally. Do not copy an arbitrary old node_modules directory into the restored state and assume it matches the current OpenClaw runtime.

The archive was exposed

Assume the credentials inside it may have been read. Rotate or revoke the affected provider keys, tokens, OAuth material, and channel credentials through their respective providers. Then create a new backup from the known-good state. Deleting the archive removes one copy; it does not invalidate a token that was already copied.

A recovery checklist

• Confirmed the actual Gateway host, profile, and state directory.
• Decided whether workspaces are included or protected separately.
• Stopped the Gateway before creating the archive.
• Used openclaw backup create instead of copying live SQLite files.
• Read the dry-run report, manifest, skipped entries, warnings, and external links.
• Stored the archive encrypted with restricted access.
• Kept the decryption key separate from the archive.
• Verified and restored into a fresh target.
• Reviewed absolute links, ownership, custom agent roots, and provider paths.
• Ran Doctor and security checks before resuming normal traffic.

The reliable promise is modest: OpenClaw gives you a verified archive and a restore operation that avoids overwriting live state. The security promise must come from the operator. A backup preserves credentials because recovery may require them. Protect the copy as if those credentials are still active, because they may be.

Sources

• OpenClaw backup CLI reference — archive contents, verification, restore targets, omitted volatile files, symbolic links, plugin dependencies, and redacted Git backups.
• OpenClaw backups guide — supported backup paths, SQLite handling, offsite storage, and sensitive archive warnings.
• OpenClaw migration guide — state-directory locations, machine-move steps, staging restores, activation, ownership, and credential exposure limits.
• OpenClaw security — Gateway trust boundaries and the documented security audit command.
• OpenClaw updating documentation — why automatic update copies are not a full-state backup and which post-update checks are documented.