How to Build a Scalable Multi‑Agent System with OpenClaw: From Single Agent to Secure, Isolated Teams

Why a single OpenClaw agent cannot sustain complex AI workflows

OpenClaw’s default openclaw onboard creates a single main agent that shares one workspace, one MEMORY.md file and a single session store. As the number of use‑cases grows, this shared state leads to context mixing, token bloat and session‑wide compaction stalls, making a multi‑agent architecture necessary.

Core composition of an OpenClaw agent

An OpenClaw agent is an isolation unit consisting of three independent resources:

Workspace directory – the default working directory for tool execution.

Agent directory – stores agent‑specific configuration and authentication data.

Session store – persists conversation history and tool side‑effects.

These resources are not shared between agents, preventing cross‑talk. The single‑agent pipeline is Channel → Gateway → Command Queue → Agent Loop → Model → Write‑back . Multi‑agent mode inserts a routing layer after the gateway, allowing the gateway to dispatch a message to the appropriate agent.

Signals that indicate a need for multiple agents

Memory cross‑talk : an agent references private DM content or unrelated scenario memories, caused by a shared workspace and MEMORY.md.

Bloated system prompts : accumulating scenario‑specific requirements inflates the system prompt by tens of thousands of tokens per turn, slowing responses.

Compaction blocking : OpenClaw’s compaction serialises tool side‑effects; in single‑agent mode one session’s compaction blocks all others, causing noticeable stalls.

All three stem from a lack of resource isolation, which multi‑agent splitting resolves.

Hands‑on: Building a multi‑agent system

1. Creating agents

OpenClaw provides a one‑line command to generate a new agent with its own workspace, agent directory and sessions folder, and automatically adds an entry to the configuration file.

# Create a work‑focused agent
openclaw agents add work
# Create a writing‑focused agent
openclaw agents add writing

For fine‑grained control, edit ~/.openclaw/openclaw.json and add entries to agents.list:

{
  "agents": {
    "list": [
      {
        "id": "home",
        "default": true,
        "name": "Life Assistant",
        "workspace": "~/.openclaw/workspace-home"
      },
      {
        "id": "work",
        "name": "Development",
        "workspace": "~/.openclaw/workspace-work"
      }
    ]
  }
}

Key points:

Each agent’s workspace path must be unique. agentDir must not be shared; otherwise authentication fails.

Mark one agent with default: true to receive unmatched messages; if omitted the first listed agent becomes the default.

Verify creation:

openclaw agents list --bindings

2. Configuring message routing (bindings)

Routing rules map channel/account conditions to an agentId. Two common patterns are shown.

By channel / account

{
  "bindings": [
    {"agentId": "home", "match": {"channel": "whatsapp", "accountId": "personal"}},
    {"agentId": "work", "match": {"channel": "whatsapp", "accountId": "biz"}},
    {"agentId": "writing", "match": {"channel": "telegram"}}
  ]
}

By group chat

{
  "bindings": [
    {"agentId": "work", "match": {"channel": "telegram", "peer": {"kind": "group", "id": "-1001234567890"}}},
    {"agentId": "home", "match": {"channel": "telegram"}} // fallback
  ]
}

Routing matching rules:

Priority order (high → low): peer → parentPeer → Discord guildId+roles → guildId/teamId → accountId → channel fallback → default agent.

All conditions in a rule must be satisfied (AND semantics).

Within the same priority level, earlier entries win.

After editing, restart the gateway and verify:

openclaw gateway restart
openclaw channels status --probe

3. Multi‑user DM isolation

If dmPolicy: "allowlist" is enabled, set dmScope to avoid shared DM contexts. The recommended value for multi‑user scenarios is per-channel-peer:

{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

To merge identities across channels, use session.identityLinks.

Three‑layer isolation solutions

1. Soft isolation (default)

All agents run in the same gateway process; isolation is limited to separate workspaces and session files.

Simple configuration, no extra dependencies.

Agents can communicate via the sessions_send tool when tools.agentToAgent is enabled.

Low resource overhead.

Risk: agents can access each other’s workspaces via absolute paths, so this mode is unsuitable for sensitive data.

2. Docker sandbox

Provides container‑level isolation (filesystem + process). Suitable for handling sensitive data or exposing agents to external users.

Key sandbox parameters (place under agents.defaults.sandbox):

{
  "mode": "non-main",   // off | non-main | all
  "scope": "session",   // session | agent | shared
  "workspaceAccess": "none" // none | ro | rw
}

mode : non-main (default) runs private DMs outside the sandbox, group chats inside.

scope : session creates a container per session – strongest isolation.

workspaceAccess : none blocks any filesystem access from the sandbox.

Build sandbox images before enabling:

# Build a basic sandbox image
scripts/sandbox-setup.sh
# Build a common image with curl, jq, python3, git
scripts/sandbox-common-setup.sh

Note: default sandbox containers have no network ( docker.network: "none"). Configure network and root permissions via setupCommand if needed.

3. Multi‑gateway (process‑level isolation)

Runs each gateway in a separate process with completely independent resources, suitable for enterprise‑grade high‑availability.

Essential unique resources per gateway: OPENCLAW_CONFIG_PATH – path to the configuration file. OPENCLAW_STATE_DIR – state directory. agents.defaults.workspace – default workspace. gateway.port – must differ by at least 20 to avoid port clashes.

Profiles automate isolation:

# Main gateway on port 18789
openclaw --profile main onboard
openclaw --profile main gateway --port 18789
# Rescue gateway on port 19789
openclaw --profile rescue onboard
openclaw --profile rescue gateway --port 19789

Install as a background service:

openclaw --profile main gateway install

Pre‑deployment security and validation checklist

Run openclaw doctor to ensure the JSON5 config syntax is correct.

Confirm each agent’s workspace and agentDir are unique.

Verify bindings follow “specific first, fallback last” ordering.

Ensure multi‑user DM has dmScope: "per-channel-peer".

Expose remote access only via SSH tunnels or Tailscale VPN; do not open ports directly.

If sandbox is enabled, confirm images are built and network/permissions match requirements.

For multi‑gateway setups, keep port gaps ≥20 and ensure all resources are isolated.

Use openclaw channels status --probe to test channel connectivity.

OpenClaw’s gateway supports hot‑reload modes: hybrid (default), off, hot, and restart. Choose the mode that matches your deployment needs.

Practical deployment guidance

Start with soft isolation for personal or small‑team use. Upgrade to Docker sandbox when security demands increase, and adopt multi‑gateway only for enterprise‑level resilience or multi‑tenant services. Follow the three signals before splitting, match the isolation tier to the scenario, and run the checklist to avoid common pitfalls.