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
.
Workspace Paths
Path
Purpose
~/.openclaw/workspace/
Default workspace for main agent
~/.openclaw/workspace-
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 See 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): SOUL.md — persona and values first; everything else follows from identity AGENTS.md — boot sequence, safety rules, checklist table IDENTITY.md — name, emoji, avatar USER.md — human profile and preferences (main agent only) TOOLS.md — environment-specific notes (add as you discover env details) MEMORY.md — start minimal; only truly universal iron laws HEARTBEAT.md — periodic health checks (optional, add when needed) BOOT.md — startup hooks (optional, only if hooks.internal.enabled = true ) 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.
Read all recent daily logs:
memory/YYYY-MM-DD.md
files from the past period
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)
Check what's already in MEMORY.md
— avoid duplicates
Draft additions
— use iron-law format: concise, action-oriented, unambiguous
Archive old daily logs
— move files older than 30 days to
memory/archive/
or delete
Check MEMORY.md total size
— keep under 10,000 chars; if larger, review for rules that are now stable enough to move to a skill's SKILL.md instead
Do NOT put in MEMORY.md:
Long narratives or session summaries
Things already covered in skill docs
Anything specific to a single past task
Episodic or task-specific memories (store those via memory_search/SQLite instead)
Workflow: Add or Update a Checklist
Use when adding a new high-risk operation type or updating an existing checklist.
Create or edit
checklists/
Checklist:
Pre-flight
[ ] Step 1
[ ] Step 2
Execution
[ ] Step 3
Verification
[ ] Confirm outcome
[ ] Log result in memory Register in AGENTS.md — add a row to the checklists table: | < Operation description
|
checklists/<filename>.md| 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.
Reference Files
Reference
Coverage
workspace-files.md
Deep-dive on each file: purpose, design principles, anti-patterns, section structure
optimization-guide.md
Token efficiency strategies, audit commands, distillation process