# 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

```bash
# 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

```bash
openclaw configure
```

### 2. Set up Telegram Channel

```bash
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:

```bash
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:

```markdown
# 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:

```json
{
  "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:

```bash
# 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

```bash
cd ~/.openclaw/workspace
bd init
```

### 8. Start the Gateway

```bash
openclaw gateway start
```

## Auto-Routing Configuration

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

```json
{
  "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.