ClawTeam 完整使用教程:用 AI 多智能体团队自动完成复杂任务
ClawTeam是一个多智能体协作框架,允许不同AI代理(如Claude Code、Codex、Kimi等)像真实团队一样协同工作,完成复杂任务。该框架支持并行任务处理、消息通信、任务调度和代码隔离等功能,通过Leader-Worker模式协调多个代理。安装简单,支持CLI操作,包含团队管理、任务分配、进度监控等完整功能。用户可快速创建开发团队,定义任务优先级和依赖关系,实现自动化代码开发、数据分
ClawTeam 完整使用教程:用 AI 多智能体团队自动完成复杂任务
ClawTeam 是一个框架无关的多智能体协调框架,让多个 AI Agent(Claude Code、Codex、Kimi 等)像一个真实团队一样协同工作,自动完成代码开发、数据分析、文献研究等复杂任务。
目录
- 一、ClawTeam 是什么
- 二、安装与依赖
- 三、核心概念
- 四、快速上手:5 分钟跑起来第一个团队
- 五、完整 CLI 命令参考
- 六、Leader-Worker 协作模式详解
- 七、任务系统:依赖、优先级与状态流转
- 八、消息系统(Inbox)详解
- 九、内置团队模板
- 十、Profile 与 Preset:接入不同 AI 提供商
- 十一、工作区隔离:多 Agent 并行改代码不冲突
- 十二、看板监控
- 十三、实战案例:自动化代码精度提升团队
- 十四、常见问题
一、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 职责:
- 分析目标,规划任务
- 创建任务并分配 owner
clawteam spawn --replace启动 Worker- 读取 Worker 完成报告(
inbox receive) - 评估结果,决定下一步
- 永不停止,直到收到 shutdown 信号
Worker 职责:
- 执行具体任务(改代码、跑测试、分析数据等)
- 更新任务状态(
in_progress→completed) - 向 Leader 汇报结果(
inbox send) - 完成后退出
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 的核心价值在于:
- 解决上下文限制:将大任务拆解,多个 Agent 并行执行
- 框架无关:Claude、Codex、Kimi 等均可混用
- 无状态 Worker:通过
--replace每次注入完整背景,避免上下文积累 - 文件系统通信:极简可靠,无需网络基础设施
- 内置任务依赖:自动解除阻塞,复杂工作流轻松实现
项目地址:https://github.com/HKUDS/ClawTeam
本教程基于 ClawTeam v0.2.0,Python 3.10+
更多推荐


所有评论(0)