Managing Multi-Agent Workflows with OpenClaw

OpenClaw's multi-agent system allows you to create sophisticated automation patterns by orchestrating multiple isolated agents. Each agent can be individually configured for specific tasks, security profiles, and tool access, enabling complex workflows while maintaining strict boundaries.

Understanding Agent Isolation

At the core of OpenClaw's architecture is complete agent isolation. Each agent operates with its own dedicated resources:

• Workspace: Separate file system for configuration, notes, and persona rules
• State directory: Isolated authentication profiles and session storage
• Session store: Private chat history and routing state

This isolation ensures that agents don't interfere with each other's operations or data. Authentication credentials are stored in per-agent auth-profiles.json files, preventing credential sharing unless explicitly configured.

Routing Messages to Agents

OpenClaw uses a deterministic "most-specific wins" routing system to direct messages to the appropriate agent:

1. Peer match: Exact direct message or group ID
2. Guild/Team ID: Discord or Slack workspace identifiers
3. Account ID match: Specific channel account
4. Channel-level match: All messages from a particular channel
5. Fallback: Default agent (usually "main")

This hierarchical approach allows for precise control over message routing, enabling sophisticated patterns like directing specific group conversations to specialized agents while maintaining general routing rules.

Practical Workflow Patterns

Role-Based Agent Architecture

Create specialized agents for different roles with appropriate tool access and security settings:

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "channel": "whatsapp",
        "peer": {
          "kind": "group",
          "id": "120363999999999999@g.us"
        }
      }
    }
  ]
}

In this example, the family group is routed to a restricted bot with read-only access, while personal messages go to a fully-featured assistant.

Performance-Optimized Agents

Differentiate agents based on performance requirements and use cases:

{
  "agents": {
    "list": [
      {
        "id": "chat",
        "name": "Everyday Assistant",
        "workspace": "~/.openclaw/workspace-chat",
        "model": "anthropic/claude-sonnet-4-5"
      },
      {
        "id": "opus",
        "name": "Deep Work Assistant",
        "workspace": "~/.openclaw/workspace-opus",
        "model": "anthropic/claude-opus-4-6"
      }
    ],
    "bindings": [
      { "agentId": "chat", "match": { "channel": "whatsapp" } },
      { "agentId": "opus", "match": { "channel": "telegram" } }
    ]
  }
}

This pattern routes everyday communication through a faster, cost-effective model while reserving high-performance models for complex tasks.

Security-Tiered Architecture

Implement different security profiles based on trust levels:

• Personal agent: Full host access with no sandboxing for trusted operations
• Family agent: Read-only operations within Docker containers
• Public-facing agent: Highly restricted, always sandboxed with minimal tool access

Tool Management and Restrictions

Tool Filtering Hierarchy

Tool restrictions are applied in a specific order, with each level only able to further restrict access (never grant back denied tools):

1. Tool profile
2. Provider tool profile
3. Global tool policy
4. Provider tool policy
5. Agent-specific tool policy
6. Agent provider policy
7. Sandbox tool policy
8. Subagent tool policy

Common Tool Groups

OpenClaw supports tool groups as shorthands for common permission sets:

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:messaging: message

Best Practices for Multi-Agent Workflows

Start with Restrictive Policies

Begin with conservative tool policies and gradually expand access as needed:

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "browser"]
  }
}

This "least privilege" approach minimizes potential security risks.

Use Explicit Binding Order

Always place more specific bindings before general ones in your configuration:

{
  "bindings": [
    // Specific: route one DM to Opus
    {
      "agentId": "opus",
      "match": { "channel": "whatsapp", "peer": { "kind": "direct", "id": "+15551234567" } }
    },
    // General: everything else to chat agent
    { "agentId": "chat", "match": { "channel": "whatsapp" } }
  ]
}

Since the first matching rule wins, this ensures specific routing rules take precedence.

Separate Authentication

Never reuse the same agentDir across multiple agents, as this can lead to authentication conflicts. If you need to share credentials between agents, explicitly copy the auth-profiles.json file to maintain intentional control over credential sharing.

Testing and Monitoring

Before deploying multi-agent configurations, verify they work as expected:

# Check agent routing configuration
openclaw agents list --bindings

# Verify sandbox containers are running
docker ps --filter "name=openclaw-sbx-"

# Monitor system logs for routing and sandboxing events
tail -f "~/.openclaw/logs/gateway.log" | grep -E "routing|sandbox|tools"

Troubleshooting Common Issues

Agent Not Sandboxed

If an agent isn't being sandboxed despite configuration, check for conflicting global defaults. Set an explicit agents.list[].sandbox.mode in your agent configuration to override any global settings.

Tools Still Available Despite Deny List

Verify the tool filtering order - once a tool is denied at any level, it cannot be re-enabled at a lower level in the hierarchy.

Container Not Isolated Per Agent

Ensure scope: "agent" is set in your agent-specific sandbox configuration. The default "session" scope creates a container per session, not per agent.

By following these patterns and best practices, you can create robust, secure, and efficient multi-agent workflows in OpenClaw that scale with your automation needs.