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.

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.
• Non-default agents (agents.list[]) 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.list[].workspace.

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

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.

Workspace file map

Standard files OpenClaw expects inside the workspace:

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/auth-profiles.json (model auth profiles: OAuth + API keys)
• ~/.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).

```bash
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"
```

    ```bash
    git branch -M main
    git remote add origin <https-url>
    git push -u origin main
    ```
  </Tab>
  <Tab title="GitHub CLI (gh)">
    ```bash
    gh auth login
    gh repo create openclaw-workspace --private --source . --remote origin --push
    ```
  </Tab>
  <Tab title="GitLab web UI">
    1. Create a new **private** repository on GitLab.
    2. Do not initialize with a README (avoids merge conflicts).
    3. Copy the HTTPS remote URL.
    4. Add the remote and push:

    ```bash
    git branch -M main
    git remote add origin <https-url>
    git push -u origin main
    ```
  </Tab>
</Tabs>

Do not commit secrets

• 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

Advanced notes

• Multi-agent routing can use different workspaces per agent via agents.list[].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.

Related

• Heartbeat - HEARTBEAT.md workspace file
• Sandboxing - workspace access in sandboxed environments
• Session - session storage paths
• Standing orders - persistent instructions in workspace files

Source: docs/concepts/agent-workspace.md