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.
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.
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.
Read all active files — AGENTS.md, SOUL.md, TOOLS.md, USER.md, IDENTITY.md, HEARTBEAT.md, BOOT.md, MEMORY.md
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
Flag files over 10,000 chars — prime candidates for trimming or offloading to docs/
Check for redundancy — same fact in SOUL.md and AGENTS.md? Same tool note in TOOLS.md and MEMORY.md?
Check for staleness — outdated SSH hosts, old tool names, deprecated rules, historical context that's no longer needed
Check MEMORY.md discipline — should contain curated facts, lessons learned, decisions, and critical rules — not raw session summaries or task-specific notes
Propose targeted edits — trim, move to docs/, or restructure
Keep checklists short — if a checklist exceeds ~50 lines, it's probably trying to be documentation; move narrative content to docs/ and keep only the actionable steps
Workflow: Update TOOLS.md
Use when adding a new tool, device, or environment capability.
TOOLS.md = environment-specific cheat sheet. It should contain:
SSH hosts and common commands for this specific machine
TTS provider, voice IDs, and any quirks
Camera IDs or device names for this setup
Node device IDs or names
Any local aliases or shortcuts that aren't obvious
Do NOT put in TOOLS.md:
General skill documentation (use skill SKILL.md files)
Things that are the same across all environments
Installation instructions (use docs/)
Format conventions:
# TOOLS.md - Local Notes## SSH- Main server: `ssh user@hostname`## TTS- Provider: Edge
- Voice: zh-CN-XiaoxiaoNeural
## Cameras- Living room: node-id `abc123`, device `camera-0`
Common Issues
File exceeds token limit
Symptom: File is over 20,000 chars; OpenClaw may truncate it.
Fix: Audit for content that belongs in docs/ (loaded on demand) instead of the bootstrap file. Move detailed references, historical context, and long examples out. Keep only what needs to be on every turn.
MEMORY.md leaking to groups
Symptom: Agent shares private context in group chats or Discord.
Fix: Ensure MEMORY.md boot step in AGENTS.md is gated: "Main session only: Read MEMORY.md". Verify the agent's boot sequence explicitly checks session type before loading.
Boot sequence not loading files
Symptom: Agent doesn't know about content in SOUL.md, USER.md, or MEMORY.md at session start.
Fix: Check that AGENTS.md boot sequence explicitly names each file to read. The agent won't auto-load files — it follows the boot sequence instructions in AGENTS.md. Verify hooks.internal.enabled = true in config if using BOOT.md.
MEMORY.md growing too large
Symptom: File approaches or exceeds 10,000 chars; reading it on every turn wastes significant context.
Fix: Run memory distillation workflow. Move stable rules that have been incident-free for months into relevant skill SKILL.md files. Delete rules that are no longer relevant.
Workspace changes not taking effect
Symptom: Agent still uses old content after editing a workspace file.
Fix: Workspace files are read at session start per the boot sequence. Restart the gateway or start a new session for changes to take effect.
