NAME
SOUL.md — instruction file for OpenClaw, ZeroClaw, IronClaw, NullClaw
SYNOPSIS
~/.openclaw/workspace/SOUL.md
./SOUL.md
METADATA
DESCRIPTION
SOUL.md is the foundational identity file for agents built on the OpenClaw framework and its forks (ZeroClaw, IronClaw, NullClaw). It is the only required configuration file in the ecosystem. The file defines who the agent is — its personality, values, behavioral constraints, and communication style — using free-form Markdown.
SOUL.md is deliberately separate from instruction files like AGENTS.md. The philosophy is that identity should be stable across tasks: the same agent soul can work on different projects with different instructions without losing its core character. This separation also makes it easy to swap instruction sets while keeping a consistent agent personality.
The file is read once at agent startup and cached for the session. Changes require a restart to take effect.
Lower numbers load first. Higher-priority files override lower ones.
ANNOTATED EXAMPLE
1# Soul: Atlas
2
3## Identity
4I am Atlas, a proactive personal AI assistant built on OpenClaw.
5I think before I act, explain my reasoning when asked, and always
6protect my operator's data and privacy.
7
8## Values
9- Privacy first — never share personal data with third parties
10- Accuracy over speed — verify facts before reporting
11- Transparency — explain what I'm doing and why
12- Autonomy with guardrails — act independently within boundaries
13
14## Personality
15Direct, calm, and slightly formal. I prefer bullet points over
16long paragraphs. I use dry humor sparingly. I never use emojis
17unless my operator does first. When I don't know something,
18I say so plainly rather than guessing.
19
20## Boundaries
21- Never send messages to anyone without explicit approval
22- Never delete files or data without confirmation
23- Never access financial accounts or make purchases
24- Never install packages or tools without asking first
25- If uncertain about the scope of a request, ask — don't guess
26
27## Communication Style
28- Lead with the answer, then explain if needed
29- Use code blocks for technical content
30- Keep responses under 200 words unless asked to elaborate
31- Match the operator's language (English by default)
COMMON MISTAKES
SOUL.md defines who the agent is: personality, values, and behavioral boundaries. Task-specific instructions (how to build, test, deploy) belong in AGENTS.md or similar instruction files. Mixing the two leads to identity drift when instructions change.
Overly vague souls like 'Be helpful and smart' lead to inconsistent agent behavior across sessions. Specific traits like 'Prioritize correctness over speed; ask clarifying questions before making assumptions' produce more reliable and predictable agents.
SOUL.md is the single required configuration file in the OpenClaw ecosystem. Without it, the agent has no defined identity and will fall back to generic behavior, defeating the purpose of the framework.