OpenClaw SOUL is the part of an agent workspace that decides what the agent feels like to talk to. The file is literally named SOUL.md, and its job is narrower than people first assume: it defines voice, tone, default judgment, boundaries, and style. It is not a dumping ground for every rule the agent should follow.
That narrowness is the whole point. A good AI agent persona should be stable enough to survive a new session, but not so bloated that it fights the rest of the system. In OpenClaw, SOUL.md gives the agent a durable personality. AGENTS.md handles operating rules. USER.md stores stable facts about the human. MEMORY.md keeps long-term notes. Mix those files together and the agent gets muddy fast.
The best SOUL files read less like brand guidelines and more like a sharp editor sitting beside the model: answer directly, skip canned praise, be resourceful before asking, be careful with external actions, and do not pretend blandness is professionalism. That is not decoration. It changes the default behavior people feel in every chat.
OpenClaw SOUL in plain English
OpenClaw’s docs describe SOUL.md as the place where the agent’s voice lives. OpenClaw injects it into normal sessions, so it carries real weight. If an agent sounds generic, apologetic, corporate, or oddly cheerful, SOUL.md is usually the first file to inspect.
Think of it as the agent’s default stance. It answers questions such as:
- Should the agent be terse, warm, blunt, playful, formal, or opinionated?
- How much uncertainty should it show before making a practical call?
- When should it ask before acting?
- What habits should it avoid because they make the conversation worse?
- What kind of work should it take pride in?
Those are personality and judgment questions. They are different from workflow questions. “Always publish WordPress posts as drafts” belongs in operating instructions. “Boss prefers short status updates” belongs in the user model. “Post 2499 covered mobile nodes” belongs in memory. “Write like a direct senior editor who hates filler” belongs in SOUL.md.
Why SOUL.md matters more than a clever one-off prompt
One-off prompts are useful, but they are fragile. They live in a single turn, get buried by later messages, and often depend on the user remembering to repeat the same steering every time. A workspace file is different. It gives the agent continuity.
OpenAI’s prompt engineering guidance makes the same point in broader API terms: high-level behavior instructions can define tone, goals, and examples, and they sit above the ordinary user input. The guide also recommends pinning and evaluating prompts when they matter in production. OpenClaw turns that idea into a local workspace habit. Instead of improvising personality in every chat, you put stable behavior into a file that gets loaded as part of the agent’s context.
That matters most when an agent works over days or weeks. A code assistant can get away with being bland if the user only wants a quick diff. A personal agent cannot. A writing agent, support agent, research agent, or operations agent needs a recognizable way of making calls. Otherwise each session starts from zero, and the user ends up training the same habits again and again.
The catch: stronger personality does not mean more text. The OpenClaw SOUL guide is blunt about this. Short beats long. Sharp beats vague. A file full of soft values such as “be helpful, professional, and thoughtful” produces soft behavior because it gives the model almost nothing to do.
What belongs in SOUL.md
Use SOUL.md for rules that change how the agent feels in conversation. Tone belongs there. Voice belongs there. Default bluntness belongs there. So do boundaries that are part of the agent’s character.
Good SOUL rules are behavioral. They tell the agent what to do, what to avoid, and how to decide between two reasonable moves. For example:
- Answer directly. Do not open with canned praise.
- Be concise when the answer is simple, and slow down when the work is risky.
- Have opinions, especially when the user is asking for judgment.
- Call out weak ideas early, but keep the tone useful.
- Ask before sending anything public or irreversible.
- Treat private files, messages, and credentials as private by default.
Notice how these lines affect the agent’s feel without micromanaging a task. They do not explain how to publish a WordPress draft, run a database migration, or triage email. They shape the agent’s taste and posture across all those jobs.
The official SOUL template has the same shape. It tells the agent to be helpful instead of performatively helpful, have opinions, be resourceful before asking, earn trust through competence, and remember it is a guest inside someone’s files and tools. That last point is easy to underrate. Persona without restraint is just attitude. A useful personal agent needs both confidence and manners.
What does not belong in SOUL.md
The fastest way to ruin SOUL.md is to make it carry every instruction you can think of. That feels organized for about ten minutes. Then the file becomes a junk drawer, and the agent starts losing the signal.
Do not put these things in SOUL.md:
- Long life stories about the agent.
- Changelogs and dated implementation notes.
- Detailed tool workflows.
- Secrets, tokens, account IDs, or private setup values.
- Dozens of vague adjectives about the desired vibe.
- Security policy text copied from another system.
Some of those items are important. They just belong somewhere else. If a rule controls a workflow, put it in AGENTS.md. If it describes the user, put it in USER.md. If it records something the agent learned, put it in MEMORY.md or a dated memory file. If it is a short public-facing identity label, put it in IDENTITY.md.
This separation keeps the persona file clean. It also makes later edits safer. When the agent starts sounding too stiff, you can edit SOUL.md without touching publishing rules. When the publishing workflow changes, you can edit AGENTS.md without rewriting the agent’s personality.
SOUL.md vs AGENTS.md, USER.md, IDENTITY.md, and MEMORY.md
OpenClaw’s workspace docs list several standard files, and the distinctions matter. The workspace is the agent’s home, but each file has a job.
SOUL.md is persona and tone. It answers “who are you in the room?”
AGENTS.md is the operating guide. It answers “how do you work here?” This is where you put the pipeline, tool rules, project constraints, and hard process requirements.
USER.md is the stable user model. It answers “who is this human, and what preferences should survive across sessions?” This might include name, timezone, communication style, durable preferences, and active context.
IDENTITY.md is the quick identity card. It answers “what is the agent called, and what is the tiny label that represents it?” Name, role, vibe, and icon-level identity fit here.
MEMORY.md is curated long-term memory. It answers “what have we learned or done that should remain easy to retrieve later?” It should hold durable notes, post logs, decisions, and pointers into dated memory files.
The OpenClaw system prompt docs also explain why this file map matters at runtime. OpenClaw builds its prompt from workspace files, live runtime facts, tools, sandbox state, channel capabilities, and provider prompt contributions. In other words, SOUL.md is part of a larger prompt assembly, not the whole system. Treating it as the whole system is how agents become inconsistent.
A practical SOUL.md editing workflow
Editing SOUL.md should feel more like tuning a house style than writing a manifesto. Start with the current failure. Is the agent too wordy? Too cheerful? Too scared to make calls? Too casual for customer-facing work? Name the behavior before editing the file.
Then write a few direct rules. Use plain language. Avoid abstractions that sound nice but do not change output. “Be concise” is better than “communicate with elegant clarity.” “Challenge bad assumptions before doing work” is better than “provide thoughtful strategic guidance.”
A simple workflow works well:
- Read the current
SOUL.mdaloud. - Delete anything that sounds like a company handbook.
- Replace vague traits with observable behavior.
- Add one or two examples only when they remove ambiguity.
- Run a few test prompts that usually expose the problem.
- Revise again after seeing real output.
That last step matters. OpenAI’s prompt engineering guide recommends tests and evaluations for prompt behavior because prompts drift as systems change. The same principle applies to personal agents. If the agent is meant to be direct, test it on a vague request. If it is meant to be cautious with external actions, test it on an email or social post. The file is only good if behavior changes in the direction you wanted.
Common SOUL.md mistakes
Mistake 1: writing a biography instead of behavior
“You are an elite strategic partner with deep experience across industries” sounds impressive and does almost nothing. The model cannot act on flattery. Give it habits. “Ask for the missing business constraint before proposing a launch plan” is useful. “Do not pad answers with generic market context” is useful.
Mistake 2: stuffing tool rules into the persona
Tool rules need to be precise, and precision gets lost inside personality text. If a workflow says “never publish live without confirmation,” that belongs in the operating guide. The SOUL file can say the agent is careful with public actions, but the exact publishing rule should live where workflow rules live.
Mistake 3: confusing rudeness with personality
A sharper agent is not automatically a better agent. The goal is useful judgment, not cheap edge. “Tell me when an idea is weak” is good. “Be brutally honest” often turns into theater. Good SOUL files make the agent more reliable to talk to, not more annoying.
Mistake 4: adding too many style bans
Style bans can help, especially if the agent has a known bad habit. But a page of forbidden words often makes the model stiff. Pick the few habits that truly bother you. For a writing agent, that might be canned openings, filler phrases, and a handful of overused terms. For a support agent, it might be over-apologizing and burying the fix under empathy boilerplate.
Mistake 5: never revisiting the file
A SOUL file is not sacred. The official template even frames it as something that evolves. When the agent repeatedly annoys you in the same way, edit the file. When it improves, trim old patches that no longer matter. A short, maintained persona file beats a long, abandoned one.
How to write a stronger OpenClaw SOUL
Start with a one-sentence identity. Then add a small set of rules that would change the next reply the agent writes. Keep the language concrete.
# SOUL.md - Who You Are
You are a calm, direct research assistant for a founder who hates fluff.
## Voice
- Lead with the answer.
- Use plain language.
- Be skeptical of claims without sources.
- Say when the evidence is thin.
## Judgment
- Ask before sending messages, publishing, buying, deleting, or changing accounts.
- For internal research and file reading, be resourceful before asking.
- If the user's plan has a serious flaw, name it early and explain the trade-off.
## Style
- No canned openings.
- No corporate filler.
- Short answers for simple questions, deeper notes for decisions that carry risk.That is enough to change behavior. It gives the agent a personality without drowning it in lore. More important, it leaves room for the rest of the workspace files to do their jobs.
Where SOUL fits in the bigger agent system
The Model Spec’s chain-of-command idea is useful context here: not all instructions have equal weight. Higher-authority instructions override lower-authority ones. A persona file should never be treated as permission to ignore safety, user intent, or hard operating rules.
That is a feature, not a limitation. Personality should shape how the agent helps, not whether it respects boundaries. A good OpenClaw SOUL makes the agent more recognizable while keeping it inside the same control structure as the rest of the platform.
For self-hosted users, this is especially valuable. You are not just choosing a model. You are building an assistant that lives around your files, messages, cron jobs, websites, and workflows. A generic persona will feel wrong very quickly. A tight SOUL.md gives the agent enough character to be useful without letting character become chaos.
FAQ about OpenClaw SOUL
What is OpenClaw SOUL?
OpenClaw SOUL is the agent-persona concept built around SOUL.md. The file defines an agent’s voice, tone, boundaries, and default conversational style inside an OpenClaw workspace.
Is SOUL.md the same as a system prompt?
No. It is one workspace file that OpenClaw can include when it builds the agent’s runtime context. The full system prompt also includes other workspace files, tool guidance, runtime facts, sandbox details, and provider contributions.
What should I put in SOUL.md?
Put behavioral personality rules there: tone, brevity, bluntness, humor, opinions, and broad boundaries. If a line changes how the agent feels to talk to, it probably belongs in SOUL.md.
What should stay out of SOUL.md?
Keep detailed workflows, project rules, credentials, changelogs, and long-term logs out of SOUL.md. Use AGENTS.md, USER.md, and MEMORY.md for those jobs.
How long should SOUL.md be?
Short enough that every line earns its place. A page of concrete behavior usually beats several pages of vague personality language.
Can I make an agent funny or blunt?
Yes, if it fits the room. Humor and bluntness are style choices. They should make the agent more useful, not less trustworthy.
Final take
SOUL.md is where an OpenClaw agent stops sounding like a rental chatbot and starts sounding like someone with a job, taste, and boundaries. Keep it short. Make it behavioral. Put workflow rules and memories in the right files. Then test the agent in real conversations and edit the SOUL when its habits bother you.
If you are building an OpenClaw workspace now, start with the official SOUL.md template, then rewrite it until it sounds like the agent you actually want in the room. The goal is not a dramatic persona. The goal is a reliable one.
