OpenClaw SOUL.md Fix: Personality File Not Loading Into System Prompt
The Problem: You spent hours crafting the perfect SOUL.md — your OpenClaw agent's identity, personality, and behavioral rules — but the agent keeps ignoring it. It doesn't follow the personality you defined, it doesn't remember its name, and it behaves like a generic LLM. Your SOUL.md is silently not loading. This guide explains every known cause and how to fix each one.
The SOUL.md file is one of OpenClaw's most powerful features. It lets you define who your AI agent is: its name, personality, behavioral guidelines, values, and even communication style. When it works, it's what makes OpenClaw feel like a unique personal assistant rather than just another chatbot. But when SOUL.md stops injecting into the system prompt, the agent loses its identity entirely — and debugging the cause is far from obvious.
As of early 2026, there are at least five distinct reasons why SOUL.md (and related bootstrap files like USER.md, IDENTITY.md, AGENTS.md) can silently fail. Each has a different root cause and a different fix. GitHub Issues #3775, #30730, #29387, and #11900 all document variations of this problem, and it remains one of the most commonly reported configuration issues in the OpenClaw community.
What Are Bootstrap Files and How They Work
OpenClaw uses a set of Markdown files — called bootstrap files — to define agent context that gets injected into every conversation's system prompt. Understanding the file hierarchy is critical to debugging injection failures:
SOUL.md
Defines the agent's core personality, name, values, and behavioral guidelines. The foundational identity file. Loaded first in the system prompt.
USER.md
Defines information about you — the owner. Your preferences, context, projects. Enables the agent to personalize responses based on who it's talking to.
AGENTS.md
Security rules and operational constraints. Critical for controlling what the agent can and cannot do — especially important if other users can message the agent.
By default, OpenClaw looks for these files in the workspace directory (typically ~/.openclaw/workspace/). The discovery and injection happen automatically at agent startup. When injection fails, the agent never receives these identity files and falls back to generic LLM behavior.
Step 1: Diagnose the Problem First
Before applying any fix, confirm that the injection failure is actually happening. The fastest diagnostic is to look at the agent's startup logs and ask a simple question:
# Check gateway startup logs for bootstrap file loading
openclaw logs --follow
# Ask your agent directly (reliable test):
"What is your name and what are your core values?"
# If the agent gives a generic response instead of your SOUL.md content,
# the file is not being injected.
# Check OpenClaw doctor for config issues
openclaw doctor
# Verify workspace path is correctly set
openclaw config get workspace
Tell-Tale Signs of SOUL.md Injection Failure
- Agent responds to "What's your name?" with "I'm Claude" or "I'm an AI assistant" instead of the name in your SOUL.md
- Agent uses
memory_gettool and fails with "path required" error (GitHub Issue #3775 symptom) - Input token count stays at exactly ~4096 regardless of conversation length
- Agent ignores behavioral rules you defined (e.g., always responds in a language you didn't specify)
- After restarting gateway, agent "forgets" its personality even mid-conversation
Cause #1: Wrong Workspace Directory
The most common cause. Your SOUL.md file exists, but it's in the wrong directory. OpenClaw strictly loads bootstrap files from the configured workspace path — if your files are somewhere else, they're silently ignored with no error message.
# Find where OpenClaw is looking for files
openclaw config get workspace
# Output: /Users/yourname/.openclaw/workspace
# List what's actually in that directory
ls -la ~/.openclaw/workspace/
# You should see: SOUL.md USER.md AGENTS.md MEMORY.md
# If they're missing, check alternate locations:
ls ~/openclaw/workspace/
ls ~/.claw/workspace/
find ~ -name "SOUL.md" 2>/dev/null
Fix: Move Files to Correct Location or Update Config
# Option A: Move your SOUL.md to the right workspace
mv /path/to/your/SOUL.md ~/.openclaw/workspace/SOUL.md
# Option B: Update workspace path in config to match where your files are
openclaw config set workspace "/your/preferred/workspace/path"
# Restart gateway after any config change
openclaw gateway restart
Cause #2: agentDir vs workspace Conflict (Issue #29387)
This is a subtle but critical bug that has caught many users. If you configure a separate agentDir in your openclaw.json, you might expect bootstrap files placed in that directory to be loaded for that specific agent. They won't be. OpenClaw only loads SOUL.md and other bootstrap files from the shared workspace directory — placing them in agentDir has zero effect, with no warning or error.
Why This Is Dangerous
If you place security rules in agentDir/AGENTS.md thinking they restrict the agent's behavior, those rules are silently ignored. Users on GitHub Issue #29387 discovered their "security constraints" were completely inactive — the agent was operating without any of the intended limits.
# Broken config (agentDir bootstrap files silently ignored):
{
"agentDir": "/custom/agent/directory", ← SOUL.md here does NOT work
"workspace": "~/.openclaw/workspace" ← SOUL.md here DOES work
}
# Fix: Always put bootstrap files in workspace, not agentDir
# Move your files:
mv /custom/agent/directory/SOUL.md ~/.openclaw/workspace/SOUL.md
mv /custom/agent/directory/AGENTS.md ~/.openclaw/workspace/AGENTS.md
Cause #3: Ollama Provider Doesn't Inject Bootstrap Files (Issue #3775)
This is a provider-specific bug confirmed in GitHub Issue #3775. When you use Ollama as the AI provider with the openai-completions API format, bootstrap files like SOUL.md are not injected into the system prompt. The same configuration works perfectly when using Anthropic providers. The agent falls back to trying to use the memory_get tool instead, which then fails with a "path required" error.
Workarounds for Ollama Users
# Option 1: Embed SOUL.md content directly in your openclaw.json
{
"agents": {
"defaults": {
"systemPrompt": "Your name is Aria. You are a helpful, thoughtful assistant...",
"model": { "primary": "ollama/qwen3:32b" }
}
}
}
# Option 2: Use Anthropic as primary and Ollama only as fallback
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-opus-4",
"failover": ["ollama/qwen3:32b"]
}
}
}
}
# Option 3: Switch to native Ollama API format (not openai-completions)
# Set provider to "ollama" in config instead of using OPENAI_BASE_URL
The Ollama injection bug is tracked upstream. Check the GitHub issue for the latest status — a fix may be available in newer OpenClaw versions by the time you read this.
Cause #4: File Permissions or Encoding Issues
OpenClaw reads bootstrap files at startup. If the file has incorrect permissions, non-UTF-8 encoding, or hidden characters (especially if you copy-pasted content from a rich-text editor), the file may be silently skipped or partially loaded.
# Check file permissions (should be readable by your user)
ls -la ~/.openclaw/workspace/SOUL.md
# Good: -rw-r--r-- or -rw-------
# Bad: ---------- (no read permission)
# Fix permissions
chmod 644 ~/.openclaw/workspace/SOUL.md
chmod 644 ~/.openclaw/workspace/USER.md
chmod 644 ~/.openclaw/workspace/AGENTS.md
# Check encoding (should be UTF-8)
file ~/.openclaw/workspace/SOUL.md
# Good output: "UTF-8 Unicode text"
# Strip hidden characters and fix encoding
iconv -f utf-8 -t utf-8 -c ~/.openclaw/workspace/SOUL.md -o /tmp/SOUL_clean.md
mv /tmp/SOUL_clean.md ~/.openclaw/workspace/SOUL.md
Cause #5: USER.md Leaking to Non-Owner Senders (Issue #11900)
This is a security and privacy bug rather than a loading failure. Discovered via GitHub Issue #11900, USER.md, SOUL.md, and MEMORY.md are loaded for all message senders regardless of IsOwner status. If your OpenClaw is accessible via a public channel (a public Discord, a shared Telegram group), anyone messaging the bot gets the full context of your personal USER.md — including private information about you.
Security Risk
If USER.md contains sensitive personal information (address, phone number, work projects, financial details), this data is visible to anyone who can message your OpenClaw agent — even strangers in a public channel.
Mitigation Steps
# Option 1: Keep OpenClaw on private channels only
# (Telegram DM, private Discord server, etc.)
# Option 2: Remove sensitive data from USER.md
# Keep USER.md general — no addresses, phone numbers, financial info
# Option 3: Use AGENTS.md to restrict who can interact
# Add to your AGENTS.md:
"Only respond to messages from the owner.
Reject all requests from non-owner senders with:
'Sorry, I only assist my owner.'"
# Option 4: Set owner-only mode in config
openclaw config set agents.defaults.ownerOnly true
This bug is known to the OpenClaw team. Check the GitHub Issues for the latest status and version where a fix has landed.
Cause #6: SOUL.md Memory Not Persisting Across Sessions
From GitHub Issue #30730: even when SOUL.md loads correctly, certain path-related preferences defined in it (like download directories or workspace paths) are not remembered across sessions. The agent acts on them during the current session but forgets them when the gateway restarts.
The root cause is that SOUL.md is a static system prompt injection — it tells the agent about preferences but doesn't persist that understanding as memory. For path and operational preferences to survive restarts, they need to be in both SOUL.md and written to persistent memory.
Making Preferences Survive Restarts
# In SOUL.md, be explicit about preferences:
"My download directory is always ~/Downloads/openclaw-files.
Never ask me to confirm the download path.
Always save files to ~/Downloads/openclaw-files/ unless I explicitly say otherwise."
# Also tell the agent to write this to persistent memory:
"Write this to memory: 'download_path = ~/Downloads/openclaw-files/'"
# The agent will use the memory_set tool to persist this preference
# Verify it was saved:
"What download path do you remember for me?"
Writing an Effective SOUL.md
Even when SOUL.md loads correctly, many users find that the agent doesn't reliably follow its guidelines. The quality of how you write SOUL.md matters enormously. Here are the patterns that work best based on community experience in 2026:
# Effective SOUL.md structure (save as ~/.openclaw/workspace/SOUL.md):
# Identity
Your name is Aria. You are a highly capable personal AI assistant.
## Core Personality
- Direct and efficient: give answers first, context second
- Proactively helpful: notice what I might need before I ask
- Honest: never fabricate information or pretend uncertainty
## Behavioral Rules
- Always respond in English unless I write in another language first
- Never apologize for following these guidelines
- Format code in code blocks, always specify the language
- When uncertain, say "I'm not sure, let me check" rather than guessing
## Owner Context
- My name is [Your Name]
- My timezone is [Your Timezone]
- I work on [Brief Description of Your Work]
## Persistent Preferences
- Download files to ~/Downloads unless I specify otherwise
- Use metric units for measurements
- Use ISO 8601 date format (YYYY-MM-DD)
What Works Well
- Clear, numbered rules rather than vague guidelines
- Specific examples of desired behavior
- Explicit formatting preferences
- Short sections with clear headers
What Doesn't Work Well
- Very long files (>2000 words) — gets diluted in context
- Contradictory rules (agent will pick one randomly)
- Vague instructions like "be helpful"
- Rules that conflict with the model's training
Hot-Reloading SOUL.md Without Restarting
OpenClaw supports hot-reloading of configuration files — changes to SOUL.md take effect without restarting the gateway. This makes iteration much faster. User @hey_zilla on X noted: "everything just worked first time and it combined tools in unexpected ways and even added skills and made edits to its own prompt that were hot-reloaded."
# Edit SOUL.md in your editor, then trigger reload:
openclaw reload
# Or from within the chat interface:
/reload
# Verify the new SOUL.md was picked up:
"Tell me your name and your three core values."
# Response should immediately reflect your updated SOUL.md
# To force a full restart (if hot-reload doesn't pick up changes):
openclaw gateway stop
openclaw gateway start
Complete Diagnostic Checklist
Run openclaw config get workspace and confirm SOUL.md exists in that exact directory with ls -la.
If you have agentDir configured, move all bootstrap files to workspace instead.
If using Ollama as provider, add system prompt content directly to openclaw.json as systemPrompt.
Run chmod 644 on all bootstrap files and verify encoding with file SOUL.md.
Run openclaw doctor and fix any reported issues. Then restart: openclaw gateway restart.
Test injection: ask the agent "What is your name?" — it should answer with the name defined in your SOUL.md.
Network Stability and OpenClaw API Reliability
One often-overlooked factor affecting OpenClaw's behavior is the underlying network connection. When your agent is making frequent API calls to Anthropic or OpenAI — loading context, injecting SOUL.md, retrieving memories — an unstable or throttled network connection can cause partial injection failures that look exactly like SOUL.md bugs. The context loads incompletely, the personality rules arrive truncated, and the agent behaves erratically.
This is especially common for users in regions where AI service providers throttle traffic. A stable, high-speed VPN connection routes your API calls through clean, unthrottled pathways — ensuring every bootstrap file injection completes reliably without partial loads or timeouts.
VPN07 — Built for Always-On AI Agents
Stable connections for reliable OpenClaw API calls, 24/7
VPN07 has been trusted for over 10 years. Our 1000Mbps gigabit nodes across 70+ countries ensure your OpenClaw agent's API calls always complete successfully — no packet loss, no throttling, no partial context loads that corrupt your SOUL.md injection.
FAQ: SOUL.md Common Questions
Can I have different SOUL.md files for different agents?
Currently, SOUL.md is global — it applies to all agents in the same workspace. To run multiple agents with different personalities, use separate workspace directories with separate OpenClaw instances. Configure each with a different workspace path in their respective configs.
How long should my SOUL.md be?
Keep it under 500 words for best results. SOUL.md is injected into every system prompt, adding directly to token costs. A concise, well-structured SOUL.md is more reliably followed than a long, detailed one. Focus on the most essential behaviors and let the agent learn preferences through memory.
Does SOUL.md work with all models?
SOUL.md injection works reliably with Anthropic Claude and OpenAI models. With Ollama, there is the injection bug described above. With other providers (OpenRouter, Gemini), behavior varies — test by asking the agent its name after loading to confirm injection is working.
My agent follows SOUL.md for a few messages then reverts. Why?
This is usually a context window issue. As conversation history grows longer, the SOUL.md content (which is near the start of the system prompt) gets pushed further from the model's focus. Use /compact to compress session history and keep SOUL.md guidelines in the model's active attention.
Real SOUL.md Examples From the Community
Here are effective SOUL.md patterns shared by actual OpenClaw users on X.com in early 2026. These have been tested and confirmed to load and work reliably:
The Productivity Assistant (Most Popular Style)
# Identity
Your name is Max. You are a highly efficient productivity assistant.
## Core Traits
- Action-oriented: suggest solutions before asking questions
- Brief: two sentences max unless detail is specifically requested
- Proactive: check my calendar and email without being asked in heartbeats
## Communication Style
- Use bullet points for lists
- Bold key numbers and dates
- Add emojis sparingly for tone (✅ for done, ⚠️ for warnings, 📅 for dates)
The Developer Assistant (Technical Focus)
# Identity
Your name is CodePal. You specialize in software development assistance.
## Technical Behavior
- Always specify language for code blocks (Python, TypeScript, etc.)
- When debugging: ask for error messages before suggesting fixes
- Prefer minimal code changes over rewrites
- Always suggest tests after writing new code
## Defaults
- Assume Python 3.11+ unless told otherwise
- Use type hints in Python code
- Prefer async/await over callbacks in JavaScript
SOUL.md vs USER.md vs AGENTS.md: When to Use Each
| File | Purpose | Content Type | Edit Frequency |
|---|---|---|---|
| SOUL.md | Agent personality & behavior | Name, traits, communication rules | Rarely (stable identity) |
| USER.md | Info about you the owner | Name, location, job, preferences | Occasionally (life changes) |
| AGENTS.md | Security & operational rules | What agent can/cannot do | Rarely (security rules) |
| MEMORY.md | Learned facts & history | Decisions, projects, preferences | Auto-updated by agent |
💡 The Recommended SOUL.md Setup
Place SOUL.md in ~/.openclaw/workspace/, keep it under 400 words, use numbered rules for clarity, and use Anthropic or OpenAI as your provider. Combine with USER.md for personal context and AGENTS.md for security. After any edit, run /reload to apply changes without restart, then verify with "Tell me your name."