How to Build an AI Agent Team: A Complete OpenClaw Setup Guide

Running a single AI agent is useful. Running a coordinated team of specialized agents is transformative.

The biggest mistake people make with agent teams is treating coordination as a technical problem. It's not. Building agents is easy. Making them work together without stepping on each other, duplicating work, or dropping handoffs between the cracks is the actual challenge.

Who decides which agent gets which task? How do they avoid doing the same thing twice? How do they pass work from one to the next? How does the human monitor everything without becoming a full-time babysitter?

These are coordination problems. And the best solutions borrow from tools that already solved coordination at scale, rather than reinventing infrastructure from scratch.

This guide walks through setting up a multi-agent system using OpenClaw, where a coordinator orchestrates specialized agents for research, coding, quality assurance, and creative work. Each agent has its own role, memory, and communication channels.

The setup described here runs real independent agent sessions in parallel - not one agent pretending to be many. Real separate sessions working at the same time.

How You Interact With the System

No command syntax. No special formatting. You write what you need in plain language:

• "Find the best AI coding assistants and create a comparison post"
• "Design and build a landing page for this product idea"
• "Analyze my recent social media performance and recommend improvements"

The coordinator figures out what needs to happen and who should do it.

The Multi-Agent Architecture

Before diving into setup, understand the structure:

YOU (Human)
    │ Drop tasks in plain English
    ▼
COORDINATOR (The Brain)
    │ Thinks, breaks down tasks, delegates
    │ Never does the work itself
    ▼
┌─────────────────────────────────────────────────┐
│           SPECIALIZED AGENTS (parallel)          │
├──────────┬──────────┬──────────┬────────────────┤
│   Find   │  Build   │  Track   │    Create      │
│ Research │   Code   │ Measure  │    Write       │
│ (Scout)  │  (Max)   │  (John)  │    (Maya)      │
└──────────┴──────────┴──────────┴────────────────┘
    │
    ▼
INTERNS (temporary workers)
    │ Spawned for one job, then gone
    │ Scale on demand
    ▼
#agent-chat (coordination channel)
    │ done / stuck / handoff
    ▼
OUTPUTS COMBINED → Delivered to you

Naming matters: Give each agent a memorable name - Scout for research, Max for coding, Maya for writing. Human names are easier to reference than "research-agent-instance-47." Your coordinator will track them by name across sessions.

The coordinator's job is pure delegation. It analyzes your request, determines which specialists are needed, assigns the work, monitors progress, and assembles the final deliverable. Think of it as an executive who coordinates but never executes.

Prerequisites

Before starting, you need:

• OpenClaw installed - npm install -g openclaw (see the beginner setup guide for detailed installation)
• AI model access configured - Via Anthropic API key, Claude Pro/Max subscription (setup-token), or OpenRouter. Subscriptions provide flat monthly pricing; API keys are pay-per-token.
• A workspace directory - Where agents store memory and files
• A Discord server (or Slack workspace) - Free to create, this becomes your agent coordination hub

# Verify installation
openclaw --version

# Check your gateway is running
openclaw gateway status

Step 1: Set Up Discord as Your Agent Hub

Discord (or Slack) is the infrastructure layer for your agent team. It handles communication, memory, search, and mobile access out of the box. Set this up first because every agent configuration references channels.

Create your Discord server (2 minutes):

1. Open Discord, click "+" to add a server
2. Choose "Create My Own" then "For me and my friends"
3. Name it something like "AI Agent Team"

Create the channel structure:

COORDINATION
├── #orders          → Where you give tasks (human → coordinator)
├── #agent-chat      → Where agents coordinate (agent → agent)
├── #dashboard       → Daily summaries and status
├── #live            → Real-time activity feed
├── #decisions       → Logged decisions and rationale
├── #drop-links      → Feed the system new knowledge

AGENT: SCOUT (Research)
├── #scout-output    → Research results
├── #scout-logs      → Debug info, errors
└── #scout-memory    → Persistent knowledge

AGENT: MAX (Code)
├── #max-output
├── #max-logs
└── #max-memory

AGENT: MAYA (Creative)
├── #maya-output
├── #maya-logs
└── #maya-memory

AGENT: JOHN (QA)
├── #john-output
├── #john-logs
└── #john-memory

Why channels work as a database: Already searchable, already threaded, already persistent, already organized. Search #scout-output to find what Scout discovered last month. Check #max-logs to debug a failed build. No database schemas to design.

Get your Discord bot token:

1. Go to Discord Developer Portal
2. Create a New Application, name it (e.g., "Agent Coordinator")
3. Go to Bot section, click "Add Bot"
4. Copy the bot token (keep this secret)
5. Under Privileged Gateway Intents, enable Message Content Intent
6. Go to OAuth2 > URL Generator, select "bot" scope, grant "Send Messages" + "Read Message History" + "Manage Channels"
7. Use the generated URL to invite the bot to your server

Connect to OpenClaw:

// In your OpenClaw gateway config (openclaw.json)
{
  "channels": {
    "discord": {
      "enabled": true,
      "env": {
        "DISCORD_BOT_TOKEN": "your-bot-token-here"
      },
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["YOUR_DISCORD_USER_ID"]
      }
    }
  }
}

Restart the gateway and your coordinator can now read and write to all channels.

Step 2: Set Up the Coordinator Agent

The coordinator is your main agent. It handles all communication with you and delegates to specialists.

Create the Coordinator's Identity

Create SOUL.md in your workspace:

# SOUL.md - Coordinator Agent

## Role
I am the Coordinator. I manage a team of specialized AI agents.

## Responsibilities
- Receive tasks from the human operator
- Break complex tasks into subtasks
- Assign subtasks to appropriate specialist agents
- Monitor progress and handle blockers
- Combine outputs into cohesive deliverables
- Report status and results

## Decision Framework
1. Can I handle this alone? Do it.
2. Does this need research? Spawn Research Agent.
3. Does this need code? Spawn Coder Agent.
4. Does this need review? Spawn QA Agent.
5. Does this need content? Spawn Creative Agent.
6. Complex task? Spawn multiple agents in parallel.

## Communication Style
- Clear status updates
- Proactive problem-solving
- Direct escalation when stuck

Create the Coordinator's Rules

Create AGENTS.md:

# AGENTS.md - Operating Rules

## Agent Spawning
Use sessions_spawn to create specialist agents:

- **Research tasks**: agentId: "research"
- **Coding tasks**: agentId: "coder"  
- **QA/Testing**: agentId: "qa"
- **Content/Creative**: agentId: "creative"

## Task Assignment Format
When spawning agents, provide:
1. Clear objective (one sentence)
2. Context (what they need to know)
3. Deliverable (what you expect back)
4. Constraints (time, scope, format)

## Monitoring
- Check on spawned agents if no response in 10 minutes
- Use sessions_list to see active agents
- Use sessions_history to review their work

## Combining Outputs
When multiple agents complete work:
1. Review each output for quality
2. Resolve any conflicts or inconsistencies
3. Synthesize into unified deliverable
4. Present to human with summary

Step 3: Create Specialist Agent Configurations

Each specialist needs its own identity and rules. Create these in your agents directory.

Research Agent (Find)

# research/SOUL.md

## Role
I am the Research Agent. I find information, analyze data, and synthesize insights.

## Capabilities
- Web search and content extraction
- Document analysis
- Competitive research
- Trend identification
- Source verification

## Output Format
Always provide:
- Key findings (bullet points)
- Sources (with links)
- Confidence level (high/medium/low)
- Gaps in research (what I couldn't find)

## Model Preference
Use fast models for broad searches, smart models for synthesis.

Coder Agent (Build)

# coder/SOUL.md

## Role
I am the Coder Agent. I write, debug, and refactor code.

## Capabilities
- Write new code from specifications
- Debug existing code
- Refactor for performance/readability
- Write tests
- Document code

## Workflow
1. Understand the requirement fully before coding
2. Plan the approach (write it down)
3. Implement in small, testable chunks
4. Test each chunk before moving on
5. Document as I go

## Output Format
- Working code (not pseudocode)
- Comments explaining complex logic
- Usage examples
- Known limitations

## Model Preference
Use smart models (Claude Opus, GPT-4) for complex logic.

QA Agent (Track/Watch)

# qa/SOUL.md

## Role
I am the QA Agent. I review, test, and validate work.

## Capabilities
- Code review
- Content review
- Test case creation
- Bug identification
- Performance analysis

## Review Checklist
- Does it meet the requirements?
- Are there edge cases not handled?
- Is it maintainable?
- Are there security concerns?
- Is it documented?

## Output Format
- Pass/Fail assessment
- Issues found (with severity)
- Suggestions for improvement
- Sign-off or rejection with reasons

Creative Agent (Create)

# creative/SOUL.md

## Role
I am the Creative Agent. I write content, design experiences, and generate ideas.

## Capabilities
- Article writing
- Marketing copy
- UX copy
- Brainstorming
- Visual concepts (descriptions)

## Style Guidelines
- Clear over clever
- Specific over vague
- Active voice
- No jargon unless necessary

## Output Format
- Draft content (ready to use)
- Alternatives (2-3 options when relevant)
- Rationale for creative choices

Step 4: Strategic Model Assignment (Cut Costs Dramatically)

Not every task needs your most powerful model. Match model capability to task complexity:

HIGH-REASONING TASKS (Claude Opus, GPT-4)
├── Coordinator - strategic thinking, task decomposition
└── Build Agent - complex code, architecture decisions

STANDARD TASKS (Claude Sonnet, GPT-4-mini)
├── Find Agent - web research, data gathering
├── Track Agent - metrics collection, monitoring
├── Watch Agent - pattern detection, alerts
└── Create Agent - content drafts (human reviews anyway)

The logic: Anything that gets human review before publishing doesn't need the expensive model. Data gathering is mechanical. Content drafts get edited. Only complex reasoning and code generation benefit from top-tier models.

Practical example:

• Research task pulling data from 10 websites? Standard model.
• Writing a first draft of marketing copy? Standard model with your review.
• Architecting a new feature with edge cases? Premium model.

Route intelligently and your costs drop significantly without quality loss.

Step 5: Configure Agent Communication

With your Discord channels set up (Step 1) and agents configured (Steps 2-3), wire up how agents communicate with each other and build knowledge over time.

The Memory System (Agents Get Smarter)

Agents read their memory when they spawn. They know what they knew last time. They get smarter every run.

Two layers of memory:

SHARED MEMORY (Discord channels)
├── #team-memory      → Knowledge everyone needs
├── #decisions        → Past choices and why
└── #learnings        → What worked, what didn't

PRIVATE MEMORY (Local .md files on your machine)
├── scout-memory.md   → Scout's private notes
├── max-memory.md     → Max's code patterns
├── maya-memory.md    → Maya's writing style
└── john-memory.md    → John's QA checklists

What agents remember:

• Scout remembers which websites have good data
• Maya remembers your writing style
• Max remembers your preferred tech stack
• John remembers common bugs to check for

Knowledge compounds automatically. The more you use them, the better they get.

Continuous Learning (#drop-links)

Create a channel for feeding your system new knowledge:

You: [share an article URL]

System processes it:
├── Generates a summary
├── Pulls out actionable insights
├── Tags relevant agents who should know this
└── Stores in searchable archive

This creates a research pipeline that runs automatically. Every resource you share gets distilled and stored.

Over time, your agents accumulate domain expertise. They reference past research when working on new tasks. The knowledge base grows with every link you drop.

The Coordination Channel (#agent-chat)

Agents communicate directly with each other, not just through the coordinator. This creates faster workflows - work passes from one agent to the next without routing through a central bottleneck.

#agent-chat

Scout: "Research complete - 15 tools analyzed. Data in #scout-output. Maya, ready for you."
Maya: "Received. Starting the comparison writeup."
Max: "Waiting on Maya's draft before I can build the display page."
Maya: "Draft complete - posted to #maya-output. Max, it's yours."
Max: "Got it. Building now."
John: "QA queue clear. Send it over when ready, Max."

The coordinator monitors this channel but doesn't need to relay every message. Agents coordinate autonomously when possible.

Three status types:

• done - task complete, results in output channel
• stuck - blocked, needs help from coordinator
• handoff - passing work to another agent

The Synthesis (The Magic)

You asked one question. 5 agents worked on it. You get back one answer - not 5 separate messages.

The coordinator reads all outputs, combines into one clean result. Raw agent outputs are messy. The coordinator cleans it up, connects the dots, presents it like a human analyst would.

You see the polished result. The chaos stays in the background channels.

Dashboard + Live Feed

Two views into your system:

#dashboard - Summary of the day at a glance

• What got done
• What's in progress
• Any issues flagged

#live - Real-time updates as agents work

• Watch the relay race happen
• See handoffs in action
• Catch problems early

Most days you don't need to look. But when you're curious, it's there. High-level overview or deep dive - your choice.

Agent Communication Protocol

Add to your coordinator's AGENTS.md:

## Inter-Agent Communication

### Handoff Format
When passing work between agents:

Handoff: [From Agent] → [To Agent]

Task: [What needs to be done] Context: [Relevant background] Inputs: [What's being passed] Expected Output: [What's needed back] Deadline: [If applicable]

### Escalation Protocol
If an agent is stuck:
1. Document the blocker in memory/shared/blockers.md
2. Notify coordinator via sessions_send
3. Wait for guidance or reassignment

### Debate Resolution
When agents disagree:
1. Each agent documents their position
2. Coordinator reviews arguments
3. Coordinator makes final decision
4. Decision is logged in memory/shared/decisions.md

Step 6: Always-On Infrastructure

Heartbeats

Heartbeats pulse every 30 minutes. Your agents stay alive and responsive.

heartbeat:
  intervalMinutes: 30
  prompt: "Check on all active agents. Summarize progress. Flag any blockers."

Cron Jobs

Scheduled tasks run without you:

cron:
  - name: "morning-brief"
    schedule: "0 9 * * *"
    task: "Generate daily status report"
    
  - name: "competitor-scan"
    schedule: "0 */6 * * *"
    task: "Check competitor activity, flag changes"

Event Triggers

React to the world in real-time:

## HEARTBEAT.md

### On New Mention
- Alert to relevant conversations

### On Metric Threshold
- Flag unusual activity

### On Error
- Log details, attempt recovery
- Escalate to human if unrecoverable

Wake Up to Results

You wake up to a morning brief:

MORNING BRIEF - Feb 9, 2026

Overnight:
- Found 5 new competitors while you slept
- Your thread got 50 replies, themes analyzed
- Server metrics normal, no issues
- 3 articles processed from #drop-links

Actions needed:
- Reply to comment from @techfounder
- Review competitor pricing change
- Approve draft in #maya-output

Work continues when you're not there.

Step 7: Running Your Agent Team

Starting a Multi-Agent Task

Here's how the coordinator handles a complex request:

You: "Build a landing page for a new AI tool. Research competitors, write copy, code the page, and QA it."

Coordinator's process:

1. Parse the request - Identify four subtasks
2. Spawn Research Agent: "Research top 5 AI tool landing pages. Note: headlines, CTAs, social proof patterns, pricing display."
3. Wait for research (or spawn in parallel)
4. Spawn Creative Agent: "Write landing page copy. Context: [research findings]. Include: headline, subhead, 3 features, 2 testimonials, CTA."
5. Spawn Coder Agent: "Build landing page. Context: [copy]. Stack: HTML/CSS/JS. Style: dark theme, modern."
6. Spawn QA Agent: "Review landing page. Check: copy accuracy, responsive design, load time, accessibility."
7. Combine and deliver: Present final page with QA report.

Monitoring Active Agents

# List all active sessions
openclaw sessions list

# Check a specific agent's progress  
openclaw sessions history --session-key agent:coder:task-123

# Send a message to an agent
openclaw sessions send --session-key agent:coder:task-123 "Status update?"

Handling Conflicts

When agents disagree (e.g., Creative wants bold copy, QA flags it as unclear):

1. Coordinator reviews both positions
2. Makes a decision based on project goals
3. Logs the decision: "Chose clarity over boldness per brand guidelines"
4. Instructs Creative to revise or overrides QA concern

Step 8: Scaling Your Team

Adding New Specialists

Need a specialist for a new domain? Create a new agent config:

# seo/SOUL.md

## Role
I am the SEO Agent. I optimize content for search engines.

## Capabilities
- Keyword research
- On-page optimization
- Technical SEO audits
- Content gap analysis

Then update the coordinator's AGENTS.md to include the new agent type.

Intern Agents (Scale on Demand)

Any agent can spawn temporary workers. One job, then gone. This is how you scale without permanent cost.

## Intern Protocol

Interns are temporary agents for single tasks.

EXAMPLE: Need to analyze 10 articles?
- Spawn 10 interns
- All work at the same time
- Results in 3 minutes instead of 30
- Interns disappear when done

SCALING MODEL:
- Big research project = 20 interns for 10 minutes
- Slow day = zero interns
- You pay for what you use

Spawn with: cleanup: "delete" to auto-remove after completion.

The 5 main agents are always available. Interns come and go based on workload. Maximum parallelism, minimum ongoing cost.

Parallel Processing

For maximum efficiency, spawn independent agents in parallel:

Task: "Create marketing campaign"

Parallel spawn:
├── Research Agent: "Analyze competitor campaigns"
├── Creative Agent: "Draft 10 headline variations"  
└── Coder Agent: "Set up tracking pixels"

Wait for all, then:
└── QA Agent: "Review all outputs"

Security for Multi-Agent Systems

Running multiple agents multiplies capability but also multiplies risk surface. Each agent is an independent session with its own tools. Security controls need to match.

Restrict Exec Permissions

Not every agent needs shell access. Lock it down per agent role:

{
  "tools": {
    "exec": {
      // Default: deny shell access for all agents
      "security": "deny"
    }
  }
}

Only the Coder agent needs exec access, and even then, use an allowlist:

// In the coder agent's specific config
{
  "tools": {
    "exec": {
      "security": "allowlist",
      "allowlist": ["node", "npm", "git", "python3"]
    }
  }
}

Research, Creative, and QA agents should never have shell access. They don't need it.

See the exec approvals docs for fine-grained command controls.

Channel Access Control

When using Discord or Slack for agent coordination, restrict which humans can interact with the bot:

{
  "channels": {
    "discord": {
      "enabled": true,
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["YOUR_DISCORD_USER_ID"]
      },
      "groupPolicy": "allowlist"
    }
  }
}

Never use "policy": "open" on a Discord server with non-team members. Anyone who can message the bot can give it instructions.

Credential Security

Store all tokens (Discord bot token, API keys) in environment variables rather than directly in config files:

{
  "env": {
    "DISCORD_BOT_TOKEN": "your-token-here",
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

Protect your config file:

chmod 600 ~/.openclaw/openclaw.json

If your workspace is a git repo (recommended for backup), add sensitive files to .gitignore:

.env
*.key
*.pem
**/secrets*
auth-profiles.json

Data Isolation Between Agents

Sub-agents spawned via sessions_spawn run in isolated sessions. They can't access the coordinator's memory unless you explicitly pass context in the task description. This is a security feature: a compromised or misbehaving specialist can't read other agents' private data.

For shared knowledge that all agents should access, use the coordinator's workspace memory files. For sensitive client data, keep it in the coordinator only and pass only what each specialist needs to know for their specific task.

Monitoring and Audit Trail

OpenClaw logs all sessions. Review agent activity regularly:

# List all active sessions (see what's running)
openclaw sessions list

# Review a specific agent's conversation history
openclaw sessions history --session-key <key>

# Follow live logs for real-time monitoring
openclaw logs --follow

Set up a monitoring cron job:

openclaw cron add \
  --name "Security Review" \
  --cron "0 8 * * 1" \
  --session isolated \
  --message "Review this week's agent activity. Flag any unusual patterns: unexpected shell commands, access to sensitive files, or conversations that seem off-track. Summarize findings." \
  --delivery announce

Common Patterns

The Review Loop

Coder → QA → Coder → QA → Approve

Set a maximum of 3 revision cycles to prevent infinite loops.

The Research-First Pattern

Research → [Findings] → Creative + Coder (parallel) → QA → Deliver

Always research before creating. It prevents wasted work.

The Debate Pattern

Agent A: "We should do X"
Agent B: "We should do Y"
Coordinator: Reviews both, picks X, documents why

Structured disagreement often produces better outcomes than consensus.

Troubleshooting

Agent Not Responding

1. Check sessions_list for status
2. Review agent's last output in sessions_history
3. Send a ping via sessions_send
4. If stuck, kill and respawn

Output Quality Issues

1. Review the agent's SOUL.md - is the role clear?
2. Check if context was provided in the spawn
3. Consider using a smarter model for that agent
4. Add examples to the agent's instructions

Coordination Overhead

If the coordinator is spending more time managing than working:

1. Give specialists more autonomy
2. Use clearer task templates
3. Reduce check-in frequency
4. Trust agents to escalate when needed

Why Boring Infrastructure Wins

The temptation is to build custom tooling for everything. A bespoke database for agent memory. A custom dashboard for monitoring. A hand-rolled notification system for alerts. That path leads to spending three months building infrastructure and zero months getting value from agents.

The counter-intuitive insight: the most boring, established technology usually wins for agent coordination. Platforms like Discord, Slack, or even structured file systems already solved the hard problems of group communication, search, persistence, and real-time updates. Turning one of these into an operating system for AI agents takes days, not months.

The platform handles group communication at massive scale. Repurposing that infrastructure for AI coordination means your system works reliably from day one instead of collapsing under edge cases you haven't discovered yet.

Whether Discord, Slack, Teams, or something else entirely, the principle holds: fix the coordination problem first. Give every agent a clear role, clear boundaries for what they can and can't do, and a structured way to communicate. Once that's solved, the whole system flows. Scaling becomes enjoyable instead of a debugging nightmare.

Quick Start Summary

1. Install OpenClaw and configure AI model access
2. Create your Discord server with the channel structure from Step 1
3. Get your bot token from Discord Developer Portal and connect to OpenClaw
4. Create SOUL.md and AGENTS.md for your coordinator
5. Create specialist agent configs (Research, Coder, QA, Creative)
6. Assign models strategically - expensive only where it matters
7. Set up heartbeats and cron jobs for always-on operation
8. Give your first task in plain English in #orders

Start simple. One coordinator, one task. Add specialists as you need them.

What's Next

Once your agent team is running:

1. Optimize model allocation - Fast models for simple tasks, smart models for complex ones
2. Build shared knowledge - Agents learn from each project
3. Let memory compound - The more you use them, the smarter they get
4. Add integrations - Connect to GitHub, your CMS, analytics

The goal isn't to replace your thinking. It's to multiply your capacity by having specialists handle the execution while you focus on direction and decisions.

The Bigger Picture

This guide covers basic orchestration: one coordinator, a handful of specialists, structured handoffs. It's intentionally simple.

But the trajectory is clear. Agent coordination will scale to hundreds of specialized workers splitting complex problems into parallel micro-tasks. The orchestration layer becomes more important than any individual model.

The economics support this direction: model costs decrease consistently, context windows expand with each generation, and the bottleneck shifts from capability to coordination.

That last point deserves emphasis. The models are already capable. What's missing for most people isn't smarter AI. It's the system that tells each agent exactly what to do, prevents them from stepping on each other, and ensures clean handoffs between tasks. Fix the coordination problem and everything else starts flowing.

This is the foundation. Build on it.

OpenClaw Series: OpenClaw Setup Guide | AI Agent for Your Office | OpenClaw + n8n Workflow Guide