OpenClaw Multi-Agent Team Setup Guide - A complete guide to setting up a team of specialized AI agents

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 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.