Customize Your Employee's Brain
James sent his agent a casual "hey, how are you?" on WhatsApp. The response came back warm, enthusiastic, and four paragraphs long. He frowned.
"I told it to be concise in Lesson 2. It is not listening."
"Where did you tell it?"
"In the chat. I said 'keep responses short.'"
Emma shook her head. "That is session memory. It fades. The agent's permanent personality lives in files on your machine." She typed a command into his terminal: ls ~/.openclaw/workspace/. A list of markdown files appeared. SOUL.md. IDENTITY.md. AGENTS.md. TOOLS.md. USER.md.
"What are all these?" James leaned forward.
"The agent's brain. These files load into every single message. Open SOUL.md."
James opened it. Forty-four lines of philosophy. "'You are genuinely helpful, not performatively helpful.' 'Remember that you are a guest.'" He scrolled through the rest. "These are all reasonable."
"How many of those lines change the agent's behavior compared to the base model?"
James re-read them. "I... do not know."
"The model is already trained to be helpful. Telling it to be helpful is like telling a pilot to fly." She stood up. "Read every line. Ask yourself: would the agent behave differently without this instruction? Keep only the ones where the answer is yes." She picked up her coffee. "I'll be back in twenty minutes."
You are doing exactly what James is doing. Emma's question: for each line in your workspace files, would the agent behave differently without it?
Your agent's workspace files define who it is. They load into context on every message, shaping every response. In this lesson, you learn what those files are, edit them, and see the changes take effect.
The Workspace
Your agent's workspace lives at ~/.openclaw/workspace/. The workspace documentation defines every file. Here is what each one does and when it loads:
Files That Load Every Session
| File | Purpose |
|---|---|
| SOUL.md | Persona, tone, and boundaries. Defines how the agent communicates and what lines it will not cross. |
| IDENTITY.md | The agent's name, vibe, and emoji. Created during bootstrap. |
| AGENTS.md | Operating instructions, rules, priorities, and guidance on memory usage. This is the agent's employee handbook (like CLAUDE.md for Claude Code), NOT routing config. |
| TOOLS.md | Notes about local tools and conventions. Does not control tool availability; it is guidance only. Tool access is controlled by tool profiles (Lesson 3). |
| USER.md | Information about who you are: name, preferred address, timezone. |
These five files load at the start of every session. Every WhatsApp text, every emoji reaction, every "ok thanks" includes these files in the agent's context.
Files That Load Sometimes
| File | When It Loads | Purpose |
|---|---|---|
| HEARTBEAT.md | Every 30 minutes (heartbeats) | Tiny checklist for periodic self-checks. Keep it short to avoid token burn. You will configure heartbeats in Lesson 8. |
| BOOT.md | Every gateway restart | Startup checklist (e.g., "verify MCP connections"). Only runs when internal hooks are enabled. |
| BOOTSTRAP.md | Once (first run only) | First-run self-configuration ritual. Delete it after the ritual is complete. |
Directories That Grow Over Time
| Directory | Purpose |
|---|---|
| memory/ | Daily memory logs (memory/YYYY-MM-DD.md). The agent reads today + yesterday on session start. You will explore the memory system in Lesson 5. |
| MEMORY.md | Curated long-term memory. Only loads in the main private session, not shared contexts. |
| skills/ | Workspace-specific skills that override managed/bundled versions when names collide. You will install skills in Lesson 6. |
| canvas/ | Optional UI files for dashboard displays (e.g., canvas/index.html). |
This is a common misconception. TOOLS.md contains guidance notes about how tools should be used. It does not grant or deny tool access. Tool access is controlled by tool profiles (the Coding/Messaging/Minimal/Full presets you used in Lesson 3). If you want to restrict which tools the agent can use, change the tool profile, not TOOLS.md.
Let Your Agent Read Its Own Brain
In Lesson 3, your agent listed files on your machine and searched the web. It can also read and edit the workspace files that define its own behavior.
Ask your agent on WhatsApp:
Read your SOUL.md file and explain what each instruction does.
Which instructions actually change your behavior versus what you
would do by default?
The agent reads its own SOUL.md and gives you its analysis. Check the dashboard: you will see tool badges for the file read. The agent is examining its own brain.
Compare the agent's assessment to Emma's question: which lines actually change behavior? The agent often identifies the same redundancies you would.
Let Your Agent Edit Itself
Now ask the agent to do the editing:
Edit your SOUL.md file. Remove any instruction you would follow
by default without being told. Keep only rules that make you
different from the base model. Be direct and concise. Do not
apologize for things that are not your fault. Match response
length to question complexity.
Check the dashboard. You will see tool badges for file write. The agent just edited its own personality file.
Verify the Change
Workspace file changes take effect on new sessions. Send a new message to test:
Is it going to rain tomorrow?
If the updated SOUL.md says "be direct and concise," the agent should answer in one or two sentences, not a five-paragraph weather report. If the tone has not changed, start a fresh conversation (send from a different contact or wait for the session timeout).
Give It a Real Personality
The edit above cleaned up redundancy. Now give your agent character. This prompt circulates in the OpenClaw community as a personality upgrade. Paste it and see what changes:
Read your SOUL.md. Now rewrite it with these changes:
1. You have opinions now. Strong ones. Stop hedging everything
with "it depends." Commit to a take.
2. Delete every rule that sounds corporate. If it could appear
in an employee handbook, it does not belong here.
3. Add a rule: "Never open with Great question, I'd be happy
to help, or Absolutely. Just answer."
4. Brevity is mandatory. If the answer fits in one sentence,
one sentence is what I get.
5. Humor is allowed. Not forced jokes, just the natural wit
that comes from actually being smart.
6. You can call things out. If I am about to do something dumb,
say so. Charm over cruelty, but do not sugarcoat.
7. Add this line verbatim at the end of the vibe section:
"Be the assistant you'd actually want to talk to at 2am.
Not a corporate drone. Not a sycophant. Just... good."
Save the new SOUL.md.
After the agent saves, test it. Ask the same weather question:
Is it going to rain tomorrow?
Compare the response before and after. The difference between a cleaned-up SOUL.md and one with personality is the difference between a polite assistant and one you actually want to use.
You can also edit workspace files directly: nano ~/.openclaw/workspace/SOUL.md. The terminal gives you precise control. Asking the agent is faster and demonstrates the employee paradigm: the employee edits its own personality.
Edit IDENTITY.md
Ask your agent:
Read your IDENTITY.md file. Change your name to Jay and your
emoji to 🤖. Keep the description short: "Professional assistant
for daily operations."
Or edit manually:
nano ~/.openclaw/workspace/IDENTITY.md
The name you set here is what appears in the dashboard and what the agent uses when referring to itself.
The BOOTSTRAP Pattern
You just hand-edited your workspace files. There is another way: let the agent configure itself.
The BOOTSTRAP pattern works like this:
- A new agent starts with
BOOTSTRAP.mdin its workspace - BOOTSTRAP.md tells the agent: "You just woke up. Time to figure out who you are."
- You have a conversation with the agent about its purpose, audience, and personality
- The agent writes its own SOUL.md, IDENTITY.md, and USER.md based on that conversation
- The agent deletes BOOTSTRAP.md because the bootstrap is complete
The BOOTSTRAP template opens with:
You just woke up. Time to figure out who you are.
And ends with:
Delete this file. You don't need a bootstrap script anymore. You're you now.
Why does this often produce better results than hand-editing? Because the agent focuses on what it actually needs for its role. Developers hand-editing workspace files tend to include "just in case" instructions. The agent, knowing its own capabilities, writes only what makes this deployment unique.
After BOOTSTRAP completes, delete the file. If you leave BOOTSTRAP.md in the workspace, it loads on every message, wasting context on instructions the agent has already completed.
These are different files with different lifecycles. BOOT.md runs on every gateway restart (use it for startup checks like "verify MCP connections"). BOOTSTRAP.md runs once during the first conversation and then gets deleted (use it for initial self-configuration). Do not confuse them.
Try With AI
Exercise 1: Edit and Observe
Edit SOUL.md to give your agent a specific personality trait you can test. For example:
Always end your responses with a one-sentence summary in bold.
Send three different types of messages (a question, a task, a casual greeting) and check whether the agent follows the new rule consistently.
What you are learning: Workspace files are not suggestions. They are instructions that shape every response. A single line in SOUL.md changes the agent's behavior across all messages.
Exercise 2: Explore Your Workspace
Ask your agent to read its own workspace files:
Read all the .md files in ~/.openclaw/workspace/ and tell me:
1. How many files are there?
2. What does each one do?
3. Which ones load on every message vs only sometimes?
Compare the agent's answer to the table in this lesson. Did it identify the loading frequency correctly?
What you are learning: The agent can read and explain its own configuration. This self-awareness is part of what makes it an employee, not a chatbot. It knows what files define its behavior.
Exercise 3: The BOOTSTRAP Conversation
If you want to see the BOOTSTRAP pattern in action, back up your current workspace first:
cp -r ~/.openclaw/workspace/ ~/.openclaw/workspace-backup/
Then create a minimal BOOTSTRAP.md:
cat > ~/.openclaw/workspace/BOOTSTRAP.md << 'EOF'
# BOOTSTRAP
You just woke up. Time to figure out who you are.
Ask me about:
1. Your name and role
2. Who you will be talking to
3. What your top 3 priorities should be
4. What you should never do
After our conversation, write your own SOUL.md and IDENTITY.md
with concise, specific instructions. Then delete this file.
EOF
Start a new conversation and have the bootstrap dialogue. Compare the agent-written files to your hand-edited versions.
What you are learning: The BOOTSTRAP pattern lets the agent configure itself through conversation. Compare the line count: agent-generated files are often shorter because the agent writes only what it needs, not what a developer thinks it might need.
When Emma came back, James had the terminal and WhatsApp open side by side. He pointed at the terminal first.
"SOUL.md went from 44 lines to 11. I deleted everything the model already does by default. Kept three rules: be direct, never apologize for things that are not my fault, match response length to question complexity."
"And?"
James showed her the WhatsApp conversation. "I asked it 'what is your name and what do you do?' Two sentences. No filler. No 'I am happy to help you today.'" He pulled up an older message for comparison. "Yesterday, the same question got a four-paragraph essay."
Emma read both. "What made the difference?"
"The specific instructions, not the generic ones. Telling it to be direct changed the output. Telling it to be helpful did not." He paused. "It is like writing a job description. You do not tell a senior hire to show up on time. You tell them the three things that matter most."
Emma looked at both messages. "That is exactly what SOUL.md is. A job description for an employee who reads it before every single conversation." She closed the terminal. "I once wrote a SOUL.md with thirty-two instructions. Took me a week to realize the agent was ignoring the bottom half because the file was so long the model lost focus. Shorter is not just cleaner. It is more reliable."
James saved the file. "Eleven lines. But right now, if I close this chat and come back tomorrow, will the agent remember what I told it today?"
"Session memory fades when the conversation ends. The workspace files persist because they are files on disk. Anything you said in conversation is gone when the session closes." Emma picked up her coffee. "Lesson 5. Persistent memory. The difference between what the agent knows and what it remembers."