The prompt architecture
How OpenClaw prompts work
Most AI tools bury your prompt settings behind a dashboard. OpenClaw takes the opposite approach. Every instruction your agent follows lives in a markdown file you control. There are no hidden system prompts. What you write is what your agent reads.
Files, Not Forms
Your agent's instructions live in markdown files inside your workspace directory. Edit them with VS Code, Vim, Obsidian, or any text editor. Version-control them with Git. Share them with your team by pushing to a repo.
Layered Configuration
Each file controls a different aspect of agent behavior. SOUL.md sets the personality. AGENTS.md provides task instructions. IDENTITY.md defines who the agent is. They layer together to create a complete agent persona.
Instant Updates
Edit a file. Start a new conversation. Your changes are live. No deployment pipeline, no waiting for caches to clear, no restarting services. The agent reads fresh instructions at the start of every chat.
The core files
The 5 prompt files that matter
OpenClaw supports several prompt files, but these five do the heavy lifting. Master these and you control 90% of your agent's behavior.
Also available: BOOT.md runs once on first startup (great for initial setup tasks). BOOTSTRAP.md runs when initializing a new workspace. These are optional and most users do not need them when getting started.
Copy and customize
Ready-to-use templates
We've tested and refined these templates across hundreds of real workflows. Copy the snippet, paste it into your AGENTS.md, and customize the details for your business. Each template is designed to work with the bundled skills.
How to use these templates: Copy any snippet above and paste it into your AGENTS.md file. Customize the specifics (channel names, criteria, output formats) for your business. The agent will follow these instructions the next time you start a conversation.
Writing effective prompts
6 principles for better prompts
We've written thousands of prompt instructions across dozens of use cases. These six principles consistently produce the best results.
Be Specific, Not Vague
Vague instructions produce vague results. Instead of 'be helpful,' specify exactly what helpful means in your context. The more precise your instructions, the more consistent the agent's output.
Use Examples and Templates
Show the agent what good output looks like. Include example responses, formatted outputs, or template structures directly in your prompt files. Agents learn better from examples than from abstract descriptions.
Set Clear Boundaries
Tell the agent what NOT to do. Boundaries prevent costly mistakes. Define actions that require human approval, topics to avoid, and limits on what the agent can promise or commit to.
Define Output Formats
Specify how you want the output structured. Bullet points? JSON? Paragraphs? Table? When the agent knows the expected format, it delivers cleaner results with less back-and-forth.
Handle Edge Cases Explicitly
Think about what could go wrong. What if the data is missing? What if the email is spam? What if the request is outside scope? Adding error handling instructions prevents the agent from making bad decisions when things are not straightforward.
Iterate Based on Real Output
Your first prompt draft will not be perfect. Run it through real scenarios, review the output, and tighten the instructions where the agent drifts. The best prompts are refined over weeks, not written in one sitting.
Get started in the workshop
The workshop includes ready-to-use templates for your first workflow. In 15 minutes, you'll have OpenClaw installed, your prompt files configured, your first channel connected, and a working automation running.
Start the $19 WorkshopOrganization tips
Organizing prompts for real workflows
As you build more automations, your prompt files grow. Here is how we keep things organized across multiple workflows and team members.
One AGENTS File Per Role
Create AGENTS.sales.md for your sales workflow, AGENTS.support.md for support, and AGENTS.content.md for content creation. Swap between them by renaming or symlinking to AGENTS.md. This keeps instructions focused and avoids bloated files.
Version Control Everything
Commit your prompt files to Git. Track changes over time. Roll back when a prompt edit makes things worse. Share across team members by pulling from a shared repo. Prompts are code, so treat them like code.
Keep SOUL.md Stable
Your SOUL.md should rarely change once dialed in. It defines personality, not procedures. If you find yourself editing SOUL.md frequently, the instructions probably belong in AGENTS.md instead.
Document Your USER.md
The more context you put in USER.md, the fewer times you repeat yourself in conversations. Include your tech stack, your preferences, your team structure, and your communication style. Update it quarterly.
~/.openclaw/workspace/
SOUL.md # Personality (stable)
IDENTITY.md # Agent identity
USER.md # Your context
HEARTBEAT.md # Autonomous tasks
# Role-specific agent files
AGENTS.md # Active agent (symlink)
AGENTS.sales.md # Sales workflow
AGENTS.support.md # Support workflow
AGENTS.content.md # Content workflow
# Shared resources
templates/
email-templates.md # Reusable email formats
report-format.md # Standard report structureAvoid these
Common prompt mistakes
We see these patterns in almost every new user's prompt files. Fixing them usually produces an immediate improvement in agent output quality.
Overloading SOUL.md
Keep personality traits in SOUL.md. Move task instructions to AGENTS.md. If your SOUL.md is longer than 300 words, it is probably doing double duty.
Being Too Vague
"Handle emails well" tells the agent nothing. "Respond to customer emails within 2 hours, use first name, keep under 150 words" gives it a clear playbook.
Skipping USER.md
Without USER.md, the agent asks the same clarifying questions every conversation. Spend 10 minutes filling in your context once. Save hours of repetition forever.
No Error Handling
Your prompts should cover what to do when things go wrong. What if the API returns an error? What if the data is missing? The agent follows your instructions literally.
Giant Monolithic Files
A 2,000-word AGENTS.md with every workflow crammed in leads to inconsistent results. Break it into role-specific files and swap as needed.
Never Iterating
Your first draft is a starting point. Review the agent's output weekly, note where it drifts, and tighten the instructions. Great prompts are refined, not written.
Keep going
Related guides
Prompts FAQ
Everything you want to know about prompts.
Written by
Kevin Jeppesen
Founder, The Operator Vault
Kevin is an early OpenClaw adopter who has saved an estimated 400 to 500 hours through AI automation. He stress-tests new workflows daily, sharing what actually works through step-by-step guides and a security-conscious approach to operating AI with real tools.
Ready to put your
prompts to work?
Premium skill packs include optimized prompt templates, matching skills, and step-by-step setup guides. Or start with the $19 workshop to get the fundamentals right.
