Skip to main content

Multi-Agent Workflows

OpenClaw supports running multiple agents within a single gateway, each with its own identity, workspace, memory, and channel bindings. This guide covers configuration, routing, coordination, and community orchestration tools.

Multi-Agent Architecture​

Each agent is a fully isolated "brain" with:

  • Its own workspace (SOUL.md, AGENTS.md, USER.md, TOOLS.md, MEMORY.md)
  • Its own state directory (auth profiles, model registry)
  • Its own session store (chat history, routing state)
  • Optionally its own LLM model and provider

All agents share a single gateway process and port.

Configuration​

Defining Agents​

~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-5"
    },
    "list": [
      {
        "id": "alex",
        "workspace": "~/.openclaw/workspace-alex",
        "model": "claude-opus-4-6"
      },
      {
        "id": "mia",
        "workspace": "~/.openclaw/workspace-mia",
        "model": "claude-haiku-4-5"
      }
    ]
  }
}

agents.defaults sets baseline settings for all agents. Individual entries in agents.list override specific fields.

Channel Bindings​

Bindings route incoming messages to specific agents based on channel, account, peer, or space:

~/.openclaw/openclaw.json
{
  "bindings": [
    {
      "agentId": "alex",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+15551230001" }
      }
    },
    {
      "agentId": "mia",
      "match": {
        "channel": "telegram"
      }
    },
    {
      "agentId": "alex",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal"
      }
    }
  ]
}

Binding rules:

  • Most specific wins — peer matches take priority over channel-wide matches
  • Deterministic — same input always routes to the same agent
  • If multiple accounts exist for a channel, use accountId to distinguish
  • Unmatched messages go to the default agent

Separate Instances (Alternative)​

For full isolation (different ports, different processes):

# Instance 1 (work)
OPENCLAW_PORT=18789 OPENCLAW_HOME=~/.openclaw-work openclaw gateway

# Instance 2 (personal)
OPENCLAW_PORT=18790 OPENCLAW_HOME=~/.openclaw-personal openclaw gateway

This provides stronger isolation but requires managing two processes.

Common Patterns​

Work + Personal Agents​

Route work contacts to a professional agent, personal contacts to a casual one:

{
  "agents": {
    "list": [
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work"
      },
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal"
      }
    ]
  },
  "bindings": [
    { "agentId": "work", "match": { "channel": "slack" } },
    { "agentId": "work", "match": { "channel": "teams" } },
    { "agentId": "personal", "match": { "channel": "whatsapp" } },
    { "agentId": "personal", "match": { "channel": "telegram" } }
  ]
}

Give each agent a distinct SOUL.md — professional tone for work, casual for personal.

Model Routing by Agent​

Assign different models based on agent role and cost tolerance:

{
  "agents": {
    "list": [
      { "id": "thinker", "model": "claude-opus-4-6" },
      { "id": "responder", "model": "claude-haiku-4-5" },
      { "id": "coder", "model": "gpt-5.3-codex" }
    ]
  }
}

Specialist Agents​

Route by topic using separate channels:

AgentChannelSOUL.md Focus
coderGitHub, CLICode review, debugging, PRs
assistantWhatsApp, iMessageCalendar, reminders, messages
researcherDiscord, TelegramWeb research, summaries
homelabHome AssistantSmart home automation

Agent Teams (RFC)​

RFC: Agent Teams proposes coordinated multi-agent orchestration — a feature not yet shipped but under active discussion.

Current limitation: The existing sessions_spawn pattern creates sub-agents that operate in isolation and report only to their parent.

Proposed features:

  • Direct inter-agent communication (teammates talk to each other)
  • Shared task lists with dependencies
  • Collaborative problem-solving
  • New team_* and task_* tools

Why not external orchestration? The RFC argues that external workflow engines add complexity mismatch, network latency, and context loss since agent context doesn't serialize well.

Orchestration Tools​

Mission Control​

Mission Control is a community-built orchestration dashboard for managing multi-agent workflows.

  • Kanban-style task board — Inbox → Assigned → In Progress → Review → Done
  • Agent management — Assign tasks to specific agents, track progress
  • Gateway integration — Communicates via OpenClaw Gateway WebSocket API
  • Flexible deployment — Can run on a different machine, connected via Tailscale
  • Storage — SQLite-based

Antfarm​

Antfarm lets you build an agent team with one command:

npx antfarm create my-team

ClawDeck​

ClawDeck and ClawController are commercial dashboards providing visual agent management and monitoring.

DigitalOcean Elastic Scaling​

DigitalOcean App Platform offers elastic scaling for multiple OpenClaw agents with safe defaults and no infrastructure management.

Security Considerations​

Multi-agent setups multiply the attack surface:

  • Each agent with shell access can execute commands as your user
  • Compromised agents can potentially access other agents' workspaces unless isolated
  • Channel bindings route messages automatically — a compromised channel can reach the wrong agent

Mitigations:

  • Use separate OPENCLAW_HOME directories for sensitive vs non-sensitive agents
  • Restrict shell access per agent where possible
  • Use sandbox mode for agents handling untrusted input
  • Monitor each agent's SOUL.md for unauthorized modifications

See Also​