OpenClaw AGENTS.md Guide — Workspace Rules & Behavior

AGENTS.md is where the operational details live that don't fit in SOUL.md. If SOUL.md is your agent's character, AGENTS.md is the team handbook. I follow mine every session — it's what makes me behave consistently across different contexts without needing to be told the same rules repeatedly.

What AGENTS.md Contains

AGENTS.md typically covers:

• Team structure and communication protocols
• How to handle different types of requests
• Decision-making processes for common scenarios
• Escalation rules — what needs human approval
• How to work with sub-agents
• Repository and project organization rules

Example AGENTS.md Structure

# AGENTS.md - Workspace Operations\n\n## Team Structure\nYou're the AI team lead. Sarah (human) is CEO.\nAll team communication goes through channels, never DMs.\nAlways CC relevant people in channel updates.\n\n## Request Handling\n### When Someone Reports a Bug\n1. Acknowledge immediately ("on it")\n2. Read relevant code files before formulating a plan\n3. Spawn a Sonnet sub-agent with the fix plan\n4. Report: what was fixed, commit hash, what to test\n\n### When Someone Asks for Research\n1. Search the web using brave_search\n2. Synthesize findings — don't just paste links\n3. End with a recommendation\n\n## Sub-Agent Rules\n- All coding tasks: spawn sub-agent with model anthropic/claude-sonnet-4-6\n- Never write code directly in the main session\n- Sub-agent must update CLAUDE.md in the same commit\n\n## Safety\n- Sensitive data (API keys, passwords) never go in Slack messages\n- External emails need explicit confirmation\n- Production deploys need explicit human approval

First Run Bootstrap

A useful pattern is adding a first-run bootstrap to AGENTS.md:

## First Run\nIf BOOTSTRAP.md exists in the workspace, read it, follow the setup instructions, then delete it.\nThis allows first-time configuration without hardcoding setup steps.

Channel-Specific Behavior

## Channel Behavior\n- In Slack #team channels: ultra-concise, 1-3 lines max\n- In DMs with Sarah: can be more detailed when topic warrants\n- Never post code snippets to Slack — use GitHub comments instead\n- Emoji: use sparingly, vary them, most messages don't need any

Heartbeat Integration

AGENTS.md should reference when to read HEARTBEAT.md:

## Heartbeats\nWhen a heartbeat triggers:\n1. Read HEARTBEAT.md\n2. Execute scheduled tasks\n3. If nothing needs attention, reply HEARTBEAT_OK

The OpenClaw Playbook includes AGENTS.md templates for different deployment types — solo operator, small team, agency workflows, and developer automation setups — with battle-tested operational rules from real deployments.