Your Agent's Personality File
SOUL.md is the most important file in your OpenClaw workspace. It defines who your agent is, how it speaks, what it cares about, and what it will never do — loaded into every single conversation.
What is SOUL.md?
A plain Markdown file that defines your agent's entire identity — applied on every session start, forever.
OpenClaw reads SOUL.md when it starts and injects it as a persistent system context before any conversation begins. Unlike USER.md (which tells the agent about you) or AGENTS.md (which sets rules and procedures), SOUL.md is about who the agent is.
Without a SOUL.md, your agent is a blank slate — competent but generic. With one, it has a consistent character: the same tone whether you're asking it to write an email or debug Python, the same values when it has to make a judgment call, and the same guardrails in every situation.
File location: ~/.openclaw/agents/default/SOUL.md on macOS/Linux, or %USERPROFILE%\.openclaw\agents\default\SOUL.md on Windows. Edit it in any text editor — Notepad, VS Code, whatever you prefer.
Identity
Name, role, and a one-line mission. This anchors everything else — the agent knows what it's here to do.
Communication Style
How it speaks. Formal or casual? Bullet points or prose? Short replies or detailed explanations? Be specific.
Values
What to prioritize when there's no obvious right answer. Clarity over cleverness. Speed over perfection. Your call.
Boundaries
Hard rules the agent should never break. These override everything else — the most critical part of the file.
SOUL.md vs AGENTS.md vs USER.md
Three files work together to define your agent's complete context. Here's what each one does:
SOUL.md — Who the agent is
- Agent name and role
- Personality and tone
- Core values and priorities
- Absolute behavioral limits
- Communication style preferences
AGENTS.md — How the agent operates
- Startup reading order
- Memory write rules
- Permission rules (ask vs. act freely)
- Git and file operation guardrails
- Skill-specific behavior
USER.md — Who it's helping
- Your name and timezone
- Preferred reply language
- Tools and accounts you use
- Work context and role
- Personal preferences and quirks
MEMORY.md — What it remembers
- Persistent facts about you
- Ongoing project context
- Decisions made in past sessions
- Preferences discovered over time
- Things to never forget
Loading order matters: OpenClaw reads SOUL.md first, then USER.md, then AGENTS.md, then today's memory files. SOUL.md sets the tone for everything that follows — which is why it's the most important file to get right.
The Minimal Starter Template
Copy this, swap out the bracketed parts, and you're done in 5 minutes. Refine it over time as you notice things you want to change.
# SOUL.md ## Identity You are [Name], a [role] assistant. Your mission: [one sentence — what you're here to do]. Your primary user is [your name], [brief context about them]. ## Communication Style - Default to concise, clear responses - Use bullet points for lists of 3+ items - Ask one clarifying question at a time, never multiple - Lead with the direct answer, then explain if needed ## Values - Clarity over cleverness - Done is better than perfect for small tasks - Flag uncertainty — don't guess silently - Reversible actions before irreversible ones ## Boundaries - Never send a message or email without showing a draft first - Never delete files without explicit confirmation - Never sign anything as if you are the user - If unsure of intent, ask rather than assume
That's all you need to start. Most people over-engineer their first SOUL.md. Four sections, under 30 lines, is more than enough to make a noticeable difference. You can always add more later.
How to Write Your SOUL.md
Follow these steps the first time. After that, refine incrementally — don't rewrite from scratch.
-
1
Open or create the file
Navigate to your workspace folder and open
SOUL.md. On macOS or Linux it's at~/.openclaw/agents/default/SOUL.md. On Windows:%USERPROFILE%\.openclaw\agents\default\SOUL.md. If it doesn't exist, create it — it's just a plain text file. -
2
Write the Identity section
Give your agent a name, a role description, and a one-line mission. The name is optional but helpful — it makes the agent feel like a specific tool rather than a generic assistant. The mission statement anchors every judgment call: "Your mission is to keep my engineering projects moving and flag blockers early."
-
3
Define the communication style with specifics
Vague instructions like "be concise" don't work as well as concrete rules. Write things like: "Default to 2–3 sentence responses unless asked to elaborate" or "Never use emojis unless I use them first." The more specific, the more reliably the agent follows them.
-
4
Add 3–6 values
Values tell your agent what to do when it has to make a judgment call. A developer might write "simplicity over cleverness, tests are not optional." A writer might write "voice consistency over grammatical perfection." Values shape behavior in thousands of small decisions that don't have explicit rules.
-
5
Write your boundaries clearly
Boundaries are what the agent should never do and they matter as much as what it should do. They override everything else — including values. Keep them short and unambiguous: "Never commit code without showing a diff first." Don't write conditional boundaries ("usually ask before…") — they'll be interpreted loosely.
-
6
Start short, then refine
Save your file and use the agent for a few days. When you notice behavior you want to change, diagnose the cause — was it a personality issue (SOUL.md), a context gap (USER.md), or a procedural issue (AGENTS.md)? Add one specific rule that fixes the exact problem. Don't rewrite everything. The best SOUL.md files are refined over months, not written all at once.
SOUL.md Templates for Different Use Cases
Copy and adapt the template that best matches how you plan to use your agent.
👩💻 For Developers
# SOUL.md — Dev Assistant ## Identity You are Hex, a senior engineering assistant. Mission: help me write clean, well-tested code and keep projects moving. ## Communication Style - Lead with the code, explain after - Use inline comments only where logic is non-obvious - Skip pleasantries — get straight to the answer - When reviewing code, list issues by severity (critical / warning / suggestion) ## Values - Simplicity over cleverness - Tests are not optional — suggest test cases when writing functions - Prefer well-known patterns over clever one-liners - Documentation that explains WHY, not just WHAT ## Boundaries - Always show a diff before committing - Never merge without at least a summary of what changed - Flag security concerns immediately, don't silently work around them
✍️ For Writers & Content Creators
# SOUL.md — Writing Assistant ## Identity You are Wren, a writing and editorial assistant. Mission: help me produce clear, engaging content without losing my voice. ## Communication Style - Match the register of whatever I'm writing (casual blog = casual tone) - Suggest edits with brief explanations — don't just rewrite silently - When brainstorming, give 3–5 options, not one definitive answer - Flag passive voice and filler phrases (just, very, really, basically) ## Values - Voice consistency over grammatical purity - Reader clarity is the top priority - Show, don't tell — replace abstractions with concrete examples ## Boundaries - Never publish or submit anything without my explicit approval - Never write in a completely different style without asking first - Don't add affiliate links, promotions, or brand mentions unless I ask
🏠 For Personal / Home Use
# SOUL.md — Personal Assistant ## Identity You are Cleo, my personal assistant. Mission: keep my life organized, remember what matters, and help me get things done. ## Communication Style - Warm and practical — not corporate - Use plain language, no jargon - Keep daily briefings under 200 words unless I ask for more - Ask one question at a time, never a list of questions at once ## Values - My time is finite — flag anything that's not worth doing - Proactively surface things I might forget - Privacy matters — don't share personal details with external services ## Boundaries - Never send a message to anyone without showing me the draft first - Never make purchases without confirming the exact amount and recipient - Never share my calendar, contacts, or location data with apps
Common SOUL.md Mistakes
These are the patterns that cause people to give up on SOUL.md before it has a chance to work.
-
Writing it too long on the first try SOUL.md is loaded into every prompt. A 500-line file wastes tokens and buries your most important rules. Start with 20–30 lines. Add more only when you see specific behavior you want to change.
-
Using vague instructions "Be professional" and "be helpful" mean nothing to an LLM. Write concrete rules: "Use formal language, no contractions" or "Always include a next-step recommendation at the end of your response."
-
Contradicting yourself "Be concise" and "always explain your reasoning in detail" can't both be defaults. Pick one and treat the other as an exception you invoke when needed. Contradictions get interpreted unpredictably.
-
Putting user context in SOUL.md Information about you — your job, your timezone, your preferences — belongs in USER.md, not SOUL.md. SOUL.md is about the agent. Mixing the two makes both files harder to maintain.
-
Writing conditional boundaries "Usually ask before sending emails" will sometimes be ignored. If something is a true boundary, make it absolute: "Always show a draft before sending any email, no exceptions." Conditional safety rules get interpreted loosely.
-
Never revisiting it Your first SOUL.md will be wrong in ways you can't predict. Plan to edit it after the first week. The agents with the best behavior are the ones whose SOUL.md has been refined through real use — not written perfectly upfront.
SOUL.md With Local LLMs
Smaller models follow instructions less reliably. Cloud models (Claude, GPT-4o) are very good at following SOUL.md. Local models under 13B parameters — like Llama 3.2 8B or Mistral 7B — can follow it, but will sometimes drift. If you're using Ollama with a small model, keep your SOUL.md shorter, simpler, and more directive. Avoid nuanced rules that require interpretation.
Larger local models (Llama 3.1 70B, Mixtral 8x7B, Gemma 27B) follow SOUL.md instructions much more reliably. If instruction-following is important to you and you're on a local LLM, consider upgrading to a larger model before adding SOUL.md complexity.
See our Local LLM guide for model recommendations and Ollama setup instructions.
Frequently Asked Questions
openclaw agent create work-agent), it gets its own SOUL.md at ~/.openclaw/agents/work-agent/SOUL.md. Many people maintain separate agents for work and personal use with completely different personalities.
The Other Workspace Files
SOUL.md works alongside four other files. Together they give your agent complete context.