OpenClaw Backups: Recover Agent State Before an Ops Mistake Costs a Day

The scariest OpenClaw failure is not a model error. It is the quiet operational mistake: a config change that points at the wrong workspace, a credentials migration that breaks a channel, a reset done before someone checked where session state lives, or a teammate cleaning up files they thought were temporary.

Agents become valuable when they accumulate state. They learn your workspace rules, keep project notes, hold channel context, and operate against real credentials. That is exactly why backup discipline belongs in the operator runbook. If your agent can touch production work, you need a boring way to prove what would be backed up before you change the machine underneath it.

OpenClaw gives you that first-class path with openclaw backup. It creates local .tar.gz backup archives for OpenClaw state, the active config file, credentials, sessions, and optionally workspaces. The important part is not the command itself. It is the habit: preview, create, verify, then make the risky change.

Know the two places your agent lives

The OpenClaw workspace docs draw a clean boundary. The workspace is the agent's home and the default working directory for file tools and workspace context. By default, it lives at ~/.openclaw/workspace, or at ~/.openclaw/workspace-<profile> when OPENCLAW_PROFILE is set to a non-default profile.

That workspace is private memory. It usually contains files like AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, optional HEARTBEAT.md, and daily files under memory/YYYY-MM-DD.md. Those are the files that tell the agent how to behave, who it is helping, and what it should remember.

OpenClaw's state directory is separate. The docs say ~/.openclaw/ stores config, credentials, skills, and session data. The workspace docs are explicit that files such as ~/.openclaw/openclaw.json, credentials, model auth profiles, session transcripts, and managed skills should not be committed to the workspace repo. If you back up only the workspace, you have not backed up the whole operating surface.

That distinction matters during recovery. A private git repo is useful for workspace files, and the docs recommend it. But git does not automatically cover credentials, active config, auth profiles, or session stores under ~/.openclaw/. The backup archive is the broader local safety net.

Preview before you trust the archive

The fastest safe pattern starts with a dry run. The backup docs include openclaw backup create --dry-run --json so an operator or automation job can inspect the planned sources before writing an archive. That is the moment to catch surprises: the wrong active config, a missing workspace, or an output path that would live inside a source tree.

openclaw backup create --dry-run --json
openclaw backup create --output ~/Backups --verify
openclaw backup verify ~/Backups/2026-05-21T15-30-00.000Z-openclaw-backup.tar.gz

When openclaw backup create writes an archive, it includes a manifest.json with resolved source paths and archive layout. Existing archive files are never overwritten. The default output is a timestamped .tar.gz in the current working directory, but if that directory is inside a backed-up source tree, OpenClaw falls back to the home directory so the archive does not include itself.

There are two verification paths worth using. openclaw backup create --verify validates the archive right after creation. openclaw backup verify <archive> validates an existing archive later. The docs say verification checks that the archive contains exactly one root manifest, rejects traversal-style archive paths, and confirms every manifest-declared payload exists in the tarball.

That is a better success condition than “the command exited zero once last month.” It means the backup is structurally readable and contains the files its own manifest promised.

Decide whether the workspace belongs in tonight's backup

By default, openclaw backup create discovers workspace directories from the current config and includes them. That is usually what you want before a host migration or a serious reset. But large workspaces are also the main driver of archive size and compression time. The docs do not impose a built-in maximum backup size or per-file limit; practical limits come from disk space, filesystem behavior, and the time needed to walk and compress big trees.

For smaller or faster backup runs, use --no-include-workspace. That keeps the state, config, and credentials in scope while skipping workspace discovery. If all you need is the active JSON config file, --only-config creates the smallest archive and avoids state, credentials, and workspace discovery.

openclaw backup create --no-include-workspace --verify
openclaw backup create --only-config
openclaw config file
openclaw config validate --json

The malformed-config behavior is especially operator-friendly. The backup command intentionally bypasses normal config preflight so it can still help during recovery, but workspace discovery depends on valid config. If the config file exists and is invalid while workspace backup is still enabled, the command fails fast. In that situation, the docs recommend rerunning with --no-include-workspace for a partial backup, or --only-config when you only need a copy of the config file.

That gives you a safe ladder instead of an all-or-nothing failure: first preserve what can be preserved, then repair the config.

Back up before risky operator moves

I would treat these as automatic backup moments: before changing the active workspace path, before editing model or channel config, before rotating credentials, before uninstalling or resetting OpenClaw, before migrating to a new machine, and before letting a new automation lane touch production state.

The config docs give you the other half of the runbook. openclaw config file prints the active config path. openclaw config get reads a path such as agents.defaults.workspace. openclaw config validate --json validates the active config against the schema without starting the Gateway. If you are about to make a change, knowing the exact active config file is not optional.

OpenClaw also supports dry-run config changes. For example, SecretRef assignments and config patches can be checked before writing. The docs explain that dry runs can perform schema and supported SecretRef resolvability checks, while exec-backed SecretRefs are skipped unless the operator explicitly opts into execution. That matters because a config check should not quietly run arbitrary credential commands unless you meant it to.

This is the pattern I like: use config file to confirm the target, use backup create --dry-run --json to inspect the backup plan, use backup create --verify to write a verified archive, then use config dry-run or validation before applying a change.

Do not confuse workspace backup with sandboxing

The workspace docs include one warning every operator should internalize: the workspace is the default current working directory, not a hard sandbox. Relative paths resolve there, but absolute paths can still reach elsewhere on the host unless sandboxing is enabled.

If you need isolation, the docs point to agents.defaults.sandbox or per-agent sandbox config. When sandboxing is enabled and workspace access is not "rw", tools operate inside a sandbox workspace under ~/.openclaw/sandboxes instead of the host workspace.

Backups and sandboxes solve different problems. A backup helps you recover after state loss or a bad change. A sandbox reduces what a session can reach during execution. You usually want both for serious operator work: sandbox boundaries before the run, backup evidence before the maintenance window.

If your agent is becoming part of the business, backup discipline is not optional. Want the full operator playbook? Get ClawKit — $9.99.

Use status as your recovery proof

A backup archive is only one artifact. After a risky change or migration, you still need to prove the live control surface is healthy. The status docs describe openclaw status as diagnostics for channels and sessions, with deeper variants for live probes and usage windows.

openclaw status
openclaw status --all
openclaw status --deep
openclaw status --usage

Plain openclaw status stays on a fast read-only path. status --all expands the report. status --deep runs live probes for supported channels such as WhatsApp Web, Telegram, Discord, Slack, and Signal. status --usage prints normalized provider usage windows as percentages remaining.

The status docs also note useful recovery details: output includes per-agent session stores when multiple agents are configured, Gateway and node host service runtime where available, update channel and git SHA for source checkouts, and supported SecretRef diagnostics without turning a missing token into a crash. That makes it a practical post-change check, not just a vanity health command.

For a production operator, “restored” should mean more than “files copied.” It should mean the active config validates, the expected workspace path is selected, the relevant channels show healthy or correctly degraded status, and any missing SecretRef or channel token is visible before the next automation run.

What a real recovery runbook looks like

Keep the runbook boring. First, identify the active config and workspace. Second, run a dry-run backup and inspect what it plans to include. Third, create a verified archive to a destination outside the backed-up source trees. Fourth, make the intended change. Fifth, run config validation and status checks. Sixth, record where the archive lives and what changed.

Do not promise a clean rollback you have never practiced. OpenClaw's backup command gives you a verified archive and manifest. Your recovery process still needs human judgment about which state, config, credentials, or workspace files to restore on the target machine. That is why the manifest matters: it tells you what was captured and where it came from.

Also do not put secrets in the workspace just because the workspace is private. The docs explicitly warn against committing API keys, OAuth tokens, passwords, private credentials, anything under ~/.openclaw/, raw chat dumps, or sensitive attachments. Keep the real secrets in the state/credential system, not in a memory file that gets pushed to git.

The operator standard is simple: before an agent touches valuable state, prove you can preserve it. Before you change the control plane, prove you know which config and workspace are active. Before you say a migration is done, prove the live status is healthy. That is how you keep an AI operator from becoming another fragile server nobody wants to touch.

Want the complete guide? Get ClawKit — $9.99