OpenClaw AGENTS.md: Workspace Configurations & Specific Behaviors

Introduction

AGENTS.md defines specific behaviors and workspace configurations for OpenClaw agents. While SOUL.md contains the agent's core identity and values, AGENTS.md contains context-specific instructions — which workspace is active, what role the agent is playing, and how it should behave in different scenarios.

Think of it this way: SOUL.md is who the agent is. AGENTS.md is who the agent is right now, in this context. When you switch from "work" to "personal" or from "research" to "writing," AGENTS.md tells the runtime which profile to load. One agent, many hats.

Purpose

AGENTS.md enables:

• Workspace switching: "When in work context, use formal tone. When in personal context, casual."
• Role definition: "As research agent, prioritize depth. As writing agent, prioritize concision."
• Context-specific tools: "In finance workspace, enable trading skills. In dev workspace, enable shell."

Without AGENTS.md, your agent has one personality and one skill set for everything. With it, you get granularity. The same agent that drafts formal client emails in "work" mode can use a friendly, casual tone in "personal" mode — and never mix them up.

Structure

AGENTS.md can define multiple agent profiles. Each profile: name, workspace path, SOUL override (optional), enabled skills, heartbeat file. When user switches context (e.g., "switch to work"), the runtime loads the corresponding AGENTS.md entry.

Location: ~/clawd/AGENTS.md. Same directory as SOUL.md and HEARTBEAT.md. The runtime reads it at context switch or session start.

AGENTS.md Examples

# Agent Profiles

## Work
- workspace: ~/clawd/work
- tone: formal, concise
- skills: calendar, email, slack, web_search
- heartbeat: HEARTBEAT-work.md

## Personal
- workspace: ~/clawd/personal
- tone: friendly, casual
- skills: calendar, weather, reminders
- heartbeat: HEARTBEAT-personal.md

## Dev
- workspace: ~/clawd/projects
- tone: technical
- skills: shell, file_system, browser, github
- heartbeat: HEARTBEAT-dev.md

Each profile isolates context. Work memory stays in work. Personal stays in personal. No cross-contamination.

Multi-Agent Use

In multi-agent setups, each agent has its own AGENTS.md (or section). Strategy Agent: AGENTS.md says "focus on goals, no execution." Execution Agent: "focus on tasks, no strategy." Shared memory (GOALS.md) coordinates; AGENTS.md defines boundaries.

Example: A three-agent team for a startup. Strategy Agent — reads market data, writes to GOALS.md. No shell, no email. Execution Agent — reads GOALS.md, executes tasks. Shell, calendar, Slack. Review Agent — reads completed tasks, summarizes for human. No execution. AGENTS.md enforces these boundaries. See multi-agent for full setup.

Quick Wins

1. Start with two profiles: Work and Personal. Add more as you need them.
2. Gate risky skills: Shell and browser only in dev workspace. Never in finance or personal.
3. Separate HEARTBEAT files: HEARTBEAT-work.md for client alerts; HEARTBEAT-personal.md for morning briefings. Prevents work tasks from firing in personal mode.
4. Use explicit tone: "formal" and "casual" are vague. Add examples: "Use 'Kind regards' to close. No emoji."

Common Pitfalls

• Overlapping skills: If work and personal both have email, the agent may use the wrong account. Use separate credentials per workspace.
• Forgotten context switch: User asks work question while in personal mode. Agent may not have work context. Train yourself to "switch to work" before work queries.
• Too many profiles: 10 profiles = cognitive overload. Start with 2–3. Add only when you have a clear use case.

Wrapping Up

AGENTS.md provides workspace and role granularity. One agent, many contexts. See multi-agent, SOUL.md, and memory system for related concepts.