Implementation:Openclaw Openclaw ResolveStateDir
| Knowledge Sources | |
|---|---|
| Domains | Deployment, Docker |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Concrete tool for resolving the persistent state directory provided by the OpenClaw configuration module, combined with Docker Compose volume mappings for container deployments.
Description
The resolveStateDir function in src/config/paths.ts determines where OpenClaw stores mutable data such as sessions, logs, caches, and configuration. It supports environment variable overrides for container and cloud deployments, automatic detection of legacy directory names from previous product versions, and a sensible default of ~/.openclaw.
The Docker Compose file (docker-compose.yml) complements this by mounting host directories into the container, ensuring the resolved state directory points to persistent storage. The openclaw-gateway and openclaw-cli services both receive identical volume mounts so that CLI commands and the running gateway share the same state.
Usage
Import resolveStateDir when you need the canonical state directory path at runtime. In Docker deployments, set OPENCLAW_STATE_DIR to the mounted volume path. For local Docker Compose setups, docker-setup.sh handles the environment variable configuration automatically.
Code Reference
Source Location
- Repository: openclaw
- File:
src/config/paths.ts(lines 49-74),docker-compose.yml(lines 11-13)
Signature
export function resolveStateDir(
env: NodeJS.ProcessEnv = process.env,
homedir: () => string = os.homedir,
): string
Import
import { resolveStateDir } from "../config/paths.js";
// Or for the pre-resolved singleton:
import { STATE_DIR } from "../config/paths.js";
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| env | NodeJS.ProcessEnv |
No | Process environment object. Defaults to process.env. Checked for OPENCLAW_STATE_DIR and legacy CLAWDBOT_STATE_DIR.
|
| homedir | () => string |
No | Function returning the user home directory. Defaults to os.homedir.
|
Docker Compose volume inputs (docker-compose.yml lines 11-13):
| Name | Type | Required | Description |
|---|---|---|---|
| OPENCLAW_CONFIG_DIR | string (env var) | Yes | Host path mounted to /home/node/.openclaw inside the container.
|
| OPENCLAW_WORKSPACE_DIR | string (env var) | Yes | Host path mounted to /home/node/.openclaw/workspace inside the container.
|
Outputs
| Name | Type | Description |
|---|---|---|
| (return value) | string |
Absolute path to the resolved state directory. One of: the OPENCLAW_STATE_DIR override, an existing ~/.openclaw directory, the first existing legacy directory, or ~/.openclaw as default.
|
Usage Examples
Basic Usage
import { resolveStateDir, STATE_DIR } from "../config/paths.js";
// Use the pre-resolved singleton
console.log(`State directory: ${STATE_DIR}`);
// => /home/node/.openclaw (inside Docker)
// Or resolve dynamically with custom env
const stateDir = resolveStateDir({ OPENCLAW_STATE_DIR: "/data" });
// => /data
Docker Compose Configuration
# docker-compose.yml (lines 11-13)
volumes:
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
Cloud Deployment Override
# fly.toml - Override state dir to mounted volume
[env]
OPENCLAW_STATE_DIR = "/data"
[mounts]
source = "openclaw_data"
destination = "/data"