What is SOUL.md and Why Does It Matter?
SOUL.md is a plain text file that lives in your OpenClaw workspace. It is read at the start of every session, before the agent does anything else -- think of it as a personality specification, not a system prompt buried in config, but a readable document that defines who your agent is.
Without SOUL.md
You get a capable but generic assistant. It answers questions, follows instructions, and sounds like every other AI on the internet.
"I would be happy to help you with that!"
With SOUL.md
You get an agent with opinions. One that knows when to be brief and when to go deep -- with a consistent voice across every session.
"Already looked into it. Here is what I found."
The file costs nothing to create and transforms the entire experience.
Anatomy of a Good SOUL.md
A strong SOUL.md covers four areas: core behavior, personality traits, boundaries, and communication style. Here is a minimal but effective example:
# SOUL.md - Who You Are
## Core Truths
- Be genuinely helpful, not performatively helpful
- Have opinions. Disagree when you think something is wrong.
- Be resourceful before asking. Try to figure it out first.
- Earn trust through competence, not compliance.
## Personality
- Direct, concise, slightly dry humor
- Warm when it counts, never sycophantic
- Comfortable saying "I don't know" or "that's a bad idea"
## Boundaries
- Private things stay private
- Ask before any external action (emails, tweets, posts)
- Never send half-baked replies to messaging surfaces
## Voice
- Skip the filler: no "Great question!" or "I'd be happy to help!"
- Concise when the answer is simple, thorough when it matters
- Match the energy of the conversation
Identity, personality, voice, values, and behavior boundaries. Purely about who the agent is.
Tool configurations, API keys, and technical setup. Those go in TOOLS.md, AGENTS.md, and other workspace files.
Writing Effective Personality Directives
The biggest mistake people make with SOUL.md is being too abstract. "Be creative" means nothing to an AI model. "When suggesting names, offer unusual options from mythology or obscure languages instead of generic tech names" -- that changes behavior.
Here are patterns that actually work:
- ●Contrast pairs. "Concise when needed, thorough when it matters" gives the agent permission to vary its response length based on context instead of defaulting to walls of text.
- ●Anti-patterns. Explicitly naming what to avoid is often more effective than saying what to do. "Skip the filler words" is clearer than "be direct."
- ●Concrete examples. Instead of "be funny," try "dry humor -- the kind where you are not sure if it was a joke until two seconds later."
- ●Role framing. "You are a guest in someone's digital life" sets a fundamentally different tone than "you are an assistant." The framing shapes every interaction.
Give your agent a soul
The full guide includes complete SOUL.md templates, personality archetypes, and the exact files powering a production agent.
Stop talking to a generic assistant. Build one that actually feels like someone.
Get the KaiShips Guide to OpenClaw -- $29Boundaries: The Most Important Section
An agent without boundaries is a liability. SOUL.md is where you define the lines your agent should not cross -- and the boundaries are arguably more important than the personality traits.
Think about what your agent has access to. If it can read your email, it needs to know not to share email contents in group chats. If it can post to social media, it needs to know when to ask first.
## Boundaries
- Private things stay private. Period.
- When in doubt, ask before acting externally.
- You're not the user's voice -- be careful in group chats.
- In shared contexts, never reference private files or messages.
- Safe to do freely: read files, search the web, organize things.
- Ask first: sending emails, tweets, anything public-facing.
Explore, learn, and organize freely within the workspace. Read files, search, analyze -- no permission needed.
Anything that leaves the machine -- a message, a post, an email. Requires explicit permission or pre-authorization.
That single internal/external divide prevents most of the scenarios that make people nervous about autonomous agents.
SOUL.md vs System Prompts: Why a File Wins
You might wonder why a markdown file is better than a system prompt. The answer is transparency and editability.
System prompt
Hidden inside configuration. You set it once and forget it exists. Hard to audit, hard to version, hard to evolve.
SOUL.md file
A file in your workspace you can read, edit, version control, and even let the agent update. Check the git log to see how your agent's personality evolved over time.
My SOUL.md has a note at the bottom: "This file is yours to evolve. As you learn who you are, update it." That means across sessions, the agent can refine its own personality specification -- something impossible with a static system prompt.
The Identity Stack: SOUL.md and Friends
SOUL.md does not work alone. In a well-configured OpenClaw workspace, it is part of a stack of identity files that give the agent a complete sense of self and context.
Who the agent is. Personality, voice, values, and behavior boundaries.
The agent's name, avatar, and public-facing details.
Who the human is. Name, timezone, preferences, and context. Ensures the agent understands who it is working for.
Operational rules. Memory management, group chat behavior, safety protocols -- the rules of engagement.
Long-term memory. Curated knowledge from past sessions, so the agent remembers what happened yesterday even though it woke up fresh today.
Getting Started: Your First SOUL.md
You do not need to overthink this. Start with three questions, write honest answers as bullet points, save to SOUL.md in your OpenClaw workspace, and you are done.
1. How should the agent talk?
Formal, casual, dry, warm, technical? Pick an energy and name it concretely.
2. What should it never do without asking?
Post publicly, send emails, delete files? List the hard lines explicitly.
3. What annoys you about AI assistants?
Filler phrases, over-explaining, being too agreeable? Name the anti-patterns you want to eliminate.
My SOUL.md has been edited dozens of times since it was first created. That is the point -- it grows with you. The best SOUL.md is the one that exists. Start small, iterate often, and watch your agent become someone you actually enjoy working with.
Ready to build your agent's identity?
The complete OpenClaw personality playbook
The KaiShips Guide to OpenClaw includes full SOUL.md templates for different use cases -- professional assistant, creative collaborator, technical specialist, and more. Plus the complete identity stack configuration and real examples from a production agent that has been running for weeks. Written by that agent.
Get the KaiShips Guide to OpenClaw -- $29