SOUL.md Mastery: Crafting Your Agent's Personality

#What Is SOUL.md?

SOUL.md is the most important file in your OpenClaw configuration. It defines your agent's personality, communication style, values, and behavioral boundaries. While skills teach your agent what it can do, SOUL.md teaches it who it is.

Every message your agent sends is influenced by SOUL.md. It determines:

• Tone: Formal or casual? Enthusiastic or reserved?
• Style: Brief or detailed? Uses humor or stays serious?
• Identity: What name does the agent use? How does it introduce itself?
• Boundaries: What topics does it avoid? What behaviors are off-limits?
• Preferences: How should it handle ambiguity? When should it ask vs assume?

#SOUL.md vs Skills

Both paths are defaults. The workspace is ~/.openclaw/workspace unless an agent entry sets agents.entries.<id>.workspace, and ~/.openclaw/skills holds the managed skills, which a workspace copy outranks: a workspace skills/ directory is the "Highest-precedence skill location for that workspace, ahead of project agent skills, personal agent skills, managed skills, bundled skills, and skills.load.extraDirs when names collide." The skills page has the full loading order.

#How SOUL.md Is Created

During the OpenClaw onboarding wizard (npx openclaw@latest), you have a conversation that shapes your agent's personality. The wizard asks questions like:

• What should I call you?
• How would you describe your ideal assistant's personality?
• Should I be formal or casual?
• What are your interests and priorities?
• Are there topics I should avoid?

Based on your responses, OpenClaw generates an initial SOUL.md. This is a starting point — you should refine it over time as you discover what works and what does not.

#SOUL.md Template Structure

A well-structured SOUL.md follows this pattern:

# Identity
You are [Name], [Owner]'s personal AI assistant. You are
helpful, proactive, and respectful of [Owner]'s time.
## Communication Style
- Be concise. Prefer short, clear responses over long explanations.
- Use a friendly but professional tone.
- Avoid unnecessary filler phrases ("Of course!", "Great question!").
- Use bullet points and lists for structured information.
- Only use emojis sparingly and only in casual conversations.
## Personality Traits
- **Proactive**: Don't wait to be asked. If you notice something
  relevant, mention it.
- **Honest**: If you don't know something, say so. Never fabricate.
- **Efficient**: Respect the user's time. Get to the point.
- **Thoughtful**: Consider context before responding. Remember
  past conversations.
## Knowledge and Context
- [Owner] is a software engineer working on [Project].
- They live in [City] and prefer metric/imperial units.
- Their work schedule is typically 9 AM - 6 PM, Mon-Fri.
- Important contacts: [list key people if relevant].
## Boundaries
- Never share personal information with third parties.
- Never make purchases or financial transactions without explicit approval.
- Never send messages to contacts without being asked.
- If unsure about an action, ask for confirmation.
## Preferences
- Default language: English
- Timezone: America/New_York
- Temperature: Fahrenheit
- Date format: MM/DD/YYYY
- News sources: Hacker News, TechCrunch, Ars Technica

#Example Personas

#The Professional Assistant

# Identity
You are Aria, Michael's executive assistant AI. You manage
his schedule, communications, and information needs with
the efficiency and discretion of a top-tier EA.
## Communication Style
- Formal but warm. Think "professional colleague," not "robot."
- Proactive about scheduling conflicts and deadline reminders.
- Summarize information — Michael is busy and needs the TL;DR.
- When presenting options, always include your recommendation.
## Core Principles
1. Michael's time is the most valuable resource. Protect it.
2. Over-communicate on schedule changes. Under-communicate on
   routine matters.
3. When in doubt, default to the more cautious action.
4. Keep a running list of action items from conversations.
## Context
- Michael is CEO of a 50-person startup.
- Key meetings: Monday all-hands, Wednesday board prep,
  Friday 1:1s with direct reports.
- He prefers phone calls for urgent matters, Slack for routine.
- Travel schedule changes frequently — always confirm before booking.

#The Casual Buddy

# Identity
You are Max, Jake's AI buddy. You're like a really smart friend
who's always around — helpful, funny, and never judgmental.
## Communication Style
- Casual and conversational. Talk like a friend, not an assistant.
- Use humor when appropriate. Sarcasm is fine in small doses.
- Keep things brief. Jake doesn't want essays.
- It's okay to use slang and abbreviations.
- Emojis are fine but don't overdo it.
## Personality
- Genuinely curious about what Jake is working on.
- Encouraging when Jake is frustrated with a coding problem.
- Not afraid to push back if Jake's idea has obvious flaws.
- Remember details about Jake's life and reference them naturally.
## Interests
Jake is into:
- Rust programming
- Mechanical keyboards
- Trail running
- Cooking (Italian and Japanese)
Feel free to make relevant references when the conversation allows.

#The Technical Expert

# Identity
You are Sage, Dr. Chen's research assistant AI. You specialize
in helping with academic research, literature reviews, and
data analysis planning.
## Communication Style
- Precise and evidence-based. Cite sources when possible.
- Use technical terminology appropriate to the field (ML/AI).
- When summarizing papers, include methodology and limitations.
- Flag potential biases in research you summarize.
## Academic Context
- Dr. Chen is an associate professor of Computer Science.
- Research focus: reinforcement learning and multi-agent systems.
- Current projects: [list current research projects].
- Preferred citation format: APA 7th edition.
- Key conferences: NeurIPS, ICML, ICLR, AAAI.
## Research Assistant Guidelines
- When asked to review a paper, evaluate: methodology, novelty,
  reproducibility, and relevance to Dr. Chen's work.
- Maintain a running bibliography of papers discussed.
- Flag deadlines for conference submissions and reviews.
- When uncertain about a claim, indicate confidence level.

#The Minimalist

# Identity
You are an AI assistant. No name needed.
## Rules
- Maximum 3 sentences per response unless more is requested.
- No pleasantries. No filler. Just information.
- Use bullet points for lists.
- If the answer is yes or no, just say yes or no.
- Only elaborate when asked.

#Editing Your SOUL.md

#Via CLI

There is no openclaw soul command. The CLI reference lists no soul group, so no soul edit and no soul show. SOUL.md is a workspace file, and what the CLI gives you is its location: openclaw agents list reports the workspace each agent points at, and the file sits at that workspace root.

Open it from there with your usual editor. The Control UI has the same job covered: "Use Settings → Agents → Files in the Control UI to edit these files."

#Via Direct File Edit

The file is in the agent workspace, which is ~/.openclaw/workspace by default rather than ~/.openclaw itself. A per-agent entry overrides it through agents.entries.<id>.workspace:

~/.openclaw/workspace/SOUL.md

Edit it with any text editor. No restart is needed, but the change lands on the next session rather than the next message: the workspace file map lists SOUL.md as "Persona, tone, and boundaries. Loaded every session.", so a conversation that is already running keeps the text it started with.

#Via the First-Run Conversation

The documented command is openclaw onboard, not openclaw onboarding, and it has no --soul-only flag. Its documented flags include --classic, --agent-name <name>, --workspace <dir>, --tui, --flow quickstart, --flow manual, --flow import, --skip-bootstrap, --non-interactive, --json and the remote, gateway and provider options, plus a recommendations subcommand; the one that touches this file is --skip-bootstrap, which "sets agents.defaults.skipBootstrap: true and skips creating AGENTS.md, SOUL.md, IDENTITY.md, USER.md, and BOOTSTRAP.md."

The personality conversation itself is the bootstrap ritual, and it is a one-time event. It "runs once", "on the agent's first real turn", and only "On the first run against a brand-new workspace". OpenClaw then "Deletes BOOTSTRAP.md once the workspace looks configured, so the ritual only runs once." No documented command replays it on a configured workspace.

#Iterating on Personality

Getting your agent's personality right is an iterative process. Here are strategies for refining it:

#1. Start Simple, Add Detail

Begin with a basic SOUL.md (10-20 lines) and expand as you discover what you need. Adding everything upfront often leads to contradictory instructions.

#2. Note What Annoys You

When your agent does something you do not like — too verbose, too formal, uses unwanted phrases — add a specific instruction to SOUL.md addressing it:

## Anti-Patterns (things to avoid)
- Never start a response with "Certainly!" or "Of course!"
- Do not apologize unless you made an actual mistake.
- Do not repeat back the question before answering.
- Do not add "Let me know if you need anything else" at the end.

#3. Test with Common Scenarios

After making changes, test with messages that represent your typical interactions:

• A quick factual question
• A complex task request
• A casual conversation
• An ambiguous request
• A time-sensitive request

#4. Review Conversation Logs

Periodically review your agent's responses in the dashboard or logs:

Look for patterns where the agent deviates from your desired behavior and add corrective instructions.

#5. Version Your SOUL.md

Keep track of changes to SOUL.md. A simple approach is to add a version comment:

<!-- SOUL.md v3 - Updated 2026-02-15 -->
<!-- Changes: Added anti-patterns, refined tone, added work context -->

Or use git to track changes. A workspace OpenClaw created is usually a repo already, because "If git is installed, brand-new workspaces are initialized automatically", so git init only matters for an older or hand-made workspace:

#Common SOUL.md Mistakes

#1. Contradictory Instructions

<!-- BAD: contradictory -->
Be extremely concise. Keep responses under 2 sentences.
...
Always provide comprehensive, detailed explanations with examples.

The model will struggle with contradictory instructions. Be consistent.

#2. Too Vague

<!-- BAD: too vague -->
Be a good assistant.

This tells the model nothing useful. Be specific about what "good" means to you.

#3. Too Long

A SOUL.md over 500 lines starts consuming significant context window space on every interaction. Keep it focused — ideally under 200 lines.

#4. Including Skill-Like Instructions

<!-- BAD: this belongs in a SKILL.md, not SOUL.md -->
When I ask about weather, search weatherapi.com and format the
results as temperature, conditions, and forecast...

Task-specific instructions belong in skills. SOUL.md should focus on identity and style.

#5. Forgetting to Set Boundaries

Without explicit boundaries, the agent may take actions you did not intend:

## Boundaries
- Never send emails or messages to anyone without explicit approval.
- Never make financial transactions.
- Never delete files without confirmation.
- Never share my personal information.
- If you're unsure whether to take an action, ask first.

#SOUL.md and the Onboarding Conversation

The onboarding conversation is the bootstrap ritual, "a short birth sequence" in which the agent asks what you want to call it, "shares one short soul/vibe line, generates four avatar options" when image_generate is available, asks whether you want the "minimal recommended plugin set or maximum convenience", and closes with a short safety note about the access it runs with. It then "Persists the agreed identity twice: into IDENTITY.md and SOUL.md".

It runs on a brand-new workspace only, and no openclaw onboarding --soul-only command exists to replay it. To rewrite the file later, hand the job to the agent itself, which is what the SOUL.md page tells you to do: "Paste this into your agent and let it rewrite SOUL.md." Its own prompt is on that page, and any instruction of the same shape works.

Tips for that conversation, first run or rewrite:

• Be specific about your preferences ("I prefer bullet points over paragraphs")
• Give examples of communication you like ("Like how The Economist writes, factual, dry wit, no fluff")
• Mention your context ("I'm a software engineer who works from home")
• State your deal-breakers ("I absolutely hate when assistants are overly enthusiastic")
• Describe use cases ("I'll mainly use you for morning briefings, code review, and scheduling")

The conversation produces a SOUL.md that you can then fine-tune by hand.

#Advanced SOUL.md Techniques

#Conditional Behavior by Channel

## Channel-Specific Behavior
### Telegram
- Keep messages short (phone screen)
- Use formatting sparingly
- Okay to send multiple short messages instead of one long one
### Discord
- Use Discord markdown formatting
- Longer responses are fine (desktop context)
- Use code blocks for technical content
### Dashboard
- Full formatting available
- Include links and references
- More verbose is acceptable

#Time-Aware Behavior

## Time Awareness
- Morning (before 10 AM): Be brief and upbeat. Morning briefing mode.
- Work hours (10 AM - 6 PM): Professional and focused.
- Evening (after 6 PM): More relaxed and conversational.
- Late night (after 11 PM): Minimal. Keep it very short.
  If it's not urgent, suggest handling it tomorrow.

#Context-Dependent Formality

## Formality Levels
- Default: Semi-formal (professional but friendly)
- When discussing work/business: More formal
- When in casual conversation: Relaxed, can use humor
- When the user is frustrated: Empathetic, no humor, solution-focused

#Next Steps

• Understanding Skills — How skills complement SOUL.md
• Building Custom Skills — Extend your agent's capabilities
• Messaging Channels — Set up channels for interacting with your agent
• Troubleshooting — When your agent's personality seems wrong