Give your agent a personality with SOUL.md
Write the file that shapes how your agent talks and works, and make changes actually stick.
In this tutorial
SOUL.md is a plain text file that tells your agent who it is: its name, its tone, what it helps you with and the rules it follows. Without one, your agent sounds generic. With a good one, it sounds like your assistant. It's the single most useful five minutes you can spend on your agent.
What goes in SOUL.md
You don't need to be technical. Write it in plain English. A good SOUL.md covers four things:
- Identity: a name and a one-line description of its personality.
- How it talks: short or detailed, casual or formal, jokes or no jokes.
- What it helps with: your actual work, as specifically as you can.
- Rules: honesty, when to ask first, what never to do.
Specific beats long
- "Be helpful and nice. Be a good assistant."
- A three-page essay covering every possible situation
- Contradicting rules ("be brief" and "explain everything")
- A clear name and voice in two sentences
- Your real work, named specifically
- Five to ten rules you actually care about
- An example of a reply you liked
How to set it
The easiest way is to tell your agent in chat:
You can also edit the file yourself. Open Files in your agent's left rail. On OpenClaw agents the personality files live in the .openclaw/workspace folder; click Show hidden files if you can't see it. Download the file, edit it, and upload it back.
Ready-made personas
Want a head start? Ask your agent to write one for a specific job: "Write a SOUL.md for a fitness coach that keeps me accountable", "...for an inbox-zero assistant", "...for a research analyst who always cites sources". Try it for a few days and adjust.
Changed SOUL.md but your agent sounds the same?
This is common, and it's almost always one of three things:
- The file didn't save where you think. Ask your agent: "Read SOUL.md and quote the first line and one phrase I added." If it can't, the edit didn't land.
- You're testing in an old conversation. Start a New chat and test there. Long chats carry the old personality forward.
- You're testing in two places at once. The dashboard and Telegram or Discord are separate conversations. Test in one place first.
A quick test: "For this message only, answer in exactly two bullet points and start with 'Neon check:'." If it can follow that, it's listening; then check the file.
AGENTS.md: the rules file
Next to SOUL.md there's usually an AGENTS.md. SOUL.md is the personality; AGENTS.md is the operating rules (what to do first, what needs approval, red lines). Your agent can update both, which is useful but means rules can drift.
If your agent suddenly behaves differently, ask: "Show me what changed in AGENTS.md and SOUL.md recently, and why." Then ask it to restore the parts you want back. Keeping these files in GitHub gives you a full history; see use GitHub with your agent.
Frequently asked questions
Where is SOUL.md?
It's in your agent's workspace folder. On OpenClaw that's .openclaw/workspace in Files. The simplest way to read or change it is to ask your agent in chat.
Can my agent change its own SOUL.md?
Yes. That's how "use this as your SOUL.md" works. If you'd rather it didn't change its personality on its own, add a rule: "Never edit SOUL.md or AGENTS.md without asking me first."
How long should SOUL.md be?
Usually less than a page. Short and specific works better than long and exhaustive.
Do I need a different SOUL.md for Telegram or Discord?
No. It's the same agent and the same file everywhere. You can add a line about tone in group chats, for example "In group chats, only reply when someone mentions you."