OpenClaw agents.md: How Top Builders Configure Their AI Agents

Q: How do I assign tools to an agent in agents.md?

Under each agent's configuration block, add a tools: section listing the tool identifiers you want that agent to access. Tools must be installed and registered in your skills directory. Assigning only necessary tools to each agent reduces attack surface and improves response reliability.

Key Takeaways

agents.md is the master config file — every agent your OpenClaw gateway loads is defined here
Each H2 heading in the file starts a new agent block; the heading text becomes the agent's display name
Tool assignments in agents.md directly control what actions each agent can take — only assign what each agent actually needs
Memory settings here override system defaults on a per-agent basis, giving fine-grained control over context windows
Syntax errors in agents.md halt the entire gateway — validate changes before deploying

Thirty minutes spent getting agents.md right saves you hours of debugging why your agents behave strangely, call the wrong tools, or refuse to load entirely. The file is the authority on everything your agent system does. Every builder who's run a multi-agent setup professionally has learned this the hard way.

What agents.md Actually Controls

When OpenClaw starts, the first thing the gateway does is read agents.md. Every agent definition in that file gets instantiated: its name, its model, its tool access, its memory configuration, its system prompt — all of it comes from this one file.

Nothing runs without it. If agents.md is missing, the gateway logs an error and exits. If it's malformed, same result. This is by design — it makes your agent system's entire capability surface explicit and auditable in one place.

Think of it as the org chart for your AI infrastructure. Every agent has a defined role, defined capabilities, and defined limits. The agents.md file is where those definitions live.

💡

Start Simple, Expand Later

The most common mistake new builders make is trying to define complex multi-agent systems from day one. Start with a single agent in agents.md, get it working end-to-end, then add agents one at a time. Each addition is a restart and a validation step.

The agents.md File Structure

The file uses Markdown conventions. Each agent is defined in a section that starts with an H2 heading. The heading text is the agent's human-readable name. Everything under that heading until the next H2 is that agent's configuration block.

## Research Agent

model: claude-3-5-sonnet-20241022
channel: telegram-research
system_prompt: |
  You are a research specialist. Your job is to find accurate,
  current information and synthesize it into clear summaries.
  Always cite your sources. Never fabricate data.

tools:
  - web_search
  - read_url
  - write_memory

memory:
  type: sliding_window
  max_tokens: 8000

## Writing Agent

model: claude-3-5-haiku-20241022
channel: slack-writing
system_prompt: |
  You are a writing assistant focused on clarity and precision.
  Edit for conciseness. Remove filler words. Preserve the author's voice.

tools:
  - read_memory
  - write_file

memory:
  type: full
  max_tokens: 16000

The structure is intentionally readable. Anyone on your team can open agents.md and immediately understand what your agent system does and what it can access. That transparency is a feature, not an accident.

Agent Configuration Fields

Here are the fields you can set under each agent heading and what they control.

Field	Required	Description
model	Yes	The LLM model identifier this agent uses
channel	Yes	The channel ID this agent listens on
system_prompt	Yes	The base instruction set that defines agent behavior
tools	No	List of tool identifiers this agent can call
memory	No	Memory type and token limits for this agent
temperature	No	LLM temperature override for this specific agent
max_tokens	No	Maximum response length in tokens

The model field accepts any model identifier your configured provider supports. OpenClaw passes this string directly to the provider API, so use the exact identifier the provider documentation specifies — not a display name.

Tool Assignment — The Part Most Builders Get Wrong

Every tool listed under an agent's tools: block is a capability that agent can invoke. More tools is not better. It's a liability.

Here's what we've seen consistently across production deployments: agents with broad tool access make more tool-calling errors than agents with tight, specific access. The model gets confused about which tool fits a given situation when too many options are available.

The right approach is surgical assignment. A research agent needs web_search and read_url. It does not need write_file or execute_command. A writing assistant needs read_memory and write_file. It does not need web_search.

# Good — tight, purposeful tool assignment
tools:
  - web_search
  - read_url
  - write_memory

# Bad — kitchen-sink assignment that creates confusion
tools:
  - web_search
  - read_url
  - write_memory
  - read_memory
  - write_file
  - execute_command
  - send_email
  - create_calendar_event

Sound familiar? Every builder has made the "I'll add all tools in case the agent needs them" mistake. The fix is always the same: strip back to what the agent's actual job requires, then add tools only when a specific use case demands it.

⚠️

Never Assign execute_command Broadly

The execute_command tool runs shell commands on your host system. Assign it only to agents with a specific, justified need for shell access — and only in environments where you control the inputs. A general-purpose assistant with shell access is a serious security exposure.

Memory Settings in agents.md

The memory: block controls how much conversation history each agent retains and how it manages that context over time. This directly affects both agent quality and your API costs.

Two memory types are most commonly used. Sliding window keeps the most recent N tokens of context, dropping older messages as the conversation grows. This is ideal for agents handling ongoing conversations where old context becomes irrelevant. Full retains the entire conversation up to the token limit before truncating. Use this for task-based agents where early context (the original task description) must stay in scope throughout.

# Sliding window — good for long-running conversations
memory:
  type: sliding_window
  max_tokens: 8000

# Full context — good for task-based agents
memory:
  type: full
  max_tokens: 32000

As of early 2025, the default memory type when no block is specified is sliding_window with a 4,000-token limit. For agents handling complex, multi-step tasks, this default is almost always too low. Explicitly set your memory config for every production agent.

Common agents.md Mistakes

Using display model names instead of API identifiers — writing model: Claude Sonnet instead of model: claude-3-5-sonnet-20241022 will fail at startup. Always use the exact provider API string.
Duplicate channel IDs across agents — two agents bound to the same channel causes unpredictable message routing. Each agent needs a unique channel identifier.
Missing system_prompt entirely — an agent without a system prompt defaults to base model behavior. It will answer anything, follow no specific role, and produce inconsistent outputs. Always write an explicit system prompt.
Incorrect YAML indentation in the system_prompt block — using the pipe literal block scalar (|) requires consistent indentation. A single off-by-one space breaks parsing silently in some configurations.
Not testing agents.md changes in staging — the file is parsed at startup. A bad config means zero agents load. Always test changes in a non-production environment first.

Frequently Asked Questions

What is the agents.md file in OpenClaw?

agents.md is the primary configuration file where you define every agent in your OpenClaw system. Each agent entry specifies its name, model, assigned tools, memory settings, channel bindings, and behavioral instructions. Without a properly structured agents.md, no agents will load at startup.

Where does OpenClaw look for agents.md?

By default, OpenClaw looks for agents.md in the project root directory where you launch the gateway. You can override this path using the OPENCLAW_AGENTS_FILE environment variable or the --agents-file CLI flag, which is useful when managing multiple configurations for different environments.

Can I define multiple agents in a single agents.md file?

Yes. agents.md supports any number of agent definitions separated by H2 headings. Each heading marks the start of a new agent block. All agents defined in the file load simultaneously when the gateway starts, making it easy to manage complex multi-agent systems from one file.

How do I assign tools to an agent in agents.md?

Under each agent's configuration block, add a tools: section listing the tool identifiers you want that agent to access. Tools must be installed and registered in your skills directory. Assign only the tools each agent actually needs — fewer tools means fewer errors and a smaller attack surface.

What happens if agents.md has a syntax error?

OpenClaw will fail to start and log a parse error pointing to the problematic line. The entire gateway halts — no agents load. Always validate changes to agents.md in a staging environment before deploying. Run openclaw status after any config change to confirm the file parsed successfully.

Can I hot-reload agents.md without restarting OpenClaw?

As of early 2025, hot-reload for agents.md is not supported. Changes require a gateway restart. Plan config changes during low-traffic windows and use openclaw status afterward to verify all agents came back online with the expected settings.

S. Rivera

AI Infrastructure Lead

S. Rivera architects multi-agent OpenClaw deployments for enterprise clients, with a focus on configuration management, agent specialization, and production reliability. Has designed and debugged agents.md files ranging from single-agent setups to 40-agent production systems.