@@ -4,26 +4,23 @@ read_when:
44 - You need to explain the agent workspace or its file layout
55 - You want to back up or migrate an agent workspace
66title: "Agent workspace"
7+sidebarTitle: "Agent workspace"
78---
899-The workspace is the agent's home. It is the only working directory used for
10-file tools and for workspace context. Keep it private and treat it as memory.
10+The workspace is the agent's home. It is the only working directory used for file tools and for workspace context. Keep it private and treat it as memory.
111112-This is separate from `~/.openclaw/`, which stores config, credentials, and
13-sessions.
12+This is separate from `~/.openclaw/`, which stores config, credentials, and sessions.
141315-**Important:** the workspace is the **default cwd**, not a hard sandbox. Tools
16-resolve relative paths against the workspace, but absolute paths can still reach
17-elsewhere on the host unless sandboxing is enabled. If you need isolation, use
18-[`agents.defaults.sandbox`](/gateway/sandboxing) (and/or per‑agent sandbox config).
19-When sandboxing is enabled and `workspaceAccess` is not `"rw"`, tools operate
20-inside a sandbox workspace under `~/.openclaw/sandboxes`, not your host workspace.
14+<Warning>
15+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).
16+17+When sandboxing is enabled and `workspaceAccess` is not `"rw"`, tools operate inside a sandbox workspace under `~/.openclaw/sandboxes`, not your host workspace.
18+</Warning>
21192220## Default location
23212422- Default: `~/.openclaw/workspace`
25-- If `OPENCLAW_PROFILE` is set and not `"default"`, the default becomes
26-`~/.openclaw/workspace-<profile>`.
23+- If `OPENCLAW_PROFILE` is set and not `"default"`, the default becomes `~/.openclaw/workspace-<profile>`.
2724- Override in `~/.openclaw/openclaw.json`:
28252926```json5
@@ -36,94 +33,74 @@ inside a sandbox workspace under `~/.openclaw/sandboxes`, not your host workspac
3633}
3734```
383539-`openclaw onboard`, `openclaw configure`, or `openclaw setup` will create the
40-workspace and seed the bootstrap files if they are missing.
41-Sandbox seed copies only accept regular in-workspace files; symlink/hardlink
42-aliases that resolve outside the source workspace are ignored.
36+`openclaw onboard`, `openclaw configure`, or `openclaw setup` will create the workspace and seed the bootstrap files if they are missing.
37+38+<Note>
39+Sandbox seed copies only accept regular in-workspace files; symlink/hardlink aliases that resolve outside the source workspace are ignored.
40+</Note>
434144-If you already manage the workspace files yourself, you can disable bootstrap
45-file creation:
42+If you already manage the workspace files yourself, you can disable bootstrap file creation:
46434744```json5
4845{ agents: { defaults: { skipBootstrap: true } } }
4946```
50475148## Extra workspace folders
524953-Older installs may have created `~/openclaw`. Keeping multiple workspace
54-directories around can cause confusing auth or state drift, because only one
55-workspace is active at a time.
50+Older installs may have created `~/openclaw`. Keeping multiple workspace directories around can cause confusing auth or state drift, because only one workspace is active at a time.
565157-**Recommendation:** keep a single active workspace. If you no longer use the
58-extra folders, archive or move them to Trash (for example `trash ~/openclaw`).
59-If you intentionally keep multiple workspaces, make sure
60-`agents.defaults.workspace` points to the active one.
52+<Note>
53+**Recommendation:** keep a single active workspace. If you no longer use the extra folders, archive or move them to Trash (for example `trash ~/openclaw`). If you intentionally keep multiple workspaces, make sure `agents.defaults.workspace` points to the active one.
61546255`openclaw doctor` warns when it detects extra workspace directories.
56+</Note>
635764-## Workspace file map (what each file means)
58+## Workspace file map
65596660These are the standard files OpenClaw expects inside the workspace:
676168-- `AGENTS.md`
69-- Operating instructions for the agent and how it should use memory.
70-- Loaded at the start of every session.
71-- Good place for rules, priorities, and "how to behave" details.
72-73-- `SOUL.md`
74-- Persona, tone, and boundaries.
75-- Loaded every session.
76-- Guide: [SOUL.md Personality Guide](/concepts/soul)
77-78-- `USER.md`
79-- Who the user is and how to address them.
80-- Loaded every session.
81-82-- `IDENTITY.md`
83-- The agent's name, vibe, and emoji.
84-- Created/updated during the bootstrap ritual.
85-86-- `TOOLS.md`
87-- Notes about your local tools and conventions.
88-- Does not control tool availability; it is only guidance.
89-90-- `HEARTBEAT.md`
91-- Optional tiny checklist for heartbeat runs.
92-- Keep it short to avoid token burn.
93-94-- `BOOT.md`
95-- Optional startup checklist run automatically on gateway restart (when [internal hooks](/automation/hooks) are enabled).
96-- Keep it short; use the message tool for outbound sends.
97-98-- `BOOTSTRAP.md`
99-- One-time first-run ritual.
100-- Only created for a brand-new workspace.
101-- Delete it after the ritual is complete.
102-103-- `memory/YYYY-MM-DD.md`
104-- Daily memory log (one file per day).
105-- Recommended to read today + yesterday on session start.
106-107-- `MEMORY.md` (optional)
108-- Curated long-term memory.
109-- Only load in the main, private session (not shared/group contexts).
110-111-See [Memory](/concepts/memory) for the workflow and automatic memory flush.
112-113-- `skills/` (optional)
114-- Workspace-specific skills.
115-- Highest-precedence skill location for that workspace.
116-- Overrides project agent skills, personal agent skills, managed skills, bundled skills, and `skills.load.extraDirs` when names collide.
117-118-- `canvas/` (optional)
119-- Canvas UI files for node displays (for example `canvas/index.html`).
120-121-If any bootstrap file is missing, OpenClaw injects a "missing file" marker into
122-the session and continues. Large bootstrap files are truncated when injected;
123-adjust limits with `agents.defaults.bootstrapMaxChars` (default: 12000) and
124-`agents.defaults.bootstrapTotalMaxChars` (default: 60000).
125-`openclaw setup` can recreate missing defaults without overwriting existing
126-files.
62+<AccordionGroup>
63+<Accordion title="AGENTS.md — operating instructions">
64+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.
65+</Accordion>
66+<Accordion title="SOUL.md — persona and tone">
67+Persona, tone, and boundaries. Loaded every session. Guide: [SOUL.md personality guide](/concepts/soul).
68+</Accordion>
69+<Accordion title="USER.md — who the user is">
70+Who the user is and how to address them. Loaded every session.
71+</Accordion>
72+<Accordion title="IDENTITY.md — name, vibe, emoji">
73+The agent's name, vibe, and emoji. Created/updated during the bootstrap ritual.
74+</Accordion>
75+<Accordion title="TOOLS.md — local tool conventions">
76+Notes about your local tools and conventions. Does not control tool availability; it is only guidance.
77+</Accordion>
78+<Accordion title="HEARTBEAT.md — heartbeat checklist">
79+Optional tiny checklist for heartbeat runs. Keep it short to avoid token burn.
80+</Accordion>
81+<Accordion title="BOOT.md — startup checklist">
82+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.
83+</Accordion>
84+<Accordion title="BOOTSTRAP.md — first-run ritual">
85+One-time first-run ritual. Only created for a brand-new workspace. Delete it after the ritual is complete.
86+</Accordion>
87+<Accordion title="memory/YYYY-MM-DD.md — daily memory log">
88+Daily memory log (one file per day). Recommended to read today + yesterday on session start.
89+</Accordion>
90+<Accordion title="MEMORY.md — curated long-term memory (optional)">
91+Curated long-term memory. Only load in the main, private session (not shared/group contexts). See [Memory](/concepts/memory) for the workflow and automatic memory flush.
92+</Accordion>
93+<Accordion title="skills/ — workspace skills (optional)">
94+Workspace-specific skills. Highest-precedence skill location for that workspace. Overrides project agent skills, personal agent skills, managed skills, bundled skills, and `skills.load.extraDirs` when names collide.
95+</Accordion>
96+<Accordion title="canvas/ — Canvas UI files (optional)">
97+Canvas UI files for node displays (for example `canvas/index.html`).
98+</Accordion>
99+</AccordionGroup>
100+101+<Note>
102+If any 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: 12000) and `agents.defaults.bootstrapTotalMaxChars` (default: 60000). `openclaw setup` can recreate missing defaults without overwriting existing files.
103+</Note>
127104128105## What is NOT in the workspace
129106@@ -135,83 +112,82 @@ These live under `~/.openclaw/` and should NOT be committed to the workspace rep
135112- `~/.openclaw/agents/<agentId>/sessions/` (session transcripts + metadata)
136113- `~/.openclaw/skills/` (managed skills)
137114138-If you need to migrate sessions or config, copy them separately and keep them
139-out of version control.
115+If you need to migrate sessions or config, copy them separately and keep them out of version control.
140116141117## Git backup (recommended, private)
142118143-Treat the workspace as private memory. Put it in a **private** git repo so it is
144-backed up and recoverable.
145-146-Run these steps on the machine where the Gateway runs (that is where the
147-workspace lives).
148-149-### 1) Initialize the repo
150-151-If git is installed, brand-new workspaces are initialized automatically. If this
152-workspace is not already a repo, run:
153-154-```bash
155-cd ~/.openclaw/workspace
156-git init
157-git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
158-git commit -m "Add agent workspace"
159-```
160-161-### 2) Add a private remote (beginner-friendly options)
162-163-Option A: GitHub web UI
164-165-1. Create a new **private** repository on GitHub.
166-2. Do not initialize with a README (avoids merge conflicts).
167-3. Copy the HTTPS remote URL.
168-4. Add the remote and push:
169-170-```bash
171-git branch -M main
172-git remote add origin <https-url>
173-git push -u origin main
174-```
175-176-Option B: GitHub CLI (`gh`)
177-178-```bash
179-gh auth login
180-gh repo create openclaw-workspace --private --source . --remote origin --push
181-```
182-183-Option C: GitLab web UI
184-185-1. Create a new **private** repository on GitLab.
186-2. Do not initialize with a README (avoids merge conflicts).
187-3. Copy the HTTPS remote URL.
188-4. Add the remote and push:
189-190-```bash
191-git branch -M main
192-git remote add origin <https-url>
193-git push -u origin main
194-```
195-196-### 3) Ongoing updates
197-198-```bash
199-git status
200-git add .
201-git commit -m "Update memory"
202-git push
203-```
119+Treat the workspace as private memory. Put it in a **private** git repo so it is backed up and recoverable.
120+121+Run these steps on the machine where the Gateway runs (that is where the workspace lives).
122+123+<Steps>
124+<Step title="Initialize the repo">
125+If git is installed, brand-new workspaces are initialized automatically. If this workspace is not already a repo, run:
126+127+```bash
128+cd ~/.openclaw/workspace
129+git init
130+git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
131+git commit -m "Add agent workspace"
132+```
133+134+</Step>
135+<Step title="Add a private remote">
136+<Tabs>
137+ <Tab title="GitHub web UI">
138+ 1. Create a new **private** repository on GitHub.
139+ 2. Do not initialize with a README (avoids merge conflicts).
140+ 3. Copy the HTTPS remote URL.
141+ 4. Add the remote and push:
142+143+ ```bash
144+ git branch -M main
145+ git remote add origin <https-url>
146+ git push -u origin main
147+ ```
148+ </Tab>
149+ <Tab title="GitHub CLI (gh)">
150+ ```bash
151+ gh auth login
152+ gh repo create openclaw-workspace --private --source . --remote origin --push
153+ ```
154+ </Tab>
155+ <Tab title="GitLab web UI">
156+ 1. Create a new **private** repository on GitLab.
157+ 2. Do not initialize with a README (avoids merge conflicts).
158+ 3. Copy the HTTPS remote URL.
159+ 4. Add the remote and push:
160+161+ ```bash
162+ git branch -M main
163+ git remote add origin <https-url>
164+ git push -u origin main
165+ ```
166+ </Tab>
167+</Tabs>
168+169+</Step>
170+<Step title="Ongoing updates">
171+```bash
172+git status
173+git add .
174+git commit -m "Update memory"
175+git push
176+```
177+</Step>
178+</Steps>
204179205180## Do not commit secrets
206181182+<Warning>
207183Even in a private repo, avoid storing secrets in the workspace:
208184209185- API keys, OAuth tokens, passwords, or private credentials.
210186- Anything under `~/.openclaw/`.
211187- Raw dumps of chats or sensitive attachments.
212188213-If you must store sensitive references, use placeholders and keep the real
214-secret elsewhere (password manager, environment variables, or `~/.openclaw/`).
189+If you must store sensitive references, use placeholders and keep the real secret elsewhere (password manager, environment variables, or `~/.openclaw/`).
190+</Warning>
215191216192Suggested `.gitignore` starter:
217193@@ -225,22 +201,29 @@ Suggested `.gitignore` starter:
225201226202## Moving the workspace to a new machine
227203228-1. Clone the repo to the desired path (default `~/.openclaw/workspace`).
229-2. Set `agents.defaults.workspace` to that path in `~/.openclaw/openclaw.json`.
230-3. Run `openclaw setup --workspace <path>` to seed any missing files.
231-4. If you need sessions, copy `~/.openclaw/agents/<agentId>/sessions/` from the
232- old machine separately.
204+<Steps>
205+<Step title="Clone the repo">
206+Clone the repo to the desired path (default `~/.openclaw/workspace`).
207+</Step>
208+<Step title="Update config">
209+Set `agents.defaults.workspace` to that path in `~/.openclaw/openclaw.json`.
210+</Step>
211+<Step title="Seed missing files">
212+Run `openclaw setup --workspace <path>` to seed any missing files.
213+</Step>
214+<Step title="Copy sessions (optional)">
215+If you need sessions, copy `~/.openclaw/agents/<agentId>/sessions/` from the old machine separately.
216+</Step>
217+</Steps>
233218234219## Advanced notes
235220236-- Multi-agent routing can use different workspaces per agent. See
237-[Channel routing](/channels/channel-routing) for routing configuration.
238-- If `agents.defaults.sandbox` is enabled, non-main sessions can use per-session sandbox
239- workspaces under `agents.defaults.sandbox.workspaceRoot`.
221+- Multi-agent routing can use different workspaces per agent. See [Channel routing](/channels/channel-routing) for routing configuration.
222+- If `agents.defaults.sandbox` is enabled, non-main sessions can use per-session sandbox workspaces under `agents.defaults.sandbox.workspaceRoot`.
240223241224## Related
242225243-- [Standing Orders](/automation/standing-orders) — persistent instructions in workspace files
244226- [Heartbeat](/gateway/heartbeat) — HEARTBEAT.md workspace file
245-- [Session](/concepts/session) — session storage paths
246227- [Sandboxing](/gateway/sandboxing) — workspace access in sandboxed environments
228+- [Session](/concepts/session) — session storage paths
229+- [Standing orders](/automation/standing-orders) — persistent instructions in workspace files
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。