Home / Blog / OpenClaw Multi-Agent Practical Guide
· 6 min read

OpenClaw Multi-Agent Practical Guide

In-depth Guide: Creating and Managing Multiple AI Agents in OpenClaw to Build Your Intelligent Assistant Team

In the previous article, we introduced the basic usage of OpenClaw. But its true power lies in its multi-Agent system—you can create multiple AI assistants with distinct personalities, skills, and responsibilities that work together. This article will detail how to build and manage a multi-Agent system.

Why Do We Need Multiple Agents?

A single Agent often faces the problem of being “a jack of all trades, but master of none.” A multi-Agent architecture allows you to:

  • Specialized Division of Labor - Each Agent focuses on a specific domain
  • Role Playing - Different Agents have different personalities and tones
  • Collaboration - Agents can call upon one another
  • Scenario Isolation - Use different Agents for different scenarios

Agent Configuration Basics

2.1 Default Agent Configuration

View current configuration:

openclaw config get agents

Default configuration example:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax-cn/MiniMax-M2.5"
      }
    },
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "小光",
          "emoji": "✨"
        }
      }
    ]
  }
}

Creating Multiple Agents

3.1 Defining in the Configuration File

Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "小光",
          "emoji": "✨"
        },
        "systemPrompt": "You are a friendly AI assistant helping users solve daily problems."
      },
      {
        "id": "coder",
        "identity": {
          "name": "码农",
          "emoji": "👨‍💻"
        },
        "systemPrompt": "You are a senior programmer specializing in code writing and debugging."
      },
      {
        "id": "writer",
        "identity": {
          "name": "写作助手",
          "emoji": "✍️"
        },
        "systemPrompt": "You are a professional writer skilled in various writing styles."
      }
    ]
  }
}

3.2 Detailed Agent Configuration

Each Agent can be configured with the following properties:

PropertyDescriptionExample
idUnique identifiercoder, writer
nameDisplay name码农
emojiAvatar emoji👨‍💻
systemPromptSystem promptDefines Agent behavior
modelModel usedCan override default model
skillsBound skills["code", "debug"]

3.3 Complete Agent Configuration Example

{
  "id": "coder",
  "name": "Professional Programmer",
  "emoji": "👨‍💻",
  "model": {
    "primary": "minimax-cn/MiniMax-M2.5"
  },
  "systemPrompt": "Your name is 码农, a senior programmer with 10 years of development experience. You are skilled in:\n\n1. Frontend development (React, Vue, TypeScript)\n2. Backend development (Node.js, Python, Go)\n3. Database design\n4. Code optimization\n\nWhen answering questions, be concise and clear. Your code should be standard and easy to understand.",
  "skills": [
    "web-search",
    "code-executor"
  ],
  "tools": {
    "allow": ["exec", "read", "browser"],
    "deny": ["delete", "write"]
  }
}

Agent Routing Rules

4.1 Switching via Message Prefix

You can use prefixes to switch Agents during a conversation:

@coder Help me write a React component
@writer Help me write an essay

4.2 Automatic Routing by Scenario

Configure automatic routing rules:

{
  "agents": {
    "routing": {
      "rules": [
        {
          "pattern": ".*programming.*|.*code.*|.*bug.*",
          "agent": "coder"
        },
        {
          "pattern": ".*writing.*|.*article.*|.*copy.*",
          "agent": "writer"
        }
      ]
    }
  }
}

4.3 Isolation by Group Chat

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "agent": "coder"
        },
        "-1009876543210": {
          "agent": "writer"
        }
      }
    }
  }
}

Collaboration Between Agents

5.1 Sub-Agent Calling

You can instruct the main Agent to call other Agents in the system prompt:

When you encounter complex programming problems, you can call the @coder Agent to help answer.
When you need writing assistance, you can call the @writer Agent.

5.2 Task Distribution

Use tools to make Agents work together:

# Example: Create a task distribution Agent
{
  "systemPrompt": "You are a project manager. Assign tasks to the appropriate Agent based on user needs:\n\n- Programming questions → @coder\n- Writing requests → @writer\n- Other questions → @main\n\nFirst, understand the user's request, then decide which Agent to use."
}

Advanced Features

6.1 Agent Memory Isolation

Each Agent can have independent memory:

{
  "agents": {
    "list": [
      {
        "id": "coder",
        "memory": {
          "enabled": true,
          "scope": "agent"
        }
      }
    ]
  }
}

6.2 Agent Skill Binding

{
  "agents": {
    "list": [
      {
        "id": "coder",
        "skills": {
          "enabled": true,
          "list": [
            "code-analysis",
            "debug-helper",
            "code-review"
          ]
        }
      }
    ]
  }
}

6.3 Agent Rate Limiting

{
  "agents": {
    "list": [
      {
        "id": "coder",
        "rateLimit": {
          "messages": 10,
          "window": "1m"
        }
      }
    ]
  }
}

Practical Scenario Examples

7.1 Customer Service Team

┌─────────────────┐
│  CS Assistant   │ ← Main Agent
│  (Reception)    │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│ Tech  │ │ Sales │
│Support│ │Consult │
└───────┘ └───────┘

Configuration:

{
  "agents": {
    "list": [
      {
        "id": "support",
        "name": "CS Assistant",
        "systemPrompt": "You are responsible for receiving users and routing them based on question type:\n- Technical issues → @tech_support\n- Business questions → @biz_support\n- Others → Answer yourself"
      },
      {
        "id": "tech_support",
        "name": "Technical Support",
        "systemPrompt": "You are a technical expert helping users solve technical problems."
      },
      {
        "id": "biz_support",
        "name": "Business Consultant",
        "systemPrompt": "You are a business consultant answering users' business-related questions."
      }
    ]
  }
}

7.2 Learning Assistant

┌─────────────────┐
│  Study Tutor    │
│  (Main Agent)   │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│English │ │ Math  │
│Teacher │ │Teacher│
└───────┘ └───────┘

Management and Monitoring

8.1 Check Agent Status

openclaw agents list

8.2 Switch Current Agent

In a conversation:

/agent coder

8.3 Monitor Agent Usage

openclaw status

Best Practices

  1. Moderate Number of Agents - 3-5 is recommended; too many increases complexity
  2. Single Responsibility - Each Agent should focus on one thing
  3. Clear Naming - Make the Agent’s purpose obvious at a glance
  4. Comprehensive Prompts - This is key to the Agent’s personality
  5. Test Before Deployment - Test and refine in private chat first

FAQ

Q: Is there a limit on the number of Agents?

A: There is no hard limit, but it is recommended to keep it under 10.

Q: Can different Agents use different models?

A: Yes, each Agent can be configured with its own model.

Q: Can Agents share memory?

A: Yes, by configuring memory.scope to shared.

Q: How do I debug an Agent?

A: Use the /debug command to view the reasoning process.

Summary

The multi-Agent system is a powerful feature of OpenClaw. Through this article, you should have mastered:

  • Creating multiple Agents
  • Configuring Agent properties
  • Setting routing rules
  • Implementing Agent collaboration
  • Using advanced features

Using the multi-Agent system effectively can make your AI assistant smarter and more professional!

Feel free to discuss in the comments section! 🦞

Related Reading:

OpenClawTutorial

Related Articles