ClawTeam Multi-Agent Coordination

ClawTeam 多 Agent 协调

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

所有操作都通过 oh CLI 执行。数据默认存储在 ~/.oh/ 中。

安装

pip install oh

需要 Python 3.10+。如需 P2P 传输支持：pip install oh[p2p]。

前置条件

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

核心概念

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

收件箱 — 每个 Agent 各自基于文件的消息队列。receive 会删除消息；peek 不会。

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

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

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

上下文 — 感知 Git／worktree 的上下文工具，用于检查重叠、查看近期更改和注入提示词。

看板 — 团队仪表板，提供看板式任务、收件箱计数和消息历史视图，以及 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 worktree）	--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。
• 预期工作者在完成第一个任务后继续轮询任务／收件箱，而不是立即退出。
• clawteam spawn 默认使用 tmux、Git 工作树隔离和跳过权限检查。
• clawteam launch 也会遵循 skip_permissions，因此模板工作者不会再卡在审批提示上。
• 所有文件写入都使用临时文件加重命名的原子操作，以防止损坏。
• 通过 clawteam spawn 启动时，会自动设置身份环境变量。
• 使用 board attach <team>，即可在平铺的 tmux 布局中查看所有 Agent。
• board show 的 JSON 输出和浏览器看板现在都包含消息历史，并提供可识别成员的别名，便于收件箱分类和交接。
• 对于非默认提供商／模型，请优先使用 --profile，而不是手动导出提供商环境变量。
• profile 是最终的运行时对象；preset 是用于生成配置档案的可复用模板。
• 在新机器／主目录上使用 Claude Code 时，请在启动前运行一次 clawteam profile doctor claude。
• 建议使用 context inject 和 context conflicts，以安全地交接跨工作树任务。

其他资源

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