ClawTeam：当一个 AI Agent 不够用的时候

前两篇写了 Claude Code 的深度使用指南 和 Superpowers 插件。一个解决"怎么用好 AI Agent"，一个解决"让它先想再做"。

但有些项目，一个 Agent 串行做实在太慢了——前后端要同时开发、多个模块互不依赖却只能排队执行、不同任务明明适合不同模型却只能用同一个。

需要的不是"一个更有纪律的 Agent"，而是一个团队。

这就是 ClawTeam 要解决的问题。

Superpowers vs ClawTeam：先搞清楚边界

在介绍 ClawTeam 之前，先说清楚它和上一篇的 Superpowers 是什么关系——因为它们解决的是两个完全不同的问题。

什么时候用 Superpowers：改一个功能、修一个 bug、做一个组件——需要的是流程纪律，不是人力。

什么时候用 ClawTeam：项目有多个独立模块要同时推进，或者不同任务需要不同模型的特长。

两者不冲突——ClawTeam 的每个 Worker 内部完全可以用 Superpowers 的流程。Leader 拆完任务，Worker 拿到任务后先 brainstorming 再 writing-plans 再执行，和单 Agent 开发一样。区别只是现在有多个 Worker 在并行。

ClawTeam 五个核心概念

后面会逐个展开。

怎么用：以 Web 应用开发为例

假设要做一个 Todo Web 应用——有后端 API、前端 UI、数据库设计、测试，天然适合并行。

第一步：创建团队

1
2
3

clawteam team spawn-team todo-dev \
  -d "Todo 应用开发团队" \
  -n tech-lead

这条命令创建了一个叫 todo-dev 的团队，同时注册了 Leader，名字是 tech-lead。

当然，也可以用内置模板一键启动，跳过手动配置：

1

clawteam launch software-dev --team todo-dev --goal "构建一个 Todo Web 应用"

这会自动创建团队，并启动 tech-lead、backend-dev、frontend-dev、qa-engineer、devops 五个角色。下面走手动流程，让你看清每一步发生了什么。

第二步：拆任务，设依赖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 并行任务：设计 API + 前端 UI 可以同时开始
clawteam task create todo-dev "设计并实现 REST API" \
  -o backend-dev -p high
# => Task ID: aaa111

clawteam task create todo-dev "构建前端 UI 组件" \
  -o frontend-dev -p high
# => Task ID: bbb222

clawteam task create todo-dev "设计数据库 schema" \
  -o backend-dev -p high
# => Task ID: ccc333

# 集成测试——必须等 API 和前端都完成
clawteam task create todo-dev "编写集成测试" \
  -o qa-engineer --blocked-by aaa111,bbb222
# => Task ID: ddd444（自动设为 blocked）

# 部署——必须等测试通过
clawteam task create todo-dev "配置 CI/CD 并部署" \
  -o devops --blocked-by ddd444
# => Task ID: eee555（自动设为 blocked）

注意 --blocked-by 参数——指定后任务状态自动设为 blocked。当上游任务全部完成时，下游任务自动解除阻塞变为 pending。不需要手动管理状态流转。

第三步：启动 Worker

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 后端开发
clawteam spawn --team todo-dev --agent-name backend-dev \
  --task "实现 Todo REST API：CRUD 端点、数据库模型、认证中间件"

# 前端开发
clawteam spawn --team todo-dev --agent-name frontend-dev \
  --task "构建 Todo 前端：任务列表、添加/删除/标记完成、响应式布局"

# QA（暂时不用 task，等依赖解除后 Leader 通知它开始）
clawteam spawn --team todo-dev --agent-name qa-engineer \
  --task "等待后端和前端完成后，编写集成测试"

# DevOps
clawteam spawn --team todo-dev --agent-name devops \
  --task "等待测试通过后，配置 GitHub Actions 并部署到生产环境"

每个 spawn 背后发生了什么：

1. 创建 tmux 窗口
2. 注入 CLAWTEAM_* 环境变量（Agent 身份、团队名等）
3. 创建独立的 git worktree（各自在隔离分支工作）
4. 启动 CLI Agent 并注入任务 prompt
5. 注册到 spawn_registry.json

四个 Worker 同时开工，各写各的分支，互不干扰。

第四步：监控进度

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 看板快照——团队状态 + 成员列表 + 四列任务板
clawteam board show todo-dev

# 实时刷新——每 3 秒更新一次，Ctrl+C 停止
clawteam board live todo-dev --interval 3

# Web 仪表板——浏览器查看，支持 SSE 实时推送
clawteam board serve --port 8080

# JSON 输出用于脚本查询
clawteam --json task list todo-dev --status in_progress

看板会显示每个任务的状态、负责人、优先级。当 backend-dev 完成 API 开发后：

1

clawteam task update todo-dev aaa111 --status completed

这一步会自动：

• 解除任务锁
• 计算耗时
• 检查 ddd444（集成测试）的所有阻塞者是否都已完成——如果 bbb222（前端）也完成了，ddd444 自动从 blocked 变为 pending

第五步：合并收工

所有任务完成后，逐个合并各 Worker 的 worktree 分支：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 合并前检查文件冲突
clawteam context conflicts todo-dev

# 查看各 Agent 修改了哪些文件
clawteam context files todo-dev

# 逐个合并
clawteam workspace merge todo-dev --agent backend-dev
clawteam workspace merge todo-dev --agent frontend-dev
clawteam workspace merge todo-dev --agent qa-engineer
clawteam workspace merge todo-dev --agent devops

# 清理团队
clawteam team cleanup todo-dev --force

context conflicts 会检测跨分支的文件重叠，报告三级严重性：

• high：同一行被多个 Agent 修改
• medium：同一文件被修改
• low：同一目录被修改

前后端分开开发，文件范围天然隔离，一般不会有 high 级冲突。

架构解析：为什么这样设计

任务状态机

四种状态，自动流转：

pending ──→ in_progress ──→ completed
   ↑                           │
   └──── blocked ←─────────────┘（解除下游阻塞）

关键行为：

为什么要加锁？因为多个 Agent 可能同时轮询任务板寻找可做的任务。没有锁，两个 Worker 可能同时认领同一个任务，导致重复工作。

Inbox 消息协议

Agent 之间不共享内存，通过消息队列通信。每个 Agent 有独立的收件箱。

两种读取方式：

• receive：读取并删除消息（消费型）
• peek：只看不删（观察型）

为什么 receive 会删消息？在多 Agent 环境下，重复消费比丢消息更危险。一条"请关闭"的指令被处理两次，可能导致另一个正常工作的 Agent 被误杀。消费即删除是最安全的语义。

消息类型不止聊天——加入团队、计划审批、关闭请求都通过 Inbox 传递：

Leader 通过 inbox watch 实时监听这些消息，决定下一步动作——分配新任务、审批计划、或者请求关闭空闲的 Worker。

Git Worktree 隔离

这是 ClawTeam 最聪明的设计之一。

每个 Agent spawn 时自动创建独立的 git worktree，在自己的分支上工作。不是共享同一个工作目录——是物理隔离的独立目录。

项目根目录/（Leader 在这里）
~/.clawteam/workspaces/todo-dev/
  ├── backend-dev/    ← 独立 worktree，分支 clawteam/backend-dev
  ├── frontend-dev/   ← 独立 worktree，分支 clawteam/frontend-dev
  ├── qa-engineer/    ← 独立 worktree，分支 clawteam/qa-engineer
  └── devops/         ← 独立 worktree，分支 clawteam/devops

好处很直接：

• 不会互相覆盖文件——每个 Agent 改自己分支里的文件，其他人看不到
• 可以随时 diff——workspace status 看各分支的改动统计
• 冲突在合并时才处理——不是工作过程中突然发现文件被别人改了

context inject 命令可以为某个 Agent 生成上下文注入——告诉它"其他 Agent 正在改哪些文件、有没有和你的工作重叠"，避免合并时才发现冲突。

生命周期管理

一个 Worker 的完整生命周期：

spawn（创建 tmux 窗口 + worktree + 注入任务）
  ↓
工作中（执行任务，更新状态为 in_progress）
  ↓
完成（更新状态为 completed，自动解除下游阻塞）
  ↓
idle（发送空闲通知给 Leader）
  ↓
Leader 分配新任务 或 请求关闭
  ↓
优雅退出（approve-shutdown → on-exit 自动清理）

死亡检测：如果一个 Agent 进程意外退出（tmux pane 关了、进程崩了），系统能检测到：

• task wait 会自动发现死亡 Agent，把它持有的任务释放回来
• task update 会检测过期锁并释放

不需要人工介入处理 Agent 挂掉的情况。

Profile 混搭：不同任务用不同模型

ClawTeam 的 Profile 机制让每个 Worker 可以用不同的模型和提供商。这不是花哨功能——省钱且高效。

三层配置

Preset（预设模板）
  → 提供商级别的共享配置
  → 内置 anthropic-official、deepseek、moonshot-cn 等

Profile（运行时配置）
  → 从 Preset 生成，包含命令、模型、API 端点
  → 是 spawn 直接使用的对象

Spawn --profile
  → 一个参数指定 Worker 用哪个 Profile

怎么搭配

不同角色适合不同模型，举个例子：

Leader 用 Opus 做决策，重要开发用 Sonnet，辅助性工作用 DeepSeek——把预算花在刀刃上。

配置流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 1. 从预设生成 Profile
clawteam preset generate-profile deepseek --client claude --name claude-deepseek

# 2. 查看生成的 Profile
clawteam profile show claude-deepseek

# 3. 冒烟测试——确保能正常调用
clawteam profile test claude-deepseek --prompt "你好"

# 4. spawn 时使用
clawteam spawn --profile claude-deepseek \
  --team todo-dev \
  --agent-name qa-engineer \
  --task "编写集成测试"

内置模板一键启动

ClawTeam 还内置了多种团队模板，一条命令就能启动完整团队——不止软件开发，还有对冲基金、代码审查、学术研究等场景：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 软件开发团队（tech-lead + backend + frontend + QA + devops）
clawteam launch software-dev --team myapp --goal "构建 Todo 应用"

# AI 对冲基金（portfolio-manager + 6 个分析师）
clawteam launch hedge-fund --team fund1 --goal "分析科技股"

# 代码审查团队（lead-reviewer + security/perf/arch reviewer）
clawteam launch code-review --team review --goal "审查 PR #42"

# 学术研究团队（PI + 文献 + 方法论 + 数据分析）
clawteam launch research-paper --team paper --goal "ML 优化调研"

如果内置预设不够用，可以自己创建：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 创建自定义预设
clawteam preset set my-provider \
  --description "自定义提供商" \
  --auth-env MY_API_KEY \
  --base-url "https://api.example.com/v1"

# 设置客户端覆盖
clawteam preset set-client my-provider claude \
  --model my-model \
  --api-key-env MY_API_KEY \
  --api-key-target-env ANTHROPIC_AUTH_TOKEN

# 生成 Profile
clawteam preset generate-profile my-provider --client claude --name claude-custom

profile wizard 还提供交互式 TUI 向导，适合第一次配置时使用。

最后

三篇文章走下来，形成了一个完整的 AI 开发工具链：

Claude Code ──→ Superpowers ──→ ClawTeam
 基础能力        流程纪律        并行扩展

Claude Code 让 AI 能写代码，Superpowers 让它先想再写，ClawTeam 让一群 AI 一起写。

工具越强，治理越重要。一个 Agent 失控只是浪费一次对话的钱，一个团队失控是浪费五个 Agent 的钱加一堆冲突的代码。CLAUDE.md 写清规则、Superpowers 约束流程、ClawTeam 管好协作——三层叠加才稳。

链接

• ClawTeam：https://github.com/HKUDS/ClawTeam
• 系列前两篇：Claude Code 深度使用指南 · Superpowers 插件