docs/concepts/agent-workspace.md
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.
</Warning>
~/.openclaw/workspaceOPENCLAW_PROFILE is set and not "default", the default becomes ~/.openclaw/workspace-<profile>.OPENCLAW_WORKSPACE_DIR overrides both of the above when set.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 } } }
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.
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 - who the user is"> Who the user is and how to address them. Loaded every session. </Accordion> <Accordion title="IDENTITY.md - name, vibe, emoji"> The agent's name, vibe, and emoji. Created/updated during the bootstrap ritual. </Accordion> <Accordion title="TOOLS.md - local tool conventions"> Notes about your local tools and conventions. Does not control tool availability; it is only guidance. </Accordion> <Accordion title="HEARTBEAT.md - heartbeat checklist"> Optional tiny checklist for heartbeat runs. Keep it short to avoid token burn. </Accordion> <Accordion title="BOOT.md - startup checklist"> Optional startup checklist run automatically on gateway restart (when [internal hooks](/automation/hooks) are enabled). 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 facts, preferences, 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> <Accordion title="canvas/ - Canvas UI files (optional)"> Canvas UI files for node displays (for example `canvas/index.html`). </Accordion> </AccordionGroup> <Note> If a bootstrap file is missing, OpenClaw injects a "missing file" marker into the session and continues. Large bootstrap files are truncated when injected; adjust limits with `agents.defaults.bootstrapMaxChars` (default: `20000`) and `agents.defaults.bootstrapTotalMaxChars` (default: `60000`). `openclaw setup` can recreate missing defaults without overwriting existing files. </Note>These live under ~/.openclaw/ and should NOT be committed to the workspace repo:
~/.openclaw/openclaw.json (config)~/.openclaw/agents/<agentId>/agent/auth-profiles.json (model auth profiles: OAuth + API keys)~/.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/ (session transcripts + metadata)~/.openclaw/skills/ (managed skills)If you need to migrate sessions or config, 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 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 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>
~/.openclaw/.If you must store sensitive references, use placeholders and keep the real secret elsewhere (password manager, environment variables, or ~/.openclaw/).
</Warning>
Suggested .gitignore starter:
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*
agents.list[].workspace. See Channel routing for routing configuration.agents.defaults.sandbox is enabled, non-main sessions can use per-session sandbox workspaces under agents.defaults.sandbox.workspaceRoot.