ClawTeam

ClawTeam 多 Agent 协调

ClawTeam 是一个与框架无关的命令行工具，用于协调多个 AI Agent 团队协作。 它提供团队/任务管理、Agent 间消息传递、Git 工作树隔离、感知提供商的运行时配置、Git 上下文注入、快照以及基于终端的监控仪表板。

所有操作均通过 clawteam CLI 执行。默认情况下，数据存储在 ~/.clawteam/ 中。

安装

检查是否已安装 clawteam：

clawteam --version

如果找不到该命令，请安装并继续：

pip install clawteam

需要 Python 3.10+。如需支持 P2P 传输，请执行：pip install "clawteam[p2p]"。

先决条件

• 已安装 tmux（默认启动后端）
• 一个 CLI 编码 Agent，例如 claude、codex、gemini、kimi、nanobot 或 openclaw
• 一个 Git 仓库，用于工作树隔离和上下文功能
• 如果要使用 TUI 向导（clawteam profile wizard），需安装默认依赖项

核心概念

团队 — 由一个负责人和零个或多个工作 Agent 组成的命名群组。

收件箱 — 每个 Agent 的基于文件的消息队列。receive 会取出消息；peek 不会。

任务 — 共享任务看板，支持 pending、in_progress、completed 和 blocked 状态。 任务支持依赖链和优先级。

配置 — 可复用的客户端/提供商/运行时配置，供 spawn 和 launch 使用。

预设 — 共享的提供商模板，用于生成一个或多个配置。

上下文 — 感知 Git/工作树的上下文工具，用于检查变更重叠、查看近期变更并注入提示词。

看板 — 团队仪表板，提供看板式任务、收件箱计数、消息历史视图以及 gource 活动可视化。

快速开始

设置包含任务的团队

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

配置运行时配置

# Inspect built-in provider templates
clawteam preset list
clawteam preset show moonshot-cn

# Generate a reusable profile from a preset
clawteam preset generate-profile moonshot-cn claude --name claude-kimi

# Or use the interactive TUI
clawteam profile wizard

# Claude Code on a fresh machine/home may need onboarding repair once
clawteam profile doctor claude

# Smoke-test the profile before using it in a team
MOONSHOT_API_KEY=... clawteam profile test claude-kimi

启动并协调 Agent

# Default path: tmux backend, claude command, git worktree isolation, skip-permissions on
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"

# Explicit backend and 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"

# Recommended for non-default providers/models
clawteam spawn tmux --profile claude-kimi --team my-team --agent-name worker5 --task "Build API endpoints"
clawteam spawn subprocess --profile gemini-vertex --team my-team --agent-name worker6 --task "Run linting"

clawteam board attach my-team
clawteam inbox send my-team worker1 "Start implementing the auth module"
clawteam board live my-team --interval 3

启动默认值

设置	默认值	覆盖方式
后端	tmux	clawteam spawn subprocess ...
命令	claude	clawteam spawn tmux my-cmd ...
工作区	auto（Git 工作树）	--no-workspace 或配置项 workspace=never
权限	跳过	--no-skip-permissions 或配置项 skip_permissions=false
运行时配置	无	--profile <name>

需要使用非默认提供商、模型、端点或身份验证映射时，请使用 --profile。

任务生命周期

# Create with dependencies
clawteam task create my-team "Deploy" --blocked-by <impl-task-id>,<test-task-id>

# Create with priority
clawteam task create my-team "Hotfix prod issue" --priority high

# Update status
clawteam task update my-team <task-id> --status in_progress
clawteam task update my-team <task-id> --status completed

# Filter tasks
clawteam task list my-team --status blocked
clawteam task list my-team --owner worker1
clawteam task list my-team --priority high

等待子 Agent

clawteam task wait my-team
clawteam task wait my-team --timeout 300 --poll-interval 10
clawteam task wait my-team --agent coordinator
clawteam --json task wait my-team --timeout 600

工作 Agent 循环协议

工作 Agent 不应在完成初始 --task 后停止。预期的循环如下：

# 1. Check tasks assigned to you
clawteam task list my-team --owner worker1

# 2. Finish any pending work, then check for new instructions
clawteam inbox receive my-team --agent worker1

# 3. If idle, notify the leader and keep monitoring for follow-ups
clawteam lifecycle idle my-team

重复此循环，直到负责人明确关闭工作 Agent。

Git 上下文与冲突检查

clawteam context log my-team
clawteam context conflicts my-team
clawteam context inject my-team --agent worker1

重新分配工作、继续其他工作 Agent 的任务或合并重叠变更前，请使用这些功能。

快照与恢复

clawteam team snapshot my-team --tag before-refactor
clawteam team snapshots my-team
clawteam team restore my-team --snapshot before-refactor

活动可视化

clawteam board gource my-team --log-only
clawteam board gource my-team --live

在无头环境中，建议使用 --log-only。

支持的 CLI Agent

常见且经过验证的 CLI 包括：

• claude
• codex
• gemini
• kimi
• nanobot
• openclaw

OpenClaw 工作 Agent 的启动命令会自动规范化。裸 openclaw 命令会被转换为 Agent 入口点，并按需配置 --local、--session-id 和 --message。

请通过 profile 和 preset 配置非默认提供商，而不要将环境变量硬编码到提示词中。

命令组

分组	用途	主要命令
preset	共享的提供商模板	list、show、generate-profile、bootstrap
profile	可复用的客户端／提供商配置	list、show、set、test、wizard、doctor
team	团队生命周期	spawn-team、discover、status、request-join、approve-join、cleanup、snapshot、restore
inbox	消息传递	send、broadcast、receive、peek、watch
task	任务管理	create、get、update、list、wait
board	监控与可视化	show、overview、live、attach、serve、gource
context	Git／工作树上下文	diff、files、conflicts、log、inject
plan	计划审批	submit、approve、reject
lifecycle	Agent 生命周期	request-shutdown、approve-shutdown、idle
spawn	进程生成	spawn [backend] [command]
identity	身份管理	show、set

JSON 输出

所有命令都支持 --json，以输出机器可读的数据。将此标志放在子命令之前：

clawteam --json team discover
clawteam --json board show my-team
clawteam --json task list my-team --status pending

重要说明

• inbox receive 会取走消息。若要进行非破坏性读取，请使用 inbox peek。
• 创建任务时指定 --blocked-by，会自动将任务状态设为 blocked。
• 完成任务后，会自动解除所有 blockedBy 列表中包含该任务的任务的阻塞状态。
• 任务还支持 priority；紧急的解除阻塞任务和生产环境修复任务请使用 high。
• 首个任务完成后，Worker 应继续轮询任务／收件箱，而不是立即退出。
• clawteam spawn 默认使用 tmux、Git 工作树隔离和跳过权限检查。
• clawteam launch 也会遵循 skip_permissions，因此模板 Worker 不再会卡在审批提示上。
• 所有文件写入都使用原子临时文件加重命名，以防止文件损坏。
• 通过 clawteam spawn 生成进程时，会自动设置身份环境变量。
• 使用 board attach <team>，即可在平铺的 tmux 布局中监看所有 Agent。
• board show 的 JSON 输出和浏览器版看板现在都包含带成员别名的消息历史记录，可用于收件箱分流和任务交接。
• 对于非默认提供商／模型，优先使用 --profile，而不是手动导出提供商环境变量。
• profile 是最终的运行时对象；preset 是用于生成 profile 的可复用模板。
• 在新机器／主目录上使用 Claude Code 时，请在生成进程前运行一次 clawteam profile doctor claude。
• 建议使用 context inject 和 context conflicts，以安全地交接跨工作树任务。

其他资源

• references/cli-reference.md — 完整的 CLI 参考，包含命令、选项和数据模型
• references/workflows.md — 多 Agent 工作流：设置、生成协调、加入协议、计划审批、优雅关闭和监控模式