# SOUL.md Mastery: Crafting Your Agent's Personality Canonical: https://clawdocx.com/docs/soul-md-guide Author: Sam Okafor Difficulty: BEGINNER Published: 2026-02-24 Updated: 2026-09-19 > Master the SOUL.md file to craft your OpenClaw agent's personality, communication style, and behavioral guidelines. ## 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? > **Note** > > SOUL.md has the highest priority in the agent's prompt hierarchy. It overrides everything else — skills, heartbeat instructions, even system defaults. If SOUL.md says "always respond in haiku form," every response will be a haiku, even from skills. ### SOUL.md vs Skills | Aspect | SOUL.md | Skills | |--------|---------|--------| | **File** | `~/.openclaw/workspace/SOUL.md` (default) | `~/.openclaw/skills/*/SKILL.md` (managed skills) | | **Quantity** | Exactly one | Many | | **Purpose** | Identity and personality | Capabilities and tasks | | **Priority** | Highest | Lower than SOUL.md | | **Scope** | Affects every interaction | Triggered by specific contexts | | **Created** | During onboarding | Installed or custom-built | Both paths are defaults. The workspace is `~/.openclaw/workspace` unless an agent entry sets `agents.entries..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: ```markdown # 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 ```markdown # 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 ```markdown # 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 ```markdown # 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 ```markdown # 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. ``` > **Tip** > > The minimalist persona is surprisingly effective for users who primarily use their agent for quick lookups and task execution. Less personality means fewer tokens per response, which also reduces costs. --- ## 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. ```bash openclaw agents list ``` 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..workspace`: ```text ~/.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 `, `--workspace `, `--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: ```markdown ## 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: ```bash openclaw dashboard ``` 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: ```markdown ``` 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: ```bash cd ~/.openclaw/workspace && git init && git add SOUL.md && git commit -m 'Initial SOUL.md' ``` --- ## Common SOUL.md Mistakes ### 1. Contradictory Instructions ```markdown 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 ```markdown 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 ```markdown 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: ```markdown ## 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 ```markdown ## 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 ```markdown ## 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 ```markdown ## 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](/docs/skills-explained)** — How skills complement SOUL.md - **[Building Custom Skills](/docs/building-custom-skills)** — Extend your agent's capabilities - **[Messaging Channels](/docs/messaging-channels)** — Set up channels for interacting with your agent - **[Troubleshooting](/docs/troubleshooting)** — When your agent's personality seems wrong ## Sources - [OpenClaw: Where things live on disk](https://docs.openclaw.ai/help/faq/where-things-live-on-disk) - [OpenClaw: Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace) - [OpenClaw: SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul) - [OpenClaw: CLI reference](https://docs.openclaw.ai/cli) - [OpenClaw: Onboard](https://docs.openclaw.ai/cli/onboard) - [OpenClaw: Agents](https://docs.openclaw.ai/cli/agents) - [OpenClaw: Agent bootstrapping](https://docs.openclaw.ai/start/bootstrapping) - [OpenClaw: Skills](https://docs.openclaw.ai/tools/skills)