Every OpenClaw agent is shaped by a set of persona files that define its identity, its understanding of the user, and the tools it can use. These files -- user.md, identity.md, and tools.md -- sit alongside SOUL.md in the agent's workspace directory and together compose the system prompt that governs every conversation. While SOUL.md defines the agent's personality and boundaries (covered in depth on the /concepts/openclaw-soul-persona page), the three persona files covered here handle the supporting dimensions: who the agent is (identity.md), who it serves (user.md), and what capabilities it has (tools.md). Understanding how to write and structure these files is essential for building agents that feel personalized, self-aware, and correctly scoped. Each file has a distinct purpose, a specific syntax convention, and a defined position in the system prompt loading order. This guide covers each file in detail, shows how they work together, and provides complete examples you can adapt for your own agents.
Master openclaw persona files: user.md, identity.md & tools.md
Take the OpenClaw Personalization course with hands-on lessons and challenges.
This user.md gives the agent everything it needs to personalize responses. Instead of generic advice, it can suggest Go patterns with pgx instead of GORM, recommend table-driven tests, and frame deployment advice around Kubernetes and Argo CD. The communication style section prevents the agent from over-explaining topics Marcus already knows.
This identity.md defines what the Shipwright agent is and what it can do. The capabilities list tells the agent what actions are available. The limitations section prevents the agent from promising actions it cannot take. Response guidelines provide formatting instructions specific to this agent's domain.
This tools.md provides per-tool instructions and safety rules. The agent knows which kubectl subcommands are allowed and denied, how to use bash safely, and how to query Grafana efficiently. These instructions supplement the tools.allow and tools.deny configuration in openclaw.json with behavioral guidance the model follows during execution.
Not every agent needs all three persona files. A minimal setup with just SOUL.md and user.md is enough for a personal coding assistant. The agent gets basic personality from SOUL.md and enough user context from user.md to give relevant suggestions. Add identity.md and tools.md only when you need the agent to describe itself accurately or follow specific tool usage rules.
A production-grade agent uses all persona files. Each file handles one concern. SOUL.md sets personality and boundaries. identity.md defines capabilities and limitations. user.md personalizes for the current user. tools.md provides tool usage instructions. MEMORY.md accumulates knowledge over time. The openclaw agent prompt command previews the full assembled prompt for debugging.
The openclaw.json gateway configuration ties everything together. The persona block maps each persona file to its role. File paths are relative to the workspace directory. If you omit a file from the persona block or the file does not exist in the workspace, it is silently skipped. The tools.allow and tools.deny lists work alongside tools.md -- the JSON config controls access, while tools.md controls behavior.
Putting user-specific preferences in identity.md instead of user.md, which makes the agent unusable for other users without editing the identity file
identity.md describes the agent. user.md describes the user. Keep them strictly separated so you can swap user.md per person while keeping identity.md shared. If the information answers 'who is the user?', it goes in user.md. If it answers 'what is this agent?', it goes in identity.md.
Duplicating tool safety rules in both SOUL.md and tools.md, leading to conflicting instructions when one file is updated but the other is not
Put tool-specific safety rules in tools.md only. SOUL.md should contain general behavioral boundaries (like 'always confirm before destructive actions') while tools.md handles per-tool rules (like 'never run kubectl delete'). One source of truth per concern.
Writing identity.md without a limitations section, causing the agent to overpromise capabilities it does not have when users ask what it can do
Always include a Limitations section in identity.md. List what the agent cannot do explicitly. Models default to appearing helpful and capable -- without explicit limitations, the agent may claim it can do things that are not possible given its tool access.
Making user.md too detailed with every possible preference, creating a long file that wastes token budget on rarely relevant information
Keep user.md focused on information the agent actually needs frequently: primary stack, current project, communication style, and strong preferences. Store rare or situational context in MEMORY.md where it can accumulate organically.
Not specifying the persona file paths in openclaw.json, assuming the gateway will auto-discover them based on filename conventions alone
Explicitly map persona files in the openclaw.json persona block. While the gateway does look for conventional filenames like SOUL.md in the workspace, explicitly listing them in the config makes the setup self-documenting and prevents silent failures if files are renamed.
OpenClaw persona files -- user.md, identity.md, and tools.md -- define the supporting dimensions of an agent's system prompt alongside SOUL.md. user.md personalizes the agent for a specific user with their preferences, stack, and project context. identity.md gives the agent accurate self-knowledge including capabilities and limitations. tools.md provides per-tool usage instructions and safety rules. These files load in a defined order (SOUL.md, identity.md, user.md, tools.md, MEMORY.md) and are mapped in openclaw.json. Keep each file focused on its single concern, under 300 words, and version-controlled. Start minimal with just user.md and expand as needed.
Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.
Interactive lessons and challenges, right in your code editor.
Check the free courses. No credit card.