Your agent has a voice and a memory. Now it needs a rulebook. AGENTS.md defines how your agent operates — priorities, tool policies, delegation patterns, and the guardrails that make autonomy safe.
AGENTS.md is described in the docs as “operating instructions for the agent and how it should use memory.” The key word is operating — this file governs mechanics, not personality.
Priorities, workflows, escalation procedures, and how the agent handles specific situations.
Guardrails that prevent destructive actions without explicit confirmation from the user.
How to read memory at startup, what order to check files, and what’s worth remembering.
“Keep AGENTS.md for operating rules. Keep SOUL.md for voice, stance, and style.” If it’s about how the agent sounds, it goes in SOUL.md. If it’s about how the agent behaves, it goes in AGENTS.md.
AGENTS.md is the first file your agent reads at session start. It sets the behavioral frame before personality, identity, or memory.
| AGENTS.md | SOUL.md | |
|---|---|---|
| Purpose | Operating instructions, rules, memory guidance | Persona, tone, voice, boundaries |
| Content Type | Mechanical: workflows, priorities, tool usage | Expressive: short beats long, sharp beats vague |
| Loaded In | All sessions + sub-agents | Normal sessions only |
| Sub-Agents See It? | Yes — always | No — filtered out |
| Example | “Always confirm before sending emails” | “Be concise and direct” |
Sub-agents only receive AGENTS.md and TOOLS.md — all other bootstrap files are filtered out to keep sub-agent context small. Your operating rules reach everywhere. Your personality stays in the main session.
Never paste file trees or credentials into a conversation. Directories and secrets stay out of chat.
No deleting files, overwriting data, or irreversible operations without explicit user confirmation.
When composing for Telegram, WhatsApp, or Discord, send the complete message — never stream fragments to external surfaces.
When a session begins, the agent reads context in this order:
The default template is described as a “personal assistant variant.” You don’t have to use it as-is — it’s the baseline your agent starts from. Today you’ll make it yours.
A sub-agent is a background agent run spawned from an existing agent run. Think of it like delegating a task to an assistant who works independently and reports back when done.
Each sub-agent gets its own context window and token usage. It only receives AGENTS.md and TOOLS.md — no personality, no identity, no full conversation history.
Spawning is non-blocking — you get a run ID back immediately and the main agent keeps working. No waiting around for the sub-agent to finish.
When a sub-agent finishes, it announces a summary or result message back to the requester’s chat channel automatically.
Sub-agents inherit AGENTS.md and TOOLS.md only. SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, and BOOTSTRAP.md are all filtered out.
Running /stop in the requester chat cascades to abort all sub-agents and their nested children. One command stops the entire delegation tree.
/subagents list — Show all current runs/subagents kill — Terminate a specific run or all/subagents log — View output (filterable)/subagents info — Metadata: model, runtime, tokens/subagents send — Message a running sub-agent/subagents steer — Give direct guidance to change coursemaxSpawnDepth ≥ 2Maximum nesting depth is 5, but the docs recommend 2.
Set maxSpawnDepth: 2 to enable a coordinator that spawns workers. Main agent → coordinator → workers. This is the recommended pattern for complex multi-step tasks.
| Setting | Default |
|---|---|
| maxSpawnDepth | 1 |
| maxChildrenPerAgent | 5 |
| maxConcurrent | 8 |
| archiveAfterMinutes | 60 |
Deny always wins. If a tool appears in both an allow list and a deny list, it’s denied. No exceptions. No overrides.
Each layer can tighten what’s available. Deny at any layer blocks the tool everywhere below.
| Group | Covers |
|---|---|
| group:runtime | exec, process, code execution |
| group:fs | read, write, edit, apply_patch |
| group:sessions | session management |
| group:memory | search and retrieval |
| group:web | web operations |
Allow or deny entire groups instead of listing individual tools.
Determines where tools execute. Modes:
Configurable globally or per-agent in openclaw.json.
Determines which tools are available. The allow/deny cascading system.
/exec cannot bypass a denied toolThe escape hatch. Determines who can override.
/elevated on — exec outside sandbox/elevated full — skip exec approvalSandbox = where. Tool Policy = which. Elevated = who can override. They operate independently because they control different dimensions. No conflicts.
~/.openclaw/agents/<id>/sessionsNever reuse agentDir across agents. Shared agentDir causes auth and session collisions. Each agent must have its own isolated state directory.
Routing determines which agent handles which conversation:
If multiple bindings match in the same tier, first in config order wins.
AGENTS.md is injected in every session type — main sessions and sub-agent sessions. A bloated AGENTS.md taxes every interaction and every delegation spawn.
bootstrapMaxChars)bootstrapTotalMaxChars)once (default), always, or off/status — Quick context window fullness check/context list — Every injected file with raw vs injected sizes, truncation status/context detail — Per-file and per-tool breakdowns for full auditSub-agents already skip SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, and BOOTSTRAP.md. AGENTS.md is one of only two files they receive, so keeping it concise benefits delegation costs disproportionately.
Open ~/.openclaw/workspace/AGENTS.md and read through what’s there. Identify the three safety defaults and the startup read order. This is your baseline.
Run /subagents spawn main "Summarize my last 3 daily memory files" in chat. Then use /subagents list and /subagents log to see the result.
Run /context list and /context detail to see how much each bootstrap file contributes. Pay attention to AGENTS.md specifically.
Something specific to your workflow: “always write code in TypeScript,” “summarize articles before responding,” or “never use exec without confirmation.” Test it in a new session.
Your agent has rules, guardrails, and the ability to delegate. Day 10 is where you extend its capabilities — built-in tools, custom Skills, ClawHub marketplace, and building your own integrations. From consumer to creator.