OpenClaw Backup and Recovery: Protect Agent Memory

Key takeaways

• openclaw backup create archives your config, credentials, cron jobs, and workspace in one timestamped .tar.gz file.
• Your workspace (~/.openclaw/workspace/) holds your agent's memory: AGENTS.md, SOUL.md, skills, and memory files. Back it up with git and with the backup command.
• Cron jobs live at ~/.openclaw/cron/jobs.json. This file is not inside the workspace, so a git sync alone won't capture it.
• Recovery is manual: extract the archive, drop files back in place, restart the gateway.
• Run openclaw backup create --verify after every backup to confirm the archive is valid before you need it.

What OpenClaw backup covers: files, cron, and credentials

openclaw backup create captures the parts of OpenClaw you'd actually miss in a bad restore: config, credentials, cron jobs, sessions, and your workspace. According to the official backup reference, the command packages four categories of data from your install:

• State directory (~/.openclaw/): config, cron, sessions, and logs
• Active config file (~/.openclaw/openclaw.json): always included, even redundantly
• Credentials directory: OAuth tokens and API key storage
• Workspace directories: discovered from config unless you pass --no-include-workspace

What it does NOT capture by default: anything outside these four paths. If you store project files in a custom location outside the workspace, you need a separate backup strategy for those.

Two directories are the heart of an OpenClaw instance. The agent workspace docs describe them clearly:

• ~/.openclaw/ stores config, credentials, and sessions. This directory contains secrets. Keep it out of version control.
• ~/.openclaw/workspace/ (or a custom path set via agent.workspace) is the agent's memory. AGENTS.md, SOUL.md, USER.md, TOOLS.md, skills, and any files your agent reads or writes. The official recommendation is to treat this as private memory and put it in a private git repo.

OpenClaw generates a manifest.json inside every backup archive that records the resolved absolute source paths and archive layout. That manifest is what openclaw backup verify checks when you validate an archive.

How to back up OpenClaw with one command

If you want the shortest safe path, run one verified backup first, then inspect the archive only if you need to recover something specific.

Prompt for your agent: Run a full OpenClaw backup and save the archive to my home directory. Verify the archive after it's written. Tell me the filename and size when it's done.

Manual backup steps:

Full backup with verification:

openclaw backup create --output ~/backups --verify

Config-only backup (fast, useful before risky config edits):

openclaw backup create --only-config

Skip the workspace (faster for large workspace trees):

openclaw backup create --no-include-workspace

Verify an existing archive:

openclaw backup verify ./2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz

The archive filename is a UTC timestamp, so archives sort chronologically in any file listing. According to the backup CLI reference, OpenClaw never overwrites an existing archive. If you run backup create twice in the same second, the second command uses a different timestamp.

If openclaw backup create fails with an "invalid config" error and your workspace backup is enabled, your config file may be malformed. In that case, fall back to:

openclaw backup create --no-include-workspace

Or capture just the config:

openclaw backup create --only-config

Both modes skip workspace discovery, which is what triggers the failure when the config can't be parsed.

Automate OpenClaw backups with a cron job

The most reliable backup is one you don't have to remember. Schedule a daily backup job using the OpenClaw cron scheduler so the archive runs without manual intervention.

You do not want backups to depend on memory. Schedule them once, verify the archive, and let the job run quietly in the background.

Prompt for your agent: Set up a cron job that runs every night at 2 AM and creates an OpenClaw backup in ~/backups. Name the job "Daily OpenClaw Backup".

Manual cron setup:

openclaw cron add \
  --name "Daily OpenClaw Backup" \
  --cron "0 2 * * *" \
  --tz "UTC" \
  --session isolated \
  --message "Run: openclaw backup create --output ~/backups --verify"

Confirm the job registered:

openclaw cron list

See the OpenClaw cron jobs guide for more on scheduling patterns, session targets, and delivery options.

A rolling window of at least 7 daily archives is a reasonable minimum. Older archives grow stale as your config and memory evolve. This is a general best practice, not a built-in OpenClaw retention policy. You manage your own archive rotation.

Back up OpenClaw workspace to a private git repo

The official FAQ recommends a private git repo for the workspace. This gives you two things openclaw backup create alone doesn't: change history (you can see exactly which line of AGENTS.md changed on which day) and off-site replication without manual archive transfers.

Set up the workspace git repo:

cd ~/.openclaw/workspace
git init
git remote add origin git@github.com:yourname/openclaw-workspace-private.git

Create a .gitignore at the workspace root:

.env
*.key
*.pem
secrets/

Credentials live in ~/.openclaw/credentials/, not in the workspace, so a workspace git repo doesn't expose tokens. But any .env files or secret files you dropped in the workspace should be excluded from commits.

Commit and push after significant changes:

cd ~/.openclaw/workspace
git add -A
git commit -m "update AGENTS.md pipeline rules"
git push origin main

The workspace repo captures everything your agent reads: AGENTS.md, SOUL.md, USER.md, TOOLS.md, skills, memory files, and any project files. If you restore the workspace from this repo on a fresh machine, your agent starts with its full context intact.

The workspace git strategy and openclaw backup create serve different purposes. Git gives you history and cheap off-site sync. The backup command captures ~/.openclaw/ state that git doesn't touch: sessions, cron jobs, and credentials.

Protect OpenClaw cron jobs from data loss

Cron jobs are the most commonly lost data when an OpenClaw instance is wiped. The reason: most users know to back up config files and workspace files, but cron jobs persist separately at ~/.openclaw/cron/jobs.json. That file is inside ~/.openclaw/, so openclaw backup create captures it. But a workspace-only git sync misses it entirely.

Verify your jobs.json is getting captured:

openclaw backup create --verify
tar -tzf ./2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz | grep jobs.json

If jobs.json appears in the tar listing, you're covered.

Manual snapshot before changes:

Before editing cron jobs manually (the docs say manual edits to jobs.json are only safe when the Gateway is stopped), copy the file first:

openclaw gateway stop
cp ~/.openclaw/cron/jobs.json ~/.openclaw/cron/jobs.json.bak

Make your edits, then restart:

openclaw gateway start

Recovering lost cron jobs from a backup archive:

tar -xzf ./2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz \
  --strip-components=2 \
  -C ~/.openclaw/cron/ \
  "*/cron/jobs.json"
openclaw gateway restart
openclaw cron list

See the persistent memory guide if your agent's memory files were also affected.

Recover OpenClaw from a corrupted config

A corrupted openclaw.json is one of the more disruptive failures. The gateway won't start, and most CLI commands that depend on config parsing will also fail. Here's the recovery path.

Symptoms of a corrupted config:

• openclaw gateway start exits immediately with a JSON parse error
• openclaw status returns "could not read config" or similar
• Cron jobs stop running silently

Step 1: Try the doctor first

openclaw doctor --fix

openclaw doctor --fix can repair and migrate common config issues without needing a full restore. If the file is syntactically broken, doctor may not be able to help, but try it first.

Step 2: Restore config from a backup archive

tar -xzf ./2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz \
  --strip-components=1 \
  -C ~/.openclaw/ \
  "*/openclaw.json"

Step 3: If no backup exists, restore from the last-only-config backup

If you ran openclaw backup create --only-config before the corruption, you have a small archive containing just the config:

tar -xzf ./config-only-backup.tar.gz -C ~/.openclaw/

Step 4: Restart and verify

openclaw gateway start
openclaw status

If the gateway starts and status returns clean, you're recovered. If not, run openclaw doctor again after the restart.

Restore OpenClaw workspace and memory after a wipe

Workspace wipes feel catastrophic because they erase your agent's memory files: AGENTS.md, SOUL.md, memory notes, and any skills or projects. Recovery depends on which backup source you have.

Option A: Restore from openclaw backup archive

BACKUP=./2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz
tar -tzf "$BACKUP" | grep workspace

Locate the workspace path in the archive, then extract:

tar -xzf "$BACKUP" -C /

This restores to the original absolute paths recorded in the archive's manifest.json.

Option B: Restore from git repo (workspace only)

If you kept the workspace in a private git repo:

cd ~/.openclaw/workspace
git pull origin main

Or on a fresh machine:

git clone git@github.com:yourname/openclaw-workspace-private.git ~/.openclaw/workspace

Restart the gateway after any workspace restore:

openclaw gateway restart
openclaw status

The agent picks up the restored workspace on the next message it receives.

Migrate OpenClaw to a new server

A server migration is a controlled version of disaster recovery: same steps, less urgency.

On the source server:

openclaw backup create --output ~/migration-backup --verify

Transfer the archive to the new server. scp works fine for this:

scp ~/migration-backup/2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz user@new-server:~/

On the new server:

Install OpenClaw first, then stop the gateway before restoring:

openclaw gateway stop

Extract the archive:

tar -xzf ~/2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz -C /

Start the gateway and verify:

openclaw gateway start
openclaw status
openclaw cron list

Check that cron jobs resumed, channels reconnected, and the workspace files are present.

For multi-agent setups, see the OpenClaw multi-agent setup guide for additional steps around per-agent workspace paths and config references.

OpenClaw backup verification: confirm your archives are valid

A backup you've never verified is a backup you can't trust. OpenClaw includes a verify command for exactly this reason.

Verify immediately after creating:

openclaw backup create --verify

The --verify flag runs validation right after writing the archive. It checks:

• The archive contains exactly one root manifest
• No traversal-style archive paths exist (a security check)
• Every file declared in manifest.json actually exists in the tarball

Verify an existing archive:

openclaw backup verify ./2026-03-23T00-00-00.000Z-openclaw-backup.tar.gz

Test your restore path before you need it. On a test machine or inside a Docker container, extract your most recent archive and confirm the gateway starts. Discovering a corrupt archive during an actual outage adds a bad variable to an already stressful situation.

Key terms

State directory: ~/.openclaw/ by default. Holds config, sessions, cron jobs, and internal state. Contains secrets; do not commit to version control.

Workspace: The agent's file-accessible home directory, default ~/.openclaw/workspace/. Contains AGENTS.md, SOUL.md, USER.md, memory, skills, and project files. Safe to put in a private git repo.

Credentials directory: OAuth tokens, API keys, and channel auth data. Included in openclaw backup create archives.

manifest.json: Embedded in every backup archive. Records the resolved absolute source paths and archive layout used for each asset. What openclaw backup verify reads to validate the archive.

jobs.json: ~/.openclaw/cron/jobs.json. The on-disk store for all cron job definitions. Edits are only safe when the gateway is stopped.

FAQ

How do I back up OpenClaw without losing cron jobs?

Run openclaw backup create, which captures the full state directory including ~/.openclaw/cron/jobs.json. A workspace-only git sync misses cron jobs because jobs.json lives in ~/.openclaw/, not in the workspace folder. After backup, run openclaw backup verify to confirm the archive includes the cron directory.

What happens to OpenClaw memory files if the server crashes?

Any memory files in ~/.openclaw/workspace/ that weren't committed to a git repo or captured in a recent backup are gone. The crash itself doesn't corrupt files that were already written to disk, but anything written between your last backup and the crash is lost. Run daily automated backups via cron and push your workspace to a private git repo to minimize the window of potential loss.

Can I restore just one file from an OpenClaw backup archive?

Yes. OpenClaw backup archives are standard tar.gz files. Use tar -tzf archive.tar.gz to list contents, locate the file path in the listing, then extract that specific path with tar -xzf archive.tar.gz path/to/file. This is useful for restoring a single corrupted memory file or recovering a specific version of AGENTS.md without overwriting your entire workspace.

Does OpenClaw backup include API keys and bot tokens?

Yes. The credentials directory is included in the default openclaw backup create archive. Store these archives somewhere private, with access limited to the same people who have access to the running server. Treat backup archives as secrets. Do not upload them to public storage or share them without reviewing the contents first.

How often should I run OpenClaw backups?

For production instances running cron jobs and active memory, a daily automated backup is the minimum. If you make frequent changes to AGENTS.md or skills, also push the workspace to a private git repo after each significant edit. The git repo gives you granular history; the daily archive gives you a single-file restore point for everything including credentials.

Evidence & Methodology

All claims in this article are sourced from official OpenClaw documentation. No claims from third-party tutorial sites were used.

• openclaw backup create behavior: docs.openclaw.ai/cli/backup.md
• Workspace location and git recommendation: docs.openclaw.ai/concepts/agent-workspace
• Cron job storage at jobs.json: docs.openclaw.ai/automation/cron-jobs.md
• Git backup recommendation from FAQ: docs.openclaw.ai/help/faq
• openclaw reset restore prerequisite: docs.openclaw.ai/cli/reset

Recovery steps for corrupted config and archive extraction are based on standard tar archive behavior and the backup manifest structure described in the official docs.

Related resources

• OpenClaw Cron Jobs: Automation Templates and Debug Steps
• OpenClaw Persistent Memory Guide
• OpenClaw Doctor --fix: Every Flag and Warning Explained
• OpenClaw Security Guide: 7 Fixes to Harden Your AI Agent
• OpenClaw Workspace Files: AGENTS.md, SOUL.md, USER.md Explained

Changelog