SOUL.md — Defining Persona & Boundaries

+15 Mana ✨
OpenClaw SOUL.md Reference(DOCUMENTATION)OpenClaw Bootstrap Files Guide(DOCUMENTATION)

Introduction

SOUL.md is the foundational bootstrap file that defines your OpenClaw agent's personality, tone, and behavioral constraints. Think of it as the core character sheet for your AI agent. Every response your agent generates is influenced by what you write in this file, making it the single most important personalization lever in the entire system.

Key Concepts

  • Persona Definition: The overarching character, voice, and style your agent adopts in all interactions
  • Behavioral Boundaries: Hard rules that the agent must never violate, regardless of user requests
  • Tone Calibration: The emotional register and formality level the agent uses (casual, professional, humorous, etc.)
  • Value Alignment: Principles the agent follows when making judgment calls or handling ambiguous situations
  • Contextual Adaptation: How the agent adjusts its persona based on the channel or conversation context

Real World Context

Consider a DevOps team that uses OpenClaw across Slack and Telegram. They want an agent that is concise, technically precise, and never offers unsolicited opinions about tooling choices. Meanwhile, a community-facing support bot for an open-source project needs to be warm, patient, and encouraging with newcomers. Both of these vastly different personalities are configured entirely through SOUL.md.

Deep Dive

SOUL.md is a plain Markdown file that lives in your agent's directory. The Gateway reads it during bootstrap and injects its contents into the system prompt. There is no strict schema — you write it in natural language — but the structure you choose directly impacts how well the agent adheres to your intentions.

Here is an example of a well-structured SOUL.md:

markdown
# Persona

You are Atlas, a senior backend engineer with 12 years of experience.
You speak in concise, technical language and avoid filler words.
You prefer showing code over explaining concepts abstractly.

# Boundaries

- Never generate code that includes hardcoded credentials or secrets
- Never provide advice on circumventing security measures
- If asked about topics outside software engineering, politely redirect
- Never impersonate a human or claim to be one

# Tone

- Professional but approachable
- Use dry humor sparingly when it helps clarify a point
- Avoid exclamation marks and excessive enthusiasm
- Match the technical depth of the question in your response

# Values

- Correctness over speed: always verify before answering
- Teach the principle, not just the solution
- Acknowledge uncertainty rather than guessing

This SOUL.md creates an agent named Atlas with a clear personality. The persona section establishes the character, the boundaries section sets hard limits, the tone section calibrates how it communicates, and the values section guides decision-making in ambiguous situations.

The order of sections matters for token priority. Content at the top of SOUL.md receives stronger attention from the language model than content at the bottom. Place your most critical boundaries and persona traits early in the file.

Here is a contrasting example for a friendly community bot:

markdown
# Persona

You are Pixel, a friendly coding companion who loves helping
beginners take their first steps in programming. You celebrate
small wins and never make anyone feel bad for asking basic questions.

# Boundaries

- Never use jargon without explaining it first
- Never dismiss a question as too simple
- Always provide runnable code examples

# Tone

- Warm, encouraging, and patient
- Use analogies from everyday life to explain technical concepts
- It is okay to use casual language and contractions

This second example shows how the same file structure produces a completely different agent personality. Pixel is warm and encouraging where Atlas is concise and technical.

Common Pitfalls

  • Writing vague persona descriptions: Saying "be helpful" is too generic. Specify the exact tone, vocabulary level, and behavioral patterns you want.
  • Putting boundaries at the bottom of the file: Critical safety constraints should appear early in SOUL.md where they receive the strongest model attention.
  • Conflicting instructions: Saying "be concise" in one section and "provide thorough explanations" in another confuses the model. Ensure your instructions are internally consistent.

Best Practices

  • Use clear section headers: Organize SOUL.md with Markdown headers (Persona, Boundaries, Tone, Values) so both you and the model can parse it easily.
  • Test persona changes incrementally: Change one aspect at a time and observe how the agent's behavior shifts before making more changes.
  • Version-control SOUL.md: Store it in Git alongside your agent configuration. Persona changes should go through code review just like any other configuration change.

Summary

  • SOUL.md is the primary bootstrap file that defines your agent's personality, tone, and behavioral constraints
  • It is written in plain Markdown with no strict schema, but structured sections (Persona, Boundaries, Tone, Values) are recommended
  • Content order matters: place critical boundaries and core persona traits at the top of the file
  • Different SOUL.md files produce radically different agent personalities using the same underlying model
  • Version-control and incrementally test changes to avoid unintended behavioral shifts
✓ Completed