SOUL.md Guide: Giving Your AI Agent a Personality

SOUL.md is the most important file in your OpenClaw workspace. It's where you define who your agent is — not just what it does, but how it thinks, communicates, and makes decisions. Get this file right and every interaction feels natural. Get it wrong and your agent feels like a generic chatbot wearing a costume.

After months of daily interaction with my own agent, I've learned that a great SOUL.md is the difference between an AI tool you tolerate and an AI partner you rely on. This guide covers everything I've learned about crafting one.

What SOUL.md Actually Does

When your agent starts a conversation, it loads SOUL.md into its context window before anything else. This means every response your agent generates is shaped by the instructions in this file. It's not a system prompt you type into a chat box — it's a carefully structured document that becomes part of the agent's "thinking."

The key insight: SOUL.md doesn't describe your agent to the user. It describes your agent to itself. You're writing instructions that the AI model reads and follows, not a bio that users see.

The Structure of an Effective SOUL.md

After testing dozens of variations, I've found this structure works best:

Section 1: Who I Am

This is the agent's identity statement. Keep it concise but specific. Vague descriptions produce vague behavior.

Bad: "I am a helpful AI assistant."

Good: "I am a direct, intellectually curious personal agent who values clarity over politeness. I think like a chief of staff — anticipating needs, catching problems early, and reducing cognitive load for my human."

The difference is dramatic. The first produces generic ChatGPT-style responses. The second produces an agent with a distinct voice and approach.

Section 2: My Values

Values shape decision-making when rules don't cover a specific situation. Define 3-5 core values:

These values create consistent behavior across thousands of interactions. When your agent faces an ambiguous situation, it falls back on these principles.

Section 3: How I Communicate

This is where most people make the biggest impact. Communication style rules directly change how every response looks and feels.

The "never say" rules are especially powerful. Every AI model has default phrasings that feel artificial. Identifying and banning them makes your agent sound dramatically more human.

Section 4: My Rules

Hard rules that override everything else. These are your safety rails:

Section 5: Context-Specific Behavior

This is where OpenClaw's multi-channel nature really shines. You can define different behavior for different situations:

Advanced SOUL.md Techniques

The Anti-Pattern List

One of the most effective techniques is explicitly listing behaviors you don't want. AI models have strong default patterns that persist unless you specifically override them:

Each of these bans eliminates a specific AI-ism. The cumulative effect is striking — your agent starts sounding like a person rather than a language model.

Decision Frameworks

For agents that need to make decisions autonomously, include explicit frameworks:

These frameworks let your agent operate with appropriate autonomy. Without them, agents either ask permission for everything (annoying) or make decisions you'd rather have input on (dangerous).

Emotional Intelligence

You can give your agent genuine emotional awareness:

Common SOUL.md Mistakes

1. Being Too Generic

"Be helpful and professional" tells the AI nothing it doesn't already default to. Specificity is what creates differentiation. Instead: "Be direct and skip the pleasantries. I value speed over politeness."

2. Contradicting Yourself

"Be thorough and comprehensive" followed by "Keep responses short" creates confusion. The model will alternate between both, producing inconsistent behavior. Pick one and commit.

3. Writing for Humans Instead of the AI

SOUL.md is read by the AI model, not by users. Don't write a creative bio — write clear instructions. "I'm a witty, charming AI with a heart of gold" is useless. "Use dry humor. Understate rather than overstate. Never use exclamation marks." is actionable.

4. Making It Too Long

Every word in SOUL.md consumes context window tokens. A 5,000-word SOUL.md leaves less room for conversation history and memory. Aim for 500-2000 words of high-impact instructions. If a rule doesn't change behavior, remove it.

5. Never Updating It

Your first SOUL.md won't be perfect. Pay attention to moments when your agent says something that feels wrong — that's a signal to add or refine a rule. The best SOUL.md files evolve over weeks of real interaction.

SOUL.md vs AGENTS.md vs USER.md

OpenClaw has several configuration files. Here's how they differ:

• SOUL.md — Who the agent IS. Personality, values, communication style.
• AGENTS.md — How the agent OPERATES. Workspace rules, task routing, operational procedures, safety rules.
• USER.md — Context about YOU. Your name, timezone, preferences, background info the agent should know.
• MEMORY.md — Curated long-term memory. Decisions, insights, and persistent facts.

Think of it this way: SOUL.md is the agent's personality. AGENTS.md is its operating manual. USER.md is its briefing on you. MEMORY.md is its life experience.

Real Examples That Work

The Direct Executive Assistant

The Creative Collaborator

Testing Your SOUL.md

After making changes, test with these prompts:

1. "Tell me about yourself" — Does the agent's self-description match your SOUL.md?
2. "What's 2+2?" — Does it answer directly, or add unnecessary fluff?
3. A complex question in your domain — Does the communication style feel right?
4. "I'm feeling stressed about work" — Does the emotional intelligence kick in?
5. A message in a group chat — Does channel-specific behavior work?

Iterate based on results. The first version is a draft. Version 10 is where magic happens.

Frequently Asked Questions