skip to content

Workspace Bootstrap Files

AGENTS.md, SOUL.md, USER.md and IDENTITY.md are injected into its sessions as the agent's rules, persona and user profile. Interviewers ask what belongs in each and what the injection costs.

part ofAI coding toolsread it →
on this pageshow

explore

questions

6

In an OpenClaw workspace, what belongs in AGENTS.md, SOUL.md, USER.md and IDENTITY.md, and how do they differ?

level: juniorimportance: must knowfreq 22%

answer

  1. four files, four jobs
  2. rules versus voice
  3. directives about the person
  4. name, emoji, avatar
  5. tool notes inside AGENTS.md now

basics

~20 s

AGENTS.md holds the agent's operating rules and memory habits, SOUL.md its persona and tone, USER.md stable directives about the owner, and IDENTITY.md its name, vibe, emoji and avatar. All four are injected prompt guidance, not enforcement.

solid answer

~40 s

All four live in the workspace (default `~/.openclaw/workspace`) and are injected into the system prompt's Project Context. `AGENTS.md` is the operating manual: rules, priorities, what to confirm, how to use memory, standing orders, and in 2026.9.9 the `## Tools` section for local notes that replaced `TOOLS.md`. `SOUL.md` is voice: tone, opinions, brevity, boundaries. `USER.md` is an optional user model written as dated `active` or `superseded` directives, with its own 4,000-character cap. `IDENTITY.md` records the agent's name, vibe, emoji and avatar, which `openclaw agents set-identity --from-identity` can sync into config. None of them enforces anything; tool policy, exec approvals and the sandbox do.

code

markdown · 15 lines
markdown
# USER.md - User Model

## Directives

<!-- observed: 2026-08-14 | status: superseded -->

- Prefer detailed explanations for every change.

<!-- observed: 2026-09-30 | status: active -->

- Prefer a two-line summary unless more detail is requested.

<!-- observed: 2026-09-02 | status: active -->

- Never schedule anything before 9:00 on weekdays.

go deeper

for a junior

Recall the one-line job of each file: rules in AGENTS.md, voice in SOUL.md, the person in USER.md, name and emoji in IDENTITY.md.

for a middle

Explain the directive format of USER.md and why it has its own small cap, and say where local tool notes live now that TOOLS.md is retired.

for a senior

Show you keep the files short because each is injected on every run, and that you never rely on them for enforcement; name the runtime layers that actually gate actions.

for a principal

Discuss who owns each file on a team install, how changes are reviewed, and why persona and policy should be versioned separately so a tone tweak never edits operating rules.

## The workspace and its bootstrap files An OpenClaw **workspace** is the agent's home folder, by default `~/.openclaw/workspace`. It is separate from `~/.openclaw/` itself, which holds config, credentials and session databases. Inside the workspace sit a handful of Markdown **bootstrap files** that OpenClaw reads and injects into the system prompt's Project Context, so the model starts every run already knowing its rules, its voice and who it works for. `openclaw onboard` (and `openclaw setup`) seed starter templates for them when they are missing. Four of those files carry most of the weight, and each has one job. ## What each file holds | File | Holds | Typical content | |---|---|---| | `AGENTS.md` | Operating instructions | rules, priorities, how to use memory, red lines, standing orders, local tool notes | | `SOUL.md` | Persona and voice | tone, opinions, brevity, humour, boundaries, default bluntness | | `USER.md` | The user model | stable preferences, communication style, relationships, active-project context | | `IDENTITY.md` | The agent's identity record | name, creature or vibe, emoji, avatar | - **`AGENTS.md`** is the agent's operating manual: what to do at session start, how to write things down, which actions need confirmation, how to behave in group chats. Standing orders (programs the agent owns, such as a weekly report) are recommended here because the file is injected every session. - **`SOUL.md`** is where the voice lives. The project's own guide says that if the agent sounds bland or corporate, this is usually the file to fix, and it warns against turning SOUL.md into a life story or a security policy dump. - **`USER.md`** is optional and has its own small budget (a fixed 4,000-character cap in 2026.9.9). It is written as **directives, not observations**: each entry is a metadata comment such as `<!-- observed: 2026-07-27 | status: active -->` followed by one imperative line beginning `Always`, `Never` or `Prefer`. When a preference changes, the old entry is marked `superseded` in place and the new one sits next to it. - **`IDENTITY.md`** is filled in during the first-run ritual. Its `- Label: value` lines (Name, Creature, Vibe, Emoji, Avatar) can be synced into agent config with `openclaw agents set-identity --from-identity`, which is what channels and the Control UI display. ## Rules versus voice The most common mistake is mixing the two big files. The split the project recommends is simple: 1. Operating rules (what to do, what to confirm, what never to share) go in `AGENTS.md`. 2. Voice, stance and style go in `SOUL.md`. 3. Facts about the person go in `USER.md`; durable non-profile facts and decisions go to memory instead, which is a separate subject. Keeping them apart makes each file short, and short files are cheaper: every bootstrap file is injected on each run and counts against per-file and total character budgets. ## Guidance, not enforcement All four files are **prompt text**. They shape what the model tends to do; they do not decide what it can do. A line in `AGENTS.md` saying "never delete files" is advice to the model. What actually gates a risky action is OpenClaw's runtime layer: tool policy, exec approvals, sandboxing and channel allowlists. OpenClaw's own system prompt says risk is enforced at runtime, not in prompt prose. An answer that lets SOUL.md or AGENTS.md "block" a command has the layers backwards. ## Where local tool notes went Older guides describe a separate `TOOLS.md`. In 2026.9.9 it is retired: environment notes (SSH hosts, camera names, device nicknames, platform formatting habits) live in the `## Tools` section of `AGENTS.md`, `TOOLS.md` is no longer a recognised runtime bootstrap file, and `openclaw doctor --fix` archives an old one and merges customised content into that section. That section is still only guidance; skills define how tools work, and tool policy decides which tools exist. ## Other files you will meet - `BOOTSTRAP.md` is a one-time first-run ritual, deleted once the workspace looks configured. - `BOOT.md` is an optional startup checklist run by a hook at Gateway start. - `MEMORY.md` and the daily `memory/YYYY-MM-DD.md` logs belong to the memory subject, not to the always-loaded persona files described here. Two practical notes complete the picture. Not every session receives all four files: sub-agent sessions keep only `AGENTS.md`, and cron sessions get `AGENTS.md`, `SOUL.md`, `IDENTITY.md` and `USER.md` but not root memory. And edits are live: a change to one of these files is picked up on a later turn of a long-lived session, with no Gateway restart. The **Settings → Agents → Files** page of the Control UI edits the same files on the Gateway host.

  • Where do local notes such as SSH hosts and camera names go now that TOOLS.md is retired?
    In the `## Tools` section of `AGENTS.md`. In 2026.9.9 `TOOLS.md` is not a recognised runtime bootstrap file; `openclaw doctor --fix` archives an old workspace `TOOLS.md` and merges customised content into that section. The notes stay guidance: skills describe how tools work, and tool policy decides which tools are available.
  • How does the name chosen in IDENTITY.md reach what a channel displays?
    `IDENTITY.md` is what the agent reads about itself. Channels and the Control UI display the identity stored in agent config, which `openclaw agents set-identity --from-identity` fills by reading the file's Name, Theme or Creature or Vibe, Emoji and Avatar lines. The first-run ritual persists the chosen identity both ways.
  • Can a rule in SOUL.md or AGENTS.md stop the agent from running a shell command?
    No. Both files are prompt guidance that makes the model less likely to try. Whether a command can run is decided at runtime by tool policy, exec approvals and sandboxing, and the system prompt itself tells the model to let those gates decide.

  • Security rules and tool permissions belong in SOUL.md.
  • A rule written in AGENTS.md blocks the agent from running a command.
  • USER.md is a running log of everything the owner has ever said.
  • Local tool notes still belong in a separate TOOLS.md file.
  • IDENTITY.md decides which model the agent runs on.

Assumes OpenClaw 2026.9.9, where TOOLS.md is retired into the ## Tools section of AGENTS.md and USER.md has a fixed 4,000-character cap.

open as a page

In OpenClaw, how does BOOTSTRAP.md differ from BOOT.md, and when does each one run?

level: middleimportance: should knowfreq 8%

basics

~20 s

BOOTSTRAP.md is a one-time first-run ritual for a brand-new workspace, deleted once the workspace looks configured. BOOT.md is an optional startup checklist that the disabled-by-default boot-md hook runs as an agent turn on every Gateway start.

open as a page

How do you back up an OpenClaw workspace in a private git repository, and what must stay out of it?

level: middleimportance: should knowfreq 9%

basics

~20 s

Commit the workspace (default ~/.openclaw/workspace: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, memory/) to a private remote. Keep ~/.openclaw/ out of it, including openclaw.json, credentials/ and the SQLite databases, and put no API keys or tokens in workspace files.

open as a page

In OpenClaw, what does injecting the workspace bootstrap files cost on every run, and what happens when one exceeds bootstrapMaxChars?

level: seniorimportance: should knowfreq 6%

basics

~20 s

By default, bootstrap files are injected into the system prompt on every run, so their size is paid each turn. Each file is capped by agents.defaults.bootstrapMaxChars (20000) and all together by bootstrapTotalMaxChars (60000); USER.md has a fixed 4,000 cap. Oversized files lose their middle.

open as a page

An OpenClaw assistant's replies drift away from the tone in SOUL.md and it keeps forgetting the owner's time zone — what do you check and change?

level: seniorimportance: should knowfreq 5%

basics

~20 s

Confirm the SOUL.md you edited is in the agent's resolved workspace and injected whole and uncontradicted, using openclaw agents list and /context list. The time zone comes from agents.defaults.userTimezone, which falls back to the Gateway host's zone, not from USER.md prose.

open as a page

When one OpenClaw Gateway serves a small, mutually trusting team, how should you govern its bootstrap files — shared rules, personal USER.md files, review and secrets?

level: principalimportance: nice to knowfreq 3%

basics

~20 s

Treat AGENTS.md and SOUL.md as shared, reviewed team policy in a private repo; give each person a personal USER.md that overlays the shared one; keep secrets out. Personal files select prompt context but do not hide data, so separate untrusted people onto separate Gateways.

open as a page