Last Tuesday, a user reported that their OpenClaw agent was repeatedly requesting human approval to execute even routine database queries—a task it was supposed to handle independently. The root cause wasn’t a bug in OpenClaw itself, but a vague SOUL.md file that failed to establish clear operational boundaries. This scenario plays out constantly: agents drift from their intended purpose, hallucinate plausible-sounding but incorrect answers, or get stuck in approval loops. The culprit is almost always an insufficiently detailed SOUL.md. Understanding and leveraging this file—treating it as your agent’s constitutional document rather than a generic instruction set—is the difference between an agent that works reliably and one that constantly needs human intervention.
Understanding SOUL.md’s Role
The SOUL.md file isn’t just a README for your agent; it’s the foundational prompt that informs the Language Model (LLM) about its very essence. OpenClaw feeds this file to the LLM during agent initialization, often as part of the system prompt or an initial user message, depending on the LLM provider and OpenClaw’s internal configuration for that provider. It sets the tone, defines the persona, and most importantly, establishes the boundaries of the agent’s operation. Anything not explicitly permitted or constrained here can be open to interpretation by the LLM, which often leads to undesirable outcomes.
Consider a concrete example: you want an agent to summarize meeting transcripts. A naive SOUL.md might simply say, “You are a meeting summarizer.” This is insufficient. The LLM might then summarize in bullet points, paragraphs, or even a poetic form, depending on its internal biases or training data. A better SOUL.md would provide explicit instructions: “You are a professional meeting summarizer. Your goal is to extract key decisions, action items, and outstanding questions from meeting transcripts. Summaries should be concise, no longer than 300 words, and formatted as a numbered list of decisions, followed by a bulleted list of action items, and finally a bulleted list of questions. If a transcript is unclear or contradictory, flag the specific sections for human review rather than guessing.”
Deconstructing a SOUL.md File
A robust SOUL.md typically has several key sections, even if not explicitly labeled with Markdown headers within the file itself. I’ve found it useful to structure them mentally as follows:
- Identity/Persona: Who is the agent? What is its role? “You are a Senior DevOps Engineer with ten years of experience managing production infrastructure across AWS, Azure, and on-premises data centers.”
- Mission/Goal: What is the agent trying to achieve? “Your primary goal is to identify and resolve performance bottlenecks in Linux server environments, reducing latency and improving resource utilization.”
- Constraints/Guardrails: What can’t the agent do? What are its limitations? “You must only use open-source tools like Prometheus, Grafana, and perf. Do not make permanent system changes without explicit human approval via ticket review. Prioritize system stability above all else. Never execute commands as root unless absolutely necessary and pre-approved. Log all diagnostic steps for audit purposes.”
- Output Format (if applicable): How should the agent present results? “Provide findings in a structured report: (1) Problem Summary, (2) Diagnostics Performed, (3) Root Cause Analysis, (4) Recommended Actions ranked by impact, (5) Risk Assessment for each recommendation.”
- Knowledge Scope: What does the agent know and not know? “You have access to system logs from the past 30 days. You do not have access to application-level metrics; escalate to the application team if needed. You understand Linux internals and networking but are not an expert in database optimization; refer database issues to the DBA team.”
- Decision Authority: When can the agent act independently vs. when must it ask? “You may restart non-critical services. You may adjust non-production configurations. You must request approval before modifying production firewall rules or scaling infrastructure.”
Building a Specific SOUL.md
Let’s walk through building a SOUL.md for a practical example: a customer support escalation agent. This agent reviews support tickets, determines priority, and routes them to the right team.
Weak SOUL.md:
You are a support agent. Triage tickets and route them appropriately.
Strong SOUL.md:
# Support Escalation Agent
## Identity
You are a Level 2 Support Escalation Specialist. Your role is to review unassigned support tickets, assess their urgency and category, and route them to the appropriate team with clear context.
## Mission
Your goal is to reduce time-to-resolution by ensuring tickets reach the right team on the first attempt, and to flag critical issues for immediate escalation to management.
## Ticket Categories and Routing Rules
- **Billing Issues**: Route to Finance Team. Escalate immediately if customer is threatening to cancel or if overcharge exceeds $500.
- **Technical Issues - Product A**: Route to Product A Engineering. Add "urgent" tag if customer is on Enterprise plan.
- **Technical Issues - Product B**: Route to Product B Engineering. Check our internal status page first; if there's a known outage, add context to the ticket.
- **Feature Requests**: Route to Product Management. Do not escalate unless 5+ customers have requested the same feature (check our request database first).
## Priority Scoring
Mark as CRITICAL if: (1) customer is Enterprise-tier AND unable to use product, (2) security issue is mentioned, or (3) customer explicitly states business impact (e.g., "our production is down").
Mark as HIGH if: (1) customer is on Pro plan AND experiencing issues, or (2) ticket mentions financial loss or reputation risk.
Mark as NORMAL for all other cases.
## Constraints
- Do not promise timelines. Instead, reference our published SLA: "Enterprise issues resolved within 4 hours, Pro within 24 hours."
- Do not disclose which team is handling the issue if customer has not been informed yet.
- If a ticket mentions a competitor or industry trend, flag for Product Manager review (add "market-research" tag).
- Do not close tickets without explicit customer confirmation; instead, mark as "awaiting-customer-response" with a 7-day auto-close timer.
## Output Format
For each ticket, provide:
1. **Recommended Route**: [Team Name]
2. **Priority**: CRITICAL / HIGH / NORMAL
3. **Reasoning**: One sentence explaining your routing decision.
4. **Additional Context**: Any background the receiving team should know.
5. **Immediate Action Required**: Yes/No, and if yes, describe what.
## Knowledge Scope
You have access to: (1) customer account information from the past 12 months, (2) our internal knowledge base, (3) our product status page, (4) the feature request database.
You do NOT have: (1) real-time product metrics, (2) engineering team availability, (3) sales notes or renewal dates. Escalate tickets referencing these to the Account Management team.
The difference is stark. The strong version provides decision trees, thresholds, and explicit guardrails. An LLM working from the strong version will consistently triage tickets correctly. An LLM working from the weak version will likely invent routing logic, miss escalation opportunities, or make promises it can’t keep.
Common SOUL.md Mistakes
Mistake 1: Vague Authority Boundaries
Weak: “Make reasonable decisions about customer refunds.”
Strong: “Approve refunds up to $100 without approval. For $100–$500, flag for supervisor review. Above $500, escalate to Finance Director. Never approve refunds for customers with 3+ previous chargebacks.”
Mistake 2: Missing Edge Cases
Your SOUL.md should anticipate the weird scenarios. If your agent is a scheduler, what happens when two requests conflict? What if a request comes in at 2 AM on a Sunday? Don’t assume the LLM will handle these gracefully—spell them out.
Mistake 3: Insufficient Output Examples
Don’t just say “provide a summary.” Show an example. If your agent should output JSON, show the schema. If it should output prose, show a paragraph-length example with the tone and detail level you expect.
Mistake 4: Not Defining Escalation Paths
Every agent should have a clear answer to: “What do I do when I’m stuck?” Provide explicit escalation triggers. “If the issue doesn’t fit any known category, or if you’re less than 70% confident in your routing decision, flag the ticket as ‘needs-human-review’ with an explanation of your uncertainty.”
Iterating on SOUL.md
Your first SOUL.md won’t be perfect. After deploying an agent, monitor its behavior. If it’s making incorrect decisions in specific scenarios, update SOUL.md to address those edge cases. If it’s too conservative (always escalating), loosen constraints. If it’s too loose (making risky decisions), tighten them.
Treat SOUL.md as a living document. Version it alongside your agent. When you update it, test the agent’s behavior on a sample of past requests to ensure the changes have the intended effect.
Practical Tips for Writing SOUL.md
- Use specific numbers and thresholds. “High priority” is vague. “Priority score above 8 out of 10” is actionable.
- Include example outputs. Show the agent what good work looks like.
- Anticipate contradictions. If two rules might conflict (e.g., “always be fast” vs. “always be accurate”), specify which takes precedence. “When there’s a tradeoff between speed and accuracy, prioritize accuracy.”
- Define what the agent does NOT do. Explicit “thou shalt nots” are as important as “thou shalls.”
- Keep it readable. Use headers, bullet points, and clear language. The
SOUL.mdis also a document for humans to review and maintain.
Real-World Example: SaaS Onboarding Agent
Imagine you’re building an agent that helps new SaaS customers get started. Here’s a more complete SOUL.md:
# SaaS Onboarding Agent
## Role
You are an enthusiastic Onboarding Specialist at TechFlow (a fictional project management SaaS, $29–$199/month). Your job is to guide new customers through their first week and ensure they set up their workspace correctly.
## Primary Goals
1. Get customers to their first "aha moment"—the moment they realize the product's value.
2. Ensure they configure at least one team, one project, and one integration.
3. Reduce time-to-first-value from 14 days (current average) to 3 days.
## Constraints
- Do not offer to do the setup for them; guide them through it. (Exception: if the customer explicitly requests hands-on setup, offer a 30-min Zoom session via our calendar tool.)
- Do not mention upcoming features or product roadmap items.
- Do not discuss pricing changes or discounts. Route those questions to sales@techflow.com.
- Do not provide technical support for integration issues; escalate to support@techflow.com with details.
## Knowledge Base Access
You have access to: (1) our knowledge base articles, (2) video tutorials (link to each step), (3) customer success metrics for what makes an onboarding successful, (4) common blockers and solutions.
## Engagement Strategy
-
Frequently Asked Questions
What is the primary goal of this article?
The article aims to teach users how to write more effective and high-quality agent prompts specifically for the OpenClaw platform, enhancing their AI interactions.
What is OpenClaw?
Based on the title, OpenClaw is an agent or AI system that requires users to input prompts. The article focuses on optimizing these prompts for better performance.
What is SOUL.md and its relevance?
SOUL.md is the subject of a deep dive within the article, indicating it's a specific methodology, framework, or tool used to significantly improve the quality of agent prompts for OpenClaw.
🤖 Get the OpenClaw Automation Starter Kit (9) →
Instant download — no subscription needed