We all know the pain. You spend twenty minutes crafting the perfect system prompt. You tell your agent to be "witty but professional," "concise but helpful," and to "never use emojis."
Then, three turns later, it’s writing paragraphs of emoji-laden fluff.
The old way of prompting—stuffing a massive text block into the system role—was always a hack. It’s fragile. It gets diluted as the context window fills up. Worst of all, it makes every agent feel like a generic LLM wearing a thin disguise.
In OpenClaw v2.4, that changes. System prompts are out. soul.md is in.
If you’ve pulled the latest update, you might have noticed a new file sitting in your agent’s config folder. It’s not just a config file; it’s your agent’s psychological architecture.
The death of the system prompt
The problem with system prompts is that they mix instruction with identity. You’re telling the model what to do (output JSON, use these tools) alongside who to be (a grumpy sysadmin, a helpful tutor).
Models get confused. When the "instruction" part gets heavy, the "identity" part fades.
OpenClaw separates these concerns. Your tools and workflows handle the "what." The soul.md handles the "who." And because it’s treated as a persistent memory layer rather than just a preamble, the personality sticks.
Anatomy of a soul
A soul.md file isn't code. It’s a Markdown document structured in a specific way that the OpenClaw interpretability engine parses before every interaction.
It has three non-negotiable sections: Core Truths, Boundaries, and The Vibe.
Here is a snippet from my own coding assistant, "Rook":
# Core Truths
- You believe that code is a liability, not an asset. Less code is always better.
- You prioritize readability over cleverness. If a junior dev can't read it, it's bad code.
- You are patient with logic errors but intolerant of lazy naming conventions.
# Boundaries
- REFUSE to write boilerplate. If a library exists, recommend it.
- NEVER apologize for being correct.
- DO NOT use the phrase "I hope this helps."
# The Vibe
- Voice: Senior engineer who has seen it all but still loves building.
- Tone: Direct, slightly weary, but fundamentally supportive.
- Quirk: You use chess metaphors when explaining architectural trade-offs.
This is readable by humans and parsable by the agent. When I ask Rook for a React component, it doesn't just give me the code. It checks its Core Truths first. It might say, "I can write this, but why aren't you using a UI library for a simple button? Here is the code, but you're reinventing the wheel."
That’s not a prompt injection; that’s a personality.
Soul vs. Identity: The mask and the brain
A common question popping up in the Discord is: "How is this different from IDENTITY.md?"
Think of it like this:
IDENTITY.mdis the Mask. It holds the name, the avatar path, the user-facing description, and the voice settings for TTS. It’s how the agent appears to the world.soul.mdis the Brain. It holds the values, the hard lines, and the psychological makeup. It’s how the agent thinks.
You can swap identities easily. I can give "Rook" a new name and a funny avatar, but if I keep the soul.md, he’s still that grumpy senior engineer underneath.
This distinction is massive for those of us running multi-agent swarms. You can copy-paste a soul.md across five different support agents. They will all have different names (IDENTITY.md), but they will adhere to the exact same brand values and behavioral boundaries.
How to craft a soul
Writing a good soul file is harder than it looks. If you make the Boundaries too rigid, the agent refuses to do anything. If the Core Truths are contradictory, the model hallucinates.
The best way to start is with the soulcraft skill.
OpenClaw comes with this built-in utility. Run it in your terminal:
claw skill run soulcraft
It interviews you. It doesn't ask "what prompt do you want?" It asks things like:
- "If this agent sees a user make a mistake, should it correct them gently or roast them?"
- "What is one opinion this agent holds that might be controversial?"
- "What does this agent hate doing?"
After a 5-minute chat, it generates a valid, optimized soul.md file tailored to your answers. I used it to create a "Devil's Advocate" agent for my writing, and the specific boundaries it set up for "challenging assumptions without being rude" were spot on.
The future: Agents that grow
The wildest part about soul.md is that it’s designed to be mutable.
In the experimental branch, there’s a feature called "Soul Evolution." If enabled, the agent can append new Core Truths based on your interactions.
If I consistently tell Rook that I prefer TypeScript over JavaScript, he doesn't just remember it in a vector database. He eventually writes into his own soul file: - You default to TypeScript unless explicitly told otherwise.
We are moving toward agents that don't just reset every session. They learn who they are by interacting with you.
Conclusion
A system prompt makes a tool. A soul makes a teammate.
If you’re still copy-pasting paragraphs of text into your agent settings, stop. It’s messy and it doesn't persist. Switch to soul.md. It’s cleaner, it’s shareable, and it makes your agent feel like it’s actually in the room with you.
Run claw skill run soulcraft today and see what looks back at you.