mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-15 10:36:09 +00:00
0a8e3604ba
* refactor(sessions): migrate runtime storage to sqlite * test(sessions): fix sqlite CI regressions * test(sessions): align remaining sqlite fixtures * fix(codex): require sqlite trajectory recorder * test(sessions): align orphan recovery sqlite fixture * test(sessions): align sqlite rebase fixtures * fix(sessions): finish current-main integration of the sqlite flip Resolve the whole-store SDK removal across its owner boundary: drop the loadSessionStore re-export and the registry whole-store wrappers, wire hasTrackedActiveSessionRun into gateway chat, complete the preserveLockedHarnessIds cleanup contract, flip the codex thread-history import to storePath targets, and port remaining main-side tests from file-store helpers to session accessor reads. * chore: drop committed pebbles log, revert plugin-inspector bump, refresh generated docs Remove the 1.8k-line .pebbles/events.jsonl work log from the branch, restore the plugin-inspector advisory lane to main's pinned 0.3.10 so the supply-chain bump gets its own review, and regenerate docs_map, the plugin SDK API baseline, and the export-surface ratchet for the merged tree. * feat(sessions): keep archived transcripts by default with zstd cold storage Codex-style retention: deleting or resetting a session archives its transcript as a zstd-compressed JSONL artifact (plain when the runtime lacks node:zlib zstd) and keeps it until the disk budget evicts oldest first. resetArchiveRetention now governs both deleted and reset archives and defaults to keep; maxDiskBytes defaults to 2gb so retention stays bounded, with archives evicted before live sessions. The cron reaper follows the same knob instead of deleting archives on its own timer. * fix(state): converge agent DB migration lineages and bound database growth Merge coherence: run both structure-gated legacy memory-schema repairs (flip-lineage drop, main-lineage identity rebuild) before the flip migration so pre-flip v1/v2 and pre-merge flip v1/v4 databases all converge, and hoist foreign_keys=OFF outside the schema transaction where the pragma was silently ignored and the v1 sessions rebuild cascade-deleted session_entries. Growth guards: fresh agent DBs enable auto_vacuum=INCREMENTAL, WAL maintenance releases freed pages in bounded passes (never a blocking full VACUUM), and doctor reports state/agent DB bloat from freelist stats. * fix(codex): resolve the store path for thread-history import via the SDK The supervision catalog passed the legacy sessionFile locator to the storePath-targeted transcript mirror; resolve the agent store path with the session-store SDK helper instead of a runtime-object seam so test fakes and headless callers need no extra surface. Drop the obsolete missing-session-id preprocessing case: sessions rows are NOT NULL on session_id and upsert repairs id-less patches at write time. * fix(sessions): fail safe on malformed disk-budget config and doctor stat errors A malformed explicit maxDiskBytes disables the budget instead of falling back to the destructive 2gb default the user never chose, and the doctor bloat check skips databases whose paths stat-fail instead of aborting doctor. * fix(sessions): complete sqlite conflict translations * test(sqlite): align hardening checks with maintenance * test(sessions): inspect compressed transcript archives * fix(tests): await session seeds and drop unused helpers flagged by CI lint The five unawaited writeSessionStoreSeed calls raced their SQLite seeds against the assertions, failing compact shards; the bloat probe drops a useless initializer and the merged tests drop now-unused helpers. * test(sessions): type legacy proof events directly * test(sessions): align hardening contracts * perf(sessions): read usage transcript sizes from SQL aggregates Usage/cost scans walked every session and materialized every transcript event just to re-stringify it for a byte estimate — the #86718 stall class reborn on the DB. readTranscriptStatsSync sums stored JSON bytes in SQLite without loading a single row. * fix(sessions): re-root foreign-root transcript paths onto the current sessions dir Restored backups, moved OPENCLAW_STATE_DIR, and rehearsal copies carry absolute sessionFile paths from the old root; the containment fallback kept those foreign paths, so migration read (and would archive) files in the original root and reported local copies missing. Re-root the canonical agents/<id>/sessions suffix onto the current dir when the file exists there; genuine cross-root layouts still fall through unchanged. * test(agents): seed harness admission through sqlite * fix(sqlite): close agent db on pragma setup failure * fix(doctor): compact and retrofit incremental auto-vacuum after session import The migration is the sanctioned offline window: post-import compact reclaims import churn and applies auto_vacuum=INCREMENTAL to databases created before the fresh-DB pragma existed, so runtime maintenance can release pages in bounded passes on every install. --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>
238 lines
9.8 KiB
Markdown
238 lines
9.8 KiB
Markdown
---
|
|
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/workspace-<profile>`.
|
|
- `OPENCLAW_WORKSPACE_DIR` overrides both of the above when set.
|
|
- Non-default agents (`agents.list[]`) without an explicit workspace resolve to `<state-dir>/workspace-<agentId>`, not the shared default workspace.
|
|
|
|
Override in `~/.openclaw/openclaw.json`:
|
|
|
|
```json5
|
|
{
|
|
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.
|
|
|
|
<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`. Keeping multiple workspace directories around can cause confusing auth or state drift, since 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` (or the per-agent `workspace` key) points to the active one.
|
|
</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 - 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>
|
|
|
|
## What is NOT in the workspace
|
|
|
|
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/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.
|
|
|
|
## 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 TOOLS.md IDENTITY.md USER.md HEARTBEAT.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.defaults.workspace` to that path in `~/.openclaw/openclaw.json`.
|
|
</Step>
|
|
<Step title="Seed missing files">
|
|
Run `openclaw setup --workspace <path>` to seed any missing files.
|
|
</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.list[].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.md workspace file
|
|
- [Sandboxing](/gateway/sandboxing) - workspace access in sandboxed environments
|
|
- [Session](/concepts/session) - session storage paths
|
|
- [Standing orders](/automation/standing-orders) - persistent instructions in workspace files
|