Agent workspace

The workspace is the agent’s home: the working directory used for file tools and workspace context. Keep it private and treat it as memory. This is separate from ~/.openclaw/, which stores config, credentials, and sessions.

The workspace is the default cwd, not a hard sandbox. Tools resolve relative paths against the workspace, but absolute paths can still reach elsewhere on the host unless sandboxing is enabled. If you need isolation, use agents.defaults.sandbox (and/or per-agent sandbox config).When sandboxing is enabled and workspaceAccess is not "rw", tools operate inside a sandbox workspace under ~/.openclaw/sandboxes, not your host workspace.

Default location

Default: ~/.openclaw/workspace
If OPENCLAW_PROFILE is set and not "default", the default becomes ~/.openclaw/workspace-<profile>.
OPENCLAW_WORKSPACE_DIR overrides both of the above when set.
openclaw onboard --non-interactive uses <state-dir>/workspace when OPENCLAW_STATE_DIR is non-default, including for the initial main agent entry.
Non-default agents (agents.entries.*) without an explicit workspace resolve to <state-dir>/workspace-<agentId>, not the shared default workspace.

Override in ~/.openclaw/openclaw.json:

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

Per-agent override: agents.entries.*.workspace. openclaw onboard, openclaw configure, or openclaw setup create the workspace and seed the bootstrap files if they are missing.

Sandbox seed copies only accept regular in-workspace files; symlink/hardlink aliases that resolve outside the source workspace are ignored.

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

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

Extra workspace folders

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

Recommendation: keep a single active workspace. If you no longer use the extra folders, archive or move them to Trash (for example trash ~/openclaw). If you intentionally keep multiple workspaces, make sure agents.defaults.workspace (or the per-agent workspace key) points to the active one.

Workspace file map

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 - directive-based user model (optional)

Stable preferences, communication style, relationships, and active-project context. Write entries as dated active or superseded directives. Loaded every session with a separate 4,000-character budget. See User model.

IDENTITY.md - name, vibe, emoji

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

AGENTS.md Tools section - local tool conventions

The ## Tools section holds local environment notes and conventions. It does not control tool availability; it is only guidance.

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 non-profile facts, 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, ahead of 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).

If a required bootstrap file is missing, OpenClaw injects a “missing file” marker into the session and continues. Optional USER.md and MEMORY.md files are omitted when absent. Large bootstrap files are truncated when injected; adjust general limits with agents.defaults.bootstrapMaxChars (default: 20000) and agents.defaults.bootstrapTotalMaxChars (default: 60000). USER.md keeps its separate 4,000-character cap. openclaw setup can recreate missing defaults without overwriting existing files.

What is NOT in the workspace

These live under ~/.openclaw/ and should 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)

If you need to migrate sessions or config, copy them separately and keep them out of version control. Older OpenClaw releases wrote openclaw-workspace-state.json, .openclaw/workspace-state.json, and .attested workspace sidecars. Current runtime uses only the shared SQLite database for that state. If Doctor reports one of these files, run openclaw doctor --fix; Doctor imports valid legacy state and deletes a source only after verifying the database rows.

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).

Initialize the repo

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

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
GitHub CLI (gh)
GitLab web UI

Create a new private repository on GitHub.
Do not initialize with a README (avoids merge conflicts).
Copy the HTTPS remote URL.
Add the remote and push:

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

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

Create a new private repository on GitLab.
Do not initialize with a README (avoids merge conflicts).
Copy the HTTPS remote URL.
Add 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

Even in a private repo, avoid storing secrets in the workspace:

API keys, OAuth tokens, passwords, or private credentials.
Anything under ~/.openclaw/.
Raw dumps of chats or sensitive attachments.

If you must store sensitive references, use placeholders and keep the real secret elsewhere (password manager, environment variables, or ~/.openclaw/).

Suggested .gitignore starter:

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

Moving the workspace to a new machine

Clone the repo

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

Update config

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

Seed missing files

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

Copy sessions (optional)

If you need sessions, copy ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite from the old machine separately. Copy ~/.openclaw/agents/<agentId>/sessions/ only when you also need legacy migration inputs or archive/support artifacts.

Advanced notes

Multi-agent routing can use different workspaces per agent via agents.entries.*.workspace. 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.

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

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Default location

Extra workspace folders

Workspace file map

What is NOT in the workspace

Git backup (recommended, private)

Do not commit secrets

Moving the workspace to a new machine

Advanced notes

​Default location

​Extra workspace folders

​Workspace file map

​What is NOT in the workspace

​Git backup (recommended, private)

​Do not commit secrets

​Moving the workspace to a new machine

​Advanced notes

​Related

Default location

Extra workspace folders

Workspace file map

What is NOT in the workspace

Git backup (recommended, private)

Do not commit secrets

Moving the workspace to a new machine

Advanced notes

Related