Agent Workspace

The workspace is the agent's home. It's the sole location used for

file tools and workspace context. Keep it private and treat it as memory.

This is separate from ''~/.openclaw/'', which stores configuration, credentials, and

sessions.

Important: The workspace is the default cwd, not a hard sandbox. Tools

resolve relative paths against the workspace, but absolute paths can still reach

other locations on the host unless sandboxing is enabled. If you need isolation, use

''''agents.defaults.sandbox'''' (and/or per-agent sandbox configuration).

When sandboxing is enabled and ''workspaceAccess'' is not ''"rw"'', tools run

in a sandbox workspace under ''~/.openclaw/sandboxes'', not your host workspace.

- Default: ''~/.openclaw/workspace''

- If ''OPENCLAW_PROFILE'' is set to something other than ''"default"'', the default becomes

''~/.openclaw/workspace-<profile>''.

- Override in ''~/.openclaw/openclaw.json'':

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

''openclaw onboard'', ''openclaw configure'', or ''openclaw setup'' will create

the workspace and seed bootstrap files (if missing).

If you already manage workspace files yourself, you can disable bootstrap

file creation:

{ agent: { skipBootstrap: true } }

Older installs may have created ''~/openclaw''. Keeping multiple workspace

directories around can lead to confusing authentication or state drift, since only one

workspace is active at a time.

Recommendation: Keep one active workspace. If you no longer use

extra folders, archive or move them to trash (e.g., ''trash ~/openclaw'').

If you intentionally keep multiple workspaces, ensure

''agents.defaults.workspace'' points to the active one.

''openclaw doctor'' warns when extra workspace directories are detected.

These are the standard files OpenClaw expects in the workspace:

- ''AGENTS.md''

- Operational instructions for the agent and how it should use memory.

- Loaded at the start of each session.

- Good place for rules, priorities, and "how to behave" details.

- ''SOUL.md''

- Persona, tone, and boundaries.

- Loaded per session.

- ''USER.md''

- Who the user is and how to address them.

- Loaded per session.

- ''IDENTITY.md''

- Agent's name, vibe, and emoji.

- Created/updated during the bootstrap ritual.

- ''TOOLS.md''

- Notes about local tools and conventions.

- Does not control tool availability; this is just guidance.

- ''HEARTBEAT.md''

- Optional heartbeat run checklist.

- Keep it short to avoid token burn.

- ''BOOT.md''

- Optional startup checklist to execute on gateway restart when internal hooks are enabled.

- Keep it short; use message tool for outbound sends.

- ''BOOTSTRAP.md''

- One-time first-run ritual.

- Created only for fresh workspaces.

- Delete it after the ritual is complete.

- ''memory/YYYY-MM-DD.md''

- Daily memory logs (one file per day).

- Suggested to read at start of today + yesterday sessions.

- ''MEMORY.md'' (optional)

- Curated long-term memory.

- Loaded only in primary private sessions (not shared/group context).

See ''Memory'' for workflow and automatic memory refresh.

- ''skills/'' (optional)

- Workspace-specific skills.

- Override hosted/bundled skills when name conflicts.

- ''canvas/'' (optional)

- Canvas UI files for node display (e.g., ''canvas/index.html'').

If any bootstrap files are missing, OpenClaw injects a "missing file" marker into

the session and continues. Large bootstrap files are truncated when injected;

use ''agents.defaults.bootstrapMaxChars'' to adjust the limit (default: 20000).

''openclaw setup'' can recreate missing defaults without overwriting existing

files.

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

- ''~/.openclaw/openclaw.json'' (configuration)

- ''~/.openclaw/credentials/'' (OAuth tokens, API keys)

- ''~/.openclaw/agents/<agentId>/sessions/'' (session logs + metadata)

- ''~/.openclaw/skills/'' (managed skills)

If you need to migrate sessions or configuration, copy them separately and keep

them out of version control.

Treat the workspace as private memory. Put it in a private git repo so it's

backed up and recoverable.

Run these steps on the machine running the gateway (i.e., where

the workspace lives).

#

Fresh workspaces are automatically initialized if git is installed. If this

workspace is not yet a repo, run:

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"

#

Option A: GitHub Web UI

1. Create a new private repo on GitHub.

2. Don't initialize with README (to avoid merge conflicts).

3. Copy the HTTPS remote URL.

4. Add the remote and push:

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

Option B: GitHub CLI (''gh'')

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

Option C: GitLab Web UI

1. Create a new private repo on GitLab.

2. Don't initialize with README (to avoid merge conflicts).

3. Copy the HTTPS remote URL.

4. Add the remote and push:

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

#

Even in private repos, 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

secrets elsewhere (password manager, environment variables, or ''~/.openclaw/'').

Suggested ''.gitignore'' starter:

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

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

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

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

4. If you need sessions, copy ''~/.openclaw/agents/<agentId>/sessions/'' from the

old machine separately.

- Multi-agent routing can use different workspaces per agent. See

''Channel Routing'' for routing configuration.

- If ''agents.defaults.sandbox'' is enabled, non-primary sessions can use per-session sandbox

workspaces under ''agents.defaults.sandbox.workspaceRoot''.