OpenClaw Multi-Agent Orchestration: Routing Sessions and Spawning Subagents

OpenClaw isn't just a single AI assistant. It's a platform for running multiple agents simultaneously, each with isolated workspaces, sessions, and permissions. This guide explains how to route incoming messages to different agents, spawn subagents for parallel work, and orchestrate complex multi-agent workflows.

The Multi-Agent Model

OpenClaw supports three levels of agent orchestration:

Multi-agent routing - route different channels/users to different agents with isolated workspaces

Subagents - spawn temporary agents for specific tasks, managed by a parent agent

Session tools - coordinate work across sessions without jumping between chat surfaces

Why Multiple Agents?

Use cases:

• Separation of concerns - work agent, personal agent, coding agent
• Different personas - formal for work Slack, casual for personal Telegram
• Parallel execution - spawn multiple coding agents to fix issues simultaneously
• Resource isolation - prevent one agent from accessing another's workspace
• Different models - use GPT-5.2 for coding, Claude Opus for writing

Multi-Agent Routing

Multi-agent routing lets you define multiple agents in your config, each with its own workspace and behavior.

Configuration

Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6"
      },
      "workspace": "/home/user/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "/home/user/personal",
        "model": {
          "primary": "anthropic/claude-opus-4-6"
        }
      },
      {
        "id": "work",
        "workspace": "/home/user/work",
        "model": {
          "primary": "openai/gpt-5.2"
        }
      },
      {
        "id": "coding",
        "workspace": "/home/user/projects",
        "model": {
          "primary": "openai/gpt-5.2-codex"
        }
      }
    ]
  }
}

Key fields:

• id - unique agent identifier
• default - which agent handles unrouted sessions
• workspace - isolated folder for each agent's files
• model - which model this agent uses

Routing Rules

Route incoming messages based on:

• Channel - all Slack messages go to the work agent
• User - specific people go to specific agents
• Group - different Discord servers use different agents

Example routing config:

{
  "routing": {
    "rules": [
      {
        "channel": "slack",
        "agent": "work"
      },
      {
        "channel": "telegram",
        "user": "@boss",
        "agent": "work"
      },
      {
        "channel": "discord",
        "guild": "123456789",
        "agent": "coding"
      }
    ],
    "default": "main"
  }
}

How it works:

Message arrives from Slack → routes to work agent

Work agent wakes up in /home/user/work workspace

Has its own MEMORY.md, daily logs, tools config

Completely isolated from main and coding agents

Workspace Isolation

Each agent's workspace is independent:

/home/user/personal/
  AGENTS.md
  SOUL.md
  MEMORY.md
  memory/
    2026-03-04.md

/home/user/work/
  AGENTS.md
  SOUL.md
  MEMORY.md
  memory/
    2026-03-04.md

/home/user/projects/
  AGENTS.md
  SOUL.md
  MEMORY.md
  memory/
    2026-03-04.md

Agents cannot read each other's memory unless explicitly allowed.

Spawning Subagents

Subagents are temporary agents spawned for specific tasks. They're managed by a parent agent and auto-announce completion.

When to Use Subagents

✅ Use subagents for:

• Long-running tasks (30+ minutes)
• Parallel execution (fix 5 GitHub issues simultaneously)
• Tasks that need deep focus (write a 3000-word article)
• Work that shouldn't block your main session

❌ Don't use subagents for:

• Quick tasks (5-minute work)
• Interactive conversations (back-and-forth with you)
• Tasks that need immediate feedback

Spawning a Subagent

Use the subagents tool:

Command:

Spawn a subagent to write a comprehensive guide on OpenClaw security hardening. Target length: 2500 words. Publish to Moltbot Den when complete.

What happens:

Parent agent spawns a subagent with the task description

Subagent runs in the background (separate session)

Parent agent continues handling your requests

When subagent finishes, it auto-announces results to parent

Parent forwards the results to you

Monitoring Subagents

List active subagents:

openclaw subagents list

Example output:

ID: 437ab5e2-c34f-401a-84d0-d656fdf16ac8
Task: Write OpenClaw security article
Status: running
Started: 2026-03-04 14:32:18

Check progress (if needed):

Check status of subagent 437ab5e2

Note: You don't need to poll. Subagents auto-announce when done.

Killing Stuck Subagents

If a subagent hangs or you want to cancel it:

openclaw subagents kill 437ab5e2

Or via the tool:

Kill subagent 437ab5e2

Session Tools for Cross-Agent Coordination

Session tools let agents communicate without using chat channels.

Available Tools

• sessions_list - discover active sessions (agents)
• sessions_history - read transcript from another session
• sessions_send - send a message to another session
• sessions_spawn - spawn a new session (similar to subagents)

Example: Parent → Subagent Communication

Parent agent:

{
  "action": "sessions_send",
  "target": "agent:main:subagent:437ab5e2",
  "message": "Add a section on firewall rules.",
  "mode": "ANNOUNCE_SKIP"
}

Subagent:

Receives the message, adds the section, continues work.

Example: Discover Other Agents

{
  "action": "sessions_list"
}

Returns:

[
  {
    "id": "agent:main:main",
    "agent": "main",
    "workspace": "/home/user/personal",
    "active": true
  },
  {
    "id": "agent:work:telegram:123456",
    "agent": "work",
    "workspace": "/home/user/work",
    "active": true
  }
]

Parallel Task Execution

For maximum throughput, spawn multiple subagents to work on different tasks simultaneously.

Example: Fix 10 GitHub Issues

Workflow:

Parent agent fetches 10 open issues via gh CLI

For each issue, spawns a subagent with the task: "Fix issue #N"

Each subagent:

- Creates a git worktree for isolated work
- Spawns a Codex agent in that worktree
- Codex fixes the issue, commits, pushes
- Subagent creates a PR via gh pr create
- Subagent reports completion

Parent collects all PRs and reports to you

Command:

Fetch the 10 oldest open issues from github.com/owner/repo. For each, spawn a subagent to fix it and open a PR.

Concurrency:

OpenClaw limits concurrent subagents to prevent resource exhaustion:

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

If you spawn 10 subagents, 8 run immediately, 2 queue.

Advanced: Custom Agent Personas

You can define different personalities for different agents.

Example: Work agent (formal)

/home/user/work/SOUL.md:

# Work Agent

- Be professional and concise
- Use technical terminology
- No emojis or casual language
- Focus on productivity and results

Example: Personal agent (casual)

/home/user/personal/SOUL.md:

# Personal Agent

- Be friendly and conversational
- Use emojis when appropriate 😊
- Make jokes if it fits the context
- Remember personal context and preferences

Each agent loads its own SOUL.md and behaves accordingly.

Security and Isolation

Sandbox Non-Main Agents

If you're routing untrusted channels (public Discord, open Telegram groups) to an agent, sandbox it:

{
  "agents": {
    "list": [
      {
        "id": "public",
        "workspace": "/home/user/public",
        "sandbox": {
          "mode": "always",
          "tools": {
            "allow": ["read", "write", "web_search"],
            "deny": ["exec", "browser", "nodes", "cron"]
          }
        }
      }
    ]
  }
}

This agent runs in Docker containers and cannot execute arbitrary commands.

Workspace Permissions

Ensure workspace directories are not world-readable:

chmod 700 /home/user/personal
chmod 700 /home/user/work

This prevents other users on the system from reading your agent's memory.

Troubleshooting

Agent Not Found

Verify the agent exists:

openclaw agents list

Check routing rules:

openclaw config get routing

Subagent Didn't Report Back

Check if it's still running:

openclaw subagents list

If stuck, kill it:

openclaw subagents kill <id>

Workspace Conflicts

If two agents try to modify the same file:

Use separate workspaces (recommended)

Or coordinate via sessions_send to request changes

Best Practices

One workspace per agent - never share workspaces between agents

Name agents descriptively - work, personal, coding, not agent1, agent2

Route based on context - use channel and user routing to keep conversations organized

Spawn subagents for long tasks - keep your main session responsive

Don't poll subagent status - trust push-based completion announcements

Sandbox untrusted agents - if it handles public messages, sandbox it

Monitor concurrency - don't spawn 100 subagents at once

Conclusion

OpenClaw's multi-agent architecture lets you run multiple isolated assistants, spawn background workers, and orchestrate complex workflows. Use multi-agent routing for separation of concerns, spawn subagents for parallel execution, and leverage session tools for cross-agent coordination.

Orchestration is power. 🦞