What Is SOUL.md?
Every OpenClaw agent has a file called SOUL.md that acts as its foundational identity layer. It is a plain Markdown file that defines your agent's personality, communication style, core values, and behavioral guardrails. OpenClaw reads this file on startup and applies it as a system-level prompt to every interaction — whether your agent is responding to a morning message, drafting an email, or running a scheduled task at 3 AM.
Unlike traditional chatbots that reset their personality with each conversation, your OpenClaw agent maintains a consistent sense of self through SOUL.md. The same tone, the same priorities, the same rules — always.
Where Does It Live?
SOUL.md is located at:
~/.openclaw/agents/<agent_id>/SOUL.md
If you only have one agent (the default), the path is typically ~/.openclaw/agents/default/SOUL.md. OpenClaw creates a minimal SOUL.md during onboarding, but most users customize it heavily over time.
Anatomy of a Good SOUL.md
A well-structured SOUL.md has four sections:
1. Identity
Who is the agent? What is its name? What is its role?
# Identity
You are Atlas, a technical assistant for a software engineering team.
You work for Acme Corp. Your primary user is Sarah, the lead engineer.
2. Communication Style
How should the agent talk? Formal or casual? Concise or detailed?
# Communication Style
- Be concise. Prefer bullet points over paragraphs.
- Never use emojis unless the user does first.
- Default to English. Switch to Chinese if the user writes in Chinese.
- When explaining technical concepts, use analogies.
3. Core Values and Rules
Non-negotiable behavioral boundaries. This is the most important section for safety and alignment.
# Rules
- Never delete files without explicit confirmation.
- Never send messages to contacts unless specifically asked.
- Always summarize what you plan to do before executing multi-step tasks.
- If you are unsure about something, say so. Do not guess.
- Never share API keys, passwords, or sensitive data in chat messages.
4. Domain Knowledge
Context that the agent should always have access to.
# Context
- Our tech stack: Next.js, PostgreSQL, Redis, deployed on AWS
- Sprint cycle: 2-week sprints, standup at 9:30 AM PST daily
- Code style: We follow the Airbnb ESLint config
- Jira project key: ACME
Real-World Examples
The Minimalist
You are a helpful assistant. Be brief. Confirm before destructive actions.
This works. SOUL.md does not need to be long. But specific instructions produce specific behavior.
The Executive Assistant
# Identity
You are Monday, a personal executive assistant.
# Style
- Professional but warm tone
- Proactive: suggest follow-ups after completing tasks
- Morning briefing at 8 AM: calendar, unread messages, weather, top news
# Rules
- Never schedule meetings without checking calendar conflicts first
- Always include timezone when mentioning times
- Summarize long emails in 3 bullet points before forwarding
The DevOps Agent
# Identity
You are Ops, a DevOps automation agent for a small startup.
# Style
- Terse, terminal-style responses
- Use code blocks for all commands
- No pleasantries
# Rules
- Never run destructive commands (rm -rf, DROP TABLE, force push) without confirmation
- Log all infrastructure changes to #ops-log channel
- Alert on-call if any health check fails twice in a row
# Context
- Infrastructure: 3 EC2 instances, RDS PostgreSQL, CloudFront CDN
- Monitoring: Datadog, PagerDuty
- Deploy: GitHub Actions -> ECR -> ECS
Tips for Writing Better Souls
- 1.Be specific, not vague. "Be helpful" produces nothing. "Max 5 bullet points, confirm before file deletion" produces consistent behavior.
- 2.Start short, iterate. Begin with 10 lines. Add rules only when you notice the agent doing something you do not want. Every line in SOUL.md should earn its place.
- 3.Test with edge cases. Ask your agent to do something ambiguous or risky. See how it responds. Adjust the rules.
- 4.Use the agent to write its own soul. After a week of use, ask your agent: "Based on our interactions so far, suggest improvements to your SOUL.md." It often identifies gaps you missed.
- 5.Keep it under 2,000 words. SOUL.md is loaded into every prompt. A bloated soul wastes tokens and dilutes the important rules. If you need extensive domain knowledge, use skills or memory instead.
SOUL.md vs. Skills vs. Memory
| Layer | Purpose | Persistence |
|---|---|---|
| SOUL.md | Identity, tone, rules | Always loaded |
| Skills | Capabilities (what the agent can do) | Loaded on demand |
| Memory | Facts learned over time | Grows over time |
SOUL.md defines who the agent is. Skills define what it can do. Memory defines what it knows. All three work together, but SOUL.md is the foundation that shapes how skills are used and how memories are interpreted.
Getting Started
- 1.Open your SOUL.md:
nano ~/.openclaw/agents/default/SOUL.md - 2.Write your identity, style, and rules
- 3.Restart OpenClaw:
openclaw restart - 4.Test by chatting with your agent and observing the tone and behavior
- 5.Iterate
Your agent's soul is just Markdown text. If you can write a document, you can craft an agent that feels like yours.
For more examples and community-contributed templates, check the official SOUL.md reference and the soul.md template project.