Principle:Openclaw Openclaw Container Storage Configuration
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Docker |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Container storage configuration is the concept of configuring persistent storage for containerized applications by mapping host directories to container volumes for state, config, and workspace data.
Description
Containers are ephemeral by default: when a container is removed, all data written inside it is lost. For an AI gateway like OpenClaw that maintains session state, configuration files, credentials, and workspace data, persistent storage is essential. The solution is to mount host directories or named Docker volumes into the container at well-known paths.
OpenClaw uses a layered approach to storage resolution. The resolveStateDir function determines the state directory at runtime by checking environment variable overrides (OPENCLAW_STATE_DIR, with legacy CLAWDBOT_STATE_DIR fallback), then probing for existing directories in a priority order: the new canonical path (~/.openclaw) first, then legacy directories (.clawdbot, .moltbot, .moldbot). This migration-aware resolution ensures containers that mount a legacy directory still function correctly.
The Docker Compose configuration maps two host directories into the container: the config directory at /home/node/.openclaw and the workspace directory at /home/node/.openclaw/workspace. For cloud platforms like Fly.io and Render, the OPENCLAW_STATE_DIR environment variable is set to a mounted persistent disk (e.g., /data), allowing the same resolution logic to work across local Docker and cloud deployments.
Usage
Apply this concept when deploying OpenClaw in any containerized environment to ensure that configuration, sessions, credentials, and workspace data survive container restarts and upgrades. The storage configuration is relevant during initial setup (onboarding), ongoing operation, and when migrating between deployment platforms.
Theoretical Basis
The storage resolution algorithm follows a deterministic fallback chain:
- Environment override: If
OPENCLAW_STATE_DIR(or legacyCLAWDBOT_STATE_DIR) is set, resolve it as an absolute path (expanding~if present) and return immediately. - New canonical directory: Check if
~/.openclawexists on disk. If it does, use it. - Legacy directory probe: Iterate through
[.clawdbot, .moltbot, .moldbot]in the home directory. Return the first one that exists. - Default: If nothing exists, return
~/.openclaw(the canonical new path), which will be created on first write.
In Docker Compose, the volumes section creates a bidirectional binding:
volumes:
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
This ensures that the container's node user (with HOME=/home/node) sees the mounted host directories as its natural state directory, and the resolveStateDir function resolves them without any special container-awareness.