OpenClaw AGENTS.md: Build Rules Your Agent Won't Forget

Key takeaways

• OpenClaw's AGENTS.md is a persistent system prompt layer loaded every session, not a coding-project description file like Codex or Copilot use
• Rules that survive compaction need context, consequences, and origin stories ("this rule exists because...")
• The bootstrap file family (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md) divides responsibility so no single file becomes unmanageable
• Session routing tables, memory architecture, and security constraints belong in AGENTS.md. Personality and humor belong in SOUL.md.
• Every AGENTS.md grows into a ball of mud without active pruning. Read yours fresh every few weeks.

OpenClaw AGENTS.md vs coding-agent AGENTS.md: what's different

If you search "how to write AGENTS.md" right now, every result is about coding agents. GitHub's analysis of 2,500 public repositories found six areas that make a good coding AGENTS.md: commands, testing, project structure, code style, git workflow, and boundaries. That's solid advice for Codex, Copilot, or Cursor.

It'll produce a bad OpenClaw AGENTS.md.

OpenClaw (previously known as Clawdbot and Moltbot) isn't a coding assistant. It's a personal AI operator that runs 24/7, manages cron jobs, sends messages across channels, handles files, and makes decisions on your behalf. Its AGENTS.md doesn't describe a codebase. It defines how a persistent agent behaves across sessions, what it remembers, where it routes work, and what it's not allowed to do.

Here's the difference in practice:

The coding version tells the agent about your project. The OpenClaw version tells the agent how to be your agent. OpenClaw's own codebase has a coding-agent AGENTS.md for its contributors. Its operator agent runs a completely different file.

OpenClaw bootstrap files: what loads and when

AGENTS.md isn't the only file OpenClaw reads at session start. It's part of a family of bootstrap files that each handle a different responsibility. Understanding this split is how you avoid stuffing everything into one file.

Every file in this family gets injected into the agent's context at the start of each session. That's the key property. Whatever you put in AGENTS.md reloads fresh every time, even after compaction wipes earlier conversation history.

Why does the split matter? Each file has different change frequency and different concerns. SOUL.md changes when you refine your agent's personality. TOOLS.md changes when you add a new API endpoint. AGENTS.md changes when you discover a behavioral failure that needs a permanent rule.

OpenClaw bootstrap file size limits

OpenClaw truncates bootstrap files at 20,000 characters per file and 150,000 characters total by default. You can adjust these with bootstrapMaxChars and bootstrapTotalMaxChars in your config.

That sounds generous, but it adds up fast. If your AGENTS.md hits 18,000 characters and your SOUL.md is 8,000, you're already using 26,000 of your per-file budget across two files. The total budget matters more when you have six or seven files all contributing.

AGENTS.md section anatomy: what to include

A production OpenClaw AGENTS.md typically contains these sections. Not every setup needs all of them, but this is the pattern that works after months of iteration.

Core rules

Numbered, specific, testable. Each rule should be something you can point to and say "the agent violated rule 3" or "the agent followed rule 3." Vague directives like "be helpful" or "be thorough" don't qualify.

1. Config claims require proof.
   If you claim something is configurable, point to the exact config path.
   If you can't find the key, treat it as a runtime restriction.
 
2. Intent confidence must be high before acting.
   If confidence is below 90% for a task with side effects,
   restate your understanding and ask for confirmation.

Tripwire rules

These are the rules that actually stick. More on these in the next section.

Memory system

Defines the three-layer architecture: AGENTS.md for permanent rules, daily notes for raw capture, MEMORY.md for synthesized patterns. Specifies where each type of information goes and how synthesis works.

Session routing table

Maps task types to specific groups or sessions. Without this, the agent asks where to route output every single time.

Security and data classification

Data tiers, PII handling, secrets management, context-aware restrictions.

Style bans

Hard vocabulary bans, punctuation rules, formatting constraints. These are mechanical rules the model can follow reliably.

Source of truth table

Tells the agent which file is canonical for which topic. Without this, the agent doesn't know whether to update AGENTS.md, TOOLS.md, or MEMORY.md when it learns something new.

Tripwire rules in OpenClaw: writing rules your agent follows

Most rules you write for an AI agent will get ignored. Not because the model is defiant. It just doesn't have enough context to know the rule matters, so it pattern-matches its way past it.

Tripwire rules fix this by embedding three things: what happened, what the rule requires, and why it exists. The "why" is the part that makes enforcement work. It gives the model a concrete scenario to match against instead of an abstract instruction to weigh.

Here's a rule that doesn't work:

Always answer questions promptly.

Here's one that does:

2. Answer the question first.
   When Chris asks a direct question, answer it before doing anything else.
   Do not continue running background work, spawning subagents, or
   executing fixes while leaving the question unanswered.
 
   This rule exists because Chris had to ask the same question four times
   before getting an answer. That is never acceptable.

The difference isn't length. It's specificity. The first version is an aspiration. The second version describes a failure mode the model can recognize: "Am I currently doing background work while a question sits unanswered? That matches the pattern this rule describes."

The compaction test

Before adding any rule to AGENTS.md, ask: "Will this fix survive compaction and session boundaries?" If the answer is no, it's not a fix. Write it to a file.

Rules stated only in conversation disappear when the context window fills up and older messages get compacted. Rules in AGENTS.md reload at every session start. That's the entire point of the file.

What makes tripwire rules work

Looking at rules that actually change agent behavior, they share three properties:

1. They describe a specific failure. Not "be careful with data" but "never surface financial figures in group contexts with non-owner participants."
2. They include consequences. Not just what to do, but what goes wrong if the rule is broken.
3. They have an origin story. "This rule exists because..." gives the model a concrete incident to generalize from.

Rules without these properties tend to erode within a few exchanges. The model follows them initially, then drifts back to its defaults as the conversation accumulates more context.

OpenClaw memory architecture: what goes in AGENTS.md vs MEMORY.md

Memory doesn't survive sessions. Files are the persistence layer. That's the first line of a good memory section, and it's the most important thing to internalize about OpenClaw's design.

The memory architecture has three layers, each with a different purpose:

The flow works like this: things happen during sessions. A nightly cron job reads session histories and writes daily notes. Periodically, you (or the agent) review recent daily notes and promote durable patterns into MEMORY.md. Rules that need enforcement go into AGENTS.md.

Here's what goes where:

• "Always check Lantern board before creating duplicate tasks" belongs in AGENTS.md because it's an operating rule that should be enforced every session.
• "Chris prefers blunt critique for ideas" belongs in USER.md because it's a user preference, not an agent operating rule.
• "On March 3, we published the ai-code-liability article" belongs in daily notes because it's a timestamped event.
• "Blog articles with specific OpenClaw error messages get 10x the traffic of generic 'best tools' posts" belongs in MEMORY.md because it's a synthesized insight from multiple data points.

Mixing these up is the most common AGENTS.md failure mode after bloat. What happens when daily events land in AGENTS.md? The file grows without bound. And when permanent rules land in MEMORY.md, they get diluted by less important content.

Session routing tables: stop your agent from asking where to send things

Without a routing table, the agent makes a guess every time it needs to route work. Sometimes it guesses right. Often it asks you, which defeats the purpose of having an autonomous agent.

So what does a routing table actually look like? It maps task categories to destinations:

| Group | Route here when... |
|-------|-------------------|
| Molty Core | Building/fixing capabilities, new skills |
| Molty Strategy | Business strategy, content calendar |
| Stack-Junkie.com | Site deployments, uptime, hosting |
| Molty Juniper (DM) | Quick tasks, status checks, casual one-offs |

The table doesn't need to be complex. It needs to cover the 80% case. The agent will still ask about ambiguous situations, but it won't ask about the obvious ones.

Two implementation notes. First, add a deference rule: "If Chris directs a task in any chat, do it there. Do not argue or insist on routing." People don't always use the "right" channel, and the agent shouldn't fight about it. Second, pair this with the right gateway bindings configuration so messages actually reach the intended agent.

OpenClaw AGENTS.md security: data classification and PII rules

Security rules in AGENTS.md aren't optional hardening. They're the behavioral constraints that prevent your agent from leaking data it has access to.

A three-tier classification system works well for most setups:

Confidential (protect from non-owner contexts): financial figures, personal contact details, deal values, contract terms. Never surface these in group chats where non-owner participants might be present.

Internal (group chats OK, no external sharing): strategic notes, tool outputs, project tasks, system health data. Fine to discuss in your own groups. Not for forwarding to external channels.

Restricted (external only with explicit approval): everything else defaults here. The agent needs you to say "share this" before content leaves internal channels.

PII and secrets handling

Add explicit rules for outbound PII scanning. Personal email addresses, phone numbers, and dollar amounts should be flagged before the agent includes them in messages.

For secrets management, the rule is simple: the agent should only share secrets from local config files when you explicitly request a specific secret by name and confirm the destination. No bulk secret dumps. No proactive sharing. If the agent is about to send outbound content, it should redact anything that looks like an API key, bearer token, or auth header.

Can you state these rules in conversation instead? You can, but they'll vanish after compaction. Put them in AGENTS.md so they apply every session, across every context.

OpenClaw AGENTS.md size: the instruction budget problem

There's a tension specific to OpenClaw operator configs. Coding-agent wisdom says keep your AGENTS.md as small as possible. That's correct for a file describing one codebase. An OpenClaw AGENTS.md has more ground to cover: memory architecture, routing, security, style rules, and whatever tripwires you've accumulated.

Research suggests frontier models reliably follow roughly 150-200 instructions. Past that, enforcement drops. Every token in your config loads on every request regardless of relevance. A 15,000-character AGENTS.md means 15,000 characters of context consumed before your first message.

The practical tradeoff: you need enough rules to cover the failure modes that actually cost you something. Time, data, trust. But not so many that the model starts ignoring rules because there are too many to track.

What to cut:

• Rules that duplicate what the model already does by default
• Rules from incidents that can't happen anymore (the system changed)
• Rules that have never triggered in production
• Information that belongs in a different bootstrap file

What to keep:

• Rules born from real failures
• Security constraints that prevent data leaks
• Routing tables (small, high-value)
• Memory architecture definition (the agent needs to know where to write)

AGENTS.md maintenance: avoid the ball of mud

Here's the natural lifecycle of every AGENTS.md. The agent does something wrong. You add a rule. It does something else wrong. You add another rule. Six months later you have 300 lines of rules, half of which reference systems that no longer exist.

The aihero.dev analysis calls this the "ball of mud" pattern and notes that stale documentation poisons LLM context worse than it poisons human developer context. A human developer reads stale docs with skepticism. An LLM reads them as ground truth on every single request.

When to add a rule

Add a rule when:

• A failure actually cost something (time, trust, data, a bad external message)
• The failure will recur without the rule (it's not a one-off typo)
• No existing rule covers the failure mode
• The rule can be stated as a testable constraint, not an aspiration

Don't add a rule when:

• You're annoyed but nothing actually broke
• The fix is a one-time correction that won't recur
• Another file (SOUL.md, USER.md, TOOLS.md) is the right home for the information

When to prune

Every few weeks, read your AGENTS.md fresh. For each rule, ask:

• Has this rule triggered in the last month?
• Does the system this rule references still exist?
• Would I add this rule today if starting from scratch?
• Is this rule duplicated in another file?

If the answer to all four questions is no, cut it. Err on the side of removing. You can always add a rule back after a failure. Try cutting aggressively for one week and see what actually breaks. You can't undo the attention cost of 50 stale rules.

Version control

OpenClaw's official docs recommend git-backing your workspace. Do it. When you prune aggressively and something breaks, you want to recover the rule you cut.

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md USER.md TOOLS.md
git commit -m "workspace snapshot"

Common OpenClaw AGENTS.md mistakes

Putting personality in AGENTS.md. Tone, humor, and voice belong in SOUL.md. AGENTS.md is for operating rules. Mixing them makes both files harder to maintain and harder for the model to prioritize.

Writing aspirational rules. "Always be thorough" is an aspiration. "Check the Lantern board before creating a task to avoid duplicates" is a constraint. Models follow constraints. They approximate aspirations.

Duplicating information across files. If your API endpoint is in both AGENTS.md and TOOLS.md, they'll eventually diverge. Pick one canonical location and reference it. The source-of-truth table in AGENTS.md exists for this reason.

No routing table. Without routing, the agent either guesses wrong or asks you every time. Both waste time. A 10-line routing table saves hundreds of unnecessary questions.

No source-of-truth table. The agent needs to know which file to update when it learns something new. Without this, it writes user preferences into AGENTS.md, tool configs into MEMORY.md, and nobody can find anything.

Ignoring truncation limits. Your file loads silently truncated at 20,000 characters. The rules near the end of a long file might never reach the model. Put your most important rules first. Check your file size periodically.

Never pruning. The most dangerous AGENTS.md is the one that's been growing for months without review. Stale rules don't just waste tokens. They actively mislead the model about what's important.

Start small, add rules from failures

Your first AGENTS.md should be short. A routing table, a memory section, a few security rules. That's enough. The file grows from failures, not from planning. When the agent does something wrong and the fix needs to survive session boundaries, that's when you add a rule.

The whole point of AGENTS.md is that your agent reads it fresh every session. Rules in conversation vanish after compaction. Rules in AGENTS.md persist. Build the file around that property and you'll end up with an agent that actually remembers how to behave.

FAQ

What is AGENTS.md in OpenClaw?

AGENTS.md is a workspace file that OpenClaw loads at the start of every agent session. It contains operating instructions, behavioral rules, memory architecture, session routing, and security constraints. Unlike coding-agent AGENTS.md files used by Codex or Copilot, OpenClaw's version configures a persistent AI operator, not a code assistant.

Does OpenClaw AGENTS.md survive context compaction?

Yes. OpenClaw reloads AGENTS.md fresh at the start of every session, so its rules persist even after compaction removes older conversation history. Rules you state only in conversation will be lost during compaction, but rules in AGENTS.md reload automatically. That's the primary reason to put important rules in the file rather than saying them in chat.

How long should an OpenClaw AGENTS.md file be?

OpenClaw truncates bootstrap files at 20,000 characters per file by default, configurable via bootstrapMaxChars. Frontier models reliably follow roughly 150-200 instructions. A production AGENTS.md typically runs 4,000 to 15,000 characters. Going beyond that risks rules being ignored or silently truncated.

What is the difference between AGENTS.md and SOUL.md in OpenClaw?

AGENTS.md handles operating instructions: rules, memory system, routing, security, and style bans. SOUL.md handles personality: tone, humor, boundaries, and persona. Putting personality rules in AGENTS.md or operating rules in SOUL.md causes both files to become bloated and less effective at their primary job.

How do you write OpenClaw AGENTS.md rules that the agent actually follows?

Write rules as specific, testable constraints with context. Include what happened that caused the rule ("this rule exists because..."), what the rule requires, and what failure looks like. Vague rules like "always be thorough" get ignored. Specific rules like "answer the question before continuing background work" get enforced because they describe a recognizable failure mode.

Evidence and methodology

This article draws from three types of sources. Primary: OpenClaw's official documentation on agent workspaces and bootstrap file loading. Secondary: published analyses of AGENTS.md patterns, including GitHub's 2,500-repo study and aihero.dev's instruction budget research. Practical: our own production AGENTS.md, which has been running daily since February 2026 across multiple session types and channels.

The tripwire rule examples and section anatomy are taken directly from a working configuration. The distinction between coding-agent and operator-agent AGENTS.md files is based on comparing OpenClaw's own codebase AGENTS.md (coding style) against the operator AGENTS.md that runs on our production agent.

Related resources

• OpenClaw persistent memory guide: covers the memory system in depth
• OpenClaw cron jobs automation guide: scheduling the daily memory cron
• OpenClaw security hardening playbook: security rules beyond AGENTS.md
• OpenClaw CLI commands reference: the commands your AGENTS.md routing table references
• OpenClaw DM policy explained: DM policy configuration that pairs with AGENTS.md security rules
• Fix OpenClaw context loss: savestate and resume, the compaction problem AGENTS.md solves

Changelog

• 2026-03-09: Initial publication