ClawTeam — 架构与原理

30 秒导读: ClawTeam 是一个让多个 AI 编码 agent 组队干活的命令行工具。它的反直觉之处在于:没有服务器、没有数据库、没有消息队列、也没有自己发明的「agent 协议」。所有协作状态就是 ~/.clawteam/ 下的一堆 JSON 文件;所有「派活、报状态、发消息」都是普通的 clawteam … shell 命令。于是任何能跑 shell 的 CLI agent(Claude Code、Codex、Gemini、Kimi…)都能直接成为团队成员——不需要 SDK、不需要 API 对接。

---

1. 这是什么(零基础也能懂)

一句话定义: ClawTeam 是一个 Python 写的命令行工具(clawteam),把「一个 leader agent 指挥若干 worker agent 协作完成一个大任务」这件事,变成几条 shell 命令。

它解决谁的什么问题。 现在的 AI 编码 agent(Claude Code 等)很强,但都是单打独斗。你想让 5 个 agent 并行写一个全栈应用,就得自己手动开 5 个终端、自己记谁在干什么、自己把一个 agent 的产出喂给另一个。ClawTeam 把这套「协调脚手架」做成工具——而且使用者不是人,是 leader agent 自己。

它和其他多 agent 框架最大的不同,用一张表说清:

维度	ClawTeam	典型多 agent 框架
谁来编排	agent 自己(靠跑 CLI 命令)	人类写编排代码
基础设施	一个文件夹 + tmux	Redis / 消息队列 / 数据库
支持的 agent	任意 CLI agent	框架专属
代码隔离	git worktree(真分支、真 diff)	容器 / 虚拟环境

(出处:README.md 的对比表,第 231-238 行)

它能做什么(功能清单):

• 建队 / 发现队伍 / 清理队伍(team)
• 派生子 agent,每个自带 git worktree + tmux 窗口 + 身份(spawn)
• 共享任务板,支持依赖链与自动解锁(task)
• agent 之间点对点收发信、广播(inbox)
• 监控:终端 kanban、实时刷新、tmux 平铺、Web 看板(board)
• 一条命令从 TOML 模板拉起整支队伍(launch)
• 计划审批、优雅关停、闲置上报等生命周期协议(plan / lifecycle)

用起来什么样(最小真实示例)。 这是 README 推荐的「手动驾驶」路径(README.md:439-455):

# 1. 建队,你(或 leader agent)成为 leader
clawteam team spawn-team my-team -d "Build the auth module" -n leader

# 2. 派生两个 worker —— 各自得到 git worktree、tmux 窗口、身份
clawteam spawn --team my-team --agent-name alice --task "Implement the OAuth2 flow"
clawteam spawn --team my-team --agent-name bob   --task "Write unit tests for auth"

# 3. 平铺看所有 agent 一起干活
clawteam board attach my-team

被派生出来的 worker,会在它的提示词里被告知该怎么用 clawteam task update / clawteam inbox send 来报告进度——所以它不需要预先知道 ClawTeam 的存在。

一句话直觉/类比: 把 ClawTeam 想成一个项目管理白板 + 收发室,钉在共享文件夹上。每个 agent 路过白板看看「派给我的卡片」(任务板)、去收发室拿信(信箱)、在自己的小隔间里改代码(git worktree)。没有中央调度服务,大家靠看同一块白板达成协作。

本节到此不深入实现。下面进入全景。

---

2. 顶层全景(它大概怎么转)

2.1 三个层次

ClawTeam 的代码可以分成三层来看,从上到下:

层	干什么	主要在哪
CLI 层	把每条 clawteam … 子命令解析成对下层管理器的调用	clawteam/cli/commands.py(单文件,约 4700 行,Typer 子命令)
协调层	队伍/任务/信箱/工作区/生命周期的业务逻辑	clawteam/team/*、clawteam/workspace/*、clawteam/spawn/*
存储/传输层	把状态原子地落到文件;把消息字节搬来搬去	clawteam/store/*、clawteam/transport/*

关键认知:几乎每个管理器最终都落到 ~/.clawteam/ 下的 JSON 文件,用「写临时文件 + rename」保证崩溃安全(README.md:761)。没有进程常驻、没有网络(P2P 传输是可选项)。

2.2 一张顶层图

怎么读这张图:左边是人给的目标,中间 leader agent 用 CLI 命令派生 worker,所有 agent 都通过底部那个共享文件夹交换状态。

  人:"做一个全栈待办应用"
        │
        ▼
  ┌─────────────────┐   clawteam spawn   ┌──────────────────┐
  │ 🦞 Leader agent  │ ─────────────────► │ 🤖 Worker: alice │
  │  (Claude Code)   │                    │  git worktree     │
  │                  │ ─────────────────► │  tmux window      │
  │  它跑这些命令:    │   clawteam spawn   ├──────────────────┤
  │  • spawn         │                    │ 🤖 Worker: bob    │
  │  • task create   │                    │  git worktree     │
  │  • inbox send    │                    │  tmux window      │
  │  • task wait     │                    └──────────────────┘
  └─────────────────┘            每个 worker 也跑:
        │  ▲                     • task list   (看派给我的活)
        │  │                     • task update (报告完成)
        ▼  │                     • inbox send  (给 leader 发消息)
  ┌────────────────────────────────────────────────┐
  │              ~/.clawteam/  (唯一的「真相源」)      │
  │  teams/<team>/config.json   谁在队里 + 信箱       │
  │  tasks/<team>/task-*.json   任务板(每个任务一文件)│
  │  teams/<team>/inboxes/...   点对点信箱            │
  │  workspaces/<team>/...      worktree 登记表        │
  │  teams/<team>/spawn_registry.json  存活探测信息    │
  └────────────────────────────────────────────────┘

(目录布局对照 README.md:751-758 与各管理器里的路径函数,如 clawteam/store/file.py:_tasks_root、clawteam/transport/file.py:_inbox_dir、clawteam/team/manager.py:_team_dir)

2.3 主线走一遍(高层,不进代码)

1. 建队。 team spawn-team → 写出 teams/<team>/config.json,把 leader 登记为成员,建好 leader 的信箱目录(clawteam/team/manager.py:create_team,第 77-112 行)。
2. 派生 worker。 spawn → 起 git worktree(隔离代码)→ 把 worker 也登记进队伍 → 用「身份 + 任务 + 协作协议」拼出提示词 → 通过 tmux 后端起一个 agent 进程并把提示词「打字」进去 → 在 spawn_registry.json 记下它的 tmux/PID,供日后探活(详见 §1)。
3. 派活。 leader 跑 task create … -o alice,worker 跑 task list --owner alice 看到自己的卡片,开始时 task update --status in_progress,完成时 --status completed——完成会自动解锁依赖它的任务(详见 §2)。
4. 通信。 任意 agent 用 inbox send <team> <to> "…",消息变成对方信箱目录里的一个 JSON 文件;对方 inbox receive 消费它(详见 §2)。
5. 收尾。 leader 用 task wait 阻塞等全部任务完成;期间会探测死掉的 agent 并把它没干完的任务退回 pending(clawteam/team/waiter.py)。

---

3. 阅读地图(建议顺序)

这套文档按「由浅入深」拆成四章。建议顺序:

1. 01-spawn.md — 「agent 生 agent」端到端。 这是项目名字所指的核心价值,也是工程含量最高的一支。一条 spawn 命令如何变成「worktree + tmux 窗口 + 注入的提示词 + 存活登记」。
2. 02-coordination.md — 三块共享状态。 任务板(依赖链 + 自动解锁 + 抢锁)、信箱(原子投递 + claim/ack/quarantine)、工作区(worktree 生命周期)。这里是「为什么不用数据库也能协作」的答案。
3. 03-cli-agnostic.md — 为什么任意 CLI agent 都能接入。 适配器契约、各家 CLI 的差异如何被一个 NativeCliAdapter 抹平、保活续跑循环、存活探测的三套办法。
4. 04-internals.md — 编排自动化与精华。 leader-watcher 主动唤醒、harness「先计划后执行」阶段机、事件总线、安全边界(路径校验)、巧妙之处、横向对比、完整代码地图。

如果你只想抓住「ClawTeam 凭什么号称零基础设施」,读 §2 顶层图 + 第 02 章即可。