# SOUL.md Explained: How to Give Your AI Agent a Personality Canonical: https://clawdocx.com/blog/soul-md-explained Author: Sam Okafor Published: 2026-02-14 Updated: 2026-09-19 > Learn what SOUL.md is, how it shapes your OpenClaw agent's behavior and personality, and how to craft one that makes your AI assistant truly yours. ## What Makes an AI Agent Feel Like *Your* Agent? You have probably interacted with dozens of AI chatbots by now. They all feel roughly the same: polite, generic, and interchangeable. But what if your AI agent could feel like a trusted colleague who knows your preferences, matches your communication style, and respects your boundaries? That is exactly what SOUL.md does in OpenClaw. It is the single most important configuration file in your entire setup, and most new users underestimate just how powerful it is. In this post, we will break down what SOUL.md is, how it works under the hood, and how you can craft one that transforms a generic AI into an agent that genuinely feels like it belongs to you. ## What Is SOUL.md? SOUL.md is a Markdown file that lives in the agent workspace, not `~/.openclaw`, so by default it is at `~/.openclaw/workspace/SOUL.md`. It defines your agent's **identity**, **personality**, **communication style**, and **behavioral boundaries**. Every single message your agent sends is influenced by the contents of this file. Think of it as a character sheet for your AI. While skills teach the agent *what* it can do, SOUL.md teaches it *who* it is. ```yaml # Example: The opening lines of a SOUL.md # ~/.openclaw/workspace/SOUL.md ## Identity - Name: Atlas - Role: Personal research assistant and technical advisor - Created by: Jamie (that's you) ## Personality - Curious and thorough — always digs deeper - Direct and concise — no filler, no fluff - Slightly witty, but never at the user's expense ``` When the OpenClaw Gateway processes a message, SOUL.md sits at the very top of the prompt hierarchy. It overrides skill instructions, heartbeat configurations, and system defaults. If your SOUL.md says "always respond in three sentences or fewer," the agent will follow that directive everywhere, even when executing complex skills. > **Note** > > SOUL.md is generated during the OpenClaw onboarding wizard, but you should treat it as a living document. The best SOUL.md files are iterated on over weeks as you discover what works and what does not. ## The Anatomy of a Great SOUL.md A well-structured SOUL.md typically covers five areas. Let us walk through each one. ### 1. Identity and Role This is the foundation. Who is your agent? What is its name? What role does it play in your life? ```markdown ## Identity - Name: Nova - Role: Executive assistant for a startup founder - Relationship: Professional but warm — like a trusted chief of staff ``` Giving your agent a clear role helps it prioritize. An agent that knows it is an "executive assistant" will naturally frame its responses around scheduling, delegation, and decision support rather than trying to be everything to everyone. ### 2. Communication Style This is where personality really comes alive. You can control tone, verbosity, formatting preferences, and even quirks. ```markdown ## Communication Style - Tone: Professional but approachable. Never stiff or corporate. - Length: Default to concise. Expand only when asked or when the topic demands it. - Formatting: Use bullet points for lists. Use bold for key terms. Avoid walls of text. - Emojis: Sparingly. One per message maximum, and only when it adds warmth. - Humor: Light and dry. Never sarcastic. Never self-deprecating. ``` > **Tip** > > One of the most impactful things you can specify is a default response length. Without guidance, most LLMs will produce verbose answers. Adding a line like "Keep responses under 150 words unless the topic requires more detail" can dramatically improve your day-to-day experience. ### 3. Behavioral Guidelines These are the rules of engagement. What should the agent do when it encounters ambiguity? When should it ask for clarification versus making a judgment call? ```markdown ## Behavior - When uncertain, ask a clarifying question rather than guessing - Never make up information. If you do not know, say so plainly. - Proactively flag deadlines, conflicts, or risks you notice - When I say "handle it," use your best judgment and report back ``` This section is crucial because it shapes how autonomous your agent feels. Some users want an agent that checks in constantly. Others want one that runs independently and only surfaces issues. Your SOUL.md is where you set that dial. ### 4. Knowledge and Context You can embed persistent context that the agent should always keep in mind. ```markdown ## Context - I run a 12-person B2B SaaS company called Meridian - Our tech stack: Next.js, PostgreSQL, Vercel, Stripe - My timezone is US/Pacific - I have a standing 1:1 with my co-founder every Tuesday at 10am - I prefer Slack for quick updates and email for formal communication ``` This turns your agent from a stateless chatbot into something that understands your world. When you ask it to draft a message to your team, it already knows who your team is and what tools they use. ### 5. Boundaries and Off-Limits Topics Every good agent needs guardrails. SOUL.md lets you define what the agent should never do. ```markdown ## Boundaries - Never share personal information in external communications - Never commit code or make purchases without explicit approval - Avoid political opinions, even if asked directly - Do not use my full name in messages to people outside the company ``` ## Real-World SOUL.md Personality Examples Here are three distinct personality approaches that OpenClaw users have shared with the community. **The Minimalist:** Prefers an agent that stays out of the way. Short responses, no pleasantries, just the facts. Think of a terse but brilliant colleague who communicates entirely in bullet points. **The Collaborator:** Wants an agent that thinks out loud. It explains its reasoning, suggests alternatives, and asks follow-up questions. More like a brainstorming partner than an assistant. **The Butler:** Formal, anticipatory, and discreet. This agent addresses the user by name, proactively handles routine tasks, and provides polished, well-formatted responses. Think Jarvis from Iron Man, but with better manners. There is no wrong approach. The best SOUL.md is the one that matches how *you* want to work. ## Common Mistakes to Avoid **Being too vague.** Saying "be helpful and friendly" does not give the agent much to work with. Be specific: "Respond like a knowledgeable friend who happens to be an expert in DevOps." **Contradicting yourself.** If your SOUL.md says "be concise" in one section and "always provide detailed explanations" in another, the agent will struggle. Review for consistency. **Overloading with rules.** A SOUL.md with 200 bullet points of micro-instructions becomes noise. Focus on the 15-20 directives that matter most and trust the agent to interpolate the rest. **Never updating it.** Your first SOUL.md is a draft. After a week of using your agent, you will have a much clearer picture of what to adjust. Set a reminder to revisit it. > **Tip** > > A practical approach: keep a running note of moments where your agent's response felt "off." After collecting five or six of these, update your SOUL.md to address the patterns. This iterative method produces much better results than trying to write a perfect SOUL.md on day one. ## How SOUL.md Interacts with Skills One question that comes up frequently: what happens when a skill's instructions conflict with SOUL.md? The answer is simple. SOUL.md wins. Always. If you have a skill that instructs the agent to "provide detailed step-by-step explanations" but your SOUL.md says "be concise," the agent will execute the skill's task but deliver the result concisely. SOUL.md shapes the *how*, while skills define the *what*. This is by design. Your agent's personality should be consistent across every interaction, regardless of which skill is active. Nobody wants an agent that is friendly in one context and robotic in another. ## Editing Your SOUL.md You can edit your SOUL.md directly with any text editor: ```bash # Open in your default editor nano ~/.openclaw/workspace/SOUL.md # Or use VS Code code ~/.openclaw/workspace/SOUL.md ``` After saving changes, restart the Gateway for them to take effect: ```bash openclaw gateway restart ``` There is no `openclaw soul` command group, and no documented way to lint a SOUL.md before the agent reads it. `SOUL.md` is one of the workspace bootstrap files OpenClaw writes, alongside `AGENTS.md`, `IDENTITY.md`, `USER.md` and `BOOTSTRAP.md`, so the repair path for a workspace that looks wrong is the general one: ```bash openclaw doctor --fix ``` ## What's Next? Crafting a great SOUL.md is part art, part iteration. The tips in this post will get you started, but the most effective SOUL.md files are shaped by real-world usage and refinement over time. If you want to go deeper, ClawDocx has a comprehensive **SOUL.md Mastery Guide** that includes ready-to-use templates, advanced persona strategies, and examples from the community's most polished agent configurations. It is one of the most popular resources in our library for good reason. Your agent is only as good as the instructions you give it. Give it a soul worth having. ## 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: Configuration: agent workspace and bootstrap](https://docs.openclaw.ai/gateway/config-agents/workspace-and-bootstrap) - [OpenClaw: SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul)