Principle:Openclaw Openclaw Persona Customization

Persona Customization

Persona Customization is the principle of loading workspace-specific markdown files that define an agent's personality, capabilities, and instructions. Each agent's workspace contains a set of bootstrap files (SOUL.md, AGENTS.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, and optionally MEMORY.md) that are read at session startup to shape the agent's behavior.

Motivation

In a multi-agent gateway, each agent serves a distinct purpose. A work agent might be formal and task-oriented, while a personal agent might be casual and conversational. A family bot might have restricted capabilities with specific mention patterns, while a deep-work agent might have extended thinking and full tool access.

Rather than encoding these differences in configuration flags, OpenClaw uses workspace markdown files as the primary mechanism for persona customization. This approach is:

• Human-readable: Operators can edit markdown files directly.
• Version-controlled: Workspace files live in a git-initialized directory.
• Composable: Each file handles one aspect of the persona.
• Portable: A workspace can be copied or shared between machines.

Bootstrap File Catalog

File	Purpose
AGENTS.md	Core agent behavior instructions. Defines what the agent does, how it responds, and its operational boundaries. Also loaded for sub-agent sessions.
SOUL.md	Personality and tone definition. Shapes the "voice" of the agent -- formal vs casual, verbose vs terse, emotional tone.
TOOLS.md	Tool usage guidelines. Describes how and when the agent should use available tools. Also loaded for sub-agent sessions.
IDENTITY.md	Name and emoji identity. Parsed to extract a display name and optional emoji for the agent's identity across channels.
USER.md	User context and preferences. Contains information about the user(s) the agent serves, enabling personalized responses.
HEARTBEAT.md	Heartbeat/scheduled task instructions. Defines what the agent should do during periodic heartbeat events.
BOOTSTRAP.md	Initial bootstrap instructions. Only created for brand-new workspaces; contains first-run setup guidance.
MEMORY.md / memory.md	Optional persistent memory notes. When present, loaded to give the agent long-term context. Both filename variants are checked (case-sensitive), with deduplication if they resolve to the same file.

Loading Behavior

Bootstrap files are loaded from the resolved workspace directory for a given agentId:

1. The workspace directory is resolved using the agent's configured workspace path, or a default based on the agentId.
2. Each known filename is checked in the resolved directory.
3. Files that exist are read and their content is included in the result.
4. Files that do not exist are reported as missing: true but do not cause errors.
5. Memory files (MEMORY.md / memory.md) are resolved with deduplication via fs.realpath to avoid loading the same file twice if both names point to the same inode.

Sub-Agent Filtering

When bootstrap files are loaded for a sub-agent session (detected via the session key format), only a subset of files is included:

• AGENTS.md -- Core behavior is always needed.
• TOOLS.md -- Tool guidance is always needed.

Other files (SOUL.md, USER.md, IDENTITY.md, etc.) are filtered out for sub-agent sessions to keep the context focused and avoid personality bleed between parent and child agents.

Workspace Resolution

The workspace directory for an agent is resolved through a priority chain:

1. Explicit configuration: agents.list[].workspace in the config file.
2. Default agent fallback: agents.defaults.workspace for the default agent.
3. Convention-based: ~/.openclaw/workspace-<agentId> for non-default agents.
4. Global default: ~/.openclaw/workspace for the default agent when no override exists.

The OPENCLAW_PROFILE environment variable can further influence the default workspace path, appending -<profile> to the workspace directory name.

Template Seeding

When a new workspace is created (via agents add or initial setup), template files from docs/reference/templates are written to the workspace using "write-if-missing" semantics -- existing files are never overwritten. This allows operators to customize templates before creating additional agents, or to modify files after creation without fear of losing changes.

Implementation

Implementation:Openclaw_Openclaw_LoadWorkspaceBootstrapFiles