Manage OpenClaw Data Storage and Backup Strategies

Ever felt that sinking feeling when you realize you don’t know where a tool is hiding your files? It’s a common frustration for developers trying to keep their machines organized or move a project to a new setup.

Getting a handle on your data storage is the best way to keep your workflow clean. Let’s look at how OpenClaw handles your files so you can manage your setup with confidence.

Is all data used with OpenClaw saved locally?

The short answer is no. While your state is local, external services still see what you send them.

• Local by default: Your sessions, memory files, config, and workspace live on the Gateway host (~/.openclaw + your workspace directory).
• Model providers: Messages you send to providers like Anthropic or OpenAI go to their APIs.
• Chat platforms: Services like WhatsApp, Telegram, or Slack store message data on their own servers.
• You control the footprint: Using local models keeps prompts on your machine, though channel traffic still goes through the channel’s servers.

Where does OpenClaw store its data?

Everything lives under $OPENCLAW_STATE_DIR, which defaults to ~/.openclaw.

Path	Purpose
$OPENCLAW_STATE_DIR/openclaw.json	Main config (JSON5)
$OPENCLAW_STATE_DIR/credentials/oauth.json	Legacy OAuth import
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json	Auth profiles (OAuth + API keys)
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json	Runtime auth cache
$OPENCLAW_STATE_DIR/credentials/	Provider state (e.g. whatsapp/<accountId>/creds.json)
$OPENCLAW_STATE_DIR/agents/	Per-agent state (agentDir + sessions)
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/	Conversation history & state

Your workspace (including AGENTS.md, memory files, and skills) is separate. You can configure it via agents.defaults.workspace. The default is ~/.openclaw/workspace.

Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?

These files belong in the agent workspace. They do not live in ~/.openclaw.

• Workspace (per agent): This includes AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, and the optional HEARTBEAT.md.
• State dir (~/.openclaw): This holds config, credentials, auth profiles, sessions, and logs.

The default workspace is ~/.openclaw/workspace. You can change it with this config:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } }
}

{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo"
    }
  }
}