Coding Team Setup v2.1 — Flexible Multi-Agent Development Team#

English#

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

What's New in v2.0#

Featurev1.0v2.0Team sizeFixed 72–10 agentsTeam namingSingle teamMultiple named teamsRoles7 preset only10 preset + custom rolesWorkflowFixed 9-step4 templates + fully customModel assignmentHardcodedAuto-detect + manual override

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)

bash

# 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)#

RoleIDEmojiCategoryDefault Model TypeProduct Managerpm📋ManagementBalancedArchitectarchitect🏗️EngineeringStrongestFrontendfrontend🎨EngineeringCodeBackendbackend⚙️EngineeringCodeQAqa🔍QualityBalancedDevOpsdevops🚀OperationsStrongestCode Artisancode-artisan🛠️QualityCodeData Engineerdata-engineer📊EngineeringCodeSecuritysecurity🔒QualityStrongestTech Writertech-writer📝ManagementBalanced

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)

text

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)

text

Direct Development → Code Review → Deployment

Best for: Small features, hotfixes, rapid iteration

3. Fullstack Solo ( fullstack-solo)

text

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:

bash

# 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/<team-name>.json

Architecture#

text

~/.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:

Model TypeBest ForAuto-detect PatternStrongest ReasoningArchitect, DevOps, Security/opus/iCode SpecializedFrontend, Backend, Code Artisan/codex/iBalancedPM, QA, Tech Writer/sonnet/iFastSimple tasks/haiku/iLong ContextCross-file analysis/gemini.*pro/i

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

Collaboration Workflow#

Activation Protocol

text

@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

javascript

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

File Structure#

text

skills/coding-team-setup/
├── 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#

ProblemCauseFixagents_list only shows mainallowAgents missing agent IDRe-run wizard or add manuallySpawn timeoutRate Limit / model unavailableCheck fallback chainMulti-team ID conflict--team parameter not usedUse --team <name> to distinguishWorkspace files missingDirectory deleted manuallyRe-run wizard

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
2. Skill learning telemetry
   • Enable usage logging per agent/skill
   • Log format: agent_id + skill_name + timestamp + context
3. 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
4. All-team scope
   • Mechanism must apply to all teams (coding/wealth/other future teams)
   • No team-specific hardcoding in the optimizer
5. Review outputs
   • Save weekly optimization summary to memory/YYYY-MM-DD.md
   • Keep optimization history under .lib/skill_analytics/
6. 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)
7. 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 新增特性#

特性v1.0v2.0团队规模固定 7 人2–10 人团队命名单一团队多个命名团队角色7 个预设10 个预设 + 自定义协作流程固定 9 步4 个模板 + 完全自定义模型分配硬编码自动检测 + 手动覆盖

适用场景#

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

快速开始#

交互式配置向导（推荐）

bash

# 默认团队
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个）#

角色IDEmoji类别默认模型类型产品经理pm📋管理均衡型架构师architect🏗️工程最强推理前端frontend🎨工程代码专长后端backend⚙️工程代码专长QAqa🔍质量均衡型DevOpsdevops🚀运维最强推理代码工匠code-artisan🛠️质量代码专长数据工程师data-engineer📊工程代码专长安全security🔒质量最强推理技术文档tech-writer📝管理均衡型

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

协作流程模板（4个）#

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

text

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

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

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

text

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

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

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

text

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

适合：2–3人精简团队

4. 完全自定义 ( custom)

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

多团队支持#

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

bash

# 团队 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/<team-name>.json

架构#

text

~/.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 中已注册的模型，按类型匹配：

模型类型适用角色自动检测规则最强推理架构师、DevOps、安全/opus/i代码专长前端、后端、代码工匠/codex/i均衡型PM、QA、技术文档/sonnet/i快速简单任务/haiku/i长上下文跨文件分析/gemini.*pro/i

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

协作工作流#

唤醒协议

text

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

调度方式

javascript

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

文件结构#

text

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

故障排查#

问题原因解决方案agents_list 只显示 mainallowAgents 缺少 agent ID重新运行向导或手动添加Spawn 超时Rate Limit / 模型不可用检查 fallback 链多团队 ID 冲突未使用 --team 参数用 --team <name> 区分Workspace 文件缺失手动删除了目录重新运行向导

经验教训#

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 个核心技能
   • 进阶/领域技能保留为按需调用
2. 技能学习与使用追踪
   • 记录每个子代理的技能调用事件
   • 记录字段： agent_id + skill_name + timestamp + context
3. 每周技能优化任务（OpenClaw Cron）
   • 通过 openclaw cron 创建每周任务（isolated session）
   • 分析近7天使用频率，自动优化 openclaw.json 的技能映射
   • 写入前必须自动备份配置
4. 全团队统一适用
   • 机制覆盖所有团队（coding/wealth/未来团队）
   • 禁止只对单一团队硬编码
5. 输出与归档
   • 每周优化结果写入 memory/YYYY-MM-DD.md
   • 优化历史保存在 .lib/skill_analytics/
6. 子代理超时治理（新增，强制）
   • 生产场景禁止裸调 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（若有）
7. Allowlist 防护（新增）
   • allowAgents 只能合并写入 main.subagents.allowAgents（追加+去重），禁止覆盖清空。
   • 写入后先用 agents_list 验证新增代理可见，再进行 spawn。