In this chapter, you will edit the files that define your agent's personality and watch the changes take effect in real time.
By the end, you should be able to name the workspace files that load on every message (SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md, USER.md). You will also learn Emma's rule: if a workspace instruction does not change the agent's behavior compared to the base model, delete it.
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 Chapter 2," James said. "It is not listening."
"Where did you tell it?" Emma asked.
"In the chat," James said. "I said 'keep responses short.'"
Emma shook her head. "That is session memory. It fades when the conversation ends. 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 asked, leaning forward.
"The agent's brain," Emma said. "These files load into every single message. Not at startup. Not once a day. Every 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?" Emma asked.
James re-read them. "I... do not know."
"The model is already trained to be helpful," Emma said. "Telling it to be helpful is like telling a pilot to fly. It wastes context on instructions the model already follows." 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 will 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 chapter, you learn what those files are, edit them, and see the changes take effect.
Your agent's workspace lives at ~/.openclaw/workspace/. The workspace documentation defines every file. Here is what each one does and when it loads:
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.
TOOLS.md Does Not Control Tools
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 Module 9.1, Chapter 3). If you want to restrict which tools the agent can use, change the tool profile, not TOOLS.md.
In Module 9.1, Chapter 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:
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.
Now ask the agent to do the editing:
Check the dashboard. You will see tool badges for file write. The agent just edited its own personality file.
Workspace file changes take effect on new sessions. Send a new message to test:
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).
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:
After the agent saves, test it. Ask the same weather question:
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.
Terminal Editing
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.
Ask your agent:
Or edit manually:
The name you set here is what appears in the dashboard and what the agent uses when referring to itself.
You just hand-edited your workspace files. There is another way: let the agent configure itself.
The BOOTSTRAP pattern works like this:
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.
BOOT.md vs BOOTSTRAP.md
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.
Edit SOUL.md to give your agent a specific personality trait you can test. For example:
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.
Ask your agent to read its own workspace files:
Compare the agent's answer to the table in this chapter. 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.
If you want to see the BOOTSTRAP pattern in action, back up your current workspace first:
Then create a minimal BOOTSTRAP.md:
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.
Five files load on every single message: SOUL.md (persona and boundaries), IDENTITY.md (name and vibe), AGENTS.md (operating instructions), TOOLS.md (tool guidance notes), and USER.md (who you are). These are the firmware from Module 9.1, Chapter 1's Agent OS analogy: foundational behavioral instructions that shape every response.
For each line in a workspace file, ask: would the agent behave differently without this instruction? If not, delete it. Telling a model to be helpful is like telling a pilot to fly. Shorter workspace files are not just cleaner; they are more reliable, because long files push instructions past the model's attention window.
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?" Emma asked.
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," James said. "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. "Module 9.1, Chapter 5. Persistent memory. The difference between what the agent knows and what it remembers."