OpenClaw Backup Restore Command Guide

💡 Quick Answer: Schedule VolumeSnapshots with a CronJob or use Velero to back up the OpenClaw PVC. Critical data: ~/.openclaw/ contains WhatsApp/Signal session keys, conversation history, and workspace files. Without backup, losing the PVC means re-pairing all channels and losing all memory.

Key concept: OpenClaw state = channel auth sessions + conversation history + workspace (SOUL.md, memory, skills). All live in ~/.openclaw/.

Gotcha: You can’t back up a WhatsApp session and restore it on a different phone number. The session is tied to the paired phone.

The Problem

• PVC failure = loss of all messaging channel sessions (WhatsApp, Signal)
• Re-pairing requires physical access to your phone
• Conversation history and agent memory are irreplaceable
• No native backup mechanism in OpenClaw

The Solution

Automated backups via VolumeSnapshots or S3 CronJobs, with tested restore procedures.

What to Back Up

~/.openclaw/
├── agents/              # Per-agent state and sessions
│   └── main/
│       ├── agent/       # Auth profiles, model config
│       └── sessions/    # Conversation history
├── workspace/           # SOUL.md, AGENTS.md, memory/, skills/
├── openclaw.json        # Configuration
└── channels/            # WhatsApp/Signal session keys (CRITICAL)

Backup & Restore Commands (CLI)

OpenClaw has no dedicated openclaw backup / openclaw restore subcommand — all state is plain files under ~/.openclaw/, so you back up and restore with standard tar/kubectl cp. Run these against the directory the Gateway uses inside the pod.

# --- BACKUP: archive the whole OpenClaw state directory ---
# Inside the pod (or a node with the PVC mounted at ~/.openclaw):
tar czf openclaw-backup-$(date +%Y%m%d).tar.gz -C ~/.openclaw .

# From your laptop, pull state straight out of the running pod:
kubectl cp openclaw/openclaw-gateway-0:/root/.openclaw ./openclaw-backup

# Config-only backup (just openclaw.json):
kubectl cp openclaw/openclaw-gateway-0:/root/.openclaw/openclaw.json ./openclaw.json

# --- RESTORE: push state back, then restart the Gateway ---
kubectl scale deploy/openclaw-gateway -n openclaw --replicas=0
kubectl cp ./openclaw-backup openclaw/openclaw-gateway-0:/root/.openclaw
kubectl scale deploy/openclaw-gateway -n openclaw --replicas=1

# Verify the Gateway came back up with restored sessions:
kubectl exec -n openclaw deploy/openclaw-gateway -- openclaw gateway status

Why no native command? OpenClaw stores everything as files (openclaw.json, agents/, channels/, workspace/). That means any file-level tool — tar, kubectl cp, VolumeSnapshots, or Velero — is the backup tool. The sections below automate exactly that on Kubernetes.

Method 1: VolumeSnapshot CronJob

# openclaw-snapshot-cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: openclaw-backup-snapshot
  namespace: openclaw
spec:
  schedule: "0 */4 * * *"    # Every 4 hours
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: snapshot-creator
          containers:
            - name: snapshot
              image: bitnami/kubectl:latest
              command: ["sh", "-c"]
              args:
                - |
                  TIMESTAMP=$(date +%Y%m%d-%H%M%S)
                  cat <<SNAPEOF | kubectl apply -f -
                  apiVersion: snapshot.storage.k8s.io/v1
                  kind: VolumeSnapshot
                  metadata:
                    name: openclaw-backup-${TIMESTAMP}
                    namespace: openclaw
                  spec:
                    volumeSnapshotClassName: csi-snapclass
                    source:
                      persistentVolumeClaimName: openclaw-state
                  SNAPEOF
                  # Clean up old snapshots (keep last 10)
                  kubectl get volumesnapshot -n openclaw --sort-by=.metadata.creationTimestamp -o name | \
                    head -n -10 | xargs -r kubectl delete -n openclaw
          restartPolicy: OnFailure

Method 2: S3 Backup CronJob

# openclaw-s3-backup.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: openclaw-backup-s3
  namespace: openclaw
spec:
  schedule: "0 */6 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: backup
              image: amazon/aws-cli:latest
              command: ["sh", "-c"]
              args:
                - |
                  TIMESTAMP=$(date +%Y%m%d-%H%M%S)
                  tar czf /tmp/openclaw-${TIMESTAMP}.tar.gz -C /backup .
                  aws s3 cp /tmp/openclaw-${TIMESTAMP}.tar.gz \
                    s3://my-backups/openclaw/openclaw-${TIMESTAMP}.tar.gz
                  echo "Backup complete: openclaw-${TIMESTAMP}.tar.gz"
              envFrom:
                - secretRef:
                    name: aws-backup-creds
              volumeMounts:
                - name: state
                  mountPath: /backup
                  readOnly: true
          volumes:
            - name: state
              persistentVolumeClaim:
                claimName: openclaw-state
          restartPolicy: OnFailure

Restore Procedure

# 1. Scale down OpenClaw
kubectl scale deploy/openclaw-gateway -n openclaw --replicas=0

# 2. Restore from S3
kubectl run restore --rm -it --image=amazon/aws-cli \
  --overrides='{"spec":{"containers":[{"name":"restore","image":"amazon/aws-cli",
  "command":["sh","-c","aws s3 cp s3://my-backups/openclaw/openclaw-LATEST.tar.gz /tmp/ && tar xzf /tmp/openclaw-LATEST.tar.gz -C /restore"],
  "volumeMounts":[{"name":"state","mountPath":"/restore"}],
  "envFrom":[{"secretRef":{"name":"aws-backup-creds"}}]}],
  "volumes":[{"name":"state","persistentVolumeClaim":{"claimName":"openclaw-state"}}]}}' \
  -n openclaw

# 3. Scale back up
kubectl scale deploy/openclaw-gateway -n openclaw --replicas=1

# 4. Verify
kubectl exec -n openclaw deploy/openclaw-gateway -- openclaw status

Best Practices

1. Back up every 4-6 hours — Balance between data loss risk and storage cost
2. Test restores regularly — A backup you can’t restore is worthless
3. Retain 7 days of backups — Enough to recover from gradual corruption
4. Encrypt backups — Use S3 server-side encryption or client-side GPG
5. Alert on backup failures — Monitor the CronJob for failed runs

FAQ

What is the OpenClaw backup command?

There is no built-in openclaw backup command. Because OpenClaw keeps all state as files under ~/.openclaw/, you back up with standard tools: tar czf openclaw-backup.tar.gz -C ~/.openclaw ., or on Kubernetes a VolumeSnapshot / Velero backup of the PVC. The same applies to restore — tar xzf or kubectl cp the files back, then restart the Gateway.

How do I back up and restore the OpenClaw config?

The config is a single file: ~/.openclaw/openclaw.json. Copy it out with kubectl cp openclaw/openclaw-gateway-0:/root/.openclaw/openclaw.json ./openclaw.json and restore by copying it back. Note the config alone does not include channel sessions or conversation history — back up the whole ~/.openclaw/ directory for a full recovery.

What does ~/.openclaw/openclaw.json contain?

It holds the Gateway configuration: the agent model (agent.model), channel allowlists (channels.whatsapp.allowFrom), routing, and security settings. It does not contain session keys or history — those live in ~/.openclaw/channels/ and ~/.openclaw/agents/, which is why a full backup must cover the entire directory.

Can I restore an OpenClaw backup to a different cluster or phone?

You can restore the files to any cluster, but WhatsApp/Signal channel sessions are tied to the paired phone number and cannot be moved to a different number. After restoring to a new environment you may need to re-pair those channels with openclaw pairing approve <channel> <code>.

Where is the OpenClaw state directory inside the pod?

It is the Gateway user’s home: typically /root/.openclaw (or ~/.openclaw). Mount your backup PVC there and point kubectl cp / tar at that path. Confirm the exact location with kubectl exec -n openclaw deploy/openclaw-gateway -- printenv HOME.

For deeper state handling, see OpenClaw PVC state management and OpenClaw secrets management.

Key Takeaways

• OpenClaw state is critical — Channel sessions can’t be recreated without phone access
• VolumeSnapshots are fastest for CSI-compatible storage
• S3 backups work everywhere and provide offsite redundancy
• Test restores periodically to ensure the backup pipeline works
• Automate with CronJobs — Manual backups are forgotten backups