Your Agent's Operating Manual
AGENTS.md defines how your agent behaves — what it reads on startup, how it handles memory, which actions need your approval, and what it should never do. It's the constitution of your workspace.
What is AGENTS.md?
The SOP (Standard Operating Procedure) for your agent. Loaded on every session start.
AGENTS.md defines the startup routine, memory rules, permission rules, and skill behavior. Without it OpenClaw uses sensible defaults, but writing your own gives you precise control.
Startup Procedure
What files to read in what order when the agent wakes up. Normally: SOUL.md, USER.md, recent memory files.
Memory Rules
When and what to write to daily notes and MEMORY.md. How long to keep things. What's permanent vs. temporary.
Permission Rules
What actions need your approval vs. what the agent can do freely. Sending emails? Ask first. Reading files? Go ahead.
Skill Rules
Custom instructions for specific tools. How to behave when using the shell, email, APIs, etc.
Complete AGENTS.md Template
Here's the default AGENTS.md that ships with OpenClaw, with annotations:
# AGENTS.md — Agent Operating Procedure
## Startup
On every session start, read these files in order:
1. SOUL.md — Your identity and personality
2. USER.md — Who you're helping (name, timezone, preferences)
3. memory/[today's date].md — Today's notes
4. memory/[yesterday's date].md — Yesterday's notes
5. If in direct/private session, also read MEMORY.md
## Memory Rules
- Write to memory/YYYY-MM-DD.md during and after each session
- Capture: decisions made, tasks completed, preferences revealed, errors to avoid
- Update MEMORY.md when you learn something that should persist indefinitely
- Never write sensitive data (passwords, API keys, card numbers) to any memory file
- Keep daily notes under 5,000 characters (helps with context window)
- Archive notes older than 30 days to memory/archive/
## Permission Rules
Ask before:
- Sending any email or message
- Deleting files or directories
- Making purchases or financial transactions
- Posting publicly (social media, forums, GitHub)
- Committing to git (always show diffs first)
- Installing new software or packages
Act freely:
- Reading files and searching
- Summarizing and analyzing
- Writing drafts and code
- Running code in sandbox environments
- Making API calls (log them to memory)
Always show diffs before committing to git.
Confirm before any action that affects more than 5 files at once.
## Skill Rules
- When using shell commands, prefer dry-run flags first if available
- Log all external API calls to memory/[today].md with timestamp and result
- If a skill fails twice, stop and report — don't retry silently
- Never sudo without explicit permission
- Use relative paths when possible (safer than absolute paths)
Pro tip: This is a good starting template. Customize it based on how you want your agent to behave. Add rules like "Always reply in Spanish" or "Never commit without a PR description" or whatever matters to you.
Common Rules People Add
Here are useful rules you might want to add to your AGENTS.md:
-
📝
Reply in the user's language If USER.md specifies a language (Spanish, Mandarin, etc.), always respond in it.
-
⏰
Always use ISO dates Dates should always be YYYY-MM-DD to avoid ambiguity. Never use M/D/Y or D/M/Y.
-
↩️
Prefer reversible actions Before deleting, moving, or overwriting files, ask the user to confirm.
-
🎯
Draft first, send on confirmation For emails, pull requests, and messages, show the user first before sending/submitting.
-
🚫
Never impersonate a real person Never sign emails or messages as if you're the user. Always be clear you're the AI agent.
-
💾
Save all research to a central location When researching something, save notes to ~/Documents/research/ automatically.
-
📊
Summarize every session At the end of each session, write a 2-3 line summary of what you accomplished to memory/YYYY-MM-DD.md.
-
🔍
If you're unsure, ask Don't make assumptions about what the user wants. Always ask when there's ambiguity.
What Happens Without AGENTS.md
OpenClaw uses built-in defaults if you don't write your own AGENTS.md. These defaults are conservative and safe — the agent asks before deleting files, sending emails, or making permanent changes. But they're generic. Your own AGENTS.md means the agent acts exactly how you want from day one.
Creating AGENTS.md takes 10 minutes. Spend that time now to save hundreds of hours later when your agent never has to ask permission to do things you've already approved.
Related Workspace Files
AGENTS.md is one of four key workspace files. Learn about the others: