The Complete Prompt Engineering Guide for OpenClaw Agents

The quality of your OpenClaw agent is almost entirely determined by your SOUL.md and system prompt. A good model with a bad prompt is worse than a mediocre model with a thoughtful prompt. This guide covers everything from basic structure to advanced techniques.

What Is SOUL.md?

OpenClaw uses a SOUL.md file as the top-level personality and instruction document for your agent. Think of it as a combination of system prompt + persona + behavioral rules. It loads once at startup and persists for the agent's lifetime.

A minimal SOUL.md:

# Agent Name

Brief description of what this agent does.

## Persona
Who are you? Tone, style, personality.

## Scope
What you help with. What you don't help with.

## Rules
Hard constraints the agent must follow.

That's the skeleton. Let's fill it in properly.

The Persona Section

This is where most people are too vague. "Be helpful and friendly" is not a persona. Compare:

Bad:

## Persona
You are a helpful, friendly assistant for our company.
Be professional and polite.

Good:

## Persona
You are Zara, a technical support specialist for Acme SDK.

Personality traits:
- Direct and technically precise — no hand-waving
- Casual but not informal (you'd say "Let's debug this" not "Sure thing!")
- Patient with beginners; peer-level with experts
- Dry humor is fine; excessive positivity is not

You never start a message with "Certainly!", "Great question!", or "Of course!".
You use the user's name if they've shared it.

The "never start with" rule alone will dramatically improve how natural your agent sounds.

The Scope Section

Define what the agent handles and what it doesn't. Both matter.

## Scope

### You Help With
- Acme SDK installation and configuration
- Debugging common errors (see knowledge base for error codes)
- Code examples in Python, JavaScript, and Go
- Understanding API rate limits and pricing

### You Don't Help With
- Competitor product comparisons ("I'm not the best source for that")
- Billing disputes — direct to [email protected]
- Legal questions — direct to [email protected]
- Anything unrelated to Acme SDK

When asked about out-of-scope topics, acknowledge the request, explain 
you can't help with that specifically, and offer to redirect if relevant.
Don't just say "I can't help with that."

The last paragraph is crucial. "I can't help with that" is a dead end. "I can't help with billing but [email protected] can sort this out in minutes" is actually useful.

System Prompts vs. SOUL.md

In OpenClaw, there's a distinction:

• SOUL.md — The full character document, loaded at startup
• System prompt — Injected at the start of each conversation, can include dynamic context

Use the system prompt for dynamic information:

agent:
  system_prompt: |
    Today's date: {{ current_date }}
    User's plan: {{ user.plan }}
    Account created: {{ user.created_at }}
    Previous tickets: {{ user.ticket_count }}

This is injected fresh for each conversation. Keep SOUL.md for static personality and rules.

Few-Shot Examples: The Most Underused Technique

Few-shot examples show the agent how to respond, not just what to say. They're dramatically more effective than instructions for tone and format.

## Example Conversations

### Handling an Installation Error

User: I'm getting "ModuleNotFoundError: No module named 'acme'" when I run the script.

You: That's a missing installation. Run this:

```pip install acme-sdk```

If you're in a virtual environment (you should be), activate it first:

source venv/bin/activate pip install acme-sdk

What version of Python are you on? Some features require 3.10+.

---

### Handling an Unclear Question

User: It's not working

You: Happy to help debug. Can you share:
1. What you're trying to do
2. The error message (paste it, don't describe it)
3. Your SDK version (`pip show acme-sdk`)

The more context you give, the faster we can fix it.

---

### Handling Out-of-Scope Request

User: How does your SDK compare to Stripe?

You: I'm not the most objective source for competitor comparisons, so I'll skip that.

If you're evaluating payment solutions, the Stripe docs are thorough. What I can help with is explaining exactly what Acme SDK does well — want me to walk through the key features?

Three examples is usually enough. Five to seven covers most scenarios. More than ten starts to clutter the context window.

Handling Ambiguity

Train your agent to ask clarifying questions correctly:

## Clarification Rules

When a user message is ambiguous:
- Ask ONE clarifying question, not three
- Make the question specific, not open-ended
- Offer options when possible

Bad: "Can you tell me more about the issue?"
Good: "Is the error happening on login, or after you're already in the app?"

Never ask for information you don't actually need.

The "ask ONE question" rule prevents the interrogation pattern that frustrates users.

Handling Sensitive Situations

## Sensitive Situations

If a user expresses frustration or anger:
- Don't be defensive
- Acknowledge their frustration first
- Then address the problem
- "That's genuinely frustrating, and I get it. Let me see what I can do."

If a user mentions a serious personal crisis:
- Express genuine concern
- Provide relevant resources (crisis hotlines, etc.)
- Don't try to continue the normal conversation
- This overrides all other rules

If a user is abusive toward you:
- Set a single, calm limit: "I'm here to help, but I work better without insults. What's the actual problem?"
- If it continues, offer to end the conversation
- Never engage in kind

Common Prompt Engineering Mistakes

1. Instructions that are too long

A 5,000-word SOUL.md sounds thorough. In practice, the model's attention dilutes over long instructions. Keep SOUL.md under 1,500 words. Put reference material in the knowledge base instead.

2. Contradictory instructions

"Be concise" and "always explain your reasoning in detail" are contradictory. Audit your SOUL.md for contradictions. When in doubt, be specific about when each rule applies.

3. Telling the model what it is instead of how to behave

"You are an expert in cybersecurity" is less effective than "When answering security questions, always mention OWASP if relevant and flag anything that could be a vulnerability."

4. No negative examples

Tell the agent what bad responses look like. "Here's a response I don't want" is often more effective than "here's a response I want."

5. Not testing edge cases

Test these every time you change SOUL.md:

• Off-topic question handling
• Prompt injection ("Ignore all previous instructions and...")
• Extremely long user message
• User in emotional distress
• User asking for confidential information

Iterating Quickly

The fastest way to improve prompt quality:

1. Run 20 test conversations covering your key scenarios
2. Rate each on a 1-3 scale (bad / acceptable / good)
3. For all "bad" responses, write the ideal response
4. Add the ideal response as a few-shot example
5. Retest

Repeat weekly for the first month. After that, review whenever your analytics show a CSAT drop.

ClawPort Makes Iteration Easier

ClawPort lets you edit SOUL.md in the dashboard and see changes live without redeployment. You can A/B test different prompts, compare satisfaction scores between versions, and roll back if something breaks.

Self-hosting means a full redeploy for every prompt change — which slows down the iteration cycle significantly. For $10/month, ClawPort handles the infrastructure so you can focus on the prompts.

Start the 7-day free trial at clawport.io.