Environment:Openclaw Openclaw State Directory And Credentials

Knowledge Sources	OpenClaw
Domains	Infrastructure, Security
Last Updated	2026-02-06 12:00 GMT

Overview

File system layout for OpenClaw state, configuration, credentials, sessions, and workspace directories with environment variable overrides.

Description

OpenClaw stores all mutable state under a single state directory (default: `~/.openclaw`). This includes the main configuration file (`openclaw.json`), OAuth credentials, session logs, media cache, and the agent workspace. The state directory supports legacy paths (`.clawdbot`, `.moltbot`, `.moldbot`) with automatic migration. Every path component can be overridden via environment variables, supporting custom deployments and containerized setups. Credentials are stored in `~/.openclaw/credentials/oauth.json` and must never be committed to version control.

Usage

This environment is required for all OpenClaw operations that read or write configuration, credentials, or session state. It is a prerequisite for the gateway startup, agent message processing, and CLI commands.

System Requirements

Category	Requirement	Notes
State Directory	`~/.openclaw` (default)	Override: `OPENCLAW_STATE_DIR` or `CLAWDBOT_STATE_DIR`
Config File	`openclaw.json` (JSON5)	Override: `OPENCLAW_CONFIG_PATH` or `CLAWDBOT_CONFIG_PATH`
Credentials	`~/.openclaw/credentials/`	Override: `OPENCLAW_OAUTH_DIR`
Sessions	`~/.openclaw/sessions/`	Per-agent JSONL session logs
Workspace	`~/.openclaw/workspace/`	Skills, prompts, memory files
Disk	100 MB+ minimum	Sessions and media cache grow over time

Dependencies

File System Layout

`~/.openclaw/` — Root state directory
- `openclaw.json` — Main configuration file (JSON5 format)
- `credentials/oauth.json` — OAuth tokens for model providers
- `sessions/` — Session log files (JSONL per agent)
- `agents/{agentId}/sessions/` — Per-agent session directory
- `workspace/` — Agent workspace (skills, prompts, memory)
- `workspace/canvas/` — Canvas working directory
- `media/` — Media cache
- `tools/` — Downloaded tool binaries (e.g., signal-cli)

Legacy Paths (Auto-Migrated)

`~/.clawdbot` — Legacy state directory (first priority for migration)
`~/.moltbot` — Older legacy directory
`~/.moldbot` — Oldest legacy directory

Credentials

The following environment variables configure model and channel access:

Model Provider Keys:

`ANTHROPIC_API_KEY`: Anthropic Claude API key
`OPENAI_API_KEY`: OpenAI GPT API key
`GITHUB_TOKEN`: GitHub API token (for Copilot integration)

Gateway Authentication:

`OPENCLAW_GATEWAY_TOKEN`: Bearer token for gateway API access
`OPENCLAW_GATEWAY_PASSWORD`: Password-based gateway authentication

Channel Tokens (set in config or env):

Telegram, Discord, Slack, Signal tokens are stored in `openclaw.json`
Never commit actual token values; use `openclaw channels add` to configure

Path Overrides:

`OPENCLAW_STATE_DIR`: Override entire state directory
`OPENCLAW_CONFIG_PATH`: Override config file path
`OPENCLAW_OAUTH_DIR`: Override OAuth credentials directory

Quick Install

# Default setup (creates ~/.openclaw automatically)
openclaw onboard

# Custom state directory
export OPENCLAW_STATE_DIR=/data/.openclaw
openclaw onboard

# Docker volume mount
docker run -v /host/data:/home/node/.openclaw openclaw ...

Code Evidence

State directory resolution with legacy fallback from `src/config/paths.ts:49-74`:

export function resolveStateDir(
  env: NodeJS.ProcessEnv = process.env,
  homedir: () => string = os.homedir,
): string {
  const override = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
  if (override) {
    return resolveUserPath(override);
  }
  const newDir = newStateDir(homedir);
  const legacyDirs = legacyStateDirs(homedir);
  const hasNew = fs.existsSync(newDir);
  if (hasNew) {
    return newDir;
  }
  const existingLegacy = legacyDirs.find((dir) => {
    try {
      return fs.existsSync(dir);
    } catch {
      return false;
    }
  });
  if (existingLegacy) {
    return existingLegacy;
  }
  return newDir;
}

Nix mode detection from `src/config/paths.ts:7-15`:

/**
 * Nix mode detection: When OPENCLAW_NIX_MODE=1, the gateway is running under Nix.
 * In this mode:
 * - No auto-install flows should be attempted
 * - Missing dependencies should produce actionable Nix-specific error messages
 * - Config is managed externally (read-only from Nix perspective)
 */
export function resolveIsNixMode(env: NodeJS.ProcessEnv = process.env): boolean {
  return env.OPENCLAW_NIX_MODE === "1";
}

OAuth directory resolution from `src/config/paths.ts:218-227`:

export function resolveOAuthDir(
  env: NodeJS.ProcessEnv = process.env,
  stateDir: string = resolveStateDir(env, os.homedir),
): string {
  const override = env.OPENCLAW_OAUTH_DIR?.trim();
  if (override) {
    return resolveUserPath(override);
  }
  return path.join(stateDir, "credentials");
}

Common Errors

Error Message	Cause	Solution
`ENOENT: no such file or directory, open '~/.openclaw/openclaw.json'`	First run, config not created yet	Run `openclaw onboard` or `openclaw setup`
`EACCES: permission denied`	State directory owned by different user	Fix permissions: `chown -R $USER ~/.openclaw`
`Config file not found` with custom `OPENCLAW_STATE_DIR`	Override path does not exist	Create the directory first: `mkdir -p $OPENCLAW_STATE_DIR`
Legacy config warnings	Old `.clawdbot` directory detected	Run `openclaw doctor` to migrate to `.openclaw`

Compatibility Notes

Docker: State directory defaults to `/home/node/.openclaw` in container. Mount persistent volumes for data retention.
Nix: When `OPENCLAW_NIX_MODE=1`, config is considered read-only. Auto-install flows are disabled.
Multiple Gateways: Use separate `OPENCLAW_STATE_DIR` values for isolated gateway instances.
Windows: Home directory resolved via `HOMEDRIVE`/`HOMEPATH` or `HOME` env var.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment