The architecture in one picture
Every OpenClaw install boils down to five files. Master these and you master the framework.
| File | Question it answers | Frequency of edits |
|---|---|---|
| Soul | What is this agent for? | Rare (once per agent) |
| Identity | How does it talk? | Occasional (tone tweaks) |
| User | Who am I to it? | Occasional (when life changes) |
| Agent | How does it operate? | Often (workflow tuning) |
| Heartbeat | When does it act on its own? | Often (schedule tuning) |
The mental model
Think of building an employee:
- Soul = the job description ("you are a research assistant who values accuracy over speed")
- Identity = the personality on the badge ("warm, blunt, lightly nerdy")
- User = the manager handbook ("the boss is a left-handed Laravel dev in Amsterdam")
- Agent = the operations manual ("for any code task, read the file first, then plan, then write")
- Heartbeat = the calendar ("at 9am, check overnight emails and summarize")
Each is small (rarely more than a page). Each has a specific job. Together they produce an agent that is recognizably yours.
Editing rules
- Start tiny — a one-paragraph Soul beats a five-page Soul nine times out of ten
- One file per edit — change one thing, observe behavior, then change the next
- Version-control the whole
~/.openclaw/(or equivalent) folder in a private git repo
Try it
Open all five files in your editor and skim the defaults. Do not change anything yet. Just notice what is there. We are about to write each one in detail.