The OpenClaw agent workspace

Every OpenClaw agent has a workspace: the working directory its file tools use and the source of its workspace context. The docs describe it in one line, the agent’s home, and give one instruction, keep it private and treat it as memory. It is separate from the state directory that holds config, credentials and sessions. Here is where it lives, the file map, the limits on what gets injected, what must stay out of it, the backup the docs recommend, and the move to another machine.

Where it lives

• The default is a workspace folder inside the state directory; a named profile moves it to a profile-specific directory, an environment variable overrides both, and a non-default state directory keeps the workspace beside it.
• A sole configured agent inherits the default; in an explicit multi-agent roster, entries without their own workspace get a subfolder of the configured root or a per-agent folder beside the state directory, and naming a shared root does not assign it to an agent.
• Onboarding, configure and setup create the workspace and seed the bootstrap files if missing; a skip-bootstrap flag exists for people who manage the files themselves, and older extra directories are not merged into the active workspace.
• The warning: the workspace is the default working directory, not a hard sandbox; relative paths resolve there, but absolute paths can still reach elsewhere on the host unless sandboxing is enabled, and with sandboxing on and workspace access not read-write, tools work in a sandbox workspace under the state directory instead.

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.

The file map

Operating instructions and how to use memory live in AGENTS.md, loaded at the start of every session, with a Tools section that carries local conventions but does not control tool availability. SOUL.md holds persona, tone and boundaries, loaded every session. USER.md is an optional directive-based user model with its own 4,000-character budget. IDENTITY.md holds the name, vibe and emoji from the bootstrap ritual. BOOT.md is an optional startup checklist run when the boot hook is enabled, and BOOTSTRAP.md the one-time first-run ritual, deleted once done. Daily memory logs sit in a memory folder, one file per day, and MEMORY.md is the curated long-term memory, loaded only in the main private session. A skills folder holds workspace skills, the highest-precedence skill location. A missing required file injects a marker and the session continues; optional files are simply omitted; large files are truncated under a per-file default of 20,000 characters and a total of 60,000, and the Control UI’s files editor is where you edit them.

What stays out, and the backup

• Not in the workspace and never committed with it: the config file, the shared state database, the per-agent runtime database with auth profiles, routing state, session rows and transcripts, the per-agent Codex home, the credentials directory, legacy session artifacts, and managed skills; older sidecar state files are imported and removed by the doctor.
• The recommended backup is a private git repository: brand-new workspaces are initialised automatically when git is present, then add the instruction, persona, identity, user and memory files, push to a private remote on GitHub or GitLab, and commit as memory changes.
• Even in a private repo, no secrets: no API keys, tokens or passwords, nothing from the state directory, no raw chat dumps or sensitive attachments; use placeholders and keep the real values in a password manager, the environment or the state directory, with the docs’ starter ignore file for env files, keys and certificates.

SOUL.md in OpenClaw covers the persona file in depth, and OpenClaw memory explained the daily logs and curated file the workspace is built around.

Moving it

Clone the repository to the desired path, point the agent’s workspace setting at it, confirm with the agents list command before starting the Gateway, and copy the per-agent session database separately if you need sessions; moving a workspace does not require rerunning onboarding. Multi-agent routing can give each agent its own workspace, and with sandboxing enabled non-main sessions can use per-session sandbox workspaces. OpenClaw backup and restore covers the archive that captures state and workspace together, and OpenClaw sandboxing explained the isolation the workspace itself does not provide.

On Diali

On Diali the workspace lives on the assistant’s persistent volume, seeded from what you wrote at onboarding, and the backups add-on is the private-repo step done for you. Hosted OpenClaw on Diali is the assistant and The OpenClaw system prompt explains where these files land in the prompt.

• The home, not a sandbox.
• Instructions, persona, identity, user, memory, skills.
• A private repo, and never a secret in it.