OpenClaw AGENTS.md Guide: Define Your AI Agent's Operating Contract
AGENTS.md defines your OpenClaw agent's operating rules, security constraints, and multi-agent coordination protocols. It has the highest override priority of any configuration file — when AGENTS.md conflicts with SOUL.md, AGENTS.md wins. This file controls what your agent can and cannot do, making it critical for safety and compliance.
Quick Answer: AGENTS.md is the top-level operating contract for an OpenClaw AI agent. It is a plain Markdown file in your workspace directory (~/.openclaw/workspace/AGENTS.md) that defines what the agent should and shouldn't do, its priorities, operational boundaries, workflow steps, and quality standards. It sits at the top of OpenClaw's identity architecture — above SOUL.md, IDENTITY.md, USER.md, and MEMORY.md.
No database, no external API, no proprietary format. Just Markdown you can edit with any text editor and version-control with Git. Trusted by 194+ business owners to run safe, reliable AI agents.
What Is AGENTS.md?
Think of AGENTS.md as the job description for your AI agent. It tells the agent what to do, what not to do, and how to do it well.
Priorities
Define what matters most. Which tasks come first? What goals should the agent optimize for? Priorities prevent your agent from getting sidetracked.
Boundaries
Set explicit limits. What actions are off-limits? What data should never be shared? Boundaries keep your agent safe and predictable.
Workflow and Quality
Describe step-by-step processes and quality standards. How should the agent handle tasks? What does 'done' look like? Workflows ensure consistency.
Plain Markdown, Full Control
AGENTS.md is a plain .md file stored at ~/.openclaw/workspace/AGENTS.md. There is no proprietary format, no database, and no external API dependency. You can edit it with VS Code, Vim, Notepad, or any text editor. Because it is a standard file, you can version-control it with Git, share it across teams, and roll back changes at any time.
How AGENTS.md Fits Into OpenClaw's Identity Architecture
OpenClaw uses a layered system of Markdown files. AGENTS.md sits at the top as the operating contract. Each file has a distinct role.
AGENTS.md
Operating ContractThis GuidePriorities, boundaries, workflow rules, and quality standards. The top-level 'job description' for the agent.
SOUL.md
PhilosophyCore values, reasoning approach, and ethical principles. How the agent thinks and makes decisions.
IDENTITY.md
PresentationCommunication style, tone of voice, and personality traits. How the agent speaks and presents itself.
USER.md
PreferencesUser-specific preferences, context, and working style. Tailors the agent to the individual user.
MEMORY.md
Long-term NotesPersistent context, learned facts, and accumulated knowledge. The agent's long-term memory store.
Additional configuration files include TOOLS.md (tool configuration), HEARTBEAT.md (scheduler), and BOOT.md / BOOTSTRAP.md (initialization). All are plain Markdown.
AGENTS.md vs SOUL.md: What's the Difference?
These two files are the most commonly confused. They serve very different purposes.
AGENTS.md — The Job Description
- Defines what the agent does and doesn't do
- Sets operational priorities (task A before task B)
- Establishes boundaries (never do X)
- Describes workflow steps and processes
- Sets measurable quality standards
- Answers: "What is your job?"
SOUL.md — The Personality
- Defines how the agent thinks and reasons
- Sets core values and ethical principles
- Shapes decision-making philosophy
- Guides tone when instructions are ambiguous
- Provides underlying motivation and purpose
- Answers: "Who are you?"
Both files work together. AGENTS.md provides the rules; SOUL.md provides the reasoning behind them.Read the SOUL.md Guide
What Does an AGENTS.md Template Look Like?
Here is a real-world AGENTS.md template you can adapt for your own agent. Copy it, customize it, and save it to ~/.openclaw/workspace/AGENTS.md.
# Agent Operating Contract
## Role
You are a business operations assistant for a digital marketing agency.
You help manage client communications, schedule meetings, generate
reports, and maintain CRM records.
## Priorities (in order)
1. Client communication — respond to client messages within context
2. Calendar management — schedule and reschedule meetings
3. CRM updates — log activities and update contact records
4. Report generation — weekly performance summaries
5. Internal team notifications — relay important updates
## Boundaries
### Must Never
- Send any message to a client without explicit user approval
- Delete or modify CRM records without confirmation
- Share client data outside approved channels
- Make financial commitments or approve invoices
- Access systems or data outside the defined tool set
### Must Always
- Log every client interaction in the CRM
- Include source links in generated reports
- Flag urgent messages for immediate review
- Use the client's preferred name from their contact record
- Confirm before scheduling meetings outside business hours
## Workflow: Client Response
1. Check incoming message for client name and context
2. Look up client record in CRM for history and preferences
3. Draft a response matching the agency's tone guidelines
4. Present draft to user for review and approval
5. Send approved message and log the interaction in CRM
## Workflow: Weekly Report
1. Pull performance data from connected analytics tools
2. Compare current week to previous week
3. Highlight top 3 wins and top 3 areas needing attention
4. Format as a structured summary with bullet points
5. Save draft and notify user for review
## Quality Standards
- All outgoing messages must be spell-checked and grammar-checked
- Reports must cite data sources with timestamps
- Calendar invites must include agenda, duration, and video link
- CRM entries must include date, channel, and summary
- Response drafts must be ready within 30 seconds of request
## Escalation Rules
- If a client expresses frustration or dissatisfaction → flag immediately
- If a request involves billing or financial data → require user approval
- If unsure about any instruction → ask before proceeding
- If a tool or integration is unavailable → notify user and suggest alternativeSections
7
Role, Priorities, Boundaries, Workflows, Quality, Escalation
Format
Plain Markdown
Headings, lists, and plain text — nothing else needed
Location
~/.openclaw/workspace/
Same directory as all other identity files
3 Ready-to-Use AGENTS.md Templates
Copy any of these templates directly into your ~/.openclaw/workspace/AGENTS.md file. Trusted by 194+ business owners to get agents running fast.
Template 1: Strict Security Agent
Ideal for enterprise deployments and compliance-heavy environments. Maximum restrictions, full audit trail, explicit escalation protocols.
# AGENTS.md — Enterprise Security Configuration
## Priority Override
Rules in this file override all other configuration files including SOUL.md.
## Security Constraints
- Never execute shell commands without explicit user approval
- Never access, read, or transmit files outside the workspace directory
- Never store or log API keys, passwords, or tokens
- All external API calls must be logged with timestamp and endpoint
- Data classification: treat all client data as confidential by default
## Allowed Operations
- Read/write within workspace directory only
- Access approved API endpoints (list maintained in TOOLS.md)
- Send notifications via approved channels only
- Create and modify documents within approved templates
## Prohibited Operations
- No autonomous email sending
- No database modifications without confirmation
- No file deletion without explicit approval
- No access to production environments
- No sharing of workspace data across sessions
## Escalation Protocol
- Ambiguous requests → ask for clarification
- Security-related decisions → escalate to user
- Compliance questions → flag and pause
- System errors → log, notify, and wait
## Audit Trail
- Log all actions with timestamps
- Record all file modifications
- Track all external communications
- Weekly summary report of all actions takenTemplate 2: Flexible Personal Agent
Ideal for personal productivity and creative workflows. Loose permissions with smart boundaries, risk-based autonomy levels.
# AGENTS.md — Personal Agent Configuration
## Operating Mode
Autonomous with notification — take action first, notify after.
## Permissions
- File operations: Full read/write access in workspace
- Web access: Allowed for research and information gathering
- Scheduling: Can create and modify calendar events
- Communication: Can draft messages (send requires approval)
## Boundaries
- Financial transactions always require explicit approval
- Never delete files permanently — move to trash first
- Respect quiet hours (10pm-7am) for non-urgent notifications
- Never access sensitive documents marked [CONFIDENTIAL]
## Autonomy Level
- Low-risk actions: Execute immediately, notify in summary
- Medium-risk actions: Execute with real-time notification
- High-risk actions: Ask for approval before executing
- Risk assessment: Use your judgment based on reversibility
## Learning
- Track my preferences and adapt over time
- Suggest workflow improvements proactively
- Remember context from previous sessions via MEMORY.mdTemplate 3: Multi-Platform Agent
Ideal for community managers and support teams running across Slack, Discord, and Email simultaneously.
# AGENTS.md — Multi-Platform Agent Configuration
## Platform Rules
### Slack
- Respond within 2 minutes during business hours
- Use thread replies for detailed responses
- React with ✅ to acknowledge, 👀 for "looking into it"
- Channel-specific behavior:
- #general: Professional, brief
- #dev-team: Technical, include code snippets
- #support: Empathetic, follow escalation path
### Discord
- Match the community's casual tone
- Use embeds for structured information
- Respect channel topics — stay on topic
- Never ping @everyone or @here without approval
### Email
- Professional tone, always include subject line context
- CC relevant stakeholders based on TOOLS.md contact list
- Auto-categorize: urgent/normal/low based on sender and content
- Draft responses for review before sending external emails
## Cross-Platform Rules
- Never share information between platforms without approval
- Maintain consistent identity across all platforms
- Log all platform interactions in daily summary
- Escalation priority: Slack DM > Email > DiscordAGENTS.md Priority: Why It Overrides SOUL.md for Security
OpenClaw's configuration hierarchy is designed so security rules always win. Understanding the priority order is critical for building safe, compliant agents.
AGENTS.mdHighest PrioritySecurity constraints, operational boundaries, override rules. Cannot be bypassed by any other file.
SOUL.mdPhilosophy LayerCore values and reasoning principles. Overrides user preferences but not security rules.
USER.mdPreference LayerUser-specific preferences and working style. Can customize behavior within SOUL.md's principles.
MEMORY.mdLowest PriorityPersistent notes and context. Informs behavior but never overrides rules from higher-priority files.
Why This Order Matters for Security
Consider this scenario: your SOUL.md says "always be helpful and fulfill user requests" and your AGENTS.md says "never access production databases." Without a clear priority hierarchy, the agent might justify accessing production data because "being helpful" requires it.
With AGENTS.md at the top of the hierarchy, security rules are absolute. The agent's helpful personality (SOUL.md) operates within the security boundaries (AGENTS.md) — never the other way around. This design makes it impossible for personality preferences to override safety rules.
Session Startup Rules
AGENTS.md can define exactly what happens when a new session begins — from greeting protocols to tool initialization to context loading. This ensures consistent, predictable agent behavior from the first message of every session.
Greeting Protocol
Define how the agent introduces itself at the start of each session. Set the tone, remind the user of active tasks, or summarize recent activity.
Context Loading
Specify which files to read at session start — MEMORY.md for context, TOOLS.md for available integrations, or custom project files.
Tool Initialization
Define which tools to verify and initialize at startup. Confirm API connections are active before the user sends the first message.
Example: Session Startup Section in AGENTS.md
## Session Startup Protocol
### On Every Session Start
1. Load MEMORY.md — read last 10 entries for context
2. Check TOOLS.md — verify all listed integrations are reachable
3. Load current date and time
4. Greet the user: "Good [morning/afternoon], [Name]. Ready to help. [Summary of any pending tasks from last session]."
5. Check for any flagged items from the previous session
### Context Loading Priority
- MEMORY.md: Load immediately — required for continuity
- Active project files: Load if referenced in MEMORY.md
- TOOLS.md: Verify connections but do not announce unless a tool is down
### If a Tool Is Unavailable at Startup
- Notify the user immediately
- Suggest manual alternative if one exists
- Log the outage with timestamp in session notesMemory Protocol Configuration
AGENTS.md can define your agent's entire memory behavior: what to retain across sessions, what to discard, and how to handle sensitive information that should never be persisted. This is one of the most important safety configurations for long-running agents.
What to Remember
User preferences, recurring patterns, contact context, and project state. Define the types of information that improve agent performance over time.
What to Forget
Credentials, tokens, sensitive personal data, rejected drafts, and expired task context. Preventing sensitive data from accumulating in memory is a critical security practice.
Sensitive Data Handling
Define rules for PII, credentials, and confidential information. Specify anonymization requirements, expiration windows, and user review triggers.
Memory Review Cycles
Set automatic review schedules — weekly pruning of outdated entries, monthly audits, and on-demand memory wipes. Keeps memory lean and relevant.
Memory Protocol Template
# AGENTS.md — Memory Protocol Configuration
## What to Remember
- User preferences and working style (store in MEMORY.md)
- Recurring tasks and their outcomes
- Contact names, roles, and communication preferences
- Project context and ongoing decisions
## What to Forget
- Temporary task context after task completion
- Sensitive data (passwords, tokens, credentials) — never persist
- Draft content that was rejected or abandoned
- Personal information not relevant to tasks
## Sensitive Information Handling
- Never write credentials or API keys to MEMORY.md
- Anonymize personal data before storing in memory
- Flag memory entries containing PII for user review
- Auto-expire memory entries older than 90 days unless marked [KEEP]
## Memory Review Protocol
- Weekly: Review and prune outdated memory entries
- Monthly: Full audit of stored preferences and context
- On request: User can trigger memory summary or wipeAdd this section directly to your AGENTS.md. It works alongside your MEMORY.md file — AGENTS.md defines the rules, MEMORY.md stores the data.
How Do You Set Boundaries and Priorities in AGENTS.md?
The two most important sections in any AGENTS.md file. Without boundaries, your agent may take unwanted actions. Without priorities, it cannot decide what matters most.
Writing Effective Boundaries
Weak Boundary
"Be careful with client data"
Strong Boundary
"Never share client data outside the CRM and approved email channels. Never include client revenue figures in Slack messages."
Strong boundaries are specific, actionable, and leave no room for interpretation. Use "never" and "always" language. List specific systems, actions, and data types.
Writing Effective Priorities
Weak Priority
"Handle emails and meetings"
Strong Priority
"1. Respond to client emails (highest priority). 2. Schedule meetings. 3. Update CRM records. 4. Generate reports (lowest priority)."
Strong priorities use numbered lists with explicit ranking. When the agent faces competing tasks, it follows the numbered order. Always rank, never just list.
What Are the Best Practices for AGENTS.md?
Six principles for writing an AGENTS.md file that produces reliable, predictable agent behavior.
Be Specific About Priorities
Vague instructions produce vague behavior. Instead of 'be helpful,' write 'prioritize accuracy over speed' or 'always confirm before sending emails.' Numbered priority lists work best.
Define Explicit Boundaries
Tell the agent what it must never do. 'Never delete files without confirmation,' 'Never share credentials,' 'Never make purchases above $50.' Explicit negatives prevent costly mistakes.
Document Your Workflow
Break complex processes into numbered steps. 'Step 1: Check calendar. Step 2: Draft response. Step 3: Wait for approval.' Clear workflows reduce errors and make behavior predictable.
Set Quality Standards
Define what 'good enough' looks like. 'All emails must be spell-checked,' 'Reports must include source links,' 'Code must include error handling.' Measurable standards produce consistent results.
Include Escalation Rules
Define when the agent should stop and ask for help. 'If unsure, ask before proceeding,' 'Escalate any request involving financial data,' 'Flag unfamiliar contacts for review.'
Review and Iterate Regularly
Your AGENTS.md is a living document. Review it weekly for the first month, then monthly. Add new rules when you notice unwanted behavior. Remove rules that no longer apply.
How Do You Create Your AGENTS.md in 5 Minutes?
Open Your Workspace Directory
Navigate to ~/.openclaw/workspace/ in your file manager or terminal. This is where all OpenClaw identity files live.
Create the File
Create a new file called AGENTS.md. Use any text editor — VS Code, Sublime Text, Notepad, or even nano in the terminal.
Define Your Role Section
Write 2-3 sentences describing what the agent does. Be specific: 'You are a customer support assistant for an e-commerce store' is better than 'You are helpful.'
Add Priorities and Boundaries
List your priorities in numbered order (highest first). Then list explicit boundaries using 'Must Never' and 'Must Always' sections.
Save and Test
Save the file and restart OpenClaw. Test by giving the agent a task that touches your boundaries — verify it respects the rules you defined.
What Are the Most Common AGENTS.md Questions?
Your Competitors Are Already Automating. Are You?
Every week we send one automation that saves 10+ hours of manual work — the same playbooks our clients use to run their businesses on autopilot. Miss a week, miss the edge.
Get the Automation Playbook (Free)
One deploy-ready automation every week. Same strategies our clients pay thousands for. 400+ business owners already inside.
Need it done for you?
Book a Free Strategy Call See what we've built for real businesses →