Technical reference for the OpenClaw framework. Real-time synchronization with the official documentation engine.
Use this file to discover all available pages before exploring further.
Agent workspace
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.
This is separate from
text
~/.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).
will 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.
If you already manage the workspace files yourself, you can disable bootstrap file creation:
json5
{ agents: { defaults: { skipBootstrap: true } } }
Extra workspace folders
Older installs may have created
text
~/openclaw
. Keeping multiple workspace directories around can cause confusing auth or state drift, because only one workspace is active at a time.
note
**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.
text
openclaw doctor
warns when it detects extra workspace directories.
Workspace file map
These are the standard files OpenClaw expects inside the workspace:
note
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.
What is NOT in the workspace
These live under
text
~/.openclaw/
and should NOT be committed to the workspace repo:
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:
text
```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>