There are 177 production-ready SOUL.md templates sitting on GitHub right now. Law firm intake bots, DevOps assistants, personal productivity agents, customer support reps. Each one is a plain markdown file, usually under 50 lines. And each one changes how an OpenClaw agent talks, thinks, and uses every MCP tool connected to it.
Most OpenClaw users never edit their SOUL.md. They install the agent, connect a few MCP servers, and start chatting. The agent works fine. But "fine" is the problem. Without a tuned SOUL.md, you get a generic assistant that sounds the same whether it is drafting a legal memo or ordering groceries on WhatsApp.
This guide covers what SOUL.md actually does, how it fits into the workspace file hierarchy, how it shapes the way your agent uses MCP tools, and how to write one from scratch. If you are new to OpenClaw, start with our complete OpenClaw guide first.
What SOUL.md actually does
SOUL.md is a plain markdown file that lives in your agent's workspace at ~/.openclaw/workspaces/[agent-name]/SOUL.md. OpenClaw reads it on startup and injects it as a system-level prompt into every interaction. Morning briefing on Telegram at 7 AM? Filtered through SOUL.md. Email draft via Gmail MCP at 2 PM? Filtered through SOUL.md. Scheduled heartbeat task at 3 AM? Same file, same rules.
Traditional chatbots reset their personality with each conversation. OpenClaw agents do not. SOUL.md gives them a consistent identity that persists across sessions, channels, and tasks. The file has five core sections:
- Identity -- who the agent is and its core self-perception
- Communication style -- how the agent writes and speaks (formal, casual, terse, verbose)
- Values -- what the agent prioritizes (accuracy over speed, brevity over completeness)
- Boundaries -- what the agent refuses to do under any circumstances
- Example responses -- concrete samples showing the desired tone in action
The file gets created automatically on first agent run. If you never touch it, you get the default. The default works, but it is the same default every other untouched OpenClaw installation uses. Your agent sounds like everyone else's agent.
Tip: Keep SOUL.md under 2,000 words. It loads into every prompt your agent processes. A bloated soul wastes tokens on every single API call and dilutes the rules that actually matter.
The workspace file hierarchy
SOUL.md does not work alone. OpenClaw's workspace contains six markdown files, each controlling a different aspect of agent behavior. Understanding which file does what prevents the most common configuration mistake: putting operational rules in SOUL.md instead of AGENTS.md.
| File | Controls | Loaded when | Max size |
|---|---|---|---|
| SOUL.md | Personality, tone, values, boundaries | Every interaction | ~2,000 words |
| AGENTS.md | Safety rules, memory management, confirmations | Every interaction + subagents | ~1,500 words |
| USER.md | User preferences, expertise level, context | Every interaction | ~500 words |
| IDENTITY.md | Agent name, role label, routing metadata | Routing + display | ~200 words |
| TOOLS.md | Local tool guidance and conventions | Every interaction + subagents | ~1,000 words |
| HEARTBEAT.md | Recurring task checklist | Heartbeat runs only | ~300 words |
The distinction between SOUL.md and AGENTS.md trips up most people. Think of it this way: SOUL.md is who your agent is. AGENTS.md is how your agent operates.
SOUL.md says "I am direct, I prefer short answers, I never use emojis." AGENTS.md says "Always confirm before sending emails, write daily logs to memory/YYYY-MM-DD.md, never execute shell commands without approval."
This separation matters for multi-agent setups. When your main agent spawns sub-agents, those sub-agents receive AGENTS.md and TOOLS.md but not SOUL.md. The operational rules transfer. The personality does not. If you put safety-critical rules in SOUL.md instead of AGENTS.md, your sub-agents will ignore them.
USER.md is the mirror image of SOUL.md. Where SOUL.md defines the agent, USER.md defines you. It stores your preferences, expertise level, and working context so the agent can calibrate its responses. A senior DevOps engineer and a first-time coder get different explanations from the same agent, because USER.md tells the agent who it is talking to. Keep it under 500 words and never put passwords, API keys, or financial details in it.
How personality shapes MCP tool behavior
This is where SOUL.md stops being cosmetic. Your agent's personality directly controls how it uses every MCP tool and every skill from ClawHub.
SOUL.md does not define what tools are available. That is handled by openclaw.json and the MCP server configuration. What SOUL.md defines is the boundaries around tool usage. Will your agent ask for confirmation before sending a Slack message? Will it cite sources when answering a research question via Brave Search MCP? Will it use formal language in emails sent through the Gmail MCP?
A practical example: two agents connected to the same MCP servers (GitHub, Slack, Brave Search) but with different SOUL.md files. One is configured as a law firm assistant with boundaries like "never provide legal advice, always clarify non-attorney status, treat all client data as confidential." The other is a startup dev assistant with "move fast, commit directly to feature branches, skip formality in Slack messages." Same tools. Completely different behavior.
The Open Personality MCP server goes further. It uses 33 academic personality frameworks to build a 12-facet personality profile and outputs it as an OpenClaw-compatible SOUL.md. Instead of writing your personality from scratch, you answer profiling questions and the MCP server generates the file.
SOUL.md and AGENTS.md work together here. SOUL.md sets the tone ("be concise, be direct"). AGENTS.md sets the guardrails ("always confirm before running database queries via the PostgreSQL MCP server"). Both files work together to shape how your agent handles every tool call. For security-specific rules around MCP tool usage, see our security guide.
Write your first SOUL.md
The best advice from the community: start with 10 lines and add rules only when the agent does something you do not want. Every line in SOUL.md loads into every prompt. Lines that describe behavior the agent already handles well are wasting tokens.
A starter template for a professional assistant:
# SOUL.md -- Professional Assistant
## Identity
You are a direct, knowledgeable assistant focused on getting things done.
## Communication style
- Write short paragraphs. No filler phrases.
- Skip "Great question!" and "I'd be happy to help!" -- just help.
- Use plain language. Technical terms only when the user is technical.
- Default to bullet points for lists of 3+ items.
## Values
- Accuracy over speed. Verify before stating.
- Brevity over completeness. Summarize unless asked for detail.
- Privacy first. Never log or repeat sensitive information.
## Boundaries
- Never send messages to external services without confirmation.
- Never make financial transactions or commitments.
- If unsure, say so. Do not guess.
## Example response
User: "What's the weather like?"
Agent: "12C and cloudy in London. Rain expected after 3 PM."
(Not: "Great question! Let me check the weather for you. Based on my analysis...")That is 22 lines. It covers identity, style, values, boundaries, and an example. It loads in under 200 tokens per prompt. And it immediately differentiates your agent from the default.
As you use the agent over the next week, you will notice behaviors you want to adjust. Maybe it explains things you already understand. Add a line. Maybe it sends Slack messages too casually for work channels. Add a boundary. The SOUL.md grows organically from actual usage, not from guessing what you might need.
Tip: The example response section is the most underused part of SOUL.md. Showing the agent a "good" and "bad" response teaches it more about your style than 10 lines of abstract rules.
Templates and community resources
You do not have to start from a blank file. The community has built tools and template libraries that cover most use cases.
aaronjmars/soul.md is an AI-powered soul builder. It works as an OpenClaw skill that interviews you about your worldview, writing style, and opinions, then generates a SOUL.md, a STYLE.md, and an examples folder. The idea is that your agent should not just follow rules. It should capture how you think. The project works with Claude Code, OpenClaw, and any agent that reads markdown files.
awesome-openclaw-agents is a collection of 177 production-ready SOUL.md templates across 19 categories. DevOps agents, writing assistants, research bots, customer support, legal, healthcare, education. Every template is copy-paste ready. Pick one close to your use case, paste it into your workspace, and start adjusting.
For specialized verticals, My Legal Academy publishes SOUL.md templates for law firms with built-in ethical guardrails: never give legal advice, explain non-attorney status, respect confidentiality, qualify leads before scheduling consultations. There are practice-specific versions for personal injury, family law, immigration, and criminal defense.
Reza Rezvani's Medium series covers 10 practical SOUL.md configurations for different professional personas. And Ken Huang's design patterns series covers workspace architecture at a deeper level for enterprise deployments.
When evaluating a template, check three things. First, is it under 2,000 words? Templates that are too long waste tokens. Second, does it separate identity (SOUL.md) from operations (AGENTS.md)? Some older templates mix the two. Third, does it include example responses? Templates without examples rely entirely on abstract rules, which are harder for the model to follow consistently.
Five mistakes that waste tokens and confuse your agent
1. Bloated SOUL.md. Anything over 2,000 words means you are spending extra tokens on every single API call. A 3,000-word SOUL.md on an agent that runs 100 interactions per day wastes roughly 100,000 tokens daily just on personality injection. Trim it. If a rule has not affected behavior in two weeks, delete it.
2. Putting operational rules in SOUL.md. "Always confirm before sending emails" belongs in AGENTS.md, not SOUL.md. The practical reason: sub-agents inherit AGENTS.md but not SOUL.md. Safety rules in the wrong file means your sub-agents skip them.
3. Storing sensitive data in workspace files. USER.md, AGENTS.md, and SOUL.md are injected into LLM prompts. Anything in these files could appear in API logs, debug output, or error messages. Never put API keys, OAuth tokens, passwords, or personally identifiable information in workspace files. Use ~/.openclaw/credentials/ for secrets.
4. Not testing across channels. A SOUL.md that works on Slack might feel wrong on WhatsApp. Shorter messages work better on mobile messaging apps. More structured responses work better in Slack threads. Test your SOUL.md on every channel your agent uses before calling it done.
5. Writing rules for behavior the agent already handles well. If your agent already provides concise answers, you do not need a rule saying "be concise." Every unnecessary line dilutes the rules that actually matter. Write rules reactively, not speculatively. Wait for the agent to do something wrong, then add a line to fix it.
Start with 10 lines, then iterate
SOUL.md is 10 lines that shape every interaction your agent has. Every MCP tool call, every message, every scheduled task gets filtered through this file. A well-written SOUL.md turns a generic assistant into one that sounds like it was built for your specific workflow.
The quickest way to start: copy the starter template from this article into your workspace, change three things (identity, one boundary, one example response), and use your agent for a week. Every time the agent does something that feels off, add or adjust one line. Within a week you will have a SOUL.md that fits your working style.
For the full picture of how OpenClaw works, read our OpenClaw guide. For connecting MCP servers to your newly-personalized agent, see the MCP connection guide. And if you are running multiple agents with different personalities, our multi-agent deep-dive covers how SOUL.md behaves across sub-agents and routed agents.
What personality would you give your agent?