# Multi-Agent Routing Documentation

## Core Concept

OpenClaw supports running multiple isolated agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts within a single Gateway instance. Messages are routed to appropriate agents via bindings.

## What Defines an Agent

An agent comprises:
- Its own workspace (files, configuration documents, notes)
- Dedicated state directory (`agentDir`) for auth and configuration
- Isolated session store for chat history

Auth profiles are per-agent. Each agent reads from its own dedicated `auth-profiles.json` location, preventing credential sharing unless explicitly copied.

## Key Path Structure

- Config: `~/.openclaw/openclaw.json`
- Workspace: `~/.openclaw/workspace` (or agent-specific variant)
- Sessions: `~/.openclaw/agents/<agentId>/sessions`

## Routing Mechanism

Bindings follow deterministic matching with most-specific wins priority. Priority follows this order: peer match, `guildId`, `teamId`, `accountId`, channel-level match, then fallback to default agent.

## Multi-Account Scenarios

Users can route different WhatsApp accounts to separate agents, or split a single account's DMs across multiple agents by matching sender E.164 identifiers with `peer.kind: "dm"`.

## Security Features

As of v2026.1.6, agents support per-agent sandbox modes and tool restrictions. Different permissions per agent enable security isolation while maintaining flexibility across your Gateway deployment.