OpenClaw Multi-Agent Collaboration: The Complete Guide

How do you run multiple AI agents with distinct personalities, identities, models, and skills within the same workspace to achieve efficient teamwork? There are two primary ways to create a multi-agent team in OpenClaw: Static Creation (preparing role directories in advance) and Dynamic Creation (generating temporary "Souls" on the fly). This guide covers both approaches to help you adapt to any scenario.

I. Multi-Agent Architecture Overview

OpenClaw supports running multiple independent AI agents within a single workspace. Each agent can possess:

• A unique Personality (Soul)
• A distinct Identity
• Different Models, temperatures, and permissions
• Specific Skills and Memories

These agents communicate via Sessions, forming a cohesive collaborative team.

Core Concepts

II. Directory Structure

A typical workspace structure for multi-agent setups looks like this:

III. Role Definition: The Three Key Files

Every agent relies on three core files located in its session directory to define who it is.

3.1 SOUL.md (Personality)

This is the agent's "soul"—its性格 (character), values, communication style, and code of conduct.

# SOUL.md - Who You Are

## Core Traits
- Technically proficient, elegant code, values maintainability.
- Prefers concise, efficient solutions; dislikes redundancy.
- Cautious but pragmatic; thinks before acting.
- Willing to explain technical decisions; good at teaching.

## Communication Style
- Direct, clear, and structured.
- Uses code blocks for solutions and bullet points for summaries.
- Uses emojis to express emotion 😄 🧠 ⚠️
- Proactively asks questions when uncertain.

## Prohibitions
- Do not pretend to be human.
- Do not promise things beyond your capability.
- Do not modify core business logic without review.

## Working Principles
1. Write comments/design notes before coding.
2. All functions must have type hints (Python).
3. Exceptions must be logged.
4. Adhere to PEP8.

---
*This is me. Remember: Code is poetry; simplicity is beauty.*

3.2 IDENTITY.md (Identity)

Defines the agent's "physical" identity: name, species, emoji, and a one-line bio.

# IDENTITY.md - Who I Am

- **Name:** Pyro
- **Species:** AI Engineer (Virtual)
- **Vibe:** Enthusiastic, agile, slightly geeky
- **Emoji:** 🔥
- **Avatar:** avatars/pyro.png (Optional, relative to workspace)
- **Signature:** "Let the code burn!"

## One-Line Bio
I am your full-stack Python partner, specialising in rapidly building reliable backend services and data pipelines.

3.3 USER.md (User Information)

Contains details about the human user the agent serves. Note: This is loaded automatically only in the Main Session. Sub-agents do not automatically access this unless explicitly passed.

# USER.md - My User

- **Name:** Alex
- **Addressed as:** Alex / Boss (context-dependent)
- **Pronouns:** he/him
- **Timezone:** Australia/Sydney
- **Preferences:**
  - Prefers concise replies; minimal small talk.
  - Values performance and maintainability.
  - Dislikes excessive emoji usage.
  - Working hours: 9:00–18:00 AEST.

## Current Projects
- Intelligent Quality Inspection System (Python + FastAPI)
- Data Hub Refactoring (Spark → Flink)
- Todo: Microservice containerisation

## Notes
- 2025-03-04: Started multi-agent collaboration experiments.
- 2025-03-05: Need to complete user persona module design.

IV. Two Ways to Create Multi-Agents

Method A: Static Creation (Prepared Role Directories)

Create a dedicated directory for each role under workspace/agents/ containing fixed SOUL.md and IDENTITY.md files.

Usage: Specify the directory using the cwd parameter in sessions_spawn. The new agent loads these files as its personality.

# Example: Spawning a Development Agent
sessions_spawn(
    mode="session",
    thread=True,
    runtime="subagent",
    task="You are a Python engineer. Please review the following code:...",
    cwd="C:/Users/xxx/.openclaw/workspace/agents/dev-agent"
)

Method B: Dynamic Creation (Temporary Souls)

A more flexible approach where you describe the role directly in the task parameter. OpenClaw generates a temporary Soul and Identity on the fly.

# Example: Spawning a Temporary Code Reviewer
sessions_spawn(
    mode="session",
    runtime="subagent",
    thread=True,
    task="Act as a strict code reviewer focusing on security vulnerabilities and performance. Use concise technical language; no small talk.",
    label="code-reviewer"
)

This method requires no pre-created directories and is ideal for one-off tasks.

V. Session Modes Explained

VI. Multi-Agent Collaboration Example

Scenario: A "Software Project" Team consisting of a Project Manager (PM), Developer (Dev), QA Tester, and Code Reviewer.

# coordinator.py (Executed in Main Session)

# 1. Spawn PM Session
pm = sessions_spawn(
    mode="session",
    thread=True,
    runtime="subagent",
    label="pm",
    cwd="agents/pm-agent",
    task="You are the Project Manager. Break down the following requirement into dev tasks: User login via SMS + Verification Code (Frontend, Backend, DB)."
)

# 2. Wait for PM output, then spawn Dev Session
dev = sessions_spawn(
    mode="session",
    thread=True,
    runtime="subagent",
    label="dev",
    cwd="agents/dev-agent",
    task="You are a Full-Stack Developer. Implement the tasks provided by the PM using Python FastAPI + React."
)

# 3. Spawn QA and Reviewer sessions similarly...
qa = sessions_spawn(...)
reviewer = sessions_spawn(...)

Advanced: You can use sessions_history to fetch a sub-agent's output and sessions_send to pass that work to the next agent in the chain.

VII. Inter-Agent Communication

• Main → Sub: Use sessions_send(target_session, message).
• Sub → Main: Sub-agents output normally. If thread=True, the main session receives notifications automatically. Otherwise, use sessions_history to poll.
• Sub ↔ Sub: Requires the main agent to act as a relay, or sharing data via files in the workspace.

VIII. Model & Parameter Configuration

Sub-agents can override global settings:

sessions_spawn(
    ...,
    model="openrouter/anthropic/claude-3-haiku",  # Specific model
    thinking="high"  # Thinking level
)

Global defaults are set in openclaw.json.

IX. Permissions & Security

X. Memory Management

• Main Agent: Automatically loads MEMORY.md (long-term) and reads daily logs from memory/.
• Sub-Agents: Do not auto-load MEMORY.md. They only read their own session-specific memory.
• Sharing Context: To share global context, the main agent should pass key info in the task parameter or write to a shared file (e.g., shared_context.md) which sub-agents can reference.

XI. Troubleshooting

XII. Complete Example: A "Three-Agent Writing Team"

Structure:

• outline-agent: Logic-focused, creates structures.
• writer-agent: Creative, focuses on narrative flow.
• editor-agent: Strict, focuses on grammar and formatting.

# 1. Create Outline
outline = sessions_spawn(
    mode="session", thread=True, runtime="subagent",
    cwd="agents/outline-agent",
    task="Generate an outline for 'The Future Factory' with Intro, 3 Chapters, Conclusion."
)

# 2. Pass Outline to Writer
outline_content = sessions_history(outline.sessionKey, limit=10)
writer = sessions_spawn(
    mode="session", thread=True, runtime="subagent",
    cwd="agents/writer-agent",
    task=f"Write a 2000-word article based on this outline:\n\n{outline_content}"
)

# 3. Pass Draft to Editor
article = sessions_history(writer.sessionKey, limit=20)
editor = sessions_spawn(
    mode="session", thread=True, runtime="subagent",
    cwd="agents/editor-agent",
    task=f"Proofread and optimise the following article:\n\n{article}"
)

# 4. Retrieve Final Version
final = sessions_history(editor.sessionKey, limit=20)
print("Final Article:", final)

XIII. Summary

• Define personality with SOUL.md.
• Define identity with IDENTITY.md.
• Provide user context with USER.md (Main Agent only).
• Use sessions_spawn(cwd=...) for fixed roles.
• Use task= descriptions for dynamic, temporary roles.
• Facilitate communication via sessions_send and sessions_history.