Multi-Agent Dev Team v2.2 — Flexible Multi-Agent Development Team

English

> Flexible setup for 2–10 agent collaborative teams on OpenClaw.

What's New in v2.0

When to Use

• Set up a multi-role collaborative development team (2–10 agents)
• Need multiple teams to work in parallel with independent configurations
• Need custom collaboration workflows (not limited to standard 9-step)
• Need flexible role combinations and model assignments

Quick Start

Interactive Setup Wizard (Recommended)

# Default team
node <skill-dir>/wizard/setup.js

# Named team (supports multiple teams coexisting)
node <skill-dir>/wizard/setup.js --team alpha
node <skill-dir>/wizard/setup.js --team beta

The wizard guides you through:

1. Team naming — Give your team a name (supports multi-team setup)
2. Select roles — Choose 2–10 from 10 preset roles or add custom ones
3. Assign models — Auto-detect registered models or specify manually
4. Select collaboration workflow — 4 preset templates or fully custom
5. Write config — Auto-update openclaw.json + create workspace

Available Role Templates (10)

Custom roles: The wizard supports adding fully custom roles (ID, name, emoji, responsibilities, model type).

Workflow Templates (4)

1. Standard 9-Step Collaboration (standard-9step)

PM → Architect Review → Frontend + Backend (parallel) → Code Review → QA → Approval → Deployment

Best for: Complete project development with strict process control

2. Quick 3-Step Flow (quick-3step)

Direct Development → Code Review → Deployment

Best for: Small features, hotfixes, rapid iteration

3. Fullstack Solo (fullstack-solo)

Requirements Design → Fullstack Development → Testing & Deployment

Best for: 2–3 person lean team

4. Fully Custom (custom)

• Free definition of step count
• Specify roles per step (supports parallel roles)
• Set feedback loops
• Mark optional steps

Multi-Team Support

A single OpenClaw instance can run multiple teams:

# Team alpha: frontend team
node setup.js --team alpha
# Select: frontend, qa, devops

# Team beta: backend team
node setup.js --team beta
# Select: backend, architect, qa, devops

# Team gamma: fullstack
node setup.js --team gamma

Each team's agent ID includes the team prefix: alpha-frontend, beta-backend, etc.

Team configs are stored at: teamtask/teams/.json

Architecture

~/.openclaw/
├── openclaw.json              # Agent config for all teams
├── workspace/
│   └── teamtask/
│       ├── teams/             # Team manifests
│       │   ├── default.json
│       │   ├── alpha.json
│       │   └── beta.json
│       └── tasks/             # Project task directory
└── agents/                    # Subagent directory
    ├── pm/                    # default team
    ├── alpha-frontend/        # alpha team
    ├── beta-backend/          # beta team
    └── ...

Model Assignment

The wizard auto-detects registered models in openclaw.json and matches by type:

Fallback chains are auto-generated based on model type relationships.

Collaboration Workflow

Activation Protocol

@codingteam wake up              — Activate default team
@codingteam <team-name> wake up  — Activate specified team
@codingteam <role>               — Activate specified role
@codingteam 收工                 — All team members sleep

Spawning Method

// Spawn by agent ID
sessions_spawn({
  task: "Implement user auth API",
  agentId: "backend"        // default team
  // agentId: "alpha-backend"  // named team
})

File Structure

skills/multi-agent-dev-team/
├── SKILL.md               # This file
├── README.md              # Public description
├── clawhub.yaml           # ClawHub metadata
├── config/
│   └── roles.json         # Role templates + workflow templates + model types
├── templates/
│   └── SOUL-template.md   # SOUL.md template
└── wizard/
    └── setup.js           # Interactive setup wizard (v2.0)

Troubleshooting

Lessons Learned

1. allowAgents must be under main agent's subagents — not under defaults.subagents
2. Model IDs must be complete — include provider prefix
3. Gateway must restart — after modifying openclaw.json, run openclaw gateway restart
4. Concurrency control — spawning too many at once triggers Rate Limit; spawn in batches
5. Team prefix — multi-team agent IDs auto-include prefix; use full ID when spawning

Standard Post-Setup Workflow (UPDATED in v2.2)

After creating any sub-agent team, execute this as mandatory standard flow:

1. Core skill baseline assignment
• Assign 2–4 core skills per role directly in openclaw.json
• Keep advanced/domain skills as on-demand skills

1. Skill learning telemetry
• Enable usage logging per agent/skill
• Log format: agent_id + skill_name + timestamp + context

1. Weekly optimization task (OpenClaw Cron)
• Create a weekly openclaw cron job in isolated session
• Analyze last 7 days usage and update openclaw.json skill mapping
• Always backup before writing config

1. All-team scope
• Mechanism must apply to all teams (coding/wealth/other future teams)
• No team-specific hardcoding in the optimizer

1. Review outputs
• Save weekly optimization summary to memory/YYYY-MM-DD.md
• Keep optimization history under .lib/skill_analytics/

1. Mandatory Subagent Timeout Governance (NEW)
• Do not call sessions_spawn directly for production fan-out checks.
• Use timeout governance wrapper with graded timeout + retry + circuit breaker.
• Recommended baseline:
• Simple tasks: 60s, retry 2
• Normal tasks: 120s, retry 3
• Complex tasks: 180s, retry 3
• Failure classification must be explicit in reports:
• SPAWN_REJECTED / TIMEOUT / NO_CHANNEL_503 / RATE_LIMIT / UNKNOWN
• Health-check outputs must include three blocks:

1) spawn accepted/rejected

2) fallback trace (primary → fallback1 → fallback2)

3) final failure type + request id (if any)

1. Allowlist Guardrail (NEW)
• allowAgents must be merged into main.subagents.allowAgents (append + dedupe), never overwritten blindly.
• After write, verify with agents_list that all new agents are visible before any spawn.

中文

> 灵活搭建 2–10 位子代理开发团队，支持多团队命名、自定义协作流程

v2.0 新增特性

适用场景

• 搭建一个多角色协作开发团队（2–10人）
• 需要多个团队并行工作，各自独立配置
• 需要自定义协作流程（不限于标准9步）
• 需要灵活的角色组合和模型分配

快速开始

交互式配置向导（推荐）

# 默认团队
node <skill-dir>/wizard/setup.js

# 命名团队（支持多个团队并存）
node <skill-dir>/wizard/setup.js --team alpha
node <skill-dir>/wizard/setup.js --team beta

向导会引导你完成：

1. 团队命名 — 给团队一个名字（支持多团队）
2. 选择角色 — 从10个预设角色中选2–10个，或添加自定义角色
3. 分配模型 — 自动检测已注册模型，或手动指定
4. 选择协作流程 — 4个预设模板或完全自定义
5. 写入配置 — 自动更新 openclaw.json + 创建 workspace

可用的角色模板（10个）

自定义角色： 向导支持添加完全自定义的角色（ID、名称、emoji、职责、模型类型）。

协作流程模板（4个）

1. 标准9步协作流程 (standard-9step)

PM → 架构师评审 → 前端 + 后端（并行） → 代码审查 → QA → 确认 → 部署

适合：完整项目开发，需要严格流程控制

2. 快速3步流程 (quick-3step)

直接开发 → 代码审查 → 部署

适合：小型功能、hotfix、快速迭代

3. 全栈独角兽 (fullstack-solo)

需求设计 → 全栈开发 → 测试部署

适合：2–3人精简团队

4. 完全自定义 (custom)

• 自由定义步骤数量
• 每步指定角色（支持多角色并行）
• 可设置 feedback loop
• 可标记可选步骤

多团队支持

一个 OpenClaw 实例可以运行多个团队：

# 团队 alpha：前端团队
node setup.js --team alpha
# 选择: frontend, qa, devops

# 团队 beta：后端团队
node setup.js --team beta
# 选择: backend, architect, qa, devops

# 团队 gamma：全栈
node setup.js --team gamma

每个团队的 agent ID 带团队前缀：alpha-frontend, beta-backend 等。

团队配置存储在：teamtask/teams/.json

架构

~/.openclaw/
├── openclaw.json              # 所有团队的 agent 配置
├── workspace/
│   └── teamtask/
│       ├── teams/             # 团队 manifest
│       │   ├── default.json
│       │   ├── alpha.json
│       │   └── beta.json
│       └── tasks/             # 项目任务目录
└── agents/                    # 子代理目录
    ├── pm/                    # default team
    ├── alpha-frontend/        # alpha team
    ├── beta-backend/          # beta team
    └── ...

模型分配

向导自动检测 openclaw.json 中已注册的模型，按类型匹配：

Fallback 链根据模型类型关系自动生成。

协作工作流

唤醒协议

@codingteam wake up              — 激活默认团队全体
@codingteam <team-name> wake up  — 激活指定团队
@codingteam <role>               — 激活指定角色
@codingteam 收工                 — 全员休眠

调度方式

// 按 agent ID 生成
sessions_spawn({
  task: "实现用户认证 API",
  agentId: "backend"        // default team
  // agentId: "alpha-backend"  // named team
})

文件结构

skills/multi-agent-dev-team/
├── SKILL.md               # 本文件
├── README.md              # 公开描述
├── clawhub.yaml           # ClawHub 元数据
├── config/
│   └── roles.json         # 角色模板 + 流程模板 + 模型类型
├── templates/
│   └── SOUL-template.md   # SOUL.md 模板
└── wizard/
    └── setup.js           # 交互式配置向导 (v2.0)

故障排查

经验教训

1. allowAgents 必须在 main agent 的 subagents 下 — 不是 defaults.subagents
2. 模型 ID 必须完整 — 包含 provider 前缀
3. Gateway 必须重启 — 修改 openclaw.json 后 openclaw gateway restart
4. 并发控制 — 同时 spawn 太多会触发 Rate Limit，建议分批
5. 团队前缀 — 多团队时 agent ID 自动带前缀，spawn 时要用完整 ID

标准后置流程（v2.2 更新）

所有子代理团队创建完成后，必须执行以下标准流程：

1. 核心技能基线配置
• 每个角色在 openclaw.json 固定配置 2–4 个核心技能
• 进阶/领域技能保留为按需调用

1. 技能学习与使用追踪
• 记录每个子代理的技能调用事件
• 记录字段：agent_id + skill_name + timestamp + context

1. 每周技能优化任务（OpenClaw Cron）
• 通过 openclaw cron 创建每周任务（isolated session）
• 分析近7天使用频率，自动优化 openclaw.json 的技能映射
• 写入前必须自动备份配置

1. 全团队统一适用
• 机制覆盖所有团队（coding/wealth/未来团队）
• 禁止只对单一团队硬编码

1. 输出与归档
• 每周优化结果写入 memory/YYYY-MM-DD.md
• 优化历史保存在 .lib/skill_analytics/

1. 子代理超时治理（新增，强制）
• 生产场景禁止裸调 sessions_spawn 做并发健康检查。
• 必须走超时治理封装（分级超时 + 重试 + 熔断）。
• 推荐基线：
• 简单任务：60s，重试2次
• 普通任务：120s，重试3次
• 复杂任务：180s，重试3次
• 报告必须输出统一失败分型：
• SPAWN_REJECTED / TIMEOUT / NO_CHANNEL_503 / RATE_LIMIT / UNKNOWN
• 健康检查结果必须包含三段：

1) spawn 是否 accepted

2) fallback 轨迹（primary → fallback1 → fallback2）

3) 最终失败类型 + request id（若有）

1. Allowlist 防护（新增）
• allowAgents 只能合并写入 main.subagents.allowAgents（追加+去重），禁止覆盖清空。
• 写入后先用 agents_list 验证新增代理可见，再进行 spawn。