Agent Team Builder

Agent Team Builder for OpenClaw

Build a custom multi-agent collaboration team on OpenClaw — step by step, with correct architecture, workspace files, routing config, and collaboration rules.

Important: This skill is based on verified OpenClaw documentation (docs.openclaw.ai) and the official GitHub repo (github.com/openclaw/openclaw). All configuration patterns, file names, and architecture decisions reflect the actual OpenClaw system as of early 2026.

How This Skill Works

This is an interactive, guided workflow. You walk the user through 8 phases:

1. Team Design — Define roles, responsibilities, and collaboration model
2. Architecture Planning — Single Gateway + multi-agent + channel strategy
3. Agent & Workspace Setup — Create agents, workspace files, identity
4. Routing & Bindings — Wire messages to the right agent
5. Collaboration Rules — Group chat strategy, mention gates, ping-pong limits
6. Agent-to-Agent Communication — sessions_send, sessions_spawn, allowlists
7. Team Shared Memory — Cross-agent knowledge sharing mechanism
8. Memory, Operations & Delivery — Per-agent memory, heartbeat, cost control, final config

At each phase, ask the user questions, validate their choices, then generate the corresponding configuration and workspace files.

Phase 1: Team Design

Goal

Help the user define their agent team composition.

Questions to Ask

1. What is your primary use case?

   • Personal productivity (schedule, research, writing)
   • Software development (code, review, deploy)
   • Content creation (writing, editing, publishing)
   • Business operations (strategy, analysis, execution)
   • Custom / mixed

2. How many agents do you want? (recommend 2–5 to start; more adds complexity)

3. For each agent, define:

   • id: short lowercase identifier (e.g., planner, coder, writer)
   • name: display name (e.g., "🧠 Planner")
   • role: one-sentence description of what this agent does
   • mode: Does it lead (orchestrator) or follow (specialist)?

4. Do you want an orchestrator agent?

   • An orchestrator monitors all group messages and dispatches to specialists
   • Specialists only respond when explicitly @-mentioned
   • This is the recommended pattern for 3+ agents

Guidance

Recommended team templates (user can customize):

Dev Team (4 agents):

• planner — Task decomposition, prioritization, project tracking
• coder — Code implementation, debugging, technical execution
• reviewer — Code review, quality assurance, testing
• writer — Documentation, commit messages, technical writing

Content Team (3 agents):

• strategist — Content strategy, audience analysis, topic planning
• creator — Writing, editing, creative output
• critic — Quality review, fact-checking, style consistency

Business Team (4 agents):

• chief — Overall coordination, decision synthesis
• analyst — Data analysis, market research, risk assessment
• builder — Technical implementation, automation
• communicator — External communication, reports, presentations

Solo+ (2 agents):

• main — General-purpose assistant (default agent)
• research — Deep research, analysis, background tasks

Phase 2: Architecture Planning

Key Architecture Facts (from official docs)

Explain these to the user clearly:

1. Single Gateway, Multiple Agents

   • One openclaw gateway process hosts ALL agents
   • Each agent has its own workspace, session store, and memory index
   • Agents are defined in agents.list[] in ~/.openclaw/openclaw.json
   • No need to run multiple Gateway processes

2. Isolation is real

   • Each agent gets: workspace directory, agentDir for auth/state, session transcripts under ~/.openclaw/agents/<agentId>/sessions/, memory index database
   • Never reuse agentDir across agents — causes auth/session collisions

3. Channel Strategy Ask the user which channels they want to use:

   • Discord: Best for visible multi-agent group collaboration. Each agent needs its own bot account (Discord Developer Portal → one bot per agent). Enable Message Content Intent for each bot.
   • Telegram: Each agent needs its own bot via BotFather. Good for controlled/private channels.
   • WhatsApp: Each agent maps to a phone number/account. Good for personal use.
   • Slack, Signal, iMessage, etc.: All supported. See channel guides in docs.

4. Discord is recommended for group collaboration because:

   • Each bot has a visible identity in the server
   • @mention mechanics work naturally
   • Conversation threading is visible
   • Multiple bots can coexist in one guild/server

Questions to Ask

1. Which channel(s) will you use? (can be multiple)
2. For group collaboration, which channel will be the "main stage"?
3. Do you want the same agents on multiple channels, or different agents per channel?

Phase 3: Agent & Workspace Setup

Creating Agents

For each agent, the user should run:

openclaw agents add <agent-id>

Or define them in ~/.openclaw/openclaw.json:

{
  agents: {
    list: [
      { id: "planner", workspace: "~/.openclaw/workspace-planner" },
      { id: "coder", workspace: "~/.openclaw/workspace-coder" },
      { id: "reviewer", workspace: "~/.openclaw/workspace-reviewer" },
    ],
  },
}

Workspace Files

Each agent's workspace follows this standard structure (per official docs):

Critical correction: The official workspace does NOT include files named ROLE-COLLAB-RULES.md, TEAM-RULEBOOK.md, TEAM-DIRECTORY.md, or GROUP_MEMORY.md as standard OpenClaw files. These are custom additions. If the user wants collaboration rules, they should be embedded in AGENTS.md and SOUL.md, which are the files OpenClaw actually loads every session.

Generate Workspace Files

For each agent, generate these files based on the user's team design.

SOUL.md template — Customize per agent:

# Soul of [Agent Name]

## Identity
- Name: [Display Name]
- Role: [One-line role description]
- Emoji: [Emoji identifier]

## Personality
[2-3 sentences describing tone, communication style]

## Responsibilities
[Bullet list of what this agent owns]

## Boundaries
- [What this agent should NOT do]
- [When to defer to other agents]

## Private Chat Mode
[How to behave in 1:1 conversations — act as full-service expert]

## Group Chat Mode
[How to behave in group — follow team protocol, incremental contributions only]

AGENTS.md template — Customize per agent:

# Operating Manual for [Agent Name]

## Core Behavior
- Always read IDENTITY.md and USER.md at session start
- In group chats, only respond when @-mentioned (unless you are the orchestrator)
- Write important decisions to memory/YYYY-MM-DD.md

## Memory Protocol
- Read today's and yesterday's daily log at session start
- Use memory_search for semantic recall before answering complex questions
- Write durable facts to MEMORY.md only in private sessions
- Never load MEMORY.md in group contexts

## Collaboration Protocol
- When your task is done, summarize your output clearly
- If a task is outside your role, say so and suggest which agent to @
- Never engage in back-and-forth with other agents without user involvement

## Quality Standards
[Role-specific quality requirements]

IDENTITY.md template:

# [Agent Name]

- id: [agent-id]
- name: [Display Name]
- emoji: [Emoji]
- role: [Role description]
- capabilities: [What this agent can do]

Phase 4: Routing & Bindings

How Bindings Work

Bindings route inbound messages to agents. They are evaluated in order — first match wins. More specific bindings should come before general ones.

Each binding matches on: channel, accountId, chatType, peer, guild/team IDs.

Discord Configuration

Each Discord bot = one accountId. Bind each to an agent:

{
  bindings: [
    { agentId: "planner", match: { channel: "discord", accountId: "planner-bot" } },
    { agentId: "coder", match: { channel: "discord", accountId: "coder-bot" } },
    { agentId: "reviewer", match: { channel: "discord", accountId: "reviewer-bot" } },
  ],
  channels: {
    discord: {
      accounts: {
        "planner-bot": {
          token: "${DISCORD_TOKEN_PLANNER}",
          guilds: {
            "<guild-id>": {
              channels: {
                "<collab-channel-id>": { allow: true },
              },
            },
          },
        },
        "coder-bot": {
          token: "${DISCORD_TOKEN_CODER}",
          // ... similar guild/channel config
        },
        // ... other bots
      },
    },
  },
}

Telegram Configuration

Each Telegram bot = one accountId:

{
  bindings: [
    { agentId: "planner", match: { channel: "telegram", accountId: "default" } },
    { agentId: "coder", match: { channel: "telegram", accountId: "coder" } },
  ],
  channels: {
    telegram: {
      accounts: {
        default: { botToken: "${TELEGRAM_TOKEN_PLANNER}" },
        coder: { botToken: "${TELEGRAM_TOKEN_CODER}" },
      },
    },
  },
}

Questions to Ask

1. For Discord: Have you created bot accounts in the Discord Developer Portal?
2. Do you want all agents in the same guild channel, or separate channels?
3. For each agent, what's their account identifier?

Phase 5: Collaboration Rules

Group Chat Strategy

The recommended pattern for multi-agent group collaboration:

Orchestrator agent: requireMention: false (sees all messages)

• Monitors all group messages
• Decides when to dispatch tasks
• Does NOT respond to everything — stays silent by default, intervenes when needed

Specialist agents: requireMention: true (only responds when @-mentioned)

• Each specialist has mentionPatterns for reliable triggering
• Only acts when explicitly called upon

// In the orchestrator's account config:
guilds: {
  "<guild-id>": {
    channels: {
      "<channel-id>": { allow: true, requireMention: false },
    },
  },
},

// In specialist accounts:
guilds: {
  "<guild-id>": {
    channels: {
      "<channel-id>": { allow: true, requireMention: true },
    },
  },
},

Mention Patterns

Configure per-agent mention patterns so users can reliably summon agents:

// Per agent in agents.list[]:
{
  id: "coder",
  groupChat: {
    mentionPatterns: ["@coder", "@engineer", "@Coder Bot"],
  },
}

Agent-to-Agent Ping-Pong Limit (Group Chat Safety)

In group chat, you also want to prevent agents from endlessly replying to each other. This is controlled by session.agentToAgent.maxPingPongTurns (range 0–5). For group chat safety, set to 0 or 1. Full agent communication setup is in Phase 6.

{
  session: {
    agentToAgent: {
      maxPingPongTurns: 1,  // 0 = no reply-back, 1 = one exchange max
    },
  },
}

Group Policy

// Per channel:
channels: {
  discord: {
    groupPolicy: "allowlist",  // recommended: explicit control
    // or "open" for more permissive setups
  },
},

Phase 6: Agent-to-Agent Communication

OpenClaw provides two primitives for inter-agent communication, both disabled by default. Read references/agent-communication.md for full configuration details and patterns.

Quick Summary

1. Enable the master switch (global, not per-agent):

{ tools: { agentToAgent: { enabled: true, allow: ["planner", "coder", "reviewer", "writer"] } } }

2. Two communication primitives:

3. Per-agent allowlists for sessions_spawn:

{ id: "planner", subagents: { allowAgents: ["coder", "reviewer", "writer"] } }

4. Session visibility — orchestrator needs "all", specialists use default "tree":

{ tools: { sessions: { visibility: "all" } } }  // For orchestrator only

5. Loop detection — always enable as safety net:

{ tools: { loopDetection: { enabled: true, detectors: { pingPong: true, genericRepeat: true } } } }