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. 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 — sessionssend, sessionsspawn, 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. 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

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

1. 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)?

1. 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
• INLINECODE8 — Code implementation, debugging, technical execution
• INLINECODE9 — Code review, quality assurance, testing
• INLINECODE10 — Documentation, commit messages, technical writing

Content Team (3 agents):

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

Business Team (4 agents):

• - chief — Overall coordination, decision synthesis
• INLINECODE15 — Data analysis, market research, risk assessment
• INLINECODE16 — Technical implementation, automation
• INLINECODE17 — External communication, reports, presentations

Solo+ (2 agents):

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

---

Phase 2: Architecture Planning

Key Architecture Facts (from official docs)

Explain these to the user clearly:

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

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

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

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

CODEBLOCK0

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

CODEBLOCK1

Workspace Files

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

File	Purpose	Loaded When
INLINECODE27	Operating instructions, memory rules, behavior priorities	Every session
INLINECODE28

Persona, tone, boundaries | Every session |
| USER.md | Who the user is, how to address them | Every session |
| IDENTITY.md | Agent name, vibe, emoji (created during bootstrap) | Every session |
| TOOLS.md | Notes about local tools/conventions (guidance only, does NOT control tool access) | Every session |
| HEARTBEAT.md | Optional tiny checklist for heartbeat runs | Heartbeat only |
| BOOT.md | Optional startup checklist on gateway restart | Gateway start |
| BOOTSTRAP.md | One-time first-run ritual, deleted after completion | First run only |
| memory/YYYY-MM-DD*.md | Daily memory logs (append-only) | On demand |
| MEMORY.md | Curated long-term memory | Private sessions only |

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:

CODEBLOCK2

AGENTS.md template — Customize per agent:

CODEBLOCK3

IDENTITY.md template:

CODEBLOCK4

---

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:

CODEBLOCK5

Telegram Configuration

Each Telegram bot = one accountId:

CODEBLOCK6

Questions to Ask

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

CODEBLOCK7

Mention Patterns

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

CODEBLOCK8

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.

CODEBLOCK9

Group Policy

CODEBLOCK10

---

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):
CODEBLOCK11

2. Two communication primitives:

Primitive	Use Case	Behavior
INLINECODE57	Direct agent-to-agent conversation	Synchronous, supports ping-pong (0–5 turns)
INLINECODE58

Delegate task to another agent | Async, isolated session, announces result back |

3. Per-agent allowlists for sessions_spawn:
CODEBLOCK12

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

5. Loop detection — always enable as safety net:
CODEBLOCK14

Questions to Ask

1. 1. Which agents need to talk to each other? (Draw the communication graph)
2. Synchronous exchanges (sessions_send) or async delegation (sessions_spawn)?
3. Should the orchestrator spawn tasks to ALL other agents?
4. Max ping-pong turns? (0 = safest, 2 = practical, 5 = max)

---

Phase 7: Team Shared Memory

Each agent has its own isolated workspace and memory. There is no built-in
cross-agent shared memory. Read references/team-shared-memory.md for full
implementation details, setup scripts, and file templates.

The Design

Create a shared directory symlinked into every agent's workspace:

CODEBLOCK15

Quick Setup

CODEBLOCK16

Why This Pattern

• - All agents read/write via memory_get and file tools — no special API needed
• Changes by one agent are immediately visible to others on next turn
• Not auto-loaded into bootstrap — avoids prompt cache invalidation on every update
• Agents read on demand per AGENTS.md instructions, keeping token costs low

AGENTS.md Rules (Add to Every Agent)

CODEBLOCK17

Memory Search Limitation

INLINECODE66 only indexes the current agent's workspace. Symlinked dirs may not
be indexed. Use memory_get (targeted file read) for shared files — it always works.

---

Phase 8: Memory, Operations & Delivery

Memory Architecture

OpenClaw's memory is file-based Markdown with semantic search.

Two standard layers (per official docs):

1. 1. Daily logs (memory/YYYY-MM-DD.md) — append-only, day-to-day decisions and context
2. Long-term memory (MEMORY.md) — curated durable facts, only loaded in private sessions

Memory tools available to agents:

• - memory_search — semantic recall over indexed snippets (hybrid BM25 + vector search)
• INLINECODE71 — targeted read of a specific file/line range

Critical correction: The article mentions GROUP_MEMORY.md as a standard file.
This is NOT a standard OpenClaw workspace file. The official approach is:

• - MEMORY.md loads only in private/main sessions (never in groups)
• Group chats have their own isolated session state
• For cross-session context sharing, use a projects/ directory pattern

with self-contained docs readable from any session

Memory Configuration

CODEBLOCK18

Cost Control Tips

1. 1. Model tiering: Use expensive models (Opus) for the orchestrator, cheaper models (Sonnet/Haiku) for specialists
2. Heartbeat budget: Keep HEARTBEAT.md short to avoid token burn
3. Bootstrap file limits: Default bootstrapMaxChars: 20000 per file, bootstrapTotalMaxChars: 150000 total
4. Memory flush: Enable auto-flush before compaction to preserve context

CODEBLOCK19

Per-Agent Tool Policies

Each agent can have its own tool allow/deny list:

CODEBLOCK20

---

Phase 9: Generate & Deliver

After collecting all information, generate:

1. 1. openclaw.json — Complete configuration (see references/openclaw-team-example.json5 for full template)
2. Workspace files — SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md for each agent
3. Team shared directory — TEAM-KNOWLEDGE.md, TEAM-DECISIONS.md, TEAM-STATUS.md, TEAM-DIRECTORY.md
4. Symlink setup script — Creates team-shared/ symlinks in every workspace
5. Setup script — Shell commands to create agents, wire channels, verify
6. Quick-start guide — How to test the team

Verification Commands

CODEBLOCK21

---

Common Corrections & Pitfalls

When guiding users, proactively correct these common misconceptions:

Architecture Misconceptions

1. 1. "Each agent needs its own Gateway process" → Wrong. One Gateway hosts all agents.

Multiple agents share the same server process and config file.

1. 2. "Workspaces are sandboxed by default" → Wrong. Agents can access other host

locations via absolute paths unless sandbox is explicitly enabled per-agent.

1. 3. "TOOLS.md controls tool access" → Wrong. TOOLS.md is guidance text only.

Actual tool access is controlled by agents.list[].tools.allow/deny in config.

File Name Misconceptions

1. 4. Custom files like ROLE-COLLAB-RULES.md, TEAM-RULEBOOK.md, GROUP_MEMORY.md

→ These are NOT standard OpenClaw files. Put collaboration rules in AGENTS.md and SOUL.md which are loaded every session. Custom files won't auto-load.

1. 5. "MEMORY.md loads everywhere" → Wrong. MEMORY.md only loads in private/main

sessions, never in group contexts. This is a privacy protection.

Routing Misconceptions

1. 6. "bindings map channel + accountId → agentId" → Partially correct but

oversimplified. Bindings can match on channel, accountId, chatType, peer (kind + id), and guild/team IDs. They are evaluated in order, first match wins.

1. 7. "You need N×M bindings for N agents × M channels" → Not necessarily. You can

use channel-wide defaults and only add specific bindings for exceptions.

Collaboration Misconceptions

1. 8. "agentToAgent ping-pong set to 0 means agents can't communicate" → It means

agents can't do reply-back ping-pong via sessions_send. They can still use sessions_spawn for sub-agent tasks, and the orchestrator can still @-mention others in group chats.

1. 9. "Discord is the only platform for multi-agent collaboration" → Any channel works.

Discord is convenient because each bot has visible identity and @mention is natural. Feishu, Slack, and others support similar patterns.

---

Reference: Official Workspace File List

From docs.openclaw.ai/concepts/agent-workspace:

• - AGENTS.md — Operating instructions (loaded every session)
• INLINECODE91 — Persona, tone, boundaries (loaded every session)
• INLINECODE92 — User profile (loaded every session)
• INLINECODE93 — Agent name/emoji (created during bootstrap)
• INLINECODE94 — Tool notes, guidance only (loaded every session)
• INLINECODE95 — Heartbeat checklist (optional)
• INLINECODE96 — Startup checklist (optional)
• INLINECODE97 — First-run ritual (deleted after completion)
• INLINECODE98 — Daily memory logs
• INLINECODE99 — Long-term memory (private sessions only)
• INLINECODE100 — Workspace-specific skills

For the complete multi-agent reference, read:

• - references/architecture-corrections.md — Common misconceptions and corrections
• INLINECODE102 — Full example configuration file