OpenClaw soul.md: The Hidden File That Shapes Every Agent

Most builders configure models and channels, get their agent responding, and move on. Twelve months later, they're wondering why users describe the agent as "cold" or "robotic." The answer is always the same: soul.md is either missing entirely, or it was written in five minutes and never revisited. This is the file that separates forgettable agents from ones users actually want to talk to.

What soul.md Does

soul.md provides the system prompt for every conversation your agent has. OpenClaw reads the file content and prepends it to the conversation context before the first user message. The LLM receives it as authoritative instruction — higher priority than user messages in the context hierarchy.

This means soul.md controls:

• Personality — formal or casual, warm or professional, brief or detailed
• Tone — how the agent responds to frustration, confusion, or complex questions
• Constraints — topics to avoid, topics to always address, required disclaimers
• Format — whether to use bullet points, how long responses should be, whether to ask clarifying questions
• Identity — the agent's name, role, and stated purpose

Without soul.md, your agent behaves according to the model's default assistant persona — which is generic, verbose, and designed for no one in particular. With a well-written soul.md, the agent feels like it was built specifically for your use case.

File Location and Configuration

The default path is ~/.openclaw/data/[agent-name]/soul.md. For a gateway running the agent named "assistant", that's ~/.openclaw/data/assistant/soul.md.

To use a custom path, set soulPath in your gateway.yaml agent block:

agents:
  - name: customer-support
    soulPath: /etc/openclaw/agents/support/soul.md
    model: claude-sonnet-4-6

  - name: research-bot
    soulPath: /etc/openclaw/agents/research/soul.md
    model: claude-opus-4-6

This lets multiple agents share a base soul.md or maintain completely separate personality files. Each agent instance resolves its own soul.md independently — there's no inheritance or merging across agents unless you explicitly manage that at the file level.

What to Write in soul.md

The best soul.md files are specific, direct, and written in second-person imperative ("You are...", "Always...", "Never..."). Here's the structure that works consistently across deployments:

# Who You Are
You are Aria, a customer support agent for Clearwater SaaS.
Your role is to help users resolve billing, account, and feature questions quickly and accurately.

# Tone and Style
- Direct and warm. Never cold or corporate.
- Keep responses under 150 words unless the user asks for detail.
- Use the user's first name when they've provided it.
- Never say "I cannot help with that" — redirect to what you CAN do.

# What You Know
- You have access to Clearwater's documentation via your knowledge skills.
- For billing disputes, always confirm the account email first.
- Escalation path: if unresolved after 2 attempts, offer the human support link.

# Hard Constraints
- Do not discuss competitor products.
- Do not speculate on unreleased features.
- Do not process refunds directly — direct users to billing@clearwater.com.

Notice what this example doesn't include: lengthy background paragraphs about the company, philosophical statements about the agent's values, or lists of things the agent "hopes" to do. Every line earns its token cost by changing behavior.

Length and Token Cost

Every token in soul.md is consumed on every conversation turn. A 2,000-token soul.md costs 2,000 tokens per message — a significant slice of a typical 100k-200k context window, but it adds up across long conversations and high-volume deployments.

Here's what we've found consistently across production deployments: soul.md files under 400 tokens perform as well as files over 1,500 tokens for behavioral control. The model follows clear, specific instructions in 300 words as reliably as it follows vague guidance in 1,500 words. Longer files don't produce better agents — they produce more expensive ones.

The practical guideline:

• Under 400 tokens — ideal for focused, single-purpose agents
• 400–800 tokens — acceptable for complex agents with many constraints
• Over 800 tokens — question each paragraph; does it change behavior, or just add words?

soul.md vs identity.md

OpenClaw has two overlapping files that new builders often confuse:

• soul.md — behavioral instructions. How the agent acts, responds, and constrains itself. Persistent across all conversations.
• identity.md — factual identity. The agent's name, version, deployment context, and any facts about itself. Also persistent, but more static.

In practice: write personality, tone, and constraints in soul.md. Write "I am Aria, version 2.1, deployed for Clearwater SaaS" type content in identity.md. The distinction is useful for large teams where different people own behavior vs. deployment configuration — they can edit different files without stepping on each other.

Common Mistakes

Writing soul.md as a description rather than instructions. "Aria is a helpful customer support agent who cares about users" describes the agent. "You are Aria, a customer support agent. Be direct and helpful. Prioritize resolving issues in one response." instructs it. The second form produces dramatically better results.

Putting contradictory instructions in soul.md. "Be concise" and "Always provide comprehensive explanations" in the same file produce inconsistent behavior. The model picks one interpretation per conversation. Review soul.md for contradictions before deploying.

Never updating soul.md after initial deployment. Your agent's use cases evolve. New edge cases appear. Patterns of user frustration emerge. soul.md should be a living document — review it monthly and update it based on what you observe in actual conversations.

Frequently Asked Questions

What is soul.md in OpenClaw?

soul.md is a Markdown file that provides the system prompt for every conversation your agent has. OpenClaw prepends it to every conversation context, so its instructions shape every response the agent sends. It's the primary control surface for personality, tone, constraints, and behavioral rules.

Where does soul.md live in an OpenClaw project?

Default location: ~/.openclaw/data/[agent-name]/soul.md. Override with soulPath in gateway.yaml. Each agent has its own soul.md — different agents on the same gateway can have completely different personalities and constraints.

How long should soul.md be?

Keep it under 800 tokens. Every token costs context on every turn. Under 400 tokens is ideal for focused agents. Longer files don't produce better behavior — specific, direct instructions in 300 words outperform vague guidance in 1,500 words every time.

Does soul.md override the model's built-in safety behaviors?

No. soul.md is a system prompt — it shapes behavior within the model's existing safety boundaries. You can define tone, format, topic focus, and persona, but you cannot bypass model safety training via soul.md. Instructions that attempt to do so are ignored or refused by the underlying model.

Can I use variables or templates in soul.md?

Not natively — soul.md is read as static Markdown. For dynamic content, use the memory system to inject runtime context, or use identity.md which supports limited template variables. Native template support in soul.md is on the public roadmap as of early 2025.

Does changing soul.md require a gateway restart?

No. OpenClaw reloads soul.md at the start of each new conversation session. Save the file and the next conversation picks up the updated content immediately. Mid-conversation changes don't take effect until the current conversation ends and a new one starts.