When an OpenClaw Backup Becomes a Second Secret Store

June 27, 2026 · Security

A backup should answer a practical question: what can be restored if the Gateway host disappears? With OpenClaw, the answer may include much more than configuration. A full archive can contain authentication profiles, channel credentials, provider state, sessions, workspace files, and plugin resources.

That makes the archive a second secret store in a precise sense. It is a second place where secret-bearing bytes may exist at rest. It is not a second OpenClaw service, and every archive will not contain every credential. The custody decision is still the same: who can read the copy, where is its decryption key, and which credentials might remain valid after the archive leaves the Gateway host?

The safer design is to keep two artifacts with different jobs. Use a protected full-fidelity archive when you need continuity. Keep a separate recovery record that tells an operator what to reinstall, where the state belongs, which secret manager references to use, and how to verify the result. The recovery record should help rebuild access without becoming another file that can log in.

The archive carries authority as well as data

OpenClaw's backup guide describes a full archive as a copy of state, configuration, credentials, configured agent directories, and workspaces by default. It also warns that backups contain auth profiles, channel and provider credentials, session history, and other sensitive records.

The backup CLI reference makes the boundary wider than a glance at ~/.openclaw suggests. The command plans the state directory, the active configuration file, a credentials directory outside the state directory when one exists, every configured agent directory, discovered workspaces, and durable resources declared by loadable plugins. A custom agentDir can remain authoritative even when it lives outside the normal state tree.

This is why a backup can be useful and dangerous at the same time. If a decrypted archive contains a still-valid provider key, anyone who can read that entry has another copy of the key. That conclusion is an operational inference from the archive contents, not a claim that OpenClaw grants the reader a new permission.

Scope flags do not erase this decision. --no-include-workspace omits ordinary workspace sources, but it does not omit configured agent directories. --only-config is smaller still: it archives the active configuration file and is not a complete state recovery point. The CLI also says a full archive is not one atomic snapshot across configuration and every database, so its timestamp should be part of the recovery record.

A recovery record is a different artifact

A recovery record is a small runbook, not a stripped-down backup. It should tell a future operator how to find the real archive and how to rebuild the parts that were deliberately left out. It should not contain a Gateway token, provider API key, OAuth refresh token, channel session file, cookie, private key, or password.

Keep the record outside the OpenClaw state directory and outside the workspace when independence matters. Workspaces are commonly included in full archives, so storing the record beside the data it describes can quietly copy it into every credential-bearing archive. A private repository or controlled operations system may be suitable for the record, but access to it should still be limited because paths, account names, and provider relationships reveal deployment structure.

An illustrative record might look like this:

gateway_host: gateway-01
profile: production
state_dir: /srv/openclaw-prod
agents:
  - id: main
    agent_dir: /srv/openclaw-prod/agents/main
provider_auth:
  - provider: openai
    method: secretref
    reference: vault://team/openclaw/openai-production
channels:
  - name: telegram
    account: support
    recovery: re-authenticate, then verify delivery
archive:
  location: private-object-storage://openclaw/opaque-archive-name
  sha256: recorded-in-operations-system
  encryption_key_ref: vault://team/openclaw/backup-key
  contains_live_credentials: true

This is an example for a human operator, not an OpenClaw configuration file. The reference points to the place where a credential can be issued or retrieved. It does not contain the credential itself.

Choose the recovery artifact by the failure you expect

A full archive is appropriate when the goal is to preserve sessions, channel continuity, custom agent state, or a complete machine move. OpenClaw's supported archive path captures OpenClaw-owned SQLite databases through an online backup process and verifies the resulting manifest and payload. The archive still needs encrypted storage, restricted access, and a separate key. Those controls remain the operator's responsibility.

A redacted Git history is a different compromise. OpenClaw documents --exclude-secrets for omitting credential-bearing tables and selected machine-state prefixes. Pushed schedules redact those areas by default because remote Git history is durable. The same documentation warns that a restore from redacted history requires device re-pairing and provider re-authentication. Mark the artifact as redacted and incomplete in the recovery record. Do not let a familiar Git workflow make it look like a full backup.

A recovery record is useful in both cases. It tells the operator whether to expect a working channel or a fresh login, where custom agents live, which provider profile should be recreated, and which checks must pass before traffic resumes. It is also the right artifact when a team wants a repeatable rebuild path but cannot justify storing full credentials in another system.

A safer sequence for creating both artifacts

1. Identify the real Gateway. Run openclaw status on the host that owns the Gateway. In remote mode, the session store and workspace belong to that host, not to the laptop displaying the interface. Record the active profile and state-directory path before collecting anything.
2. Preview the scope. Use openclaw backup create --dry-run --json and inspect the planned sources, skipped paths, custom agent roots, workspace inclusion, and external symbolic links. Resolve an unexpected path before creating a portable archive.
3. Audit the live state separately. The read-only openclaw secrets audit --check scans configuration, auth stores, generated model files, and legacy residues for plaintext, unresolved references, and precedence problems. A clean audit is evidence about the live state. It is not a sanitizer for an archive that already exists. If the installation uses exec-backed references, decide separately whether an audit with --allow-exec is acceptable, because provider commands may run.
4. Quiesce the Gateway. Stop it before the archive so files and databases are not changing during the copy. Use the supported command rather than copying live SQLite files and their -wal, -shm, or -journal sidecars.
5. Create and protect the archive. A documented full-archive sequence is:

openclaw gateway stop
openclaw backup create --output ~/Backups/openclaw --verify

Move the finished archive through a protected channel. Store it encrypted with access controls comparable to the live state directory, and keep the decryption key in a separate control boundary. Add the archive location, digest, scope, and classification to the recovery record. Do not put the passphrase in that record.

6. Test recovery in a fresh target. OpenClaw's restore operation refuses a non-empty target and does not activate files in place. The proposed check is:

openclaw backup verify <archive.tar.gz>
openclaw backup restore <archive.tar.gz> --target ./restored-openclaw

Inspect the extracted manifest.json, paths, ownership, and symbolic links while the Gateway remains stopped. If the test proceeds to activation, use the manifest to place state, configuration, workspace, and custom agent roots, then run openclaw doctor before restarting. Record what was actually tested. A planned test is not evidence that recovery works.

Failure paths the record must make visible

The profile is wrong

OpenClaw's migration guide warns that a profile or state-directory mismatch can leave channels logged out and sessions empty. Write the exact profile and state path into the record, and name the Gateway host. A note saying only restore OpenClaw is not enough for a remote deployment.

The archive is redacted

Redaction lowers credential exposure, but it changes the recovery promise. The operator may need to re-authenticate providers and re-pair devices. Write that limitation beside the archive location, not in a separate document that may be missed during an outage.

The archive leaks

OpenClaw's incident-response guidance says to assume compromise when secrets leak. Its rotation list includes Gateway authentication, remote-client secrets, provider and API credentials, channel credentials, and model credentials stored in SQLite. Deleting the archive removes one copy; it does not revoke a provider key that someone already read. The authentication documentation makes the same operational point for saved provider auth: removing it from OpenClaw does not revoke it at the provider.

The restore points to the old machine

Absolute symbolic links retain their original target locations. The backup CLI preserves the link rather than copying the target, so a restored link can still point at an old host path or at a separately backed-up credential file. List external links in the recovery record and require a review before activation.

A channel rolls back in time

Restoring an old archive can desynchronize ratcheting channel credentials, especially WhatsApp. Approvals and delivery or deduplication state also roll back. The record should say whether a channel needs relinking and whether pending approvals must be reviewed before the Gateway resumes normal traffic.

A plugin is present but incomplete

Plugin node_modules trees are treated as rebuildable and are not archived. Record the plugin IDs and the documented update or reinstall step. Do not solve a missing dependency by copying an arbitrary old dependency tree into a restored state and calling the test complete.

Verification passes but trust is unresolved

openclaw backup verify checks archive structure, manifest-declared payloads, symbolic-link safety, and selected SQLite integrity. The CLI explicitly says verification does not authenticate an archive or make untrusted content safe. A valid archive from an unknown source is still untrusted input. Record who created it, how it was transferred, and which key or signature system protects its provenance.

The practical boundary

A full backup can be the right recovery artifact and still be the wrong place to keep the only recovery instructions. Keep the archive for continuity. Keep a separate, low-sensitivity record for paths, provider references, re-authentication steps, version requirements, scope limits, and validation results.

The record is safer only when it cannot authenticate by itself and is stored away from the credential-bearing copy. A successful verification proves that OpenClaw accepted the archive's structure and integrity checks. It does not prove that secrets were absent, that the archive came from a trusted operator, or that every provider will accept state from an earlier point in time.

Sources

• Backups - OpenClaw — archive contents, sensitive-record warning, redacted Git schedules, offsite storage, and restore tradeoffs. Accessed 2026-09-13.
• Backup - OpenClaw — source planning, manifests, scope flags, verification limits, symbolic links, SQLite handling, and fresh-target restore. Accessed 2026-09-13.
• Secrets, storage, and logs - OpenClaw — credential-bearing paths, shared and per-agent databases, channel state, and filesystem controls. Accessed 2026-09-13.
• Migration guide - OpenClaw — Gateway ownership, profiles, state-directory paths, staging restore, permissions, remote mode, and backup exposure. Accessed 2026-09-13.
• Secrets CLI - OpenClaw — read-only secret audits, plaintext findings, unresolved references, and safe secret-store behavior. Accessed 2026-09-13.
• Authentication - OpenClaw — provider auth storage, profile migration, status checks, and provider-side revocation limits. Accessed 2026-09-13.
• Operator incident response - OpenClaw — containment, credential rotation, audit steps, and evidence collection after a leak. Accessed 2026-09-13.