The Markdown files that configure your OpenClaw agent

June 28, 2026Claworc Team

Tags:tips

One of the nicest things about OpenClaw is that you don’t configure your AI agent through code or a maze of opaque settings. You should pay the most attention to editing a few plain Markdown files to shape how your agent thinks, speaks, and behaves.

This post walks through each file, what it’s for, and what belongs where.

Where the files live

Open your instance in Claworc and click the Files tab, then navigate to .openclaw → workspace (the default directory). Click any file to view it, see exactly what goes into your agent’s context.

There’s a fixed set of these “bootstrap” files. Here’s the whole cast at a glance:

File	What it does
AGENTS.md	The operating manual — rules and behavior
SOUL.md	Personality, voice, and tone
IDENTITY.md	Structured identity (name, emoji, vibe, avatar)
USER.md	Profile of the human the agent serves
TOOLS.md	Your notes about local tools and devices
HEARTBEAT.md	Checklist for periodic background check-ins
BOOTSTRAP.md	First-run setup ritual (deletes itself)
MEMORY.md	Long-term curated memory

Let’s go through them.

AGENTS.md — the operating manual

AGENTS.md is the heart of the configuration. It’s injected into nearly every session and acts as your agent’s contract. A good AGENTS.md covers the startup ritual (what to read first), the memory policy (what to record and where), “red lines” the agent must never cross, and how to behave in group chats.

Because it’s almost always in the prompt, it’s your most direct lever over day-to-day behavior. OpenClaw seeds it from a template when the workspace is created, but from then on it’s yours to maintain — the agent doesn’t normally rewrite its own manual.

What goes here: rules, safety boundaries, and the routines you want followed every session.

SOUL.md — give your agent a personality

SOUL.md defines the persona: voice, character, tone. This file is special — when OpenClaw sees it, it adds an explicit instruction telling the model to embody its persona, avoid stiff generic replies, and follow this guidance. It’s the single file that stops your agent from sounding like a default chatbot.

You write the persona. Some people let the agent help refine its own SOUL.md over time, but the file is yours to control. Keep it under roughly 20,000 characters — beyond that OpenClaw trims it.

What goes here: how your agent should sound and behave, its character and quirks.

IDENTITY.md — the agent’s name badge

IDENTITY.md is unusual because it’s both injected as text and parsed structurally. OpenClaw reads simple key-value lines like - Name: ... and extracts fields such as name, emoji, creature, vibe, theme, and avatar. Those values power dashboards and anywhere your agent’s identity is displayed.

It’s mostly written by the agent itself during the first-run setup ritual, but you can edit it directly anytime to rename or restyle your agent.

What goes here: the agent’s name, emoji, and visual identity — usually as short key-value lines.

USER.md — knowing the human

USER.md is the profile of the person the agent works for: your name, pronouns, timezone, ongoing projects, and preferences — anything that helps the agent serve you better.

This is a shared, living document. OpenClaw encourages the agent to update it over time as it learns about you, and you can edit it directly too. The more it knows, the better the personalization.

What goes here: facts about you that make the agent’s help more relevant.

TOOLS.md — notes, not switches

A common misconception: TOOLS.md does not turn tools on or off. It’s just notes for the agent on how to use the tools it already has. Record the practical specifics the model can’t guess — camera names, SSH hostnames, device nicknames, voice preferences, and so on.

This one is largely user-maintained. Update it as your devices and setup change.

Note

Claworc writes into TOOLS.md too. When it provisions an instance, it adds its own instructions for the tools it provides — like browser control — so your agent knows how to drive them from the start. Your own notes live right alongside what Claworc adds.

What goes here: local context and how-to notes for the tools and devices your agent touches.

HEARTBEAT.md — background check-ins

OpenClaw agents can run on a heartbeat — a scheduled ping that wakes the agent to do periodic background work. HEARTBEAT.md is the checklist it follows. During these lightweight runs OpenClaw injects only this file and strips the rest, which keeps token cost low.

Because it loads on every heartbeat, keep it short and focused. You author it.

What goes here: a small, focused list of things to check on each background pass.

BOOTSTRAP.md — the first-run ritual

BOOTSTRAP.md appears only when a brand-new workspace is created. It guides the agent through introducing itself, getting to know you, and filling in IDENTITY.md and USER.md. Once setup is done, the agent deletes it — it’s a one-time onboarding script you’ll rarely touch.

MEMORY.md — long-term memory

MEMORY.md is the agent’s curated long-term memory: the facts, decisions, and context worth carrying across sessions. The agent curates it according to the policy in AGENTS.md, and you can prune or correct it by hand. OpenClaw treats memory carefully — during context cleanup it marks files like MEMORY.md, SOUL.md, and AGENTS.md as read-only so they’re never accidentally overwritten.

Alongside that single file, OpenClaw keeps a memory/ folder of dated daily notes named YYYY-MM-DD.md (or YYYY-MM-DD-<slug>.md). These hold the granular day-to-day material — observations, session summaries, and raw context that might be useful later. Today’s and yesterday’s notes load automatically; the rest stay searchable without being injected into every turn. If MEMORY.md outgrows its budget OpenClaw trims it, so the idea is to keep the curated file lean and let the detail live in the dated notes.

MEMORY.md is also just the default memory layer — OpenClaw can swap the whole engine for something more capable:

• Builtin (default) — SQLite-based, with keyword, vector, and hybrid search out of the box.
• QMD — a local-first sidecar that adds reranking, query expansion, and indexing of directories outside the workspace.
• Honcho — AI-native cross-session memory with user modeling, semantic search, and multi-agent awareness.
• LanceDB — LanceDB-backed memory with OpenAI-compatible embeddings, auto-recall, auto-capture, and local Ollama embeddings.

There’s also memory-wiki, which augments memory with a provenance-rich wiki vault — claims, dashboards, and Obsidian-friendly workflows.

What goes here: durable facts and decisions the agent should remember long-term; let the dated daily notes carry the granular detail.

A quick note on who reads what

Not every session loads every file. OpenClaw tailors injection to the run type to control relevance and cost:

• Main chat (you talking to your agent): all the files load.
• Subagents and scheduled tasks: a leaner set — AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md — while heartbeat, bootstrap, and memory are left out.
• Heartbeat runs: only HEARTBEAT.md.

The practical takeaway: keep your files lean. Everything competes for the model’s context budget, so concise files mean more room for actual work and lower token cost.

The takeaway

OpenClaw’s design is refreshingly transparent: your agent is configured by Markdown you can read and edit. AGENTS.md sets the rules, SOUL.md gives it character, IDENTITY.md and USER.md ground it in identity and relationship, MEMORY.md provides continuity, and HEARTBEAT.md and BOOTSTRAP.md handle lifecycle moments. To customize your agent, you don’t need to write code — you just need to write Markdown.