Openclaw Fleet Mode

What You'll Need

⏱ Time: 18 minutes  |  📋 Tasks:

• Basic understanding of agents from the Basic Agents track
• Familiarity with Docker and Docker Swarm (covered in Lesson 2)
• A terminal and Docker Desktop running

One Agent Isn't Always Enough

Hermes runs one agent, one loop, one task at a time. That's fine for a lot of things. But some workflows need more than one agent working at once — not because the task is too big for one agent, but because one agent can't do everything well.

Consider a task like: "Review this pull request, check for bugs, run the tests, suggest fixes, implement the fixes, verify the tests pass, and deploy." A single agent could do all of that, but it would be doing everything with the same model, the same tool access, the same attention. That's like asking the same person to write code, review it, test it, and deploy it — there's no separation of concerns, no second pair of eyes, no specialized tooling.

A fleet splits that work across specialized agents. One agent writes code. Another reviews it. A third runs tests. A fourth deploys. They work in parallel where possible, pass results to each other where not, and the whole pipeline runs faster and more safely than any single agent could manage alone.

What Fleet Mode Is

Openclaw Fleet Mode runs multiple agent instances as coordinated services inside Docker Swarm. Each agent is a separate container with its own model configuration, tool access, and security boundary. An orchestrator service manages the fleet — it watches a shared task queue, assigns work to agents based on their role, collects results, and handles retries when an agent fails.

The architecture looks like this:

Each agent runs in its own container with its own secret bundle. The orchestrator never sees the agents' API keys — it only sees the task assignments and results. This means even if one agent is compromised, the others and their credentials are isolated.

Agent Roles and the Orchestrator

In a fleet, every agent has a role. The role determines what kind of work the agent accepts, what tools it has access to, and what model configuration it uses. These are common roles:

The orchestrator is the traffic controller. It doesn't do the work itself — it reads new tasks from the queue, checks which agents are available, and dispatches each task to the agent whose role matches the work type. If an agent crashes or a task times out, the orchestrator re-queues it for another agent. If all agents of a role are busy, tasks wait in the queue until one frees up.

Coordination Patterns

Once we have multiple agents, we need ways for them to work together. There are three fundamental coordination patterns Openclaw supports:

Fan-Out

One task spawns many independent sub-tasks that can run in parallel. The orchestrator distributes them across available agents. Example: "Analyze all 20 files in this directory" — the orchestrator sends each file to a different Coder agent, and they all work at the same time. The pattern scales linearly with the number of agents.

Sequential (Pipeline)

Tasks must run one after another because each depends on the previous step's output. The orchestrator routes the output of agent A to the input of agent B. Example: Coder writes code → Reviewer audits it → Coder fixes issues → Deployer ships it. Each step waits for the previous one to complete.

Arbitration

Multiple agents work on the same problem with different approaches, and a decider agent compares their results and picks the best one. Example: Three agents each design a database schema independently. A fourth agent reviews all three, combines the best ideas, and produces a final design. This is expensive — multiple agents burning tokens on the same task — but useful when correctness matters more than speed.

Walkthrough: A Two-Agent Fleet

Let's set up a basic two-agent fleet: a Coder agent and a Reviewer agent, sharing a queue. The Coder writes code; the Reviewer checks it. This is the simplest useful fleet — two agents, two roles, one pipeline.

Step 1: Define the shared spec

Create a shared configuration file that both agents will read. Openclaw uses a opencode.json file to define the fleet:

{
  "fleet": {
    "name": "basic-fleet",
    "orchestrator": {
      "mode": "queue",
      "queue_dir": "./Tasks/Queue",
      "poll_interval": 30
    },
    "agents": {
      "coder": {
        "role": "Coder",
        "model": "deepseek-v4-flash",
        "work_dir": "./Tasks/Code"
      },
      "reviewer": {
        "role": "Reviewer",
        "model": "deepseek-v4-pro",
        "work_dir": "./Tasks/Review"
      }
    }
  }
}

Step 2: Deploy the stack

Open a terminal and run:

docker stack deploy -c docker-compose.interclaw.yml basic-fleet

This launches the orchestrator service and both agent containers. Each agent starts up, registers with the orchestrator, and waits for work.

Step 3: Add a task to the queue

Create a task file in the queue directory:

# Tasks/Queue/001-add-user-auth.md
---
role: Coder
goal: Implement user authentication for the Flask app
  - Add a login endpoint with email and password
  - Add a registration endpoint
  - Hash passwords with bcrypt
  - Return JWT tokens on successful login
---

The orchestrator picks up this file, sees the role: Coder header, and dispatches it to the Coder agent.

Step 4: Watch the pipeline

The Coder agent reads the task, implements the code, and writes the output. When it finishes, it moves the task file to the Reviewer's queue. The Reviewer agent picks it up, inspects the code, runs any tests, and either approves it (moving it to done) or writes feedback and sends it back to the Coder queue for fixes.

Single Agent vs Fleet

When does a fleet make sense? Here's how the trade-offs compare:

The fleet wins on throughput, specialization, and safety — at the cost of operational complexity and higher peak cost. Single agents win on simplicity and cost control. The right choice depends on the task: a single agent is perfect for a focused automation, while a fleet shines when you need a reliable, scalable multi-step pipeline.

Deliverable: Fleet Config Template

Here's a reusable two-agent fleet configuration. Save it as opencode.json and adapt it for your own fleet:

{
  "fleet": {
    "name": "my-fleet",
    "orchestrator": {
      "mode": "queue",
      "queue_dir": "./Tasks/Queue",
      "poll_interval": 30,
      "max_retries": 3
    },
    "agents": {
      "coder": {
        "role": "Coder",
        "model": "deepseek-v4-flash",
        "work_dir": "./Tasks/Code",
        "tools": ["filesystem", "git", "code_execution"],
        "max_iterations": 50
      },
      "reviewer": {
        "role": "Reviewer",
        "model": "deepseek-v4-pro",
        "work_dir": "./Tasks/Review",
        "tools": ["filesystem_read", "test_runner"],
        "max_iterations": 20
      }
    },
    "limits": {
      "max_concurrent_tasks": 4,
      "per_agent_budget": 2.00
    }
  }
}

Start with two agents and a simple pipeline — Coder → Reviewer. Once that's running reliably, add a Planner agent that prepares work for the Coder, or a Deployer agent that ships finished code. Each new role makes the fleet more capable, but add them one at a time so you understand the coordination patterns before scaling up.

Try It

Set up the two-agent fleet from the walkthrough. Deploy the stack, add a task to the queue, and watch the orchestrator dispatch it from the Coder to the Reviewer. Then swap the models — give the Coder a cheaper model and the Reviewer a more expensive one — and see how that changes the pipeline speed and output quality.

Once you've seen the basic pipeline work, try adding a third role. Create a Planner agent that pre-processes tasks before they reach the Coder. The Planner reads each task, breaks it into sub-steps, and enriches the task file with implementation notes. This three-agent pattern — Planner → Coder → Reviewer — is the foundation that most production fleets are built on.