Skip to content
OpenClaw Docs

Agent workspace

The workspace is the agent’s home. It is the only working directory used for file tools and for workspace context. Keep it private and treat it as memory.

This is separate from ~/.openclaw/, which stores config, credentials, and sessions.

Default location

Section titled “Default location”
  • Default: ~/.openclaw/workspace
  • If OPENCLAW_PROFILE is set and not "default", the default becomes `~/.openclaw/workspace-

`.

  • Override in ~/.openclaw/openclaw.json:
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

openclaw onboard, openclaw configure, or openclaw setup will create the workspace and seed the bootstrap files if they are missing.

If you already manage the workspace files yourself, you can disable bootstrap file creation:

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

Extra workspace folders

Section titled “Extra workspace folders”

Older installs may have created ~/openclaw. Keeping multiple workspace directories around can cause confusing auth or state drift, because only one workspace is active at a time.

Workspace file map

Section titled “Workspace file map”

These are the standard files OpenClaw expects inside the workspace:

AGENTS.md - operating instructions

Operating instructions for the agent and how it should use memory. Loaded at the start of every session. Good place for rules, priorities, and “how to behave” details.

SOUL.md - persona and tone

Persona, tone, and boundaries. Loaded every session. Guide: SOUL.md personality guide.

USER.md - who the user is

Who the user is and how to address them. Loaded every session.

IDENTITY.md - name, vibe, emoji

The agent’s name, vibe, and emoji. Created/updated during the bootstrap ritual.

TOOLS.md - local tool conventions

Notes about your local tools and conventions. Does not control tool availability; it is only guidance.

HEARTBEAT.md - heartbeat checklist

Optional tiny checklist for heartbeat runs. Keep it short to avoid token burn.

BOOT.md - startup checklist

Optional startup checklist run automatically on gateway restart (when internal hooks are enabled). Keep it short; use the message tool for outbound sends.

BOOTSTRAP.md - first-run ritual

One-time first-run ritual. Only created for a brand-new workspace. Delete it after the ritual is complete.

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

Daily memory log (one file per day). Recommended to read today + yesterday on session start.

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

Curated long-term memory: durable facts, preferences, decisions, and short summaries. Keep detailed logs in memory/YYYY-MM-DD.md so memory tools can retrieve them on demand without injecting them into every prompt. Only load MEMORY.md in the main, private session (not shared/group contexts). See Memory for the workflow and automatic memory flush.

skills/ - workspace skills (optional)

Workspace-specific skills. Highest-precedence skill location for that workspace. Overrides project agent skills, personal agent skills, managed skills, bundled skills, and skills.load.extraDirs when names collide.

canvas/ - Canvas UI files (optional)

Canvas UI files for node displays (for example canvas/index.html).

What is NOT in the workspace

Section titled “What is NOT in the workspace”

These live under ~/.openclaw/ and should NOT be committed to the workspace repo:

  • ~/.openclaw/openclaw.json (config)
  • `~/.openclaw/agents/

/agent/auth-profiles.json` (model auth profiles: OAuth + API keys)

  • `~/.openclaw/agents/

/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/

/sessions/` (session transcripts + metadata)

  • ~/.openclaw/skills/ (managed skills)

If you need to migrate sessions or config, copy them separately and keep them out of version control.

Section titled “Git backup (recommended, private)”

Treat the workspace as private memory. Put it in a private git repo so it is backed up and recoverable.

Run these steps on the machine where the Gateway runs (that is where the workspace lives).

  1. Initialize the repo

    If git is installed, brand-new workspaces are initialized automatically. If this workspace is not already a repo, run:

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

  2. Add a private remote

    1. Create a new private repository on GitHub.
    2. Do not initialize with a README (avoids merge conflicts).
    3. Copy the HTTPS remote URL.
    4. Add the remote and push:
    Terminal window
    git branch -M main
    git remote add origin

    git push -u origin main

  3. Ongoing updates

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

Do not commit secrets

Section titled “Do not commit secrets”

Suggested .gitignore starter:

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

Moving the workspace to a new machine

Section titled “Moving the workspace to a new machine”

  1. Clone the repo

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

  2. Update config

    Set agents.defaults.workspace to that path in ~/.openclaw/openclaw.json.

  3. Seed missing files

    Run `openclaw setup —workspace

    ` to seed any missing files.

  4. Copy sessions (optional)

    If you need sessions, copy `~/.openclaw/agents/

    /sessions/` from the old machine separately.

Advanced notes

Section titled “Advanced notes”
  • Multi-agent routing can use different workspaces per agent. See Channel routing for routing configuration.
  • If agents.defaults.sandbox is enabled, non-main sessions can use per-session sandbox workspaces under agents.defaults.sandbox.workspaceRoot.
Section titled “Related”