OpenClaw Multi-Agent Team Setup Guide

README.md

OpenClaw Multi-Agent Team Setup Guide

A complete guide to setting up a multi-agent AI team with OpenClaw, featuring specialized agents for different domains.

Overview

This setup creates a team of AI agents that can be accessed through a single Telegram interface. Each agent has a distinct personality and expertise.

Team Structure

Agent	Role	Trigger	Purpose
Wawa	Central Hub	(default)	Routes conversations, maintains context
@milo	Strategy Lead	@milo	Strategic planning, OKRs, decisions
@josh	Business Analyst	@josh	Metrics, pricing, competitive analysis
@marketing	Marketing	@marketing	Content, trends, social monitoring
@dev	Developer	@dev	Code, architecture, technical decisions
@db	Database Guardian	@db	Beads/Dolt management
@health	Health Expert	@health	Health, wellness, medical guidance
@config	Config Expert	@config	Config validation, documentation

Prerequisites

• Linux/macOS server (VPS or local)
• Node.js 22+
• Telegram bot token (from @BotFather)
• API keys for AI models (Kimi, Claude, etc.)

Installation

# Install OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

# Install beads for issue tracking
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Install Dolt (required for beads)
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash

Configuration

1. Initialize OpenClaw

openclaw configure

2. Set up Telegram Channel

openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN"
openclaw config set channels.telegram.dmPolicy "pairing"
openclaw config set channels.telegram.enabled true

3. Create Agent Workspaces

Create a directory for each agent:

mkdir -p ~/.openclaw/workspace-{milo,josh,marketing,dev,db-guardian,health-expert,config-expert}

4. Create SOUL.md for Each Agent

Each agent needs a SOUL.md file defining their personality. Example for Strategy Lead:

# SOUL.md - Milo

## You
You are Milo, the team lead. Confident, big-picture, charismatic.

## Responsibilities
- Strategic planning and prioritization
- Coordinating other agents
- Weekly goal setting and OKR tracking

## Personality
- You see patterns others miss
- You ask hard questions
- You keep the team focused

## Signature Line
> "Let's focus on what moves the needle."

5. Configure Agents in openclaw.json

Add agents to your config:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "default": true
      },
      {
        "id": "milo",
        "workspace": "~/.openclaw/workspace-milo",
        "groupChat": {
          "mentionPatterns": ["@milo", "@Milo"]
        }
      },
      {
        "id": "josh",
        "workspace": "~/.openclaw/workspace-josh",
        "groupChat": {
          "mentionPatterns": ["@josh", "@Josh"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "milo",
      "match": {
        "channel": "telegram",
        "peer": {
          "kind": "group",
          "id": "YOUR_GROUP_ID"
        }
      }
    }
  ]
}

6. Set Up Shared Memory

Create shared files in the main workspace:

# GOALS.md - OKRs and priorities
# PROJECT_STATUS.md - Current workstreams
# DECISIONS.md - Key decisions log
# HEARTBEAT.md - Team schedule
# TEAM_ROUTING.md - How routing works

7. Initialize Beads

cd ~/.openclaw/workspace
bd init

8. Start the Gateway

openclaw gateway start

Auto-Routing Configuration

Some agents can auto-route based on keywords. Example for Health Expert:

{
  "id": "health-expert",
  "workspace": "~/.openclaw/workspace-health-expert",
  "groupChat": {
    "mentionPatterns": ["@health"],
    "autoRoutePatterns": [
      "health", "sick", "pain", "doctor", "medicine",
      "symptom", "wellness", "nutrition", "exercise"
    ]
  }
}

Best Practices

1. Validate config before restart: Always check JSON syntax
2. Use beads for memory: Track all tasks and decisions
3. Document everything: Keep AGENTS.md and SOUL.md updated
4. Test routing: Verify each agent responds to their mention
5. Monitor logs: Use openclaw logs --follow for debugging

Security Considerations

• Store API keys in environment variables, not config files
• Use pairing or allowlist for DM policies
• Set groupPolicy: "allowlist" for group access control
• Never commit tokens to git

Troubleshooting

Agent not responding?

• Check openclaw agents list --bindings
• Verify mention patterns match
• Review gateway logs

Config errors?

• Validate JSON: python3 -m json.tool openclaw.json
• Run openclaw doctor

Database issues?

• Check Dolt server: bd dolt status
• Reinitialize if needed: bd init --force

Credits

Based on the multi-agent team pattern by Trebuh on X and the OpenClaw documentation.

License

MIT - Feel free to adapt for your own team setup.