If OpenClaw:
- “forgets everything” after a restart/redeploy,
- never writes memory files,
- or claims it saved files but the directory is empty,
you’re almost always dealing with persistence (wrong directory / wiped disk) or permissions (can’t write).
This guide helps you validate the real on-disk paths and make them stable.
Related (high value):
- Deployment persistence + tokens: /guides/openclaw-deployment-troubleshooting
- Config precedence: /guides/openclaw-configuration
- Native Windows runtime / service edge cases: /guides/openclaw-native-windows-field-guide
- Windows path choice (native vs WSL2): /guides/openclaw-windows-native-vs-wsl2
What this guide helps you finish
By the end of this guide, you should be able to:
- identify the real state and workspace paths the running gateway is using,
- separate persistence failures from plain write-permission failures,
- verify that files, memory, and approvals survive a restart,
- make recovery boring by backing up the right directories as a unit.
Who this is for (and not for)
Use this guide if OpenClaw:
- forgets state after restarts,
- says it wrote files but you cannot find them,
- fails to write memory or workspace artifacts in Docker, VPS, or service-managed setups.
This is not the best page if your main issue is model/provider auth or channel routing. In those cases, treat persistence as a separate layer and debug the runtime path first.
Before you debug persistence: collect these five facts
Before you change mounts or permissions, confirm:
- the effective state directory,
- the effective workspace path,
- which user or container UID/GID the gateway is running as,
- whether the disk or container layer is actually persistent across restarts,
- one artifact you can use as a repeatable proof that the fix worked.
If you cannot state those five facts clearly, you are still guessing at the write path.
0) The two directories that matter
A) State directory (must persist)
Default: ~/.openclaw/ (unless overridden by OPENCLAW_STATE_DIR).
It commonly contains:
openclaw.json(config)- credentials/tokens
- device approvals (Control UI pairing)
- cron job state
- caches and internal DBs
If this directory is wiped, you didn’t “lose a token” — you created a new machine.
B) Workspace directory (must exist + be writable)
This is where tools and runs write artifacts (reports, downloads, generated files). If the workspace path points to a nonexistent or unwritable directory, you’ll see “it said it wrote a file” but nothing appears.
Where it’s configured varies by version, but you can always confirm the effective value via CLI:
openclaw config get agents.defaults.workspaceIf you’re on Docker, also check any workspace env var you set (for example OPENCLAW_WORKSPACE_DIR) and make sure it
matches the container path.
1) Confirm what the running gateway is actually using
The #1 footgun is editing the wrong config file or assuming your interactive shell env is what the service uses.
Use:
openclaw status --deep
openclaw doctorThen re-check config precedence:
2) Fix the most common “can’t write” failures
2.1 Docker: bind-mounted ~/.openclaw not writable (UID/GID mismatch)
Symptoms:
- errors like
EACCES: permission denied ... openclaw.json.*.tmp - config changes don’t persist
- workspace artifacts never appear
Fix page:
2.2 Unsafe temp dir /tmp permission issues
If OpenClaw refuses to start with an “unsafe fallback temp dir” error, fix temp directory ownership/permissions:
3) Fix the most common “it forgets after restart” failures
3.1 You did not persist the state directory
If you are on:
- Docker → you must mount a host volume for the state directory
- VPS/PaaS → avoid ephemeral root disks / container layers
Use the persistence playbook:
3.2 You have multiple installs and the service uses a different runtime
This is especially common when the shell you used for install is not the same environment the running service actually uses. On native Windows, that mismatch can look like PATH drift, Scheduled Task drift, or “ghost writes” to the wrong home/state path. For that path specifically, also see:
If updates/installs were done in one shell, but the daemon runs another Node/PATH, you can get inconsistent behavior and “ghost writes” (writes go to a different home/state than you think).
Start here:
4) A persistence verification drill (do once)
- Create a timestamped artifact in the workspace (via a tool/run or manually).
- Restart the gateway service.
- Verify the artifact still exists on disk.
If you also rely on Control UI:
- Confirm device approvals persist (no repeated pairing every reboot):
If you rely on cron:
- Confirm cron runs persist and history is readable:
Verification checklist after the persistence fix
Before you call the problem solved, verify:
- a timestamped artifact appears in the workspace where you expected,
- the same artifact is still present after a restart,
- the state directory still contains the approvals, config, or cron state you depend on,
- the running service can write again without permission errors in logs.
If the first write succeeds but the second restart loses it, you fixed only the symptom, not the persistence boundary.
5) Backup strategy (minimum viable)
Back up the entire state directory as a unit, not “just openclaw.json”.
CoClaw checklist: