openclaw - 💡(How to fix) Fix Gateway image: support mounting $HOME on a persistent volume (seed image defaults on first boot) [1 comments, 1 participants]

Problem

When OpenClaw gateway is deployed to a platform that gives the container a single persistent volume (Fly.io, Render, fly-style K8s persistent volumes, etc.), everything outside that volume is ephemeral. But meaningful agent state lives under $HOME:

• Default agent workspace — $HOME/.openclaw/workspace/ (SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/, HEARTBEAT.md). resolveDefaultAgentWorkspaceDir in src/agents/workspace.ts hardcodes $HOME/.openclaw/workspace regardless of OPENCLAW_STATE_DIR.
• Potentially other ~/.openclaw/* paths, plus cache-ish state some agents/extensions may put under ~/.cache/, ~/.config/, etc.

Today operators work around this with one of:

1. Pin agents.defaults.workspace to a path inside the mounted volume (covers only the default workspace).
2. Symlink $HOME/.openclaw → /volume/.openclaw in the platform-level startup script (covers all of ~/.openclaw/* but leaves other home-dir state ephemeral, and is invisible inside the image).
3. Move $HOME onto the volume via HOME=/volume/home — breaks because the image's preshipped $HOME contents (~/.local/bin with clawhub etc., shell profile, npm cache) aren't on the volume, so ~/.local/bin/clawhub suddenly doesn't exist at runtime. Some configs like tools.exec.pathPrepend then have to be rewritten to absolute /home/node/.local/bin paths, which is exactly what we're trying to avoid.

The cleanest fix is at the image level. Same pattern Postgres/MySQL official images use for /var/lib/postgresql/data.

Proposal

Treat $HOME as an expected-to-be-empty persistent volume mount in the ghcr.io/openclaw/openclaw image:

1. Move the image's baked-in user files (whatever currently lives at /home/node/*: .local/bin/*, any shell config, pre-pulled caches) to a seed location like /opt/openclaw/home-seed/.
2. Make the entrypoint, before exec-ing the gateway, run something like:

   if [ -d /opt/openclaw/home-seed ]; then
     rsync -a --ignore-existing /opt/openclaw/home-seed/ \"\$HOME/\"
   fi

   --ignore-existing so user data on the volume always wins, seed only fills gaps.
3. Document that operators can now mount their persistent volume directly at \$HOME (e.g. /home/node) and everything OpenClaw writes under ~/ survives restarts, with no per-path agents.defaults.workspace or symlink hacks.

Benefit

• Deployment templates become one line: [[mounts]] destination = \"/home/node\".
• Future state paths OpenClaw adds under ~/ persist automatically — no platform-level template changes needed.
• Matches widely-understood Docker persistence conventions.

Context / motivation

Hit this while deploying OpenClaw gateways via a Fly.io-based "db-agent-openclaw-deployer" setup. Our current workaround symlinks ~/.openclaw → /data/.openclaw at boot from the fly.toml [processes] script — works, but it's platform-specific glue that would be unnecessary if the image supported HOME-on-volume directly.

Happy to send a PR if the approach sounds right.