/openclaw-workspace

name: openclaw-workspace
description: Use when maintaining or optimizing OpenClaw workspace files — AGENTS.md, TOOLS.md, SOUL.md, USER.md, IDENTITY.md, HEARTBEAT.md, BOOT.md, MEMORY.md, and related checklists and memory files. Covers workspace auditing, token budget analysis, new agent workspace setup from scratch, memory distillation, and cross-file consistency reviews.

OpenClaw Workspace Skill

Overview

OpenClaw workspace files form the agent's "soul and memory" — they are injected into the system prompt on every turn (or on relevant turns), giving the agent its identity, behavioral rules, environmental knowledge, and long-term memory. Managing these files well is critical: bloat wastes tokens, redundancy creates confusion, and stale content leads to bad decisions.

**Token budget:** 20,000 chars per file, ~150,000 chars total across all bootstrap files.

File Inventory

| File | Purpose | Loaded When | Sub-agents? | |------|---------|-------------|-------------| | `AGENTS.md` | Boot sequence, checklists, behavioral rules | Every turn (all agents) | Yes | | `SOUL.md` | Persona, tone, values, continuity philosophy | Every turn (all agents) | Yes | | `TOOLS.md` | Env-specific notes (SSH, TTS, cameras, devices) | On-demand reference (part of bootstrap set) | Yes | | `USER.md` | Human profile, preferences, relationship context | Every turn (all agents) | Yes | | `IDENTITY.md` | Name, emoji, avatar, self-description | Every turn | Yes | | `HEARTBEAT.md` | Periodic check tasks and health routines | Every heartbeat turn | Depends | | `BOOT.md` | Startup actions (requires `hooks.internal.enabled`) | On gateway startup | No | | `BOOTSTRAP.md` | First-time onboarding script — delete after use | New workspaces only | No | | `MEMORY.md` | Long-term curated facts and iron-law rules | Main sessions only | No | | `memory/YYYY-MM-DD.md` | Daily session logs | Loaded per AGENTS.md boot sequence | No | | `checklists/*.md` | Step-by-step ops guides | Referenced in AGENTS.md, loaded on demand | No |

**Security rule:** MEMORY.md must NEVER be loaded in group chats or sub-agent sessions — it contains private context that should not leak.

For full details on each file's design, anti-patterns, and section structure, see [references/workspace-files.md](references/workspace-files.md).

Workspace Paths

| Path | Purpose | |------|---------| | `~/.openclaw/workspace/` | Default workspace for main agent | | `~/.openclaw/workspace-<profile>/` | Per-profile workspace (multiple agents) | | `~/.openclaw/workspace/vendor/OpenClaw-Memory/` | Vendor-managed base files (synced from upstream) | | `~/.openclaw/workspace/checklists/` | Checklist files referenced from AGENTS.md | | `~/.openclaw/workspace/memory/` | Daily session logs | | `~/.openclaw/workspace/docs/` | On-demand documentation (NOT auto-loaded) |

Config key: `agents.defaults.workspace` or per-agent `agents.list[].workspace`.

Workflow: Audit Existing Workspace

Use when workspace files may be bloated, stale, or redundant.

1. **Read all active files** — AGENTS.md, SOUL.md, TOOLS.md, USER.md, IDENTITY.md, HEARTBEAT.md, BOOT.md, MEMORY.md 2. **Check character counts:**

   wc -c ~/.openclaw/workspace/AGENTS.md
   wc -c ~/.openclaw/workspace/SOUL.md
   wc -c ~/.openclaw/workspace/TOOLS.md
   wc -c ~/.openclaw/workspace/USER.md
   wc -c ~/.openclaw/workspace/IDENTITY.md
   wc -c ~/.openclaw/workspace/MEMORY.md
   # Or all at once:
   wc -c ~/.openclaw/workspace/*.md

3. **Flag files over 10,000 chars** — prime candidates for trimming or offloading to `docs/` 4. **Check for redundancy** — same fact in SOUL.md and AGENTS.md? Same tool note in TOOLS.md and MEMORY.md? 5. **Check for staleness** — outdated SSH hosts, old tool names, deprecated rules, historical context that's no longer needed 6. **Check MEMORY.md discipline** — should contain curated facts, lessons learned, decisions, and critical rules — not raw session summaries or task-specific notes 7. **Propose targeted edits** — trim, move to docs/, or restructure

See [references/optimization-guide.md](references/optimization-guide.md) for specific optimization strategies.

Workflow: Set Up New Workspace

Use when creating a workspace for a new agent from scratch.

**File creation order** (matters for boot sequence to work):

1. `SOUL.md` — persona and values first; everything else follows from identity 2. `AGENTS.md` — boot sequence, safety rules, checklist table 3. `IDENTITY.md` — name, emoji, avatar 4. `USER.md` — human profile and preferences (main agent only) 5. `TOOLS.md` — environment-specific notes (add as you discover env details) 6. `MEMORY.md` — start minimal; only truly universal iron laws 7. `HEARTBEAT.md` — periodic health checks (optional, add when needed) 8. `BOOT.md` — startup hooks (optional, only if `hooks.internal.enabled = true`) 9. `BOOTSTRAP.md` — first-run onboarding (optional; delete after first successful startup)

**Minimal viable workspace:** AGENTS.md + SOUL.md + TOOLS.md. Everything else is optional.

**BOOTSTRAP.md note:** If creating a BOOTSTRAP.md, include a self-deletion instruction at the end:

## Final Step
Delete this file: exec `rm ~/.openclaw/workspace/BOOTSTRAP.md`

Workflow: Memory Distillation

Use periodically (weekly or monthly) to keep MEMORY.md lean.

1. **Read all recent daily logs:** `memory/YYYY-MM-DD.md` files from the past period 2. **Identify candidates for promotion to MEMORY.md:**

• Rules violated more than once (recurring mistakes)
• Hard-won discoveries that aren't in skills docs
• Env-specific facts that should always be in context (not left to memory_search recall)

3. **Check what's already in MEMORY.md** — avoid duplicates 4. **Draft additions** — use iron-law format: concise, action-oriented, unambiguous 5. **Archive old daily logs** — move files older than 30 days to `memory/archive/` or delete 6. **Check MEMORY.md total size** — keep under 10,000 chars; if larger, review for rules that a