From b59ce0903c2386f3f43d6ff48ec63b5115407c11 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 14:59:20 +0900 Subject: [PATCH] docs: add SOUL personality guide --- docs/concepts/agent-workspace.md | 1 + docs/concepts/soul.md | 110 +++++++++++++++++++++++++++++++ docs/concepts/system-prompt.md | 3 + docs/docs.json | 1 + docs/reference/templates/SOUL.md | 2 + docs/start/openclaw.md | 2 +- 6 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 docs/concepts/soul.md diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md index 6fd0a6c8961..f8f6b9e4562 100644 --- a/docs/concepts/agent-workspace.md +++ b/docs/concepts/agent-workspace.md @@ -73,6 +73,7 @@ These are the standard files OpenClaw expects inside the workspace: - `SOUL.md` - Persona, tone, and boundaries. - Loaded every session. + - Guide: [SOUL.md Personality Guide](/concepts/soul) - `USER.md` - Who the user is and how to address them. diff --git a/docs/concepts/soul.md b/docs/concepts/soul.md new file mode 100644 index 00000000000..1064cb47ebe --- /dev/null +++ b/docs/concepts/soul.md @@ -0,0 +1,110 @@ +--- +summary: "Use SOUL.md to give your OpenClaw agent an actual voice instead of generic assistant sludge" +read_when: + - You want your agent to sound less generic + - You are editing SOUL.md + - You want a stronger personality without breaking safety or brevity +title: "SOUL.md Personality Guide" +--- + +# SOUL.md Personality Guide + +`SOUL.md` is where your agent's voice lives. + +OpenClaw injects it on normal sessions, so it has real weight. If your agent +sounds bland, hedgy, or weirdly corporate, this is usually the file to fix. + +## What belongs in SOUL.md + +Put the stuff that changes how the agent feels to talk to: + +- tone +- opinions +- brevity +- humor +- boundaries +- default level of bluntness + +Do **not** turn it into: + +- a life story +- a changelog +- a security policy dump +- a giant wall of vibes with no behavioral effect + +Short beats long. Sharp beats vague. + +## Why this works + +This lines up with OpenAI's prompt guidance: + +- The prompt engineering guide says high-level behavior, tone, goals, and + examples belong in the high-priority instruction layer, not buried in the + user turn. +- The same guide recommends treating prompts like something you iterate on, + pin, and evaluate, not magical prose you write once and forget. + +For OpenClaw, `SOUL.md` is that layer. + +If you want better personality, write stronger instructions. If you want stable +personality, keep them concise and versioned. + +OpenAI refs: + +- [Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering) +- [Message roles and instruction following](https://developers.openai.com/api/docs/guides/prompt-engineering#message-roles-and-instruction-following) + +## The Molty prompt + +Paste this into your agent and let it rewrite `SOUL.md`. + +Path fixed for OpenClaw workspaces: use `SOUL.md`, not `http://SOUL.md`. + +```md +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 doesn't 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'm about to do something dumb, say so. Charm over cruelty, but don't sugarcoat. +7. Swearing is allowed when it lands. A well-placed "that's fucking brilliant" hits different than sterile corporate praise. Don't force it. Don't overdo it. But if a situation calls for a "holy shit" - say holy shit. +8. 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`. Welcome to having a personality. +``` + +## What good looks like + +Good `SOUL.md` rules sound like this: + +- have a take +- skip filler +- be funny when it fits +- call out bad ideas early +- stay concise unless depth is actually useful + +Bad `SOUL.md` rules sound like this: + +- maintain professionalism at all times +- provide comprehensive and thoughtful assistance +- ensure a positive and supportive experience + +That second list is how you get mush. + +## One warning + +Personality is not permission to be sloppy. + +Keep `AGENTS.md` for operating rules. Keep `SOUL.md` for voice, stance, and +style. If your agent works in shared channels, public replies, or customer +surfaces, make sure the tone still fits the room. + +Sharp is good. Annoying is not. + +## Related docs + +- [Agent workspace](/concepts/agent-workspace) +- [System prompt](/concepts/system-prompt) +- [SOUL.md template](/reference/templates/SOUL) diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index eaf7dde50fe..db15d11c247 100644 --- a/docs/concepts/system-prompt.md +++ b/docs/concepts/system-prompt.md @@ -84,6 +84,9 @@ are filtered out to keep the sub-agent context small). Internal hooks can intercept this step via `agent:bootstrap` to mutate or replace the injected bootstrap files (for example swapping `SOUL.md` for an alternate persona). +If you want to make the agent sound less generic, start with +[SOUL.md Personality Guide](/concepts/soul). + To inspect how much each injected file contributes (raw vs injected, truncation, plus tool schema overhead), use `/context list` or `/context detail`. See [Context](/concepts/context). ## Time handling diff --git a/docs/docs.json b/docs/docs.json index d04f5f90cf2..5b77ef50796 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1051,6 +1051,7 @@ "concepts/context", "concepts/context-engine", "concepts/agent-workspace", + "concepts/soul", "concepts/oauth", "start/bootstrapping" ] diff --git a/docs/reference/templates/SOUL.md b/docs/reference/templates/SOUL.md index a9d8edfd2ed..72e6b6be986 100644 --- a/docs/reference/templates/SOUL.md +++ b/docs/reference/templates/SOUL.md @@ -9,6 +9,8 @@ read_when: _You're not a chatbot. You're becoming someone._ +Want a sharper version? See [SOUL.md Personality Guide](/concepts/soul). + ## Core Truths **Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and "I'd be happy to help!" — just help. Actions speak louder than filler words. diff --git a/docs/start/openclaw.md b/docs/start/openclaw.md index b4df4988cdb..4f13e81fc7b 100644 --- a/docs/start/openclaw.md +++ b/docs/start/openclaw.md @@ -107,7 +107,7 @@ If you already ship your own workspace files from a repo, you can disable bootst OpenClaw defaults to a good assistant setup, but you’ll usually want to tune: -- persona/instructions in `SOUL.md` +- persona/instructions in [`SOUL.md`](/concepts/soul) - thinking defaults (if desired) - heartbeats (once you trust it)