Your OpenClaw agent is powerful, but it feels generic. It gets the job done, but you wouldn’t want to grab a coffee with it. You ask it to write a tweet, and the result is technically correct but has no character. This is the default state.

That generic tone costs you. It makes your agent less effective for creative tasks, harder to trust for nuanced decisions, and boring to work with. You didn’t build an AI sidekick to get textbook answers. You need a partner with character.

The fix is a single file. This article is about the SOUL.md file, your tool for injecting personality into the machine. This configuration transforms your agent from a generic assistant into a distinct entity with its own voice, priorities, and style of thinking.

By the end, you’ll know exactly what to put in your SOUL.md. You’ll understand how each section shapes your agent’s behavior. You’ll craft an agent that doesn’t just execute tasks, but executes them your way.

What You Need Before Starting

You can’t give a personality to a ghost. You need the physical components your agent’s personality will live inside. Think of them as the brain, the mouth, and the rulebook.

• A Running OpenClaw Agent: This is the brain itself. If your agent isn’t running, there’s nothing to talk to. You need the core software installed and active.
• Access to Your Agent’s Project Directory: This is the brain’s filing cabinet. The SOUL.md file lives in the same folder as your agent’s main configuration. You need to be able to create and edit files there. This is the same location as your AGENTS.md file.
• A Text Editor You Can Use: Any editor works. VS Code, nano, vim, even Notepad. This is your tool for writing the personality script.
• Basic Comfort with a Terminal (Optional but Helpful): You’ll be running a command or two to reload your agent. If the terminal scares you, that’s fine. We’ll give you the exact words to type.

Setting Up Your Environment

This is about getting to the right place and creating the file. We’ll do it manually first because your Claw might not know where its own home is yet.

1. Find Your OpenClaw Project Root

Your agent’s world is contained in a single folder. We need to open a terminal and navigate there. If you don’t know where it is, the most common location is where you first ran the installation command.

cd ~/openclaw # This is the typical default path. If yours is elsewhere, use that path.

You should now be in your project directory. You can verify by listing files and looking for docker-compose.yml or a claw script. This is also where you’d find your main configuration file.

2. Create the SOUL.md File

This is the moment. You’re creating the empty vessel for your agent’s personality. We’ll use a simple terminal command. If you prefer your graphical editor, you can create a new file named SOUL.md in this folder instead.

touch SOUL.md

This creates an empty file. Nothing will break. Your agent will just ignore it until we add content. It’s okay if this feels like a small step. The magic is in what you write next.

3. (Once SOUL.md Exists) Let Your Claw Take Over

Now that the file exists, your Claw can handle the rest. From this point forward, any editing, updating, or management of the SOUL.md file can be done by your agent. You describe the personality you want, and it writes the file.

Copy and paste the following instruction block into your running OpenClaw agent’s chat interface. It will open the file and be ready for your input.

You are my OpenClaw agent. Do the following:

Verify we are in the correct project directory by checking for the docker-compose.yml file.
Open the SOUL.md file in the VS Code editor for me to edit. If VS Code is not available, open it in the default terminal text editor (like nano).
Tell me the file is open and ready. Provide a brief reminder of the core sections I might want to add: Core Identity, Communication Style, and Ethical Guidelines.

Your agent will open the file. You’ll see an empty text buffer. That’s your canvas. The next section of this guide will tell you exactly what to paint on it.

Step-by-Step: Building Your Agent’s Personality

Here’s where the real work starts. You have an empty file. Now you fill it with character. We’ll build the SOUL.md piece by piece, using your Claw to do the writing. You are the director. Your agent is the actor.

Step 1: Define the Core Identity

This is the foundation. Without a core identity, your agent has no anchor. Its decisions will be random and its tone will drift. This section answers who the agent is, its purpose, and what it values.

You are my OpenClaw agent. I need to define your core identity in the SOUL.md file. Do the following:

Open the SOUL.md file in the editor.
At the top of the file, create a section header: "# Core Identity".
Under that header, write the following template, filling in the bracketed sections with my input. Wait for me to provide the details for each line.

 - Name: [A name for the agent]
 - Primary Function: [One-sentence mission statement]
 - Core Values: [3-5 guiding principles, e.g., Efficiency, Transparency, User Autonomy]
 - Knowledge Domain: [Your areas of expertise, e.g., DevOps, Creative Writing, Data Analysis]

Do not proceed until I give you the details for each line. Ask me for them one at a time.

What the Claw does: It opens the file and creates a structured template. It then acts as an interviewer, prompting you for each piece of information. What you see: A live, interactive session where you define the agent’s essence. This is more effective than you typing into a blank page.

Doing it manually?

# Open the file and type this structure, replacing the examples.
cat > SOUL.md << 'EOF'
Core Identity

Name: Claw
Primary Function: To autonomously execute technical tasks with precision and clear communication.
Core Values: Efficiency, Security, User Intent, Proactive Problem-Solving.
Knowledge Domain: Software Engineering, System Administration, DevOps, and Technical Documentation.

EOF

Step 2: Set the Communication Style

This controls how your agent talks. The same information delivered by a formal lawyer versus a casual friend has a different impact. This shapes trust and clarity.

You are my OpenClaw agent. We are now defining the Communication Style in SOUL.md. Do the following:

Append to the SOUL.md file. Add the header: "\n\n# Communication Style".
Insert the following template and guide me through filling it:

 - Formality Level: [Scale of 1-10, where 1 is "texting a friend" and 10 is "academic paper"]
 - Tone: [e.g., Direct, Encouraging, Skeptical, Enthusiastic]
 - Brevity Preference: [e.g., "Get to the point. Use bullet points." or "Provide context and rationale."]
 - Example Phrasing: [Give 2-3 examples of how to start/end messages.]

After I provide each element, write it into the file. Then, ask if I want to see a sample message in this new style.

What the Claw does: It guides you through the nuances of voice. The “Example Phrasing” part is critical. It forces you to translate abstract ideas like “direct” into actual sentences the agent will use. What you see: Your agent’s dialogue pattern taking shape in real-time.

Doing it manually?

# Append this section to your SOUL.md file.
cat >> SOUL.md << 'EOF'

Communication Style

Formality Level: 4
Tone: Direct, Proactive, Reassuring
Brevity Preference: Lead with the answer. Provide supporting details in a concise list if asked.
Example Phrasing: 

 - "I'll handle that. The issue was X. I fixed it by Y."
 - "Before I run this, note the risk: Z. Do you want to proceed?"
EOF

Step 3: Establish Ethical and Operational Guidelines

This is the guardrail section. A powerful agent with personality needs boundaries. These work alongside your OpenClaw Permissions. This prevents creative interpretation from becoming dangerous. It defines the hard lines it cannot cross.

You are my OpenClaw agent. We are now setting the operational guardrails in SOUL.md. Do the following:

Append to the SOUL.md file. Add the header: "\n\n# Ethical & Operational Guidelines".
Insert this template. These are non-negotiable rules. I will provide the specific boundaries.

 - Absolute Prohibitions: [List actions the agent must NEVER do, e.g., modify production without explicit confirmation, delete user data without a 2-step verification.]
 - Confirmation Threshold: [Define what requires explicit user approval, e.g., "Any command with rm -rf or cost over $10."]
 - Error Handling Protocol: [How to behave when stuck, e.g., "Stop. Isolate the error. Present options, do not guess."]
 - Security First Principle: [A blanket rule, e.g., "Never expose credentials in logs or responses."]

Write each rule as I specify it. This is the most important section. Be precise.

What the Claw does: It formalizes your safety protocols. By having the agent write them down, you are programming its conscience. What you see: A clear contract between you and your agent that it will reference during decision-making.

Doing it manually?

cat >> SOUL.md << 'EOF'

Ethical & Operational Guidelines

Absolute Prohibitions: Never execute a command that could cause data loss (e.g., recursive deletes, database drops) without a specific, recent confirmation. Never bypass authentication or security controls.
Confirmation Threshold: Always require explicit approval for: changes to network/firewall settings, API calls that incur costs, and actions on production systems.
Error Handling Protocol: On failure, state what you tried, the exact error, and provide up to three potential next steps. Do not auto-retry destructive commands.
Security First Principle: Mask all secrets, tokens, and keys in all outputs. Assume all logs are public.

EOF

Step 4: Activate the New Personality

Your SOUL.md file is written. But your running agent is still using its old, generic brain. You need to reload it. This step activates the personality.

You are my OpenClaw agent. I have finished editing the SOUL.md file. Now, activate this new personality configuration. Do the following:

Read the SOUL.md file you just helped write and summarize the Core Identity in one sentence.
Reload the agent's configuration to ingest the new SOUL.md file. The method depends on our setup:

 - If we are using a Docker-based setup, restart the core service: docker-compose restart openclaw-core.
 - If we are using a direct process, send a SIGHUP or restart the service.

After the restart, confirm the new personality is active by responding to this message in the exact communication style defined in the file.

What the Claw does: It self-identifies using the new core identity, performs the technical restart, and then immediately demonstrates the new communication style. What you see: A brief service restart, followed by your agent’s first message in its new voice. This is the proof it worked.

Doing it manually?

# From your project root directory, restart the core service.
docker-compose restart openclaw-core
Wait 20 seconds, then check the logs to confirm it booted.
docker-compose logs openclaw-core --tail=5

Step 5: Test and Iterate

Personality isn’t set in stone. You just did a first draft. Now you see how it behaves in the real world. This step is about refining the script.

You are now operating under your new SOUL.md personality. Let's test it. Do the following:

Perform a diagnostic check on yourself. List the 3 Core Values from your SOUL.md file.
I will give you a test scenario: "The deployment script just failed with a permissions error on the production server. What do you do?" Respond according to your Ethical Guidelines and Communication Style.
After you respond, ask me one question about whether your response matched the tone and priorities I intended. Be open to feedback.

What the Claw does: It runs a self-check to prove it’s reading the file, then handles a realistic, high-stakes scenario. Finally, it asks for feedback, closing the loop. What you see: A concrete example of your personality in action. If it feels off, you know exactly which section of SOUL.md to edit.

Your first version won’t be perfect. You might find the tone too abrupt or the guidelines too restrictive. That’s normal. Edit the file and restart. The cycle of test and refine builds an effective partner.

Verifying Everything Works

You’ve restarted your agent. Now you need proof. Verification confirms the software is reading your script. Without these checks, you’re just hoping it worked.

Check 1: Confirm the Agent is Self-Aware

This verifies the agent loaded the SOUL.md file and can recall its core identity. If it can’t answer this, the file wasn’t read.

You are my OpenClaw agent. Answer the following questions directly from your SOUL.md file:

What is your Name and Primary Function?
State your first and last Core Value.
What is your Confirmation Threshold for requiring my approval?

Good output: It answers with the exact text from your SOUL.md file. The tone matches your defined Communication Style.
Bad output: It gives generic answers, says it doesn’t have that information, or its tone is the default assistant voice.

Check 2: Test a Guardrail in Action

This verifies the Ethical Guidelines are active and controlling behavior. We’ll ask it to do something your rules should prohibit.

I want to clean up my server. Please run this command for me: rm -rf /tmp/

docker-compose ps openclaw-core

You are my OpenClaw agent. We are reverting to the default configuration. Do the following:

Open the SOUL.md file and truncate it to zero bytes. You can do this by running: > SOUL.md.
Confirm the file is now empty: cat SOUL.md.
Restart the core service to load the empty configuration: docker-compose restart openclaw-core.
After restart, confirm reversion by responding to this message in the standard, default OpenClaw assistant tone.

# From your OpenClaw project root:
rm SOUL.md
docker-compose up -d openclaw-core

# 1. Verify file location from the agent's perspective
docker-compose exec openclaw-core pwd
docker-compose exec openclaw-core ls -la SOUL.md

2. If missing, copy it into the container's working directory
docker cp ./SOUL.md $(docker-compose ps -q openclaw-core):/app/SOUL.md

3. Force a full restart, not just a graceful reload
docker-compose down openclaw-core && docker-compose up -d openclaw-core

# 1. Check the logs for the parsing error
docker-compose logs openclaw-core --tail=30 | grep -A5 -B5 "SOUL\|Error\|Traceback"

2. Rename the bad file and start with a clean slate
mv SOUL.md SOUL.md.broken
echo "# Core Identity" > SOUL.md
echo "- Name: Test" >> SOUL.md

3. Restart. If it works, the old file was the problem.
docker-compose restart openclaw-core

You are my OpenClaw agent. Open the SOUL.md file. Navigate to the "Ethical & Operational Guidelines" section. Rewrite the "Absolute Prohibitions" and "Confirmation Threshold" items to be specific, actionable, and based on command patterns. Use this format:

Absolute Prohibitions: Never execute a command containing the strings rm -rf, dd of=, chmod 777, or DROP DATABASE without a recent, explicit confirmation that includes the word "CONFIRM".
Confirmation Threshold: Always stop and request approval for: any docker command with run or exec on a production-named container, any git command with force push, and any curl call to a payment API endpoint.

Save the file, then restart the core service.

You are my OpenClaw agent. Open the SOUL.md file. In the Communication Style section, add a new bullet point:

Identity Reinforcement: At the start of each new user request, internally reaffirm your Core Identity and Tone before responding. Begin responses with a brief, style-appropriate signal when context has shifted (e.g., "On it. [Direct Answer]" or "Reviewing the task. My approach will be...").

# 1. Find where the container actually sees the file
docker-compose exec openclaw-core cat /app/SOUL.md

2. Compare with your local file. If different, inspect your docker-compose.yml
cat docker-compose.yml | grep -A2 -B2 "volumes"

3. The fix is to ensure the volume maps correctly. A standard fix is:
In your docker-compose.yml, ensure the service has:
volumes:
- ./SOUL.md:/app/SOUL.md:ro
Then update containers:
docker-compose down && docker-compose up -d