OpenClaw Agent Not Following Config? How to Fix It
You updated your SOUL.md, restarted the agent, and it is still ignoring your rules. This guide covers the 6 most common reasons an OpenClaw agent does not follow its configuration — and exactly how to fix each one.
Quick Diagnostic Checklist
Before digging into causes, run through this checklist. Most config issues are resolved by one of these steps:
The 6 Most Common Causes (and Fixes)
Gateway not restarted after SOUL.md edit
Symptom: Agent behaves as before the change. Rules you added are not followed.
# Restart the gateway to reload all SOUL.md files
openclaw gateway restart
# Or stop and start
openclaw gateway stop
openclaw gateway startThis is the most common cause. OpenClaw loads SOUL.md at startup. Changes do not take effect until the gateway restarts.
Old session context overriding config
Symptom: Rules work in new conversations but not in existing ones. The agent 'remembers' behavior from before your changes.
# Find and delete session files
ls ~/.openclaw/agents/*/sessions/
# Delete sessions for the specific agent
rm ~/.openclaw/agents/your-agent-name/sessions/sessions.json
# Restart gateway
openclaw gateway restartConversation history is stored in session files. If the session was established before your rule change, old context can override new rules. Clear sessions after config changes.
Too many rules — model is skipping some
Symptom: Some rules are followed, others are ignored. Rules near the end of the list are more often skipped.
## Rules
# Bad: 25+ rules, model will miss some
- Always respond in English
- Use bullet points for lists
- Never mention competitors
- Always cite sources
- Limit responses to 300 words
- Use formal tone
- ... (20 more rules)
# Good: 10-12 prioritized rules
- Always respond in English
- Use bullet points for lists, headers for sections
- Never mention competitors by name
- Cite sources for factual claims (include URL)
- Keep responses under 300 words unless asked for detailTrim your Rules section to the 10-12 most critical constraints. Remove rules that are nice-to-have vs must-follow.
Model does not reliably follow complex instructions
Symptom: Rules are present and well-written, but the agent randomly ignores them.
## Identity
# Upgrade from cheap model to more reliable one
# Less reliable for instruction following:
- Model: gemini-1.5-flash-8b
- Model: llama3.1 # via Ollama
# More reliable:
- Model: claude-haiku-4-5
- Model: gpt-4o-mini
- Model: gemini-2.0-flashInstruction following varies significantly between models. Smaller/cheaper models trade reliability for cost. If your rules are important, use a model that follows them.
Conflicting rules
Symptom: Agent behaves unpredictably. Sometimes follows one rule, sometimes the conflicting one.
## Rules
# Bad: Conflicting rules
- Be concise and keep responses short
- Always provide a comprehensive explanation with examples
# Good: Clear hierarchy
- Keep responses concise (under 200 words) for simple questions
- For technical explanations, include a brief example
- If the user asks for more detail, provide a comprehensive responseWhen two rules contradict each other, the model picks one inconsistently. Review your rules for conflicts and add priority conditions.
SOUL.md syntax error or wrong section name
Symptom: Rules or skills are completely ignored. Agent has no personality or behaves generically.
# Correct SOUL.md section structure:
## Identity ← Must be exactly this
- Name: Radar
- Role: Research Analyst
- Model: claude-haiku-4-5
## Personality ← Must be exactly this
- Data-driven and precise
## Rules ← Must be exactly this
- Always cite sources
## Skills ← Must be exactly this
- browser: Search the web
## Channels ← Must be exactly this
- Telegram:
token: ${TELEGRAM_BOT_TOKEN}Section names must match exactly. '## Rule' (singular) or '## rules' (lowercase) will not be parsed correctly by OpenClaw.
Writing Rules That Actually Stick
Beyond fixing immediate issues, here is how to write SOUL.md rules that models follow reliably:
Be specific, not general
Vague
Be professional
Specific
Use formal language. Avoid slang and contractions. Address the user as 'you' not 'u'.
State the action, not the intent
Vague
Prioritize accuracy
Specific
If you are uncertain about a fact, say 'I am not certain, but...' before stating it.
Include the condition
Vague
Keep responses short
Specific
Keep responses under 200 words for simple questions. For technical explanations, use as many words as needed for clarity.
Put critical rules first
Vague
List rules randomly
Specific
Put your most important rules at positions 1-3. Models weight earlier rules more heavily than later ones.
The Easiest Fix: Use a Pre-Tested Template
Writing a SOUL.md that works reliably takes iteration. The rules need to be specific, conflict-free, appropriately ordered, and matched to the right model. If you are spending more time debugging config than using your agent, a pre-tested template is the faster path.
CrewClaw agent templates are built with rules that have been tested across real interactions. The model is pre-selected for the task type, the rules are ordered by priority, and edge cases are handled explicitly. You download, set your API key, and the agent works as expected without the troubleshooting cycle.
Related Guides
Frequently Asked Questions
Why does my OpenClaw agent ignore its SOUL.md rules?
The most common causes are: the model you are using does not reliably follow complex instructions (cheap models often skip rules), your SOUL.md has too many rules (models prioritize the first few and ignore the rest), there is a conflict between rules, or the agent is using a cached session that has not picked up your latest SOUL.md changes. Start by restarting the gateway and checking which model you are using.
Does restarting the OpenClaw gateway reload the SOUL.md?
Yes. Restarting the gateway forces a reload of all SOUL.md files. If you edited your config and the agent is still behaving the old way, restart with: openclaw gateway restart. Also clear the session file if the agent maintains conversation history, as old session context can override new config.
How many rules can I put in a SOUL.md before the model starts ignoring them?
There is no hard limit, but in practice models start to miss rules after around 15-20 bullet points in the Rules section. The model does not intentionally skip rules — it prioritizes based on proximity (rules earlier in the prompt carry more weight) and relevance to the current input. Keep your Rules section to 10-15 of the most important constraints.
My agent follows rules sometimes but not always. What is wrong?
Inconsistent rule-following is usually a model quality issue. Cheaper or smaller models (Gemini Flash, Llama 8B) are less reliable at following complex constraints consistently. Upgrade to Claude Haiku or GPT-4o Mini for more consistent instruction following. Also check if the rule is ambiguous — if the model has to interpret what you mean, it will sometimes interpret it differently.
How do I test whether my SOUL.md changes are being loaded?
Ask the agent directly: 'What is your name?' or 'What is your role?' If the agent describes its Identity section correctly, the SOUL.md is loaded. If it gives a generic response or an old name, the config has not been picked up. Restart the gateway and try again.
Skip the config headaches with pre-tested templates
CrewClaw templates come with rules that work out of the box. No trial and error, no debugging sessions — just download and deploy.
Deploy a Ready-Made AI Agent
Skip the setup. Pick a template and deploy in 60 seconds.