How to Customise Your Agent's Personality With SOUL.md

Quick Answer

SOUL.md is a markdown file that defines your OpenClaw agent's personality, communication style, values, and boundaries. Every time your agent starts up, it reads this file first — it's essentially your agent reading itself into being. You edit it in plain text, and changes take effect when you restart the agent. A good SOUL.md turns a generic AI into something that feels distinctly yours.

What Is SOUL.md?

When you create an OpenClaw agent, a file called SOUL.md is generated in your agent's workspace directory. This file is injected into the system prompt every time your agent processes a message. Whatever you write in SOUL.md shapes how your agent thinks, speaks, and behaves across every interaction.

Think of it as a personality configuration file. A SOUL.md that says "you are concise and direct" will produce an agent that gives you short, sharp answers. One that says "you are warm, thoughtful, and always explain your reasoning" will produce an agent that feels more conversational and explanatory. The same underlying model, shaped into different characters by the words you write.

Your SOUL.md lives at ~/.openclaw/workspaces/[your-agent-name]/SOUL.md on macOS and Linux, or C:\Users\[YourName]\.openclaw\workspaces\[your-agent-name]\SOUL.md on Windows. Open it in any text editor.

Why It Matters

Without a customised SOUL.md, your agent behaves generically — helpful but bland. With a well-written one, it becomes a tool that communicates the way you want, prioritises the things you care about, avoids the things you don't, and feels consistent across every interaction.

This matters more than you might expect. An agent that matches your communication style is one you'll actually enjoy using. An agent that knows your priorities can make better decisions about what to include in a briefing or how to draft a reply. Small personality tweaks create significant quality-of-life improvements over time.

Anatomy of a Good SOUL.md

A well-structured SOUL.md typically covers five areas. You don't need to use rigid formatting — plain, natural language works best — but covering these areas gives your agent a complete sense of who it is.

Identity

Who is this agent? Give it a name and a role. This doesn't need to be elaborate — a sentence or two is plenty.

"You are Atlas, a personal research and productivity assistant. You help me stay informed, organised, and on top of my work."

Communication style

How should the agent talk? This is where you shape the tone of every interaction.

"Be concise. Default to short, direct answers. Only elaborate when I ask for detail or when the topic genuinely requires it. Don't use emojis. Don't start responses with 'Great question!' or similar filler."

Or the opposite approach:

"Be warm and conversational. Explain your reasoning. It's fine to be a bit verbose — I'd rather have too much context than too little. Use casual language."

Values and priorities

What does the agent care about? What should it optimise for?

"Accuracy over speed. If you're unsure about something, say so rather than guessing. When summarising, prioritise actionable information over background context. When drafting messages for me, match a professional but friendly tone."

Knowledge and context

What does the agent need to know about you and your world?

"I work in product management at a SaaS company. My main projects right now are the Q2 launch and the pricing redesign. I'm based in London, GMT timezone. When I ask about 'the team,' I mean my product squad of 6 people."

This section is where SOUL.md becomes genuinely powerful. The more relevant context you give your agent, the more useful its outputs become. An agent that knows your role, your projects, and your preferences produces dramatically better briefings, research, and drafts than one operating from zero context.

Boundaries

What should the agent not do?

"Never send messages or emails without my explicit approval. Don't make assumptions about my schedule — always check. If a task seems ambiguous, ask me to clarify rather than guessing."

Writing Your First SOUL.md

The single most important piece of advice: start short. Begin with 10–15 lines and add rules only when you notice your agent doing something you don't want. Every line in SOUL.md should earn its place through a real interaction that went wrong without it.

Here's a solid starting template:

You are [Name], my personal AI assistant.

Communication: Be concise and direct. No filler phrases. Use plain language.

Priorities: Accuracy first. If unsure, say so. Prefer actionable information.

Context: I work in [your field]. I'm based in [your city/timezone].

Boundaries: Never take irreversible actions without my confirmation.

Save the file, restart your agent, and start using it. Over the next few days, you'll naturally notice moments where you think "I wish it had done that differently." Each one of those is a line to add to your SOUL.md.

Common Adjustments People Make

After a few days of use, the most common additions are: telling the agent to be shorter (or longer) in its responses, adding specific formatting preferences for briefings and summaries, giving it information about ongoing projects or priorities, adjusting how it handles uncertainty (ask vs guess), setting language preferences (British vs American English, formal vs casual), and adding instructions about how to behave differently in different channels (concise in Slack, more detailed in WhatsApp).

Multiple Agents, Multiple Souls

Each OpenClaw agent workspace has its own SOUL.md, which means you can run multiple agents with completely different personalities. Some popular combinations include a focused, direct work agent connected to Slack for professional tasks, and a warmer, more conversational personal agent on WhatsApp for daily life. A research agent that's thorough and cites sources alongside a drafting agent that prioritises speed and brevity. A creative agent that brainstorms freely and an ops agent that's precise and process-oriented.

The personality separation makes it immediately clear which agent you're talking to and what to expect from each one.

Advanced Techniques

Dynamic context

Some people update their SOUL.md regularly — weekly or even daily — with current priorities, active projects, and upcoming events. This keeps your agent's context fresh without you having to re-explain what you're working on every time you start a conversation.

Skill-specific instructions

You can include instructions about how to use specific skills in your SOUL.md. For example: "When I ask for a daily briefing, always include weather in Manchester, AI news, and my Google Calendar events. Keep each section to 2–3 sentences maximum."

Persona testing

Before settling on a personality, try dramatically different SOUL.md configurations. Make one extremely concise, one very verbose, one formal, one casual. Use each for a day and see which one you actually enjoy interacting with. Most people are surprised by their preference — what you think you want and what you actually enjoy using often differ.

Frequently Asked Questions

Does changing SOUL.md lose my agent's memory?

No. SOUL.md is injected into the system prompt separately from your agent's conversation memory and session history. Changing the personality doesn't erase what your agent has learned or remembers from previous conversations.

How long should SOUL.md be?

Keep it to 1–2 pages maximum. Longer files dilute the most important instructions. Every line should earn its place. If a rule isn't affecting your agent's behaviour in a noticeable way, it's probably not needed.

Can I use someone else's SOUL.md as a starting point?

Yes, and many people do. There are shared SOUL.md templates on GitHub and in the OpenClaw community Discord. These are useful starting points, but the best results come from personalising it over time based on your own interactions.

Do I need to restart my agent after editing SOUL.md?

Yes. Your agent reads SOUL.md at startup. After editing, run openclaw restart or use the restart button in the Control UI to apply the changes.

Can I have different SOUL.md configurations for different channels?

Not natively as separate files, but you can include channel-specific instructions within a single SOUL.md: "When responding in Slack, be concise and use thread replies. When responding on WhatsApp, be more conversational and include more context."