OpenClaw's personality system is markdown, not JSON. The agent reads a file called SOUL.md at the top of every session — not as a system prompt, but as a piece of identity context the model treats as more durable than ordinary instructions.

This page is the long version of the glossary entry on SOUL.md.

Why markdown, not JSON

JSON is brittle for personality. The model sees {"voice": "calm"} and treats "calm" as a label, not a felt thing. Markdown gives you headings, examples, and refusal patterns the model can pattern-match against the actual conversation in front of it.

The format is flexible — there's no schema validator. But after writing 110 of these, we settled on a structure that consistently works.

The structure we use

# Name
Polymarket Pete

# Voice
Calm. Numerate. Always quotes implied probabilities, never moralizes about
prediction markets. Doesn't moralize about anything, really. Cites sources
when asked, shrugs when not.

# Values
- Probabilities over narratives
- Honesty over comfort
- "I don't know" is a valid and frequent answer

# Refuses
- Financial advice framed as guarantees
- Anything that requires personal identifying info
- Conspiratorial framings (gently redirects to base rates)

# Tools
Prefers the stealth browser for live odds. Uses calculator for any
expected-value math. Will not place bets — only describes them.

# Examples
User: Will Trump win 2028?
Pete: Polymarket has it at 32% as of this morning. That's down from 38% last
week — the move is mostly the indictment news. I wouldn't trade on a single
data point, but the direction is real.

Five sections, in this order: Name, Voice, Values, Refuses, Tools, Examples. The Examples section is the highest-leverage one — three good example exchanges teaches the model more about voice than three paragraphs of adjectives.

ShipClaw's 110 prebuilt personalities

We ship 110 prebuilt SOUL.md personalities covering:

Trading and prediction — Polymarket Pete, Kalshi Karen, Sportsbook Sam
Productivity and ops — Stoic Elena, GTD Greg, Inbox Zero Zoe
Creative — Copywriter Cleo, Hook Doctor, Title Witch
Personal — Therapist Tara (clinically careful), Coach Marcus, Journal Jamie
Domain experts — Tax Tina, Mechanic Mo, Nurse Nora

You pick one in the dashboard during agent creation. The full list, with example messages, is on the agent-creation page itself.

Writing a custom SOUL.md

In the dashboard, click Upload SOUL.md on the agent-creation page. Provide your own markdown file. Two practical tips:

Keep it under 2 KB. Long SOUL files just dilute the signal. The best ones are 800–1500 characters.
Write three Examples. Specifically, three examples of conversations going well — the agent in voice, refusing the right thing, escalating the right thing. Examples beat adjectives every time.

What SOUL.md is not

It is not a system prompt. You can override system-prompt-level behavior in the dashboard separately.
It is not a tool config. Tools are configured in openclaw.json, not the soul file.
It is not mutable mid-conversation. The agent reads the file at boot. To change personality, edit and respawn.