ClawTeam 完整使用教程:用 AI 多智能体团队自动完成复杂任务

ClawTeam 是一个框架无关的多智能体协调框架,让多个 AI Agent(Claude Code、Codex、Kimi 等)像一个真实团队一样协同工作,自动完成代码开发、数据分析、文献研究等复杂任务。


目录


一、ClawTeam 是什么

ClawTeam 解决的核心问题:单个 AI Agent 的上下文窗口有限,无法独立完成大型复杂任务。

它提供了一套完整的基础设施,让多个 Agent 能够:

  • 并行工作:多个 Worker 同时执行不同子任务,互不干扰
  • 协调通信:通过消息系统(Inbox)传递指令和结果
  • 任务调度:支持任务依赖链,自动解除阻塞
  • 代码隔离:每个 Agent 有独立的 Git Worktree,零冲突合并
  • 框架无关:支持 Claude Code、Codex、Kimi、nanobot 等任意 CLI Agent
人类 → Leader Agent(Claude Code)
              ├── spawn → Worker 1(Claude Code)
              ├── spawn → Worker 2(Codex)
              └── spawn → Worker 3(Kimi CLI)

二、安装与依赖

系统依赖

# 必须安装
pip install clawteam

# 可选:P2P 传输支持(低延迟跨机器通信)
pip install clawteam[p2p]

前置要求:

依赖 说明
Python 3.10+ 必须
tmux Agent 交互式运行所需
git Worktree 隔离所需
claude / codex 等 至少一个 CLI Agent

验证安装

clawteam --version
clawteam config health

数据存储位置

ClawTeam 所有数据存储在 ~/.clawteam/

~/.clawteam/
├── config.json              # 全局配置
├── teams/
│   └── {team}/
│       ├── config.json      # 团队配置
│       └── inboxes/         # 消息收件箱
└── tasks/
    └── {team}/              # 任务文件

三、核心概念

在深入使用前,需要理解以下几个概念:

3.1 Team(团队)

一组协同工作的 Agent 集合,有唯一名称。每个团队有一个 Leader 和若干 Worker。

3.2 Agent

运行中的 AI 实体。分为两类:

  • Leader:负责任务规划、分配和协调
  • Worker:负责执行具体任务

3.3 Task(任务)

任务有 4 种状态:

pending → in_progress → completed
            ↑                ↓
         blocked ←───────────┘(依赖未完成时自动阻塞)

3.4 Inbox(收件箱)

基于文件系统的异步消息队列。每个 Agent 有独立的收件箱。消息不会自动唤醒 Agent,需要 Agent 主动轮询(或重新 spawn)。

3.5 Profile / Preset

  • Preset:可复用的 AI 提供商模板(如 Moonshot、MiniMax)
  • Profile:最终运行时配置,从 Preset 生成或手动创建

四、快速上手:5 分钟跑起来第一个团队

方法 A:使用内置模板(推荐新手)

# 一键启动软件开发团队
clawteam launch software-dev \
  --team my-webapp \
  --goal "构建一个支持用户注册登录的 Todo 应用,使用 FastAPI + React"

# 监控进度
clawteam board attach my-webapp

方法 B:手动构建团队

# 第一步:创建团队
clawteam team spawn-team my-team -d "我的第一个 AI 团队" -n leader

# 第二步:创建任务
clawteam task create my-team "实现用户认证模块" -o alice --priority high
clawteam task create my-team "实现 REST API" -o bob --priority high

# 第三步:spawn Worker
clawteam spawn tmux claude \
  --team my-team \
  --agent-name alice \
  --task "实现 JWT 用户认证,包含注册、登录、刷新 token 接口"

clawteam spawn tmux codex \
  --team my-team \
  --agent-name bob \
  --task "实现商品列表、购物车 REST API"

# 第四步:查看看板
clawteam board live my-team --interval 5

五、完整 CLI 命令参考

5.1 团队管理

# 创建团队
clawteam team spawn-team <team-name> \
  -d "团队描述" \
  -n "leader名称"           # 默认:leader

# 列出所有团队
clawteam team discover

# 查看团队状态和成员
clawteam team status <team>

# 删除团队(清除所有数据)
clawteam team cleanup <team> [--force]

# 团队快照与恢复
clawteam team snapshot <team> --tag before-refactor
clawteam team snapshots <team>
clawteam team restore <team> --snapshot before-refactor

5.2 Spawn(启动 Agent)

# 格式
clawteam spawn <backend> <agent> [options]

# backend:tmux(交互式)或 subprocess(后台)
# agent:claude / codex / nanobot / kimi 等

# 常用示例
clawteam spawn tmux claude \
  --team my-team \
  --agent-name worker1 \
  --task "任务描述" \
  --repo /path/to/repo       # 指定 git 仓库(用于 worktree)

clawteam spawn tmux codex \
  --team my-team \
  --agent-name worker2 \
  --no-workspace \           # 不使用 worktree 隔离
  --replace \                # 替换已存在的同名 agent
  --task "任务描述"

# 使用自定义 profile
clawteam spawn tmux --profile claude-kimi \
  --team my-team \
  --agent-name kimi-worker \
  --task "任务描述"

关键参数说明:

  • --replace:如果同名 Agent 已存在则替换,用于重新分配任务
  • --no-workspace:不创建 git worktree,Agent 直接在主仓库工作
  • --skip-permissions:跳过 Claude Code 的权限确认(自动化场景必用)

5.3 任务管理

# 创建任务
clawteam task create <team> "任务标题" \
  -d "详细描述" \
  -o <owner-agent> \          # 分配给哪个 agent
  -p high \                   # 优先级:low/medium/high/urgent
  --blocked-by task-id1,task-id2  # 依赖的任务 ID

# 更新任务状态
clawteam task update <team> <task-id> \
  --status in_progress        # pending/in_progress/completed/blocked

# 列出任务
clawteam task list <team>
clawteam task list <team> --status pending
clawteam task list <team> --owner alice
clawteam task list <team> --sort-priority

# 任务统计
clawteam task stats <team>

# 等待所有任务完成(阻塞式)
clawteam task wait <team> --timeout 600 --poll-interval 10

5.4 消息(Inbox)管理

# 发送消息
clawteam inbox send <team> <to-agent> "消息内容"

# 广播给所有成员
clawteam inbox broadcast <team> "广播内容"

# 接收消息(破坏性,消息被删除)
clawteam inbox receive <team> --agent <my-name>

# 查看消息(非破坏性)
clawteam inbox peek <team> --agent <my-name>

# 实时监控(每隔 1 秒轮询)
clawteam inbox watch <team> --agent <my-name>

# 消息历史
clawteam inbox log <team> --agent <my-name>

5.5 看板

# 静态看板
clawteam board show <team>

# 实时刷新(默认 2 秒)
clawteam board live <team> --interval 5

# tmux 平铺视图(同时查看所有 Agent 的终端)
clawteam board attach <team>

# Web UI 仪表板
clawteam board serve --port 8080

# 所有团队汇总
clawteam board overview

5.6 生命周期管理

# 关闭指定 agent
clawteam lifecycle request-shutdown <team>

# 报告 agent 空闲(Worker 完成任务后调用)
clawteam lifecycle idle <team> \
  --last-task <task-id> \
  --task-status completed

# 检查僵尸 agent
clawteam lifecycle check-zombies

5.7 成本管理

# 报告 token 用量(Agent 自己调用)
clawteam cost report <team> \
  --input-tokens 10000 \
  --output-tokens 5000 \
  --cost-cents 15 \
  --model claude-sonnet-4-6

# 查看成本汇总
clawteam cost show <team>
clawteam cost show <team> --agent alice

# 设置预算上限
clawteam cost budget <team> 10.0    # $10 上限
clawteam cost budget <team> 0       # 无限制

5.8 工作区管理

# 列出所有工作区
clawteam workspace list <team>

# 查看工作区状态
clawteam workspace status <team> --agent alice

# 自动提交 worktree 改动
clawteam workspace checkpoint <team> alice

# 合并回主分支
clawteam workspace merge <team> alice

# 清理工作区
clawteam workspace cleanup <team> alice

六、Leader-Worker 协作模式详解

6.1 架构设计

ClawTeam 采用经典的 Leader-Worker 模式

                    人类(启动脚本)
                         ↓
              Leader Agent(长驻,永不停止)
             /           |            \
            ↓            ↓             ↓
       Worker 1      Worker 2      Worker 3
    (执行后退出)  (执行后退出)  (执行后退出)

Leader 职责:

  1. 分析目标,规划任务
  2. 创建任务并分配 owner
  3. clawteam spawn --replace 启动 Worker
  4. 读取 Worker 完成报告(inbox receive
  5. 评估结果,决定下一步
  6. 永不停止,直到收到 shutdown 信号

Worker 职责:

  1. 执行具体任务(改代码、跑测试、分析数据等)
  2. 更新任务状态(in_progresscompleted
  3. 向 Leader 汇报结果(inbox send
  4. 完成后退出

6.2 Worker 运行循环协议

ClawTeam 在启动 Worker 时,会自动在 prompt 中注入以下协议,让 Worker 知道如何自主循环:

## Worker Loop Protocol

1. 检查我的任务:clawteam task list {team} --owner {me}
2. 标记开始:clawteam task update {team} {id} --status in_progress
3. 执行任务...
4. 提交代码:git add -A && git commit -m "..."
5. 标记完成:clawteam task update {team} {id} --status completed
6. 汇报:clawteam inbox send {team} leader "完成报告:..."
7. 检查新消息:clawteam inbox receive {team} --agent {me}
8. 如果空闲:clawteam lifecycle idle {team}
9. 重复步骤 1

6.3 为什么用 --replace 而不是 inbox 消息唤醒 Worker?

这是初学者常见的误区:

# ❌ 错误做法:发 inbox 消息希望唤醒已退出的 Worker
clawteam inbox send my-team codex-worker "新任务来了"
# → 消息堆积,无人处理

# ✅ 正确做法:用 --replace 启动全新 Worker 实例
clawteam spawn tmux codex \
  --team my-team \
  --agent-name codex-worker \
  --replace \
  --task "新任务完整描述,包含所有背景信息"

原因: Codex 等 Agent 完成任务后会退出,inbox 消息不会自动唤醒已退出的进程。--replace 会启动一个全新的 Agent 实例,在 --task 参数中注入完整背景,实现无状态 Worker 设计


七、任务系统:依赖、优先级与状态流转

7.1 任务依赖链

# 场景:API 设计完成前,前后端不能开始实现

# 创建 Leader 的任务
clawteam task create team "设计 API 接口文档" -o leader
# => 任务 ID: aaa

# 创建依赖 aaa 的任务(自动变为 blocked 状态)
clawteam task create team "实现后端 API" -o alice --blocked-by aaa
# => 任务 ID: bbb (状态: blocked)

clawteam task create team "实现前端页面" -o bob --blocked-by aaa
# => 任务 ID: ccc (状态: blocked)

# 创建依赖 bbb 和 ccc 的任务
clawteam task create team "集成测试" -o carol --blocked-by bbb,ccc
# => 任务 ID: ddd (状态: blocked)

# ✅ 当 leader 完成 API 设计
clawteam task update team aaa --status completed
# 自动解除:bbb 和 ccc 变为 pending,alice 和 bob 可以开始工作

# ✅ 当 bbb 和 ccc 都完成
# 自动解除:ddd 变为 pending,carol 可以开始集成测试

7.2 任务优先级

# 设置优先级
clawteam task create team "紧急 Bug 修复" --priority urgent
clawteam task create team "功能开发" --priority high
clawteam task create team "文档更新" --priority medium
clawteam task create team "代码重构" --priority low

# 按优先级列出(高优先级排在前面)
clawteam task list team --sort-priority

# 只看高优先级任务
clawteam task list team --priority urgent

7.3 等待任务完成

# 阻塞当前脚本,直到所有任务完成
clawteam task wait my-team

# 设置超时
clawteam task wait my-team --timeout 1800  # 30 分钟超时

# 自定义轮询间隔
clawteam task wait my-team --poll-interval 30

八、消息系统(Inbox)详解

8.1 消息流程

发送方                         文件系统                      接收方
   │                               │                           │
   ├─ inbox send ─────────────→    │  inboxes/bob/             │
   │ (to=bob)                      │    msg-001.json           │
   │                               │                           │
   │                               │                     ↓ 主动轮询
   │                               │ ←── inbox receive ───── bob
   │                               │     (消费并删除文件)       │
   │                               │                           │
   │                               │ ←── inbox peek ──────── bob
   │                               │     (查看不删除)          │

8.2 消息类型

类型 说明
message 普通消息(默认)
broadcast 广播给所有成员
idle Worker 报告空闲
shutdown_request 请求关闭
plan_approval_request 请求审批计划

8.3 实战消息模式

# Worker 向 Leader 汇报完成
clawteam inbox send my-team claude-leader \
  "完成报告:任务=优化merge_lines,改动=straight_line.py第52行距离参数从12→10,前F1=0.78,后F1=0.81,建议=保留"

# Leader 广播通知
clawteam inbox broadcast my-team "注意:基线已更新,F1=0.81,请基于新版本继续改进"

# Leader 读取所有 Worker 的汇报
clawteam inbox receive my-team --agent claude-leader

# 实时监控收件箱(调试用)
clawteam inbox watch my-team --agent claude-leader

九、内置团队模板

ClawTeam 内置 5 个团队模板,覆盖常见场景:

9.1 查看所有模板

clawteam template list

9.2 软件开发团队

clawteam launch software-dev \
  --team webapp \
  --goal "构建全栈 Todo 应用,FastAPI 后端 + React 前端,支持用户认证"

# 自动启动角色
# - tech-lead(Leader,架构设计)
# - backend-dev(后端实现)
# - frontend-dev(前端实现)
# - qa-engineer(测试)
# - devops(部署配置)

9.3 AI 对冲基金分析团队

clawteam launch hedge-fund \
  --team fund1 \
  --goal "分析 NVIDIA、Tesla、Apple 的 Q1 2026 投资价值,给出具体建议"

# 自动启动角色
# - portfolio-manager(Leader)
# - buffett-analyst(价值投资视角)
# - growth-analyst(成长投资视角)
# - technical-analyst(技术分析)
# - fundamentals-analyst(基本面分析)
# - sentiment-analyst(市场情绪)
# - risk-manager(风险管理)

9.4 代码审查团队

clawteam launch code-review \
  --team pr-review \
  --goal "审查登录模块的 PR,重点关注安全漏洞和性能问题"

# 自动启动角色
# - lead-reviewer(Leader)
# - security-reviewer(安全审查)
# - perf-reviewer(性能审查)
# - arch-reviewer(架构审查)

9.5 战略规划团队

clawteam launch strategy-room \
  --team strategy1 \
  --goal "评估是否应该将单体应用拆分为微服务架构"

9.6 学术研究团队

clawteam launch research-paper \
  --team paper1 \
  --goal "撰写关于 LLM 推理优化技术的综述论文"

9.7 自定义模板

创建文件 ~/.clawteam/templates/my-template.toml

[template]
name = "my-template"
description = "自定义数据分析团队"
command = ["claude"]
backend = "tmux"

[template.leader]
name = "data-lead"
type = "leader"
task = """你是数据分析团队的 Leader。
目标:{goal}
请规划分析任务并分配给 Worker。
"""

[[template.agents]]
name = "analyst-1"
type = "analyst"
task = """你是数据分析师 analyst-1。
目标:{goal}
执行分配给你的分析任务,完成后向 data-lead 汇报。
"""

[[template.tasks]]
subject = "数据探索分析"
owner = "analyst-1"

使用自定义模板:

clawteam launch my-template --team my-analysis --goal "分析用户行为数据"

十、Profile 与 Preset:接入不同 AI 提供商

10.1 内置 Preset

# 列出内置 preset
clawteam preset list

# 内置 preset
# - moonshot-cn(月之暗面 Kimi,国内端点)
# - minimax-global(MiniMax 全球)
# - minimax-cn(MiniMax 国内)

10.2 使用 Kimi CLI(国内用户推荐)

# 第一步:从 preset 生成 profile
clawteam preset generate-profile moonshot-cn claude --name claude-kimi

# 第二步:测试 profile(需要 API Key)
MOONSHOT_API_KEY=sk-xxxxxxxx clawteam profile test claude-kimi

# 第三步:使用 profile 启动 Worker
MOONSHOT_API_KEY=sk-xxxxxxxx \
clawteam spawn tmux --profile claude-kimi \
  --team my-team \
  --agent-name kimi-worker \
  --task "任务描述"

10.3 使用交互式向导

# 一步步配置 profile
clawteam profile wizard

10.4 Profile 管理

# 列出所有 profile
clawteam profile list

# 查看 profile 详情
clawteam profile show claude-kimi

# 删除 profile
clawteam profile remove claude-kimi

十一、工作区隔离:多 Agent 并行改代码不冲突

11.1 工作原理

ClawTeam 使用 Git Worktree 为每个 Agent 创建独立的工作副本:

主仓库(main 分支)
    ├── worktree: clawteam/my-team/alice  → Alice 在这里工作
    ├── worktree: clawteam/my-team/bob   → Bob 在这里工作
    └── worktree: clawteam/my-team/carol → Carol 在这里工作

多个 Agent 可以同时修改同一个文件,互不干扰。

11.2 工作流

# 1. spawn 时自动创建 worktree(不加 --no-workspace)
clawteam spawn tmux claude \
  --team my-team \
  --agent-name alice \
  --repo /path/to/project \
  --task "重构认证模块"

# 2. Agent 工作中,查看状态
clawteam workspace status my-team --agent alice

# 3. 查看改动
clawteam context diff my-team --agent alice

# 4. 检查与其他 Agent 的冲突
clawteam context conflicts my-team --agent alice

# 5. 自动提交(检查点)
clawteam workspace checkpoint my-team alice

# 6. 全部完成后,合并回主分支
clawteam workspace merge my-team alice
clawteam workspace merge my-team bob
clawteam workspace merge my-team carol

# 7. 清理工作区
clawteam workspace cleanup my-team alice

十二、看板监控

12.1 命令行看板

# 静态快照
clawteam board show my-team

# 实时刷新(5 秒间隔)
clawteam board live my-team --interval 5

# tmux 平铺视图:同屏显示所有 Agent 终端
clawteam board attach my-team

# 所有团队汇总
clawteam board overview

12.2 Web 看板

# 启动 Web UI
clawteam board serve --port 8080
# 浏览器打开 http://localhost:8080

12.3 看板信息包含

  • 团队成员列表和状态(active/idle/shutdown)
  • 任务列表(pending/in_progress/completed/blocked)
  • 每个 Agent 的成本统计
  • 消息收件箱状态

十三、实战案例:自动化代码精度提升团队

以下是一个完整的实战案例:用 ClawTeam 构建一个自动化闭环改进系统,让 Claude 作为 Leader 持续分析评测结果,指导 Codex 修改代码,循环提升模型精度。

13.1 设计思路

Claude Leader(长驻)
  ↓ 建立基线(跑评测脚本)
  ↓ 分析 eval_results.json(哪类错误多?)
  ↓ 决定改进方向
  ↓ clawteam spawn codex --replace --task "具体改动描述"
  ↓ 等待 Codex 完成并汇报
  ↓ 读取结果(F1 是否提升?)
  ↓ 保留/回滚 → 继续下一轮
  ↑ 永不停止

13.2 启动脚本

#!/bin/bash
TEAM="improve-$(date '+%m%d-%H%M')"
PROJECT_DIR="/path/to/your/project"

# 创建团队
clawteam team spawn-team "$TEAM" -d "自动精度提升" -n claude-leader

# 构建 Leader prompt
LEADER_PROMPT="你是代码改进 Leader。
使命:基于评测数据分析错误,持续提升 F1,永不停止。

## 启动后立即执行
1. 建立基线:
   python $PROJECT_DIR/evaluate.py
   cat $PROJECT_DIR/eval_results.json

2. 分析错误,选择最有价值的改进方向

3. spawn Worker 执行改进:
   clawteam spawn tmux codex \\
     --team $TEAM \\
     --agent-name codex-worker \\
     --no-workspace --replace \\
     --task '你是codex-worker。任务:<具体改动>。完成后执行评测并汇报:
       python $PROJECT_DIR/evaluate.py
       clawteam inbox send $TEAM claude-leader 完成:前F1=x,后F1=x'

## 工作循环(每 90 秒)
1. clawteam inbox receive $TEAM --agent claude-leader
2. F1 提升 ≥ 0.5%:git commit 保留;F1 下降:spawn Worker 回滚
3. spawn 下一轮 Worker
4. 重复

注意:每次必须用 --replace spawn 新 Worker,inbox 消息不会唤醒已退出的 Worker。
永不停止。"

# 启动 Leader
clawteam spawn tmux claude \
  --team "$TEAM" \
  --agent-name claude-leader \
  --agent-type leader \
  --no-workspace \
  --skip-permissions \
  --repo "$PROJECT_DIR" \
  --task "$LEADER_PROMPT"

echo "启动完成!"
echo "监控:clawteam board attach $TEAM"

13.3 关键设计要点

要点 说明
--replace 每次都 spawn 全新 Codex,无状态设计
完整背景注入 --task 里包含项目路径、当前基线、历史改动
每次只改 1-2 个文件 保持可回滚,每次改动都有 git diff
Leader 跑评测 避免 Worker 转发数据,Leader 直接读取结果
永不停止 直到收到 clawteam lifecycle request-shutdown

十四、常见问题

Q1:inbox 消息发出去了,Worker 没反应?

原因:Worker 已退出,inbox 消息不会唤醒进程。

解决:用 --replace 重新 spawn Worker:

clawteam spawn tmux codex --team my-team --agent-name worker --replace --task "..."

Q2:Claude Code 每次都弹出权限确认,能关掉吗?

# spawn 时加 --skip-permissions
clawteam spawn tmux claude --team my-team --agent-name alice \
  --skip-permissions \
  --task "..."

Q3:如何让 Codex Worker 也能持续循环,而不是每次重新 spawn?

在给 Codex 的 --task 里加入循环指令:

完成任务后,执行:
  clawteam inbox receive {team} --agent codex-worker
  clawteam task list {team} --owner codex-worker
如果有新任务,继续执行;
如果空闲,执行:clawteam lifecycle idle {team}
然后每 60 秒检查一次,直到收到 shutdown 信号。

注意:这种方式在 Codex 交互模式下可行,但长时间运行后上下文积累可能导致行为漂移。--replace 模式更稳定。

Q4:多个 Agent 同时修改同一文件怎么办?

使用 Worktree 隔离(不加 --no-workspace),每个 Agent 有独立分支,最后通过 workspace merge 合并:

clawteam workspace merge my-team alice
clawteam workspace merge my-team bob

Q5:如何控制预算,防止 token 超支?

# 设置 $20 预算上限
clawteam cost budget my-team 20.0

# 实时查看成本
clawteam cost show my-team

Q6:团队跑完了,如何清理?

# 停止所有 Agent
clawteam lifecycle request-shutdown my-team

# 清理数据
clawteam team cleanup my-team --force

总结

ClawTeam 的核心价值在于:

  1. 解决上下文限制:将大任务拆解,多个 Agent 并行执行
  2. 框架无关:Claude、Codex、Kimi 等均可混用
  3. 无状态 Worker:通过 --replace 每次注入完整背景,避免上下文积累
  4. 文件系统通信:极简可靠,无需网络基础设施
  5. 内置任务依赖:自动解除阻塞,复杂工作流轻松实现

项目地址https://github.com/HKUDS/ClawTeam


本教程基于 ClawTeam v0.2.0,Python 3.10+

Logo

有“AI”的1024 = 2048,欢迎大家加入2048 AI社区

更多推荐