How to Turn a Single OpenClaw Agent into a Multi‑Agent Team: A Step‑by‑Step Guide

Agent Architecture

An OpenClaw Agent is a fully isolated unit consisting of three independent resources:

Workspace – directory that stores personality and memory files such as AGENTS.md, SOUL.md, USER.md. Default: ~/.openclaw/workspace-<em>agentId</em> AgentDir – state directory that holds authentication profiles ( auth-profiles.json) and model registrations. Default: ~/.openclaw/agents/<em>agentId</em>/agent Sessions – JSONL chat logs for each conversation. Default: ~/.openclaw/agents/<em>agentId</em>/sessions These resources are completely independent, so different agents never share memory, credentials, or files.

Initialize a Single Agent

If you have never run OpenClaw, start with the onboard wizard: openclaw onboard The wizard creates ~/.openclaw/openclaw.json with a default agent (id main) and a single channel.

Minimal viable configuration:

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing"
    }
  }
}

Run a stable channel first; later you can add agents.list and bindings for multi‑agent routing.

When to Split Agents

Watch for any of the following signals while using a single agent:

Memory mixing – the agent recalls unrelated private chats.

Bloated system prompt – the prompt grows large and consumes many tokens each turn.

Compaction blocking – a session’s compaction stalls other sessions.

If any appear, it’s time to create separate agents.

Add Multiple Agents

OpenClaw provides a one‑line wizard:

openclaw agents add work
openclaw agents add writing

Each command creates a distinct Workspace, AgentDir, and Sessions and adds an entry to the configuration file.

Manual JSON example:

{
  "agents": {
    "list": [
      {"id": "home", "default": true, "name": "Home", "workspace": "~/.openclaw/workspace-home"},
      {"id": "work", "name": "Work", "workspace": "~/.openclaw/workspace-work"},
      {"id": "writing", "name": "写作助手", "workspace": "~/.openclaw/workspace-writing"}
    ]
  }
}

Key points:

Each agent’s workspace path must be unique.

Never reuse agentDir across agents.

The agent marked default: true receives any message that does not match a binding; otherwise the first listed agent acts as the fallback.

Message Routing – bindings Layer

After agents exist, the Gateway decides which agent handles an incoming message using bindings, a deterministic list of routing rules that map match conditions to an agentId.

Typical channel‑or‑account routing:

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

Group‑based routing (single bot serving multiple groups):

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

Binding priority is deterministic; earlier entries win. Matching order (high to low) is:

Exact peer (DM or group ID) parentPeer (thread inheritance) guildId + roles (Discord role routing) guildId (Discord server) teamId (Slack team) accountId (specific channel account) accountId: "*" (catch‑all for the channel)

Default agent (fallback)

DM Safety – Configuring dmScope

If you enable multi‑user DMs (e.g., dmPolicy: "allowlist"), set dmScope to avoid all users sharing the same session context. Four possible values: main – single shared DM (good for a solo user). per-peer – isolate by sender, but share across channels. per-channel-peer – isolate by both channel and sender (recommended for multi‑user setups). per-account-channel-peer – isolate by account, channel, and sender (best for multi‑account scenarios).

Example to enforce per‑channel‑peer isolation:

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

Isolation Strategies

Three levels of isolation are available, each solving different risk profiles:

Soft isolation – agents share the same Gateway process but have separate workspaces and sessions. Low resource cost, suitable for personal or small trusted teams.

Docker sandbox – each agent’s tool execution runs inside a container, providing filesystem and process isolation. Medium cost, ideal for handling sensitive data.

Multiple Gateways – completely separate Gateway processes (different ports, config paths, state dirs). High cost, recommended for multi‑tenant services or high‑availability deployments.

Docker Sandbox Configuration

Sandbox does not wrap the Gateway; only tool execution is containerised.

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

Field explanations: mode – when to enter the sandbox. non-main isolates group/channel sessions while keeping private chats on the host. scope – container granularity: session (one container per session), agent (one container per agent), or shared (single container for all agents). workspaceAccess – what the sandbox can see: none (default, no host file access), ro (read‑only), or rw (read‑write).

Per‑agent overrides are allowed. Example:

{
  "agents": {
    "list": [
      {"id": "personal", "workspace": "~/.openclaw/workspace-personal", "sandbox": {"mode": "off"}},
      {"id": "family", "workspace": "~/.openclaw/workspace-family", "sandbox": {"mode": "all", "scope": "agent"}, "tools": {"allow": ["read","exec","sessions_list","sessions_send"], "deny": ["write","edit","apply_patch","browser","canvas"]}}
    ]
  }
}

Before enabling sandbox, build the base image:

# Basic image
scripts/sandbox-setup.sh
# Common tools (curl, jq, nodejs, python3, git)
scripts/sandbox-common-setup.sh

Note: the default sandbox container has no network access ( docker.network = "none"). Set docker.network explicitly if networking is required.

Multiple Gateways

Running several Gateways on the same host requires fully isolated resources: OPENCLAW_CONFIG_PATH – separate config files. OPENCLAW_STATE_DIR – separate state directories. agents.defaults.workspace – distinct workspaces. gateway.port – ports must differ by at least 20 to avoid clashes.

The easiest way is to use profiles:

openclaw --profile main onboard
openclaw --profile main gateway --port 18789
openclaw --profile rescue onboard
openclaw --profile rescue gateway --port 19789

# Install as background services
openclaw --profile main gateway install
openclaw --profile rescue gateway install

Remote Access

Gateway WebSocket binds to 127.0.0.1:18789 by default. Access it remotely via an SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Or use a VPN such as Tailscale. If you must expose the port publicly, enable authentication with gateway.auth.token or gateway.auth.password.

Hot‑Reload Configuration

The Gateway watches the config file and applies changes according to gateway.reload.mode: off – no automatic reload. hot – only hot‑updatable changes are applied. restart – any change triggers a restart. hybrid (default) – hot‑updates when possible, otherwise auto‑restart.

Adding a new binding or changing dmScope usually does not require a manual restart; you can run openclaw doctor to verify the configuration.

Quick‑Selection Guide

Just starting, single user – use a single agent.

Memory starts mixing – switch to soft‑isolation multi‑agent.

Small trusted team – soft‑isolation + appropriate dmScope.

Handling sensitive data – enable Docker sandbox.

Providing a public service / multi‑tenant – deploy multiple Gateways.

Need high availability or rescue capability – multiple Gateways with a rescue profile.

Pre‑Deployment Checklist (Security First)

Run openclaw doctor to ensure JSON5 syntax is correct.

Verify each agent’s Workspace and AgentDir paths are unique.

Order bindings from most specific to most generic; place catch‑all rules last.

For multi‑user DMs, set dmScope (recommended per-channel-peer).

Access remote Gateways via SSH tunnel or Tailscale; never expose ports without authentication.

Build sandbox images before enabling sandbox ( scripts/sandbox-setup.sh).

If using multiple Gateways, keep ports at least 20 apart and isolate all resources.

Confirm channel connections with openclaw channels status --probe.