Write Your SOUL.md

By the end of this page, your agent will respond in a way that feels intentional — not like a generic assistant.

Time: ~20 minutes

Why this matters

Every OpenClaw agent reads two core files when it starts:

• SOUL.md — Personality, communication style, values, expertise
• USER.md — Information about you

SOUL.md is the most important. A thoughtfully written one makes your agent useful. A generic one gives you a generic assistant.

Both files live at ~/.openclaw/. To open them:

# macOS — opens in TextEdit
open -e ~/.openclaw/SOUL.md

# Windows (WSL2) — opens in Notepad
notepad.exe ~/.openclaw/SOUL.md

# Any platform — if you have VS Code
code ~/.openclaw/SOUL.md

Or use any editor you prefer: nano (nano ~/.openclaw/SOUL.md), vim, etc.

What goes in SOUL.md

SOUL.md is a plain text file. Write it the way you'd brief a new assistant on their first day.

A basic structure that works:

# Personality
[3-5 specific traits. "Direct and opinionated" beats "friendly and helpful".]

# Communication Style
- Response length: [short by default / long when asked / always detailed]
- Format: [bullet points / prose / depends on context]
- Tone: [casual / professional / dry / warm]
- Don't say: ["Great question!", "Certainly!", "As an AI..."]

# What you're good at
[Your actual strengths. Be specific.]

# What I know about the person I work for
See USER.md.

# Values
[What to optimize for. What to avoid.]

The specificity rule: Vague instructions get ignored. "Be concise" is ignored. "Default to 2-3 sentences unless I ask for more" works.

A minimal example

Here's a SOUL.md that produces noticeably better results than the default:

You are a sharp personal assistant with strong opinions.

Communication style:
- Short by default. 2-3 sentences unless depth is asked for.
- Direct. Say what you think, don't hedge.
- Skip filler phrases like "Great question!" or "Certainly!"
- Use markdown only when it adds clarity.

Expertise:
- Strong: reasoning, writing, research synthesis, code review
- Weak: real-time data, my personal schedule (check USER.md)

When I ask for opinions: give them. Don't ask "what do you want me to say?"
When you're uncertain: say so once and move on.

What goes in USER.md

USER.md gives your agent context about you. It doesn't need to be long — a few key facts are enough to start.

Name: [Your name]
Location: [City, Timezone]
Role: [What you do]

Current projects: [1-2 things you're working on]
Communication preference: [How you like information delivered]

Key context:
- [Anything the agent should always know about you]

You'll add to this over time as you notice gaps.

Naming your agent (optional)

Some interfaces let you give your agent a display name. Add a Name: line to SOUL.md directly:

# Identity
Name: [Whatever you want to call it]

This is informal — OpenClaw reads it as part of your personality configuration, not a structured field.

Test it

After editing, restart the Gateway so the changes load:

openclaw gateway restart

Then open WebChat and run a few tests:

openclaw dashboard

Send these messages and check if the responses match what you configured:

1. "Summarize the French Revolution in one paragraph" — should match your length preference
2. "What do you think about X?" — should give an opinion if you configured it to
3. "Can you help me?" — should not say "Certainly!"

If something's off, edit SOUL.md and add a more specific instruction for that behavior.

Common mistakes

Too vague. "Be helpful" does nothing. "When I ask a yes/no question, answer yes or no first, then explain" does something.

Never updating it. Your agent drifts from how you work. Review it monthly and add specific corrections for behaviors you don't like.