Agent Workspace: Location & Backup

The workspace serves as the agent's home base: it is the working directory that file tools and workspace context rely on. Treat it as private memory and keep it secure.

It exists independently of ~/.openclaw/, which holds configuration, credentials, and session data.

Warning

The workspace acts as the default cwd, not a strict sandbox. Relative paths in tools are resolved against the workspace, yet absolute paths can still access other parts of the host unless sandboxing is turned on. For isolation, set up agents.defaults.sandbox (and optionally per-agent sandbox settings).

With sandboxing active and workspaceAccess different from "rw", tools run inside a sandbox workspace located at ~/.openclaw/sandboxes, not your host workspace.

Default location

Default value: ~/.openclaw/workspace
When OPENCLAW_PROFILE is configured and not "default", the default shifts to ~/.openclaw-<profile>/workspace.
Setting OPENCLAW_WORKSPACE_DIR takes precedence over both defaults above.
A non-default OPENCLAW_STATE_DIR retains the default workspace at <state-dir>/workspace, covering scheduled maintenance and the initial main agent entry.
Agents that are non-default (agents.entries.*) and lack an explicit workspace fall back to <state-dir>/workspace-<agentId>, rather than the shared default workspace.

Set the override in ~/.openclaw/openclaw.json:

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

To override per agent, use agents.entries.*.workspace.

The workspace and its bootstrap files are created by openclaw onboard, openclaw configure, or openclaw setup when those files are absent.

Note

Sandbox seed copies accept only regular files that live inside the workspace; symlink or hardlink aliases pointing outside the source workspace are skipped.

If you handle the workspace files on your own, turn off bootstrap file creation:

{ agents: { defaults: { skipBootstrap: true } } }

Extra workspace folders

Installs from earlier versions may have generated ~/openclaw. Having several workspace directories around can lead to confusing auth problems or state drift, because only one workspace is active at any given moment.

Note

Recommendation: stick with a single active workspace. If the extra folders are no longer needed, archive them or move them to Trash (for instance trash ~/openclaw). If you deliberately keep multiple workspaces, confirm that agents.defaults.workspace (or the per-agent workspace key) points to the active one.

Workspace file map

Below are the standard files OpenClaw looks for inside the workspace:

AGENTS.md - operating instructions

Instructions on how the agent should operate and use memory. Injected at the beginning of each session. A suitable spot for rules, priorities, and behavioral guidance.

SOUL.md - persona and tone

Persona, tone, and boundaries. Injected each session. Reference: SOUL.md personality guide.

USER.md - directive-based user model (optional)

Durable preferences, communication style, relationships, and context for active projects. Record entries as dated active or superseded directives. Injected each session with its own 4,000-character budget. See User model.

IDENTITY.md - name, vibe, emoji

The agent's name, vibe, and emoji. Generated or refreshed during the bootstrap ritual.

AGENTS.md Tools section - local tool conventions

The ## Tools section captures local environment notes and conventions. It does not govern tool availability; it serves only as guidance.

BOOT.md - startup checklist

An optional startup checklist that runs automatically on gateway restart (when internal hooks are enabled). Keep it brief; use the message tool for outbound sends.

BOOTSTRAP.md - first-run ritual

A one-time first-run ritual. Created only for a brand-new workspace. Remove it once the ritual finishes.

memory/YYYY-MM-DD.md - daily memory log

A daily memory log, one file per day. Recommended reading at session start covers today and yesterday.

MEMORY.md - curated long-term memory (optional)

Curated long-term memory: durable facts outside the profile, decisions, and short summaries. Keep detailed logs in memory/YYYY-MM-DD.md so memory tools can fetch them on demand without pushing them into every prompt. Load MEMORY.md only in the main, private session, not in shared or group contexts. The workflow and automatic memory flush are described in Memory.

skills/ - workspace skills (optional)

Workspace-specific skills. This is the highest-precedence skill location for that workspace, ranking above project agent skills, personal agent skills, managed skills, bundled skills, and skills.load.extraDirs when names clash.

Note

When a required bootstrap file is absent, OpenClaw inserts a "missing file" marker into the session and proceeds. Optional USER.md and MEMORY.md files are left out if they do not exist. Large bootstrap files get truncated during injection; tune the general limits with agents.defaults.bootstrapMaxChars (default: 20000) and agents.defaults.bootstrapTotalMaxChars (default: 60000). USER.md keeps its own 4,000-character cap. Missing defaults can be recreated by openclaw setup without touching existing files.

What is NOT in the workspace

These reside under ~/.openclaw/ and must NOT be committed to the workspace repo:

~/.openclaw/openclaw.json (config)
~/.openclaw/state/openclaw.sqlite (shared workspace setup state and attestations)
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (model auth profiles, routing state, standing intents, and other agent-scoped durability)
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (session rows, transcripts, and per-agent runtime state)
~/.openclaw/agents/<agentId>/agent/codex-home/ (per-agent Codex runtime account, config, skills, plugins, and native thread state)
~/.openclaw/credentials/ (channel/provider state plus legacy OAuth import data)
~/.openclaw/agents/<agentId>/sessions/ (legacy migration sources and archive/support artifacts)
~/.openclaw/skills/ (managed skills)

When sessions or config need to be moved, handle them as separate copies and exclude them from version control.

Earlier OpenClaw versions stored openclaw-workspace-state.json, .openclaw/workspace-state.json, and .attested as sidecar files in the workspace. The current runtime relies exclusively on the shared SQLite database for that data. If Doctor flags any of these files, execute openclaw doctor --fix; Doctor brings in valid legacy state and removes the source file only after confirming the database rows exist.

Git backup (recommended, private)

Consider the workspace as private memory. Store it in a private git repository to ensure backups and recoverability.

Perform these actions on the machine hosting the Gateway, since that is where the workspace resides.

Initialize the repo

When git is available, new workspaces get initialized automatically. For a workspace that is not yet a repo, use:

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md IDENTITY.md USER.md memory/
git commit -m "Add agent workspace"

Add a private remote

GitHub web UI

On GitHub, create a new private repository.
Skip the README initialization to prevent merge conflicts.
Grab the HTTPS remote URL.
Attach the remote and push:

git branch -M main
git remote add origin <https-url>
git push -u origin main

GitHub CLI (gh)

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

GitLab web UI

On GitLab, create a new private repository.
Skip the README initialization to prevent merge conflicts.
Grab the HTTPS remote URL.
Attach the remote and push:

git branch -M main
git remote add origin <https-url>
git push -u origin main

Ongoing updates

git status
git add .
git commit -m "Update memory"
git push

Do not commit secrets

Warning

Even with a private repo, keep secrets out of the workspace:

API keys, OAuth tokens, passwords, or private credentials.

Anything under ~/.openclaw/.

Raw dumps of chats or sensitive attachments.

For sensitive references, use placeholders and store the actual secret elsewhere (password manager, environment variables, or ~/.openclaw/).

A suggested .gitignore starter:

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

Moving the workspace to a new machine

Clone the repo

Clone the repo to your chosen path (default ~/.openclaw/workspace).

Update config

In ~/.openclaw/openclaw.json, set agents.defaults.workspace to that path.

Seed missing files

Run openclaw setup --workspace <path> to seed any missing files.

Copy sessions (optional)

For sessions, copy ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite from the old machine as a separate step. Copy ~/.openclaw/agents/<agentId>/sessions/ only if you also need legacy migration inputs or archive/support artifacts.

Advanced notes

Multi-agent routing can assign different workspaces per agent via agents.entries.*.workspace. See Channel routing for routing configuration.
With agents.defaults.sandbox enabled, non-main sessions can use per-session sandbox workspaces under agents.defaults.sandbox.workspaceRoot.

Heartbeat - heartbeat monitors and cron scratch
Sandboxing - workspace access in sandboxed environments
Session - session storage paths
Standing orders - persistent instructions in workspace files