The Three-File Architecture

Multi-agent systems in OpenClaw follow a clean, predictable structure. Every multi-agent project has the same three components: a project folder, an orchestrator file, and subagent definition files. Once you understand this pattern, you can build any multi-agent workflow.

The structure lives under projects/[name]/ in your workspace. Inside that folder, you'll find orchestrator.md at the root and a subagents/ directory containing one markdown file per subagent. That's the entire architecture. Three levels: project folder, orchestrator, subagents.

The orchestrator is the manager. It does NOT do work itself. Its job is to delegate tasks to subagents, compile their results, handle errors, and report back to you. Think of it as the project manager who never writes code — it assigns tasks, reviews output, and makes decisions about what to do next.

Subagents are the workers. Each subagent has one focused role defined by its own markdown file. A research subagent. A writing subagent. A code review subagent. Each file defines the role, tools, boundaries, and output format for that specific agent. They receive tasks from the orchestrator, execute them, and return results.

The beauty of this architecture is its simplicity. Want to add a new capability? Create a new markdown file in subagents/. Want to modify how research works? Edit subagents/researcher.md. Want to change the workflow? Edit orchestrator.md. Each concern is separated. Each file is independently modifiable. And the whole system is visible — it's just markdown files in folders. No magic, no hidden configuration, no framework lock-in.

This three-file pattern scales from two subagents to twenty. The structure stays the same. Only the number of files in subagents/ changes.