Back
Openclaw-Series

10. OpenClaw Multi-Agent Routing and Session Isolation

This article explains OpenClaw's multi-Agent architecture in depth, including how to configure multiple Agent instances, message routing rules, session isolation strategies, and best practices for team collaboration scenarios, helping you build enterprise-grade AI assistant systems.

  • “AI workspace”
  • “OpenClaw team collaboration”

For OpenClaw v2026.2 | This article is for team users or those who need isolated contexts.

TL;DR: Multi-Agent config: "agents": {"instances": {"personal": {...}, "work": {...}}}. Routing rules: "routing": {"rules": [{"match": {"channel": "telegram"}, "agent": "personal"}]}. Session isolation: "sessions": {"isolation": "user"}. Sandbox mode: "sandbox": {"mode": "non-main"}. Suitable for multi-user, multi-project, multi-purpose scenarios.

Why Multi-Agent?

Limitations of Single Agent

Scenario Single Agent Problem Multi-Agent Solution
Multi-user Context confusion, privacy issues Independent Agent per user
Multi-project Project info mixed together Independent Agent per project
Multi-purpose One Agent, many roles Specialized Agents
Multi-team Hard to control permissions Isolate Agents by team
Cost Control Cannot separate usage Independent billing per model

Multi-Agent Use Cases

flowchart TB
    subgraph Users["Users"]
        U1[User A]
        U2[User B]
        U3[Team X]
        U4[Team Y]
    end
    
    subgraph Router["Message Routing"]
        R[Routing Rules]
    end
    
    subgraph Agents["Agent Instances"]
        A1[Personal Agent A]
        A2[Personal Agent B]
        A3[Team Agent X]
        A4[Team Agent Y]
    end
    
    subgraph Models["Models"]
        M1[Claude Opus]
        M2[Claude Sonnet]
        M3[GPT-4o]
        M4[Haiku]
    end
    
    U1 --> R
    U2 --> R
    U3 --> R
    U4 --> R
    R --> A1
    R --> A2
    R --> A3
    R --> A4
    A1 --> M1
    A2 --> M2
    A3 --> M3
    A4 --> M4

Multi-Agent Configuration

Basic Structure

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.openclaw/workspace"
    },
    "instances": {
      "personal": {
        "model": "anthropic/claude-opus-4-6",
        "workspace": "~/.openclaw/workspaces/personal",
        "thinkingLevel": "high"
      },
      "work": {
        "model": "anthropic/claude-sonnet-4",
        "workspace": "~/.openclaw/workspaces/work",
        "skills": ["github", "jira", "confluence"]
      },
      "assistant": {
        "model": "anthropic/claude-haiku-3.5",
        "workspace": "~/.openclaw/workspaces/assistant"
      }
    }
  }
}

Agent Config Options

Config Option Description Example
model Model to use anthropic/claude-opus-4-6
workspace Working directory ~/.openclaw/workspaces/personal
thinkingLevel Thinking level high, medium, low
skills Enabled skills ["gmail", "calendar"]
sandbox Sandbox config { "mode": "non-main" }
contextWindow Context window 200000

Workspace Structure

~/.openclaw/
├── workspace/              # Default workspace
│   ├── AGENTS.md
│   ├── SOUL.md
│   └── skills/
├── workspaces/
│   ├── personal/          # Personal Agent
│   │   ├── AGENTS.md
│   │   ├── SOUL.md
│   │   └── USER.md
│   ├── work/              # Work Agent
│   │   ├── AGENTS.md
│   │   └── skills/
│   └── assistant/         # Assistant Agent
│       └── AGENTS.md
└── openclaw.json          # Main config

Message Routing Rules

Routing Configuration

{
  "routing": {
    "rules": [
      {
        "match": {
          "channel": "telegram",
          "sender": "123456789"
        },
        "agent": "personal"
      },
      {
        "match": {
          "channel": "discord",
          "guild": "987654321"
        },
        "agent": "work"
      },
      {
        "match": {
          "session": "main"
        },
        "agent": "personal"
      }
    ],
    "default": "personal"
  }
}

Routing Rule Fields

Match Field Description Example
channel Channel type telegram, discord, slack
sender Sender ID 123456789
guild Discord server ID 987654321
group Group ID -100123456789
session Session ID main, telegram:user:123
pattern Regex match ^work-

Complex Routing Example

{
  "routing": {
    "rules": [
      {
        "name": "Personal Telegram",
        "match": {
          "channel": "telegram",
          "sender": ["123456789", "987654321"]
        },
        "agent": "personal"
      },
      {
        "name": "Work Discord",
        "match": {
          "channel": "discord",
          "guild": "111222333"
        },
        "agent": "work"
      },
      {
        "name": "Work Group",
        "match": {
          "channel": "telegram",
          "group": "-100111222333"
        },
        "agent": "work"
      },
      {
        "name": "Test Environment",
        "match": {
          "pattern": "^test-"
        },
        "agent": "assistant",
        "config": {
          "sandbox": { "mode": "always" }
        }
      }
    ],
    "default": "personal"
  }
}

Routing Priority

flowchart TB
    MSG[Message Arrives] --> R1{Match Rule 1?}
    R1 -->|Yes| A1[Agent 1]
    R1 -->|No| R2{Match Rule 2?}
    R2 -->|Yes| A2[Agent 2]
    R2 -->|No| R3{Match Rule 3?}
    R3 -->|Yes| A3[Agent 3]
    R3 -->|No| D[Default Agent]

Rules are matched in order; the first matching rule takes effect.

Session Isolation

Isolation Levels

Level Description Use Case
No Isolation Shared context Single user, single purpose
Channel Isolation Independent context per channel Multi-channel access
User Isolation Independent context per user Multi-user sharing
Session Isolation Independent per session Full isolation
Agent Isolation Independent per Agent Multi-Agent deployment

Configuring Session Isolation

{
  "sessions": {
    "isolation": "user",
    "persistence": true,
    "retention": {
      "maxAge": 604800000,
      "maxSessions": 100
    }
  }
}

Isolation Config Details

{
  "sessions": {
    "isolation": "user",
    "storage": {
      "type": "file",
      "path": "~/.openclaw/sessions"
    },
    "encryption": {
      "enabled": true,
      "algorithm": "aes-256-gcm"
    },
    "retention": {
      "maxAge": 604800000,
      "maxSessions": 100,
      "cleanupInterval": 86400000
    }
  }
}
Config Option Description Default
isolation Isolation level user
storage.type Storage type file
encryption.enabled Enable encryption true
retention.maxAge Max retention time 7 days
retention.maxSessions Max session count 100

Team Collaboration Scenarios

Scenario 1: Small Team Sharing

{
  "agents": {
    "instances": {
      "team": {
        "model": "anthropic/claude-sonnet-4",
        "workspace": "~/.openclaw/workspaces/team",
        "skills": ["github", "jira", "slack"]
      }
    }
  },
  "routing": {
    "rules": [
      {
        "match": { "channel": "slack" },
        "agent": "team"
      },
      {
        "match": { "channel": "discord" },
        "agent": "team"
      }
    ],
    "default": "team"
  }
}

Scenario 2: Department Isolation

{
  "agents": {
    "instances": {
      "engineering": {
        "model": "anthropic/claude-opus-4-6",
        "workspace": "~/.openclaw/workspaces/engineering",
        "skills": ["github", "jira", "pagerduty"],
        "sandbox": { "mode": "off" }
      },
      "marketing": {
        "model": "anthropic/claude-sonnet-4",
        "workspace": "~/.openclaw/workspaces/marketing",
        "skills": ["mailchimp", "analytics"],
        "sandbox": { "mode": "non-main" }
      },
      "support": {
        "model": "anthropic/claude-haiku-3.5",
        "workspace": "~/.openclaw/workspaces/support",
        "skills": ["zendesk", "intercom"],
        "sandbox": { "mode": "always" }
      }
    }
  },
  "routing": {
    "rules": [
      {
        "name": "Engineering Discord",
        "match": { "channel": "discord", "guild": "111111111" },
        "agent": "engineering"
      },
      {
        "name": "Marketing Slack",
        "match": { "channel": "slack", "team": "T22222222" },
        "agent": "marketing"
      },
      {
        "name": "Support Telegram",
        "match": { "channel": "telegram", "group": "-100333333333" },
        "agent": "support"
      }
    ],
    "default": "support"
  }
}

Scenario 3: Multi-tenant SaaS

{
  "agents": {
    "dynamic": true,
    "template": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.openclaw/workspaces/tenants/{{tenantId}}",
      "skills": ["base"],
      "sandbox": { "mode": "always" }
    },
    "limits": {
      "maxAgents": 100,
      "maxSessionsPerAgent": 50,
      "maxTokensPerMonth": 1000000
    }
  },
  "routing": {
    "rules": [
      {
        "name": "Tenant Routing",
        "match": { "header": "X-Tenant-Id" },
        "agent": "tenant_{{tenantId}}",
        "createIfNotExists": true
      }
    ]
  }
}

Permissions and Security

Agent Permission Control

{
  "agents": {
    "instances": {
      "trusted": {
        "model": "anthropic/claude-opus-4-6",
        "sandbox": { "mode": "off" },
        "permissions": {
          "filesystem": { "read": true, "write": true },
          "network": { "outbound": true },
          "process": { "execute": true }
        }
      },
      "restricted": {
        "model": "anthropic/claude-haiku-3.5",
        "sandbox": { "mode": "always" },
        "permissions": {
          "filesystem": { 
            "read": ["~/allowed/"],
            "write": ["~/allowed/"]
          },
          "network": { 
            "outbound": ["api.example.com"]
          },
          "process": { "execute": false }
        }
      }
    }
  }
}

Sandbox Modes

Mode Description Use Case
off No sandbox Trusted Agent
non-main Sandbox for non-main sessions Team sharing
always Always sandbox Untrusted environment

Sandbox Configuration

{
  "sandbox": {
    "mode": "non-main",
    "container": {
      "image": "openclaw/sandbox:latest",
      "timeout": 30000,
      "memory": "512m",
      "cpu": "0.5"
    },
    "allowlist": ["read", "write", "edit", "bash"],
    "denylist": ["browser", "canvas", "nodes"],
    "networkPolicy": {
      "allow": ["api.example.com"],
      "deny": ["*"]
    }
  }
}

Monitoring and Management

Agent Status Monitoring

# List all Agent instances
openclaw agents list

# Sample output:
# Name        Model                  Sessions  Status   Last Active
# personal    claude-opus-4-6        3         active   2 min ago
# work        claude-sonnet-4        5         active   5 min ago
# assistant   claude-haiku-3.5       2         idle     1 hour ago

# View Agent details
openclaw agents show personal

# View routing rules
openclaw routing list

Session Management

# List all sessions
openclaw sessions list --agent personal

# Sample output:
# Session ID              Channel    Sender      Created      Messages
# telegram:user:123       telegram   123456789   2026-02-26   42
# main                    cli        -           2026-02-25   128

# View session details
openclaw sessions show telegram:user:123

# Export session
openclaw sessions export telegram:user:123 --format json

# Delete session
openclaw sessions delete telegram:user:123

Usage Statistics

# View usage grouped by Agent
openclaw usage --by-agent

# Sample output:
# Agent       Tokens In    Tokens Out   Cost      Requests
# personal    125,000     45,000      $2.10     128
# work        89,000      32,000      $1.25     95
# assistant   15,000      8,000       $0.15     42

# Stats by time range
openclaw usage --by-agent --from 2026-02-01 --to 2026-02-28

Best Practices

1. Reasonable Agent Partitioning

Dimension Description Example
Purpose By function coding, research, assistant
Project By project project-alpha, project-beta
Team By team engineering, marketing
Model By model opus, sonnet, haiku

2. Config Inheritance

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.openclaw/workspace",
      "thinkingLevel": "medium",
      "sandbox": { "mode": "non-main" }
    },
    "instances": {
      "opus": {
        "model": "anthropic/claude-opus-4-6",
        "thinkingLevel": "high"
        // Inherits workspace and sandbox from defaults
      },
      "haiku": {
        "model": "anthropic/claude-haiku-3.5",
        "thinkingLevel": "minimal"
        // Inherits other config from defaults
      }
    }
  }
}

3. Least Privilege

{
  "agents": {
    "instances": {
      "restricted": {
        "model": "anthropic/claude-haiku-3.5",
        "sandbox": { "mode": "always" },
        "permissions": {
          "filesystem": {
            "read": ["~/allowed/read"],
            "write": ["~/allowed/write"]
          },
          "network": {
            "outbound": []
          },
          "process": {
            "execute": false
          }
        }
      }
    }
  }
}

4. Monitoring and Alerts

{
  "monitoring": {
    "alerts": [
      {
        "condition": "usage > 1000000",
        "action": "notify"
      },
      {
        "condition": "error_rate > 0.1",
        "action": "notify"
      },
      {
        "condition": "response_time > 10000",
        "action": "notify"
      }
    ],
    "webhook": "https://your-monitoring.com/webhook"
  }
}

Troubleshooting

Routing Not Working

# View current routing rules
openclaw routing list

# Test routing
openclaw routing test --channel telegram --sender 123456789

# Sample output:
# Matched Rule: Personal Telegram
# Target Agent: personal
# Route Path: default -> rule 1 -> personal

Session Isolation Issues

# Check session isolation config
openclaw config get sessions.isolation

# Check session list
openclaw sessions list --all

# Reset session isolation
openclaw sessions reset --agent personal

Permission Issues

# Check permission config
openclaw agents permissions show personal

# Test permission
openclaw agents test-permission personal --action filesystem.read --path ~/test

# Sample output:
# Permission: filesystem.read
# Path: ~/test
# Result: ALLOWED

Summary

The multi-Agent architecture is an advanced OpenClaw feature that provides strong support for team and enterprise scenarios:

  • Flexible Routing: Assign different Agents by channel, user, or project
  • Session Isolation: Protect privacy and avoid context confusion
  • Permission Control: Fine-grained permission management
  • Cost Optimization: Choose different models by purpose
  • Scalability: Support dynamic Agent creation and management

Key Takeaways:

  • Understood multi-Agent architecture value and use cases
  • Mastered Agent config and message routing rules
  • Learned session isolation configuration
  • Understood best practices for team collaboration
  • Mastered permission control and monitoring

Changelog:

  • 2026-02-26: Initial release, based on OpenClaw v2026.2

Series Navigation: