ClawTeam Multi-Agent Coordination 是一个与具体框架无关的 CLI 工具，用于将多个 AI 智能体作为一个团队进行协调。它提供基于文件的团队管理、智能体之间的消息通信、带依赖解析的共享任务跟踪、计划审批工作流，以及基于终端的监控看板。所有操作均通过 clawteam CLI 执行，数据默认存储在 ~/.clawteam/ 目录中。
核心概念
Teams（团队）：一个具名的智能体分组，包含一名 leader 和零个或多个 worker。通过 clawteam team spawn-team 创建。leader 负责审批加入请求、审阅计划并协调关闭流程。
Inbox（收件箱）：每个智能体对应一个基于文件的消息队列。inbox send 用于点对点发送，inbox broadcast 用于向所有成员广播。inbox receive 会消费（删除）消息，inbox peek 则为非破坏性读取。
Tasks（任务）：共享任务板，状态包括 pending、in_progress、completed、blocked。任务支持依赖链（--blocks、--blocked-by）。完成任务会自动解除依赖它的任务阻塞。
Board（看板）：终端 kanban 仪表盘。board show 查看单个团队，board overview 查看所有团队，board live 实时自动刷新，board attach 则以平铺 tmux 视图展示所有智能体。
Identity（身份）：每个智能体拥有环境变量（CLAWTEAM_AGENT_ID、CLAWTEAM_AGENT_NAME、CLAWTEAM_AGENT_TYPE、CLAWTEAM_TEAM_NAME）。通过 clawteam spawn 生成时会自动设置。
快速上手
创建带任务的团队
# 为当前会话设置身份
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"
# 创建团队
clawteam team spawn-team my-team -d "Project team" -n leader
# 创建任务
clawteam task create my-team "Design system" -o leader
clawteam task create my-team "Implement feature" -o worker1
clawteam task create my-team "Write tests" -o worker2
# 查看看板
clawteam board show my-team
生成并协调智能体
# 生成 worker —— 默认：tmux 后端、claude 命令、git worktree 隔离、开启 skip-permissions
clawteam spawn --team my-team --agent-name worker1 --task "Implement the auth module"
clawteam spawn --team my-team --agent-name worker2 --task "Write unit tests"
# 或显式指定后端与命令（位置参数：[BACKEND] [COMMAND]）
clawteam spawn tmux claude --team my-team --agent-name worker3 --task "Build API endpoints"
clawteam spawn subprocess claude --team my-team --agent-name worker4 --task "Run linting"
# 同时观察所有智能体工作（平铺 tmux 面板）
clawteam board attach my-team
# 发送指令
clawteam inbox send my-team worker1 "Start implementing the auth module"
# 监控任务看板
clawteam board live my-team --interval 3
生成默认值
生成智能体时使用合理的默认值，常见场景无需任何标志：
| 设置项 | 默认值 | 覆盖方式 |
|---|---|---|
| Backend | tmux | clawteam spawn subprocess ... |
| Command | claude | clawteam spawn tmux my-cmd ... |
| Workspace | auto（git worktree） | --no-workspace 或 config workspace=never |
| Permissions | skip（无需审批） | --no-skip-permissions 或 config skip_permissions=false |
使用默认值生成的智能体将获得：
- 自己的 git worktree（独立分支，与其他智能体无冲突）
- 完整工具权限（--dangerously-skip-permissions），以便自主工作
- 一个可通过 board attach 观察的 tmux 窗口
任务生命周期
# 创建带依赖的任务
clawteam task create my-team "Deploy" --blocked-by <impl-task-id>,<test-task-id>
# 更新状态
clawteam task update my-team <task-id> --status in_progress
clawteam task update my-team <task-id> --status completed # 自动解除依赖任务阻塞
# 过滤任务
clawteam task list my-team --status blocked
clawteam task list my-team --owner worker1
等待子智能体
# 阻塞直到所有任务完成（无超时）
clawteam task wait my-team
# 带超时和自定义轮询间隔
clawteam task wait my-team --timeout 300 --poll-interval 10
# 监控指定智能体的收件箱而非 leader
clawteam task wait my-team --agent coordinator
# JSON 流式输出（NDJSON：progress + message 事件，最后是最终结果）
clawteam --json task wait my-team --timeout 600
观察智能体工作
# 将所有智能体的 tmux 窗口平铺为一个视图（最佳观察方式）
clawteam board attach my-team
# 或手动附加到 tmux 会话，用 Ctrl-b + 数字切换窗口
tmux attach -t clawteam-my-team
命令分组
| 分组 | 用途 | 主要命令 |
|---|---|---|
| team | 团队生命周期 | spawn-team, discover, status, request-join, approve-join, cleanup |
| inbox | 消息通信 | send, broadcast, receive, peek, watch |
| task | 任务管理 | create, get, update, list, wait |
| board | 监控 | show, overview, live, attach, serve |
| plan | 计划审批 | submit, approve, reject |
| lifecycle | 智能体生命周期 | request-shutdown, approve-shutdown, idle |
| spawn | 进程生成 | spawn [backend] [command]（默认：tmux、claude） |
| identity | 身份管理 | show, set |
JSON 输出
所有命令均支持 --json 以获得机器可读输出。该标志需放在子命令之前：
clawteam --json team discover
clawteam --json board show my-team
clawteam --json task list my-team --status pending
结合 jq 用于脚本编写：
clawteam --json board show my-team | jq '.taskSummary'
clawteam --json task list my-team | jq '.[].subject'
重要说明
- inbox receive 会消费消息（删除文件）。非破坏性读取请使用 inbox peek。
- 当创建时指定 --blocked-by 时，任务状态 blocked 会被自动设置。
- 完成任务会自动解除所有在 blockedBy 中列出该任务的任务阻塞。
- clawteam spawn 默认使用 tmux 后端，并启用 git worktree 隔离与 skip-permissions。
- 所有文件写入均采用原子 tmp+rename 方式，以防止数据损坏。
- 通过 clawteam spawn 生成时，身份环境变量会自动设置。
- 使用 board attach <team> 可在平铺 tmux 布局中观察所有智能体。
附加资源
参考文件
详细的命令参数、数据模型与存储布局：
- references/cli-reference.md —— 完整 CLI 参考，包含所有命令、选项与数据模型
分步协调工作流与常见模式：
- references/workflows.md —— 多智能体工作流：团队搭建、生成协调、加入协议、计划审批、优雅关闭、监控模式