openclaw/docs/concepts/agent-workspace.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Agent workspace: location, layout, and backup strategy"
read_when:
  - You need to explain the agent workspace or its file layout
  - You want to back up or migrate an agent workspace
title: "Agent workspace"
sidebarTitle: "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.

<Warning>
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`](/gateway/sandboxing) (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.
</Warning>

## Default location

- Default: `~/.openclaw/workspace`
- If `OPENCLAW_PROFILE` is set and not `"default"`, the default becomes `~/.openclaw-<profile>/workspace`.
- `OPENCLAW_WORKSPACE_DIR` overrides both of the above when set.
- A non-default `OPENCLAW_STATE_DIR` keeps the default workspace at `<state-dir>/workspace`, including scheduled maintenance and the initial `main` agent entry.
- A sole configured agent inherits the default workspace unless its entry sets `workspace`.
- In an explicit multi-agent roster, entries without `workspace` use `<agents.defaults.workspace>/<agentId>` when that root is configured, or `<state-dir>/workspace-<agentId>` otherwise. Naming a shared root does not assign it to an agent.

Override in `~/.openclaw/openclaw.json`:

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

Per-agent override: `agents.entries.*.workspace`. To keep `main` at an existing shared root in a multi-agent roster, pin `agents.entries.main.workspace` to that root explicitly; changing `agents.defaults.workspace` alone sets the base for unpinned entries.

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

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

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

```json5
{ agents: { defaults: { skipBootstrap: true } } }
```

## Extra workspace folders

Older installs may have created `~/openclaw`. Each agent uses one resolved workspace; keeping extra directories does not merge their persona or memory files into the active workspace.

<Note>
Keep each agent's workspace path explicit when retaining older directories. Before switching back to an older workspace, stop the Gateway, configure the intended path, run [`openclaw doctor --fix`](/cli/doctor) to migrate retired setup state, and restart. Doctor also discovers legacy setup files in a still-configured `agents.defaults.workspace` root even when no agent currently uses that root directly. Archive unused folders only after verifying which files you want to retain.
</Note>

## Workspace file map

Standard files OpenClaw expects inside the workspace:

<AccordionGroup>
  <Accordion title="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.
  </Accordion>
  <Accordion title="SOUL.md - persona and tone">
    Persona, tone, and boundaries. Loaded every session. Guide: [SOUL.md personality guide](/concepts/soul).
  </Accordion>
  <Accordion title="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](/concepts/user-model).
  </Accordion>
  <Accordion title="IDENTITY.md - name, vibe, emoji">
    The agent's name, vibe, and emoji. Created/updated during the bootstrap ritual.
  </Accordion>
  <Accordion title="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.
  </Accordion>
  <Accordion title="BOOT.md - startup checklist">
    Optional startup checklist run on Gateway startup when the [boot-md hook](/automation/hooks#boot-md) is enabled. Enabling a different internal hook does not enable `boot-md`. Keep it short; use the message tool for outbound sends.
  </Accordion>
  <Accordion title="BOOTSTRAP.md - first-run ritual">
    One-time first-run ritual. Only created for a brand-new workspace. Delete it after the ritual is complete.
  </Accordion>
  <Accordion title="memory/YYYY-MM-DD.md - daily memory log">
    Daily memory log (one file per day). Recommended to read today + yesterday on session start.
  </Accordion>
  <Accordion title="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](/concepts/memory) for the workflow and automatic memory flush.
  </Accordion>
  <Accordion title="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.
  </Accordion>
</AccordionGroup>

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

## 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. Empty reserved
hashed files under `workspace-attestations/` are discarded because they contain
no importable state; other unreadable sources stay in place and Doctor names
their paths.

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

<Steps>
  <Step title="Initialize the repo">
    If git is installed, brand-new workspaces are initialized automatically. If this workspace is not already a repo, run:

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

  </Step>
  <Step title="Add a private remote">
    <Tabs>
      <Tab title="GitHub web UI">
        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:

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

  </Step>
  <Step title="Ongoing updates">
    ```bash
    git status
    git add .
    git commit -m "Update memory"
    git push
    ```
  </Step>
</Steps>

## Do not commit secrets

<Warning>
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/`).
</Warning>

Suggested `.gitignore` starter:

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

## Moving the workspace to a new machine

<Steps>
  <Step title="Clone the repo">
    Clone the repo to the desired path (default `~/.openclaw/workspace`).
  </Step>
  <Step title="Update config">
    Set `agents.entries.<agentId>.workspace` to the cloned path in `~/.openclaw/openclaw.json` for the agent that should use it. A sole agent without a per-agent override can use `agents.defaults.workspace` instead; in a multi-agent roster, that setting only changes the base directory for unpinned entries.
  </Step>
  <Step title="Verify the workspace">
    Run `openclaw agents list` and confirm that the intended agent points to the cloned path before starting the Gateway. Moving an existing workspace does not require rerunning onboarding.
  </Step>
  <Step title="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.
  </Step>
</Steps>

## Advanced notes

- Multi-agent routing can use different workspaces per agent via `agents.entries.*.workspace`. See [Channel routing](/channels/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](/gateway/heartbeat) - heartbeat monitors and cron scratch
- [Sandboxing](/gateway/sandboxing) - workspace access in sandboxed environments
- [Session](/concepts/session) - session storage paths
- [Standing orders](/automation/standing-orders) - persistent instructions in workspace files