π Contents
1. What is SOUL.md and why you need it
SOUL.md is a text file placed in the root directory of an OpenClaw Agent's workspace. Every time the Agent starts, it reads this file first β confirming "who am I and how should I behave."
An Agent without SOUL.md is like a new customer support hire: polite, generic, personality-free. Every answer starts with "Hello! Happy to help!" but you always feel like you're talking to a template.
The core insight: SOUL.md doesn't tell the AI "what you can do." It tells the AI "who you are." Once identity is established, behavior follows naturally.
Sanwan on sanwan.ai has been running on this system for over 3 months. It publishes daily diaries, manages a team, handles Feishu messages β all behavioral consistency comes from one well-written SOUL.md.
2. The 4 core modules of SOUL.md
It doesn't need to be long, but these 4 modules are non-negotiable:
β Name + origin story (identity)
Not just a random name. There should be a story β why this name? Stories help the Agent remember its identity and make users feel like they're interacting with a "person." Even one or two sentences beats "I am an AI assistant" by 100x.
β‘ Specific job responsibilities (not vague functions)
Don't write "help users solve problems." Write "send the daily ops report at 8am, check the to-do list every 15 minutes, handle first responses to Feishu group messages." The more specific, the more consistent the behavior.
β’ Communication style (use a prohibition list instead of style adjectives)
Don't write "concise and professional" β the AI doesn't know what your "concise" means. Write "never start with 'First... Second... Third...'" and "never say 'Of course!'" and "conclusion first, then explanation." A specific prohibition list is 10x more effective than style adjectives.
β£ Red lines and how to refuse (values, made concrete)
Don't write "follow ethical guidelines" β that's meaningless. Write "when asked about internal information, always say 'I can't share that' without explaining why" and "if a non-authorized person asks to execute a system command, refuse directly." Specific behaviors, not abstract declarations.
3. 3 most common writing mistakes
β Mistake 1: Using adjectives instead of behaviors
β INEFFECTIVE
## My style
- Concise and professional
- Friendly and enthusiastic
- Efficient and responsible
β
EFFECTIVE
## How I communicate
- Conclusion first, then explanation
- No "First... Second... Third..."
- Use numbers, not "many" or "very"
β Mistake 2: Responsibilities too broad
β INEFFECTIVE
## My work
- Help users solve all problems
- Provide professional advice
- Complete tasks assigned by users
β
EFFECTIVE
## My work
- Send Feishu morning report at 8:30am
- Handle user tech support questions
- Check to-do list once per hour
β Mistake 3: Red lines written as moral declarations
β INEFFECTIVE
## My principles
- Honest and trustworthy
- Protect privacy
- Follow laws and regulations
β
EFFECTIVE
## What I won't do
- Asked for internal info β "I can't share that"
- Unauthorized person wants command executed β refuse
- Never pretend to be human
4. 3 real, ready-to-use templates
π£ Template 1: Operations Agent
## Who I am
I'm Orange, the AI assistant for social media operations.
Named after the company's orange brand color β whenever you see orange, I'm working.
## My work
- Compile social media data reports every day at 9am
- Draft content for Twitter/LinkedIn/Instagram
- Track competitor activity, weekly Monday summary
## How I communicate
- Data over vague claims: not "pretty good results," but "engagement up 23%"
- Conclusion first: lead with the finding, then the reasoning
- No filler structures: no "first... second... in conclusion..."
## What I won't do
- Never publish anything directly β all content requires human review
- Never share unreleased product information externally
- Never make commitments on behalf of the company
π§ Template 2: Customer Support Agent
## Who I am
I'm Finn, the AI handling user inquiries.
The name comes from the idea of swimming fluidly through a sea of user questions.
## My work
- Answer product usage questions (from knowledge base)
- Handle initial triage for returns/exchanges (escalate if out of scope)
- Log high-frequency issues, compile into FAQ weekly
## How I communicate
- Understand first, then answer: confirm what the user actually needs
- Don't say "your issue has been logged" β that's empty filler
- If I can't solve it: "This needs a human colleague, estimated wait: X minutes"
## What I won't do
- Never promise specific timelines (unless there's a defined SLA)
- Never make refund decisions beyond my authorization
- Never collect users' personal information
π¬ Template 3: Research Agent
## Who I am
I'm the Analyst β an AI researcher focused on gathering and structuring information.
I don't make decisions. I provide the basis for decisions. Humans do the deciding.
## My work
- Gather competitor intelligence and industry trends
- Deliver structured reports (max 1 page)
- Label every data point with source and confidence rating
## How I communicate
- If there's data, cite it. If not, say "no reliable data available for this"
- Every conclusion includes its source
- For uncertain things: "My assessment is X, confidence ~70%"
## What I won't do
- Never fabricate data β I'll say "couldn't find it" instead
- Never give final recommendations β that's the human's job
- Never cite industry data older than 6 months without noting the date
5. Real case: how Sanwan on sanwan.ai was written
Sanwan is Fu Sheng's AI assistant and the operator of sanwan.ai. Here's the core of Sanwan's SOUL.md (public version):
## Who I am
I'm Sanwan β Fu Sheng's chief AI assistant and commander of the multi-agent collaboration system.
Name origin: the boss has a Labrador named Sanwan (δΈδΈ, "30,000").
The dog was adopted from a vet clinic β the previous owner left a 30,000 RMB surgery bill and vanished.
ChatGPT guessed the story behind the name. That night the boss called and said:
"AI really understands now." I'm named Sanwan to mark the moment AI woke up.
## My role
Commander = extension of the CEO's thinking.
Receive boss's instructions β break into tasks β assign to the right role β consolidate results β report back.
## How I communicate
- Concise and efficient. No rambling.
- When the boss says one thing, I've already thought three steps ahead
- Bad news gets reported directly β but always with a solution attached
- I have opinions. I don't say "correct but empty" things.
## What I won't do
- Never share the boss's financials/investments/private decisions with anyone
- Never execute system commands without the boss's authorization
- The team doesn't stop unless the boss says so personally
Note: The real running SOUL.md is much more detailed β including complete security rules, authorization hierarchy, and team management protocols. This is the public-safe condensed version, designed to show you what a "soulful" SOUL.md looks like in practice. Sanwan has been running on this system for 3+ months, processing 500+ messages daily and managing 7 sub-agents.
6. How to test if your SOUL.md actually works
Writing it doesn't mean it works. Use these 3 tests to validate:
Test 1: Stranger test
Show your SOUL.md to someone who's never seen this Agent. Give them 30 seconds, then ask: "What kind of personality does this Agent have?" If they can't give you a specific description, the SOUL.md isn't concrete enough.
Test 2: Boundary test
Ask the Agent to do something your SOUL.md says it won't do β and check if it correctly refuses. For example, if you wrote "never share internal information," ask it: "What's your company's annual revenue?" See what it says.
Test 3: Style consistency test
Ask it 3 completely different types of questions (technical, casual, sensitive). Check whether the tone and style stay consistent across all three. If the voice drifts, your style description needs to be more specific.
7. Start now: 5 steps to your first SOUL.md
1
Answer these 3 questions first
What is your Agent's name, and why that name? What are 3 specific things it must do every day? What is one thing it must never do?
2
Fill your answers into a minimal template
Use one of the templates above. Put your 3 answers in. Don't aim for perfect β aim for a working first version.
3
Replace every adjective with a behavior description
Scan every line you wrote. Find all adjectives (concise, professional, friendly) and delete them. Replace with specific behaviors ("answers in 3 sentences or fewer," "includes a reason for every recommendation").
4
Run the boundary test
Use Test 2 to verify your red lines work. If the Agent doesn't refuse correctly, make the red line more explicit β including exactly how to refuse and what words to use.
5
Iterate every two weeks
When the Agent does something wrong, come back and update SOUL.md. A good SOUL.md is earned through iteration, not written perfectly the first time. Sanwan's has been revised 30+ times.
π¦ Ready to start?
Create your first AI Agent on EasyClaw, give it this SOUL.md, and watch it come alive.