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
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:
5) Backup strategy (minimum viable)
Back up the entire state directory as a unit, not “just openclaw.json”.
CoClaw checklist: