Agent Workspace

Understand OpenClaw workspace files, agent directories, context injection, backup boundaries, and how workspace guidance differs from memory.

OpenClaw agents run with a workspace: a directory of human-readable files that shape the agent's context and behavior. The workspace is the default working directory for an agent, not a hard security boundary.

Workspace vs Agent Directory

OpenClaw separates two important paths:

• Workspace: prompt and project context, usually ~/.openclaw/workspace
• Agent directory: agent-scoped state such as auth profiles, model registry, and sessions under ~/.openclaw/agents/<agentId>/

In multi-agent setups, each agent should get its own workspace and agent directory. Never reuse one agentDir across unrelated agents, because that can collide auth, model, and session state.

If OPENCLAW_PROFILE is set to a non-default profile, the default workspace becomes ~/.openclaw/workspace-<profile>. You can also override it with agents.defaults.workspace.

Standard Workspace Files

AGENTS.md

Operating instructions, priorities, workflow preferences, and guidance for how the agent should use memory. It is loaded every session, so keep it direct and stable.

# Operating Instructions

## Communication

- Reply in the user's language
- Keep chat-platform replies concise
- Ask before taking destructive or expensive actions

## Workflows

- Confirm timezone before scheduling
- Summarize long tool output before replying

SOUL.md

Personality, tone, and boundaries. This is where you put the assistant's default voice and behavioral limits. It is also loaded every session.

# Persona

Professional, calm, and efficient.

# Boundaries

- Never forward private messages without explicit approval
- Never make purchases or financial transactions autonomously
- Escalate uncertainty instead of pretending

USER.md and IDENTITY.md

USER.md captures user profile information such as timezone and preferences. IDENTITY.md describes the agent's name, vibe, and presentation details. Keep sensitive secrets out of both.

TOOLS.md

Tool usage notes. This file does not grant tools. It tells the agent how you prefer existing tools to be used.

# Tool Notes

- Prefer read-only inspection before edits
- Use the browser only when web_fetch is insufficient
- Ask before deleting files or sending external messages

HEARTBEAT.md and BOOT.md

HEARTBEAT.md is an optional tiny checklist for heartbeat runs. BOOT.md is an optional startup checklist that can run on Gateway restart when internal hooks are enabled.

BOOTSTRAP.md

First-run onboarding questions and setup ritual. It is created for brand-new workspaces only, and can be deleted after the ritual is complete.

MEMORY.md

Curated long-term memory: durable facts, preferences, decisions, and short summaries. Keep detailed logs out of this file; put them in daily memory notes.

memory/YYYY-MM-DD.md

Daily memory notes. Today and yesterday are loaded automatically, and the memory/ tree is indexed for memory tools such as memory_search and memory_get.

DREAMS.md

Optional human-readable memory consolidation review output. Dreaming can write review summaries here, while long-term promotion writes to MEMORY.md.

skills/ and canvas/

skills/ contains workspace-specific skills with high precedence. canvas/ is optional Canvas UI content.

Workspace Is Not Memory

Workspace files are explicit context. Some memory files live in the workspace too:

• MEMORY.md is curated long-term memory
• memory/YYYY-MM-DD.md is daily working memory
• QMD or the built-in backend indexes memory for recall
• active memory can inject relevant recall into an interactive session
• memory wiki can compile curated knowledge beside the main memory layer

Use workspace files for stable instructions. Use memory systems for learned facts, recall, and cross-session continuity.

File Behavior

• Blank files are skipped.
• Large files may be trimmed before injection. The disk file remains intact.
• Missing files can appear as missing-file markers.
• Relative paths resolve from the workspace, but absolute paths can still reach the host unless sandboxing blocks them.
• With sandboxing enabled and restricted workspace access, file tools may operate inside a sandbox workspace under ~/.openclaw/sandboxes instead of the host workspace.

Not in the Workspace

Keep these out of workspace backups and prompt context:

• ~/.openclaw/openclaw.json
• auth profiles and provider credentials
• session JSONL files under ~/.openclaw/agents/<agentId>/sessions/
• managed skills under ~/.openclaw/skills/
• browser profiles, channel state, and credential stores

Backup Strategy

Back up both workspace and agent state:

openclaw backup create --verify
openclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz

Also version-control the human-authored workspace files, especially AGENTS.md, SOUL.md, USER.md, TOOLS.md, MEMORY.md, daily memory notes, and custom skills. Do not commit API keys, browser profiles, channel state, raw chats, sensitive attachments, or private transcripts.

Best Practices

1. Keep AGENTS.md short enough to remain useful in every prompt.
2. Put durable voice and boundaries in SOUL.md.
3. Put operational preferences in TOOLS.md, not tool documentation.
4. Keep MEMORY.md curated; put verbose session detail in memory/YYYY-MM-DD.md.
5. Use one workspace per agent persona.
6. Treat workspace access as context engineering, not tenant isolation.