Workspace Overview

OpenClaw Workspace Architecture

This skill covers the structure, loading mechanics, and organization of an OpenClaw agent workspace.

Instance Directory Structure

Standard layout: ~/.openclaw/ (single instance). Multi-profile via OPENCLAW_PROFILE env var creates ~/.openclaw/workspace-<profile>.

Docker multi-instance layout: Each instance lives at ~/.openclaw-{name}/ (e.g. ~/.openclaw-<name>/). This is a deployment convention for running multiple OpenClaw instances, each with its own config and workspace.

Instance dir vs Project dir

For Docker deployments these are two different directories:

Resolution priority used by workspace-aware commands (workspace-scan, config-validate, workspace-optimize, the permissions hook):

OPENCLAW_INSTANCE_DIR  >  OPENCLAW_PROJECT_DIR  >  $(pwd)

OPENCLAW_PROJECT_DIR alone is used by instance-update (git pull / rebuild) and as the docker compose working dir when fixing permissions. All other commands target the instance dir. When both are unset, the plugin falls back to CWD and the legacy single-instance layout still works.

All paths below are relative to the resolved instance dir.

./                              # Instance root (~/.openclaw-{name}/)
├── workspace/                  # Workspace files (auto-injected)
│   ├── AGENTS.md               # Operating rules, procedures
│   ├── SOUL.md                 # Persona, tone, boundaries
│   ├── USER.md                 # User profiles, preferences
│   ├── IDENTITY.md             # Agent name, emoji, avatar
│   ├── TOOLS.md                # Tool notes, priorities
│   ├── HEARTBEAT.md            # Background task checklist
│   ├── MEMORY.md               # Curated long-term memory
│   ├── BOOT.md                 # Gateway restart instructions
│   ├── BOOTSTRAP.md            # First-run ritual (deleted after)
│   ├── docs/                   # On-demand reference files
│   │   ├── rules/              # Extended rules
│   │   ├── procedures/         # Task-specific guides
│   │   ├── clients/            # Client profiles
│   │   └── standing-orders/    # Recurring autonomous tasks
│   ├── workflows/              # .prose workflow files
│   ├── canvas/                 # Canvas UI files (optional)
│   ├── memory/                 # Daily logs (auto-created)
│   └── skills/                 # Instance-specific skills
├── agents/
│   └── main/
│       └── sessions/
│           ├── sessions.json   # Session index
│           └── *.jsonl         # Session transcripts
├── memory/
│   └── main.sqlite             # Hybrid BM25 + vector search index (auto-built)
├── cron/
│   └── jobs.json               # Scheduled jobs
├── logs/
│   └── openclaw.log            # Gateway log
├── openclaw.json               # Central gateway configuration
├── credentials/                # DO NOT SCAN
├── telegram/                   # DO NOT SCAN
├── devices/                    # DO NOT SCAN
├── subagents/                  # DO NOT SCAN
├── completions/                # DO NOT SCAN
├── delivery-queue/             # DO NOT SCAN
├── media/                      # DO NOT SCAN
├── identity/                   # DO NOT SCAN
├── config.yaml                 # DO NOT SCAN
└── *.bak*                      # DO NOT SCAN

Shared Resources

Standard paths:

~/.openclaw/skills/*/SKILL.md               # Managed/local skills

Docker deployment paths (deployment-specific, may vary):

/root/openclaw-skills/*/SKILL.md            # Shared public skills
/root/openclaw-private-skills/*/SKILL.md    # Shared private skills
/root/openclaw-plugins/packages/*/          # Shared public plugins
/root/openclaw-plugins-private/packages/*/  # Shared private plugins

Additional skill directories via skills.load.extraDirs in openclaw.json.

ClawHub (clawhub.com) is the public registry for discovering and sharing skills and plugins.

Scan Categories (A–J + Shared)

Write scope: The plugin creates/edits files in ./workspace/ and ./openclaw.json (with explicit user permission). Everything else is read-only for analysis.

DO NOT SCAN — Excluded Directories

These contain sensitive/internal data (OAuth tokens, session state, device pairing, certs) — reading them risks exposing secrets in LLM context. Do not scan:

• ./credentials/ — OAuth tokens, API keys
• ./telegram/ — Telegram session state
• ./devices/ — device pairing data
• ./subagents/ — internal subagent state
• ./completions/ — LLM completion cache
• ./delivery-queue/ — message delivery queue
• ./media/ — media file cache
• ./identity/ — certificates and identity data
• ./config.yaml — internal gateway config
• ./*.bak* — backup files
• ./memory/main.sqlite-wal — sqlite WAL (do not touch)
• ./memory/main.sqlite-shm — sqlite shared memory (do not touch)

Auto-Injected Files (loaded every session)

These 7 files are injected into the agent's context window on every turn — they consume tokens constantly. The bootstrapMaxChars and bootstrapTotalMaxChars limits apply to these files.

Sub-agents only get AGENTS.md and TOOLS.md — other files are filtered out to keep sub-agent context small.

BOOTSTRAP.md — Auto-Injected When Present (Temporary)

BOOTSTRAP.md IS auto-injected into the agent's context while it exists. It is created for brand-new workspaces during openclaw onboard and deleted after the bootstrap ritual completes. While present, it counts toward bootstrapMaxChars / bootstrapTotalMaxChars limits like any other auto-injected file.

Scanning behavior:

• BOOTSTRAP.md missing → good (means bootstrap completed successfully)
• BOOTSTRAP.md present → warning (bootstrap hasn't finished — the agent should complete or remove it)
• Can be skipped: --dev flag or agent.skipBootstrap: true in openclaw.json

BOOT.md — Hook-Executed, NOT Auto-Injected

BOOT.md is NOT injected into the session context window. It is executed via the boot-md hook on gateway:startup event only. It is NOT counted toward character limits.

Scanning behavior:

• BOOT.md missing → normal (optional file, user creates if needed)

Character Limits

These limits apply ONLY to the 7 auto-injected files listed above. Other files in workspace/ (agent-created files, docs/ subfolders, etc.) are NOT counted toward these limits and are NOT loaded into context automatically.

• Per file: bootstrapMaxChars = 20,000 characters (default)
• Total across all auto-injected files: bootstrapTotalMaxChars = 150,000 characters (default)
• Files exceeding limits are truncated with a marker
• BOOT.md is NOT counted (not auto-injected — hook-executed only)
• BOOTSTRAP.md IS counted while present (auto-injected on new workspaces, deleted after bootstrap)
• Override in ./openclaw.json:

  {
    "agents": {
      "defaults": {
        "bootstrapMaxChars": 30000,
        "bootstrapTotalMaxChars": 200000
      }
    }
  }
  

The workspace/ folder can contain any files — agents create files there during sessions (research notes, drafts, exports). These extra files are perfectly fine — they don't consume context tokens and don't count toward limits. If they're reference material the agent should access later, move them to docs/ and reference from AGENTS.md.

Warning Signs — When to Extract to Subfolders

• Auto-injected file > 15K chars → approaching the 20K truncation limit, move infrequently-used sections to docs/
• AGENTS.md contains procedure sections → extract to docs/procedures/
• AGENTS.md contains client-specific rules → extract to docs/clients/
• AGENTS.md contains detailed security policies → extract to docs/rules/
• Any non-standard .md file in workspace/ root → if it's reference material, move to docs/ and add a reference in AGENTS.md

Key Rule: SOUL vs AGENTS Separation

• SOUL.md = WHO the agent IS (persona, values, tone, boundaries)
• AGENTS.md = HOW the agent OPERATES (procedures, rules, memory management, group chat behavior)
• Never mix personality into AGENTS.md or procedures into SOUL.md

Workspace Subfolders — On-Demand Reference Files

Only auto-injected files are loaded every session. Everything in subfolders is read on demand by the agent via the read tool — saving tokens when content is not relevant.

Key rules:

• If content is needed in >= 50% of sessions → keep in auto-injected files
• If content is needed in < 50% of sessions → move to docs/
• If content is critical for safety → keep in AGENTS.md or SOUL.md regardless
• One topic per file, lowercase-hyphen naming

See references/subfolder-patterns.md for detailed subfolder structure, templates, and examples.

Files NOT Auto-Loaded

These exist in workspace/ but are NOT injected into context — the agent reads them on demand:

• BOOT.md — executed via hook on gateway restart, not injected
• memory/YYYY-MM-DD.md — daily memory logs (accessed via memory tools)
• docs/**/*.md — documentation subfolders (read when referenced from AGENTS.md)
• workflows/*.prose — workflow files
• canvas/ — canvas UI files
• skills/ — instance-specific skills (injected as compact XML list ~97 chars per skill; full SKILL.md loaded on demand when triggered)
• Any other files — agents can create arbitrary files in workspace/ during sessions (research, exports, drafts). These are stored but not loaded into context.

Content Language

Write all workspace file content in English. This ensures consistency across multi-user setups, better compatibility with LLM models (which process English instructions more reliably), and clearer prompt engineering. Users may communicate with the agent in any language, but the workspace files themselves are always English.

Referencing Subfolders from AGENTS.md

Since subfolders are NOT auto-loaded, reference them explicitly:

## Reference Documents
Before starting a task, check if a relevant doc exists.
Read it with: read docs/<folder>/<file>.md

Available docs:
- docs/rules/         — security rules, data classification
- docs/procedures/    — step-by-step guides for specific task types
- docs/clients/       — client profiles, contracts, key facts
- docs/standing-orders/ — recurring tasks and schedules

Version Control

Initialize git tracking for workspace files in a private repository. Exclude secrets:

.env
*.key
*.pem
secrets*

Customization Workflow

The recommended approach for workspace optimization:

1. Scan — read all current workspace files, check for gaps
2. Interview — understand goals, users, tasks, channels, success criteria
3. Analyze — identify missing rules, conflicts, unused tools, pain points
4. Security audit — check for secrets, prompt injection risks, missing safety rules
5. Optimize — generate improved files following best practices
6. Apply — show diffs, get approval, write changes to ./workspace/
7. Fix permissions — run chown + doctor in Docker after edits
8. Iterate — start short, add rules when problems are observed

SOUL.md Size Rule

Keep SOUL.md under 2,000 words. Every word costs tokens on EVERY interaction since it's injected into every prompt. Be concise — personality doesn't need a novel.

Memory Security

MEMORY.md is loaded only in main private sessions, never in group chats. This prevents data leakage across shared contexts. Design AGENTS.md group chat rules accordingly.