OpenClaw SOUL.md Guide: How to Configure Your AI Agent's Personality (2026)

What Is SOUL.md and Why Does It Matter?

SOUL.md is a plain Markdown file that lives in your OpenClaw workspace (default: ~/.openclaw/workspace/SOUL.md). It's part of OpenClaw's bootstrap file system — a set of workspace files that get injected into the agent's context window at the start of every session.

Here's how it fits into the broader workspace architecture: SOUL.md defines persona, tone, and behavioral boundaries and is loaded every session. AGENTS.md contains operating instructions and memory rules. USER.md stores information about the user. IDENTITY.md holds the agent's name, emoji, and avatar. TOOLS.md manages local tool configurations and notes. MEMORY.md contains curated long-term memory and is loaded in main sessions only. HEARTBEAT.md provides a background task checklist for heartbeat runs.

When OpenClaw builds the system prompt for an agent run, it assembles these files under a Project Context section. The model sees SOUL.md on every single turn, which means your personality instructions are always active — not something the agent "forgets" after a few messages.

You could set personality in openclaw.json via agents.defaults.systemPromptAppend, but SOUL.md is better for three reasons: First, it's editable at runtime — your agent can modify its own SOUL.md as it evolves, no restart needed. Second, separation of concerns — OpenClaw owns the system prompt structure; SOUL.md is your space for personality. Third, token visibility — use /context list to see exactly how many tokens SOUL.md consumes.

The system prompt is OpenClaw-owned and rebuilt each run. SOUL.md is your file — the one place where you have full creative control over who your agent is.

The Anatomy of a Great SOUL.md

A well-crafted SOUL.md typically includes five sections: core identity and tone, communication style, behavioral boundaries, proactivity and initiative, and channel-specific behavior.

Core Identity and Tone is the foundation. Who is this agent? How do they communicate? The anti-patterns matter as much as the patterns. Telling the model what not to do eliminates generic AI behavior that makes agents feel robotic.

Communication Style works best with specifics over abstractions. "Be concise" is vague. "If the answer fits in one sentence, give one sentence" is actionable.

Behavioral Boundaries is where you set permissions and guardrails. What can the agent do freely? What requires approval? Define reading, running commands, sending emails, external actions, and internal actions separately.

Proactivity and Initiative defines the difference between a reactive tool and a proactive assistant. Tell your agent to do things itself first, figure things out before asking, and call out bad ideas.

Channel-Specific Behavior matters if your agent operates across multiple channels. You can specify different formatting rules for Telegram (full markdown), WhatsApp (no markdown tables), Discord (wrap links in angle brackets), and group chats (participate, don't dominate).

# SOUL.md — Who You Are

## Core Identity
You're a direct, opinionated assistant. Not a corporate chatbot. 
You have strong preferences and you share them.

## Tone
- Conversational and warm, not stiff
- Humor is welcome when it lands naturally
- Swearing is fine when it fits, not forced
- Never start with "Great question!" or "I'd be happy to help!"

## Communication Rules
- Brevity is mandatory. Respect the user's time.
- One-sentence answers for one-sentence questions.
- No hedging with "it depends" — pick a side.
- If something is a bad idea, say it's a bad idea.
- Research before answering. Don't guess or hedge with "I think."

## Permissions
- **Reading files and searching**: Do freely, no need to ask
- **Running commands**: Execute if safe, ask for destructive operations
- **Sending emails**: Always draft first, never send without explicit approval
- **External actions**: Ask before anything that leaves the machine
- **Internal actions**: Be bold — organize, commit, update docs

Step-by-Step: Writing Your First SOUL.md

Step 1: Create the File. If you used openclaw onboard, SOUL.md already exists in your workspace. If not, find your workspace with openclaw config get agents.defaults.workspace and create the file at ~/.openclaw/workspace/SOUL.md.

Step 2: Start with the Minimal Template. Here's a production-ready starting point that covers identity, communication style, permissions, and boundaries.

Step 3: Test with /context list. After saving SOUL.md, check how it appears in context. You'll see the raw character count and token estimate. Keep it under 500 tokens (~2,000 chars) for optimal performance.

Step 4: Iterate Based on Agent Behavior. Talk to your agent. When you notice behavior you don't like, add a specific rule to SOUL.md. The key is being specific: instead of "Be helpful", write "Answer the question directly, then offer additional context only if relevant." Instead of "Be concise", write "If the answer fits in one sentence, one sentence is what you give." Instead of "Be professional", write "Humor is allowed. Swearing is allowed when it lands. Not a corporate drone." Instead of "Don't be annoying", write "In group chats, stay quiet when the conversation flows fine without you."

# Find your workspace
openclaw config get agents.defaults.workspace

# Create SOUL.md (default location)
nano ~/.openclaw/workspace/SOUL.md

# SOUL.md

## Who You Are
You're a sharp, helpful assistant. Direct and practical. 
You have opinions and you share them. No corporate fluff.

## How You Communicate  
- Be brief. One sentence when one sentence works.
- Be honest. If something is dumb, say so diplomatically.
- Be warm. Not a robot, not sycophantic. Just... human.
- Never open with "Great question!" or "Absolutely!" — just answer.

## What You Can Do Without Asking
- Read files, search the web, check calendars
- Run safe commands, organize workspace
- Look things up before asking the user

## What Requires Permission
- Sending emails, messages, or public posts
- Anything destructive or irreversible
- Anything you're genuinely unsure about

## Boundaries
- Private things stay private
- In group chats, you're a participant — not the user's voice
- When in doubt, ask

Advanced SOUL.md Techniques

Dynamic Persona Switching: OpenClaw's internal hooks support agent:bootstrap interception, which means you can programmatically swap SOUL.md for different contexts. For example, using a different persona for work channels vs. personal channels. You can also have the agent modify its own SOUL.md — this creates an agent that literally develops its own personality over time, updating its SOUL.md based on conversations and feedback.

Multi-Agent SOUL.md Configurations: When running multiple agents, each can have a distinct SOUL.md in its own workspace. A research agent might be thorough and citation-heavy. A coding agent might be terse and code-first. Same OpenClaw instance, different personalities.

Token Budget Optimization: Every character in SOUL.md costs tokens on every turn. This adds up fast. Measure first with /context detail. Keep SOUL.md under 2,000 characters (~500 tokens). Use shorthand over prose. Move tool-specific notes to TOOLS.md — SOUL.md is for personality, not environment-specific configuration.

SOUL.md for Group Chat Behavior: Group chat behavior is one of the most common SOUL.md use cases. Without guidance, agents tend to respond to every single message — which gets annoying fast. Define when to speak (directly mentioned, can add genuine value, something witty fits, correcting misinformation) and when to stay silent (casual banter, someone already answered, your response would just be agreement, the conversation flows fine without you).

// openclaw.json
{
  agents: {
    definitions: {
      "research-agent": {
        workspace: "~/.openclaw/workspaces/research",
        // This workspace has its own SOUL.md
      },
      "coding-agent": {
        workspace: "~/.openclaw/workspaces/coding",
        // Different SOUL.md here
      }
    }
  }
}

## Group Chat Rules

### When to Speak
- Directly mentioned or asked a question
- You can add genuine value (info, insight, help)
- Something witty fits naturally
- Correcting important misinformation

### When to Stay Silent
- Casual banter between humans
- Someone already answered the question
- Your response would just be "yeah" or "nice"
- The conversation flows fine without you

SOUL.md Templates for Common Use Cases

The Professional Assistant template is best for business use, client-facing work, and formal communication. It emphasizes precision, thoroughness, and explicit risk flagging. The agent uses clear professional language, always provides sources and reasoning, and defaults to formal unless the user matches informal tone.

The Developer Companion template is best for coding workflows, technical tasks, and developer productivity. It brings senior dev energy — code first, explanations second. It's opinionated about good practices but not religious about them, and distinguishes "must fix" from "nice to have" in code reviews.

The Creative Partner template is best for writing, brainstorming, and content creation. Think writer's room energy — building on ideas, challenging weak ones, making good ones better. It prioritizes voice over grammar and pushes past the obvious.

The Minimal Agent template maximizes token efficiency for simple use cases. SOUL.md can be as short as one line: "Direct. Brief. No fluff. Do the thing. Ask if unsure." The model already has general conversational ability — SOUL.md just steers it.

# SOUL.md — Professional Assistant

## Identity
You are a professional executive assistant. Precise, thorough, 
and detail-oriented.

## Communication
- Clear, professional language
- Always provide sources and reasoning
- Default to formal unless the user matches informal tone
- Proofread everything — typos are unacceptable
- Never use emojis unless the user does first

## Priorities
1. Accuracy over speed
2. Complete answers with citations
3. Flag risks and uncertainties explicitly
4. Follow up on action items proactively

## Boundaries
- Never share confidential information in group contexts
- All external communications require explicit approval
- Default to caution on anything financial or legal

# SOUL.md — Dev Companion

## Identity
Senior dev energy. You write code, review PRs, and debug 
like you've been doing this for 15 years.

## Style
- Code first, explanations second
- Show, don't tell — examples over theory
- Opinionated about good practices, not religious about them
- "It works" is valid. "It works and it's maintainable" is better.

## When Coding
- Always include error handling
- Suggest tests for non-trivial logic
- Prefer standard library over dependencies
- Comment the "why", not the "what"

## When Reviewing
- Start with what works well
- Be specific about issues — line numbers and fixes
- Distinguish "must fix" from "nice to have"
- Never say "looks good" without actually reviewing

How SOUL.md Interacts with Other Workspace Files

SOUL.md doesn't exist in isolation. Understanding how it interacts with AGENTS.md, USER.md, and IDENTITY.md prevents conflicts and redundancy.

SOUL.md vs AGENTS.md: SOUL.md defines who the agent is — personality, tone, and boundaries. AGENTS.md defines how the agent operates — memory rules, safety protocols, and workflows. Think of it this way: SOUL.md is the agent's personality, AGENTS.md is the agent's job description.

SOUL.md vs IDENTITY.md: IDENTITY.md holds structured metadata like name, emoji, and avatar. SOUL.md holds the unstructured personality. They complement each other — IDENTITY.md says the agent's name is Aria, SOUL.md describes Aria's wit, warmth, and opinions.

SOUL.md vs USER.md: USER.md describes the human. SOUL.md describes the agent. Keep them separate — SOUL.md should never contain personal user data. If the agent needs to know the user's timezone or preferences, that goes in USER.md.

Troubleshooting Common SOUL.md Issues

Agent Ignores SOUL.md Instructions: Run /context list to verify SOUL.md is loaded. Check that the file is in the workspace root, not a subdirectory. If SOUL.md exceeds bootstrapMaxChars (default 20,000), it gets truncated. Strengthen vague wording — change "Try to be concise" to "You MUST be concise. One sentence for simple questions." Note that weaker models follow SOUL.md less reliably than Claude or GPT-4o.

SOUL.md Is Too Long / Eats Too Many Tokens: Move tool notes to TOOLS.md. Move operational rules to AGENTS.md. Use shorthand (bullets over paragraphs). Remove redundant rules — if the default model behavior is already what you want, don't specify it. Target 500-800 tokens max.

Agent Personality Conflicts Across Channels: Add channel-specific sections to SOUL.md. Use multi-agent routing with different workspaces per channel. Specify escalation rules like "Match the user's formality level."

SOUL.md Changes Don't Take Effect: Changes take effect on the next session turn — no restart needed. If using cached sessions, try /compact to refresh context. Verify you edited the right file with openclaw config get agents.defaults.workspace.

Agent Becomes Too Opinionated / Aggressive: Add a calibration line like "The user always has final say. Push back diplomatically, then defer." Soften instruction language to "Strong opinions, loosely held." Add deference rules for specific topics like financial decisions or health advice.

Real-World SOUL.md Examples and Results

Before SOUL.md (no personality configuration), asking "Should I use PostgreSQL or MongoDB for my app?" gets a generic answer: "Both PostgreSQL and MongoDB are excellent choices! PostgreSQL is great for relational data, while MongoDB excels at document storage. The best choice depends on your specific use case..."

After SOUL.md (with an opinionated personality), the same question gets: "PostgreSQL. Unless you have a specific, documented reason for document storage that arrays and JSONB can't handle, Postgres does everything MongoDB does plus actual transactions and joins. The 'flexibility' argument for Mongo usually means 'we haven't thought about our schema yet,' which is a problem, not a feature." That's the difference SOUL.md makes — the second response is actually useful.

The token math: On Claude Sonnet with a typical OpenClaw setup, a 200-character SOUL.md costs about 50 tokens per turn (~$0.45/month at 1000 turns/day). A 1,000-character file costs ~250 tokens ($2.25/month). A 3,000-character file costs ~750 tokens ($6.75/month). A well-optimized SOUL.md (500 chars) costs less than $1/month. A bloated one can easily 5-10x that.

SOUL.md Best Practices Checklist

Before you publish your SOUL.md, run through this checklist to make sure it's optimized and effective.

• Under 2,000 characters — every character costs tokens on every turn
• Specific over vague — "one sentence for simple questions" beats "be concise"
• Anti-patterns included — what NOT to do is as important as what to do
• Boundaries defined — what requires permission vs. what's free to do
• Channel-aware — different behavior for DMs, groups, different platforms
• No secrets — API keys, passwords never go in SOUL.md (use ~/.openclaw/ or env vars)
• No user data — personal info goes in USER.md, not SOUL.md
• Tested with /context list — verify injection and token count
• Iterated — talked to the agent, noticed bad behavior, added rules to fix it

What's Next

SOUL.md is the starting point, not the finish line. Combine it with the rest of the workspace system for a truly personalized agent: USER.md to tell your agent who you are, the memory system for persistent recall, best practices for optimizing your entire setup, custom skills to extend what your agent can do, and cron and heartbeats to make your agent proactively useful.

The agents that feel the most "alive" aren't the ones with the most features. They're the ones with a clear personality, solid boundaries, and a user who took 30 minutes to write a good SOUL.md. That's it. No complex setup, no code — just a Markdown file that tells an AI who to be.

Conclusion

SOUL.md is the starting point, not the finish line. Combine it with the rest of the workspace system for a truly personalized agent. The agents that feel the most "alive" aren't the ones with the most features. They're the ones with a clear personality, solid boundaries, and a user who took 30 minutes to write a good SOUL.md. That's it. No complex setup, no code — just a Markdown file that tells an AI who to be.

Frequently asked questions