Workspace & soul documents
The seven files that define a Teammate's identity and behavior, managed vs. custom, overlays, and the read-only runtime mount.
What workspace files are
A Teammate's workspace — its soul documents, in OpenClaw terms — is the set of plain-text files that define who it is and how it behaves: its personality, its identity, its safety rules, its context on the person it's helping. You edit these in the workspace editor; nothing takes effect until you deploy (see Deploys & pending changes).
The seven files
| File | Purpose |
|---|---|
SOUL.md |
Personality, behavior rules, and vibe — who the Teammate is |
IDENTITY.md |
Name, role, and communication style per audience |
AGENTS.md |
Safety rules, delegation rules, and self-modification workflow |
BOOTSTRAP.md |
The first-run bootstrap ritual — a template-level concern, not something a from-scratch Teammate needs by default |
TOOLS.md |
Directory permissions and the Teammate's specific tools and integrations (skills define how tools work generally; this file covers your specifics) |
USER.md |
Context about the human the Teammate is helping, built up over time |
HEARTBEAT.md |
Periodic tasks the Teammate should check on — leave it empty to skip periodic checks entirely |
A Teammate created from scratch (Custom) starts with all of these except BOOTSTRAP.md, which stays specific to catalog templates — you can still add your own BOOTSTRAP.md later if you want one, but it isn't seeded automatically.
Managed vs. custom
A Teammate created from a catalog template is managed: its workspace files are the template's files, and they update automatically whenever we update the template. The moment you edit one of those files directly, the Teammate converts to custom — the files become yours, permanently, and template auto-updates stop.
Warning: Converting to custom is irreversible. Once a Teammate's workspace is customized, there's no way back to receiving managed template updates for it — the only way to get a managed, auto-updating Teammate again is to create a new one from a template. Changing which template a Teammate uses is only possible while it's still managed.
Overlay files
On a managed Teammate, you can add extra files beyond the seven above — for example, an OVERRIDES.md with team-specific notes. Two restrictions apply: an overlay can't reuse one of the seven workspace filenames (that would shadow the template file rather than add to it), and it can't be named SKILL.md.
SKILL.md is reserved
SKILL.md is never a valid workspace-root file, on any Teammate, managed or custom. It belongs to the Skills tab — see Skills — and a stray one at the workspace root won't be picked up by anything.
Size limit
Each workspace file is capped at 200 KB.
Trust architecture: mounted read-only
Workspace files are mounted read-only at runtime. A Teammate can't rewrite its own instructions on the fly, no matter what it's asked to do — every change to its workspace goes through the same pending-change, review-and-approve path you use for everything else, whether you make the edit yourself or a Teammate proposes one for you to approve. This is a structural choice, not a behavioral one: it holds even if a Teammate is convinced (via prompt injection or otherwise) to try to modify itself. See Core concepts for how this fits the platform's broader security posture.
API and MCP
Reading, writing, and deleting workspace files, converting to custom, and changing template all have full dashboard/API/MCP parity. See API & MCP for the resource map.