Build a Multi-Agent OpenClaw System Without Config Hell: Orchestrator + Sub-Agents in 15 Minutes

Single agents hit the ceiling fast. After a few thousand tokens, the context window fills up, response quality drops, and your agent starts hallucinates and repeating itself. The sooner you admit "one agent can't do everything," the sooner you can actually build something that scales.

The good news: OpenClaw already has the tools for orchestrator + sub-agent patterns. The problem is that community tutorials show you how to wire it, but not where the config lives or what each agent needs to know. Three hours of reading Reddit threads, ClawHub workflows, and BoxminingAI tutorials later, you're still not sure if your folder structure is correct.

This guide shows you the exact folder layout, AGENTS.md config, and prompt patterns that the top-performing multi-agent deployments use today. By the end, you'll have a working orchestrator that spawns sub-agents, gathers their results, and decides what happens next—without the config mess.

The Single-Agent Context Trap

One agent with a 128K context window sounds like enough until it isn't. Each memory lookup consumes 5-10K tokens. Each tool call eats another 2K tokens. A few recursive loops and suddenly you're down to 30K tokens for the actual task—which is why your agent starts making dumb decisions and repeating steps.

The solution isn't "get a bigger context window." It's "use the right tool for the right subtask."

If your agent is supposed to:

• Monitor a database and send alerts
• Handle customer emails
• Generate reports
• Manage team calendars
• Execute deployments

...then you don't have one job. You have five jobs. Each one deserves its own agent with its own focused context, memory, and toolset.

The Orchestrator Pattern: One Brain, Many Hands

The architecture is simple:

Orchestrator Agent: Receives the top-level task, decides which sub-agents to spawn, collects their outputs, synthesizes the result.

Sub-Agents: Focused on one domain (email handling, database monitoring, report generation). Each one has a narrow SOUL.md, limited tool access, and its own MEMORY.md for domain-specific state.

The orchestrator doesn't execute the work—it coordinates it. The sub-agents do the real work without the cognitive overhead of knowing about everything else.

Folder Structure: Where Everything Lives

Standard OpenClaw single-agent layout:

~/.openclaw/agents/my-agent/
├── SOUL.md
├── AGENTS.md
├── IDENTITY.md
├── USER.md
├── TOOLS.md
├── HEARTBEAT.md
├── MEMORY.md
└── memory/
    └── YYYY-MM-DD.md

Multi-agent layout: Create a workspace for the orchestrator, then subfolders for each sub-agent:

~/.openclaw/agents/
├── orchestrator/
│   ├── SOUL.md                    # Orchestrator's role
│   ├── AGENTS.md                  # Sessions_spawn config
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── TOOLS.md                   # Has access to sessions_spawn
│   ├── HEARTBEAT.md
│   └── MEMORY.md
├── email-handler/
│   ├── SOUL.md                    # Email-focused agent
│   ├── AGENTS.md
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── TOOLS.md                   # Email tools only
│   ├── HEARTBEAT.md
│   └── MEMORY.md
├── db-monitor/
│   ├── SOUL.md                    # Database monitoring agent
│   ├── AGENTS.md
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── TOOLS.md                   # Database + alerting tools
│   ├── HEARTBEAT.md
│   └── MEMORY.md
└── report-gen/
    ├── SOUL.md                    # Report generation agent
    ├── AGENTS.md
    ├── IDENTITY.md
    ├── USER.md
    ├── TOOLS.md                   # Data aggregation + formatting tools
    ├── HEARTBEAT.md
    └── MEMORY.md

The orchestrator's AGENTS.md contains the spawning logic. Sub-agent folders are identical in structure to single-agent setups—OpenClaw treats them the same way, they just live in sibling folders.

The Orchestrator's AGENTS.md: Spawn Logic

The orchestrator's AGENTS.md needs to know:

1. Where each sub-agent workspace lives
2. What task to give each one
3. How to handle the results

Here's a real example:

# AGENTS.md - Orchestrator

## Sub-Agents

- **email-handler**: Processes incoming emails. Runs on every message arrival.
- **db-monitor**: Checks database health. Runs every 15 minutes via HEARTBEAT.
- **report-gen**: Generates daily reports. Runs once per day.

## Session Spawning Pattern

When a top-level task arrives (via message, webhook, or cron):

1. **Parse the request** — What category of work is this?
2. **Spawn the right sub-agent** — Use `sessions_spawn()` with:
   - `runtime: "subagent"`
   - `task: "{specific instructions for this sub-agent}"`
   - `cwd: "/path/to/subagent-workspace"`
3. **Collect results** — Wait for the sub-agent's response
4. **Synthesize & execute** — Combine outputs, make decisions, take action
5. **Log to MEMORY.md** — Record what happened for future context

### Example: Email Triage Orchestrator

Incoming: "Check Slack #alerts and respond to any urgent email forwarded there"

Orchestrator receives message → spawns email-handler sub-agent: cwd: ~/.openclaw/agents/email-handler task: "Read the urgent emails in Slack #alerts. For each one, draft a response."

Sub-agent email-handler executes (in its own workspace) → returns 3 drafts

Orchestrator receives sub-agent output → Reviews each draft:

• If tone/content is good → use sessions_send() to post to Slack
• If tone is wrong → spawn email-handler again with feedback
• If requires escalation → use sessions_send() to notify the human

Orchestrator logs to MEMORY.md: "Processed 3 urgent emails. 2 auto-responded, 1 flagged for human review."

This pattern keeps each agent focused: the email-handler doesn't care about Slack formatting or escalation logic. It just drafts emails. The orchestrator handles routing and decision-making.

## Sub-Agent SOUL.md: Narrow, Focused Mission

Your sub-agents need tight, specific SOUL.md files. This is the opposite of "put everything in one agent."

**Bad SOUL.md for an email-handler sub-agent:**
```markdown
# SOUL.md - Email Handler

You are a helpful assistant that manages emails, handles notifications, 
monitors databases, generates reports, and more. You are flexible and can 
adapt to many tasks...

This is the "dumb zone" pattern—overstuffed context kills performance.

Good SOUL.md for an email-handler sub-agent:

# SOUL.md - Email Handler

You read emails from configured inboxes. Your only job: extract sender, 
subject, urgency level (critical/high/normal), and a one-line summary. 
You do not respond to emails yourself. You do not make decisions about 
escalation. You extract facts and return them structured as JSON.

## Constraints

- You cannot send emails (no SEND_EMAIL tool)
- You cannot modify calendar events
- You cannot spawn other agents
- You cannot retry failed email reads more than twice

When confused, ask the orchestrator (via sessions_send) instead of guessing.

Short, clear, scoped. The sub-agent knows exactly what it's for and what it can't do.

Orchestrator Memory: Tracking Agent Coordination

Your orchestrator's MEMORY.md should track:

• Which sub-agents are running
• What tasks are pending
• Which sub-agents have failed and why
• Patterns in sub-agent behavior

Example MEMORY.md entry:

## 2026-04-09 Orchestrator Coordination Log

### Running Tasks
- email-handler: Processing urgent messages (started 10:30 UTC)
- db-monitor: Health check in progress (started 10:32 UTC)
- report-gen: Idle (next run: 2026-04-10 09:00 UTC)

### Sub-Agent Status
- email-handler: 47 emails processed, 3 failures (network timeout)
- db-monitor: All checks passing
- report-gen: Generated 23 reports this week, 100% success

### Decision Log
- Escalated 2 high-urgency emails to human (escalation threshold hit)
- Retry email-handler on timeout: success on second attempt
- Alert: db-monitor detected 15% increase in query latency — flagged for investigation

This becomes your audit trail. When something breaks, you can trace exactly which sub-agent failed and why.

Real Setup: 15-Minute Walkthrough

1. Create the orchestrator workspace (5 minutes)

   • Copy OpenAgents.mom bundle to ~/.openclaw/agents/orchestrator/
   • Edit SOUL.md: narrow the role to "coordinate email and database tasks"
   • Edit TOOLS.md: add sessions_spawn, sessions_send, sessions_history

2. Create sub-agent workspaces (5 minutes)

   • Copy the bundle 2 more times to email-handler/ and db-monitor/
   • For email-handler: keep email + message tools, remove database tools
   • For db-monitor: keep database tools, remove email tools

3. Wire the orchestrator's AGENTS.md (3 minutes)

   • Add the sub-agent spawning logic
   • Set up the task routing (if email → spawn email-handler, if database query → spawn db-monitor)
   • Add timeout and error handling

4. Test with a manual task (2 minutes)

   • Send a test message to the orchestrator
   • Verify it spawns the right sub-agent
   • Check the sub-agent's output

That's it. Your multi-agent system is live.

Why This Beats the Alternatives

LangGraph / CrewAI / AutoGen: Powerful but require Python, dependency management, and custom orchestration code. You're writing and maintaining code that will break when you upgrade a library.

Hosted AI platforms (Botpress, Dify): Fast to set up but lock you into their pricing and interface. When they change pricing (like Anthropic cut Claude subscriptions for OpenClaw), you're stuck.

OpenClaw multi-agent with OpenAgents.mom bundles: File-based, versioned, portable. Your orchestrator and sub-agent configs are markdown. They travel with you across VPS, Docker, ClawGo, any OpenClaw runtime. When you need to scale, just copy a workspace folder and edit SOUL.md.

The OpenAgents.mom Advantage

Building multi-agent systems by hand means wiring:

• SOUL.md for each agent (focused vs. overstuffed)
• AGENTS.md with spawning logic
• Sub-agent tooling constraints
• Memory sync patterns
• Timeout and error handling
• Audit logging

That's 4-6 hours of setup, testing, and iteration.

OpenAgents.mom takes your multi-agent architecture and generates the starting point for all of it. You get pre-configured SOUL.md templates that teach you the scoping pattern, AGENTS.md with sub-agent spawning examples, and TOOLS.md with the right tool constraints for each agent role.

Then you customize for your specific tasks instead of building from first principles.