英语 | 简体中文 | 繁体中文 | 日语 | 韩语 | 法语 | 西班牙语 | 德语 | 意大利语 | 俄语 | 葡萄牙语（巴西）

🦞ClawTeam-OpenClaw

面向 CLI 编程代理的多智能体群集协调 — 默认采用 OpenClaw

HKUDS/ClawTeam 的分支，深度整合了 OpenClaw：默认使用 openclaw 代理，支持每代理独立会话、自动配置执行审批，以及经过生产环境严苛考验的 spawn 后端。所有上游修复都已同步到位。

你设定目标，剩下的工作由代理群集来完成——包括启动工作节点、分配任务、进行协调，并将结果汇总。 该方案可与 OpenClaw（默认）、Claude Code、Codex、nanobot、Cursor 以及任何 CLI 代理协同工作。

为什么选择 ClawTeam？

当前的人工智能代理功能强大，但往往处于孤立状态。而 ClawTeam 让代理能够自我组织成团队——在不依赖人工微观管理的情况下，分工协作、相互沟通，并最终达成一致的结果。

工作原理

clawteam spawn --team my-team \
  --agent-name worker1 \
  --task "实现认证模块"

clawteam task list my-team --owner me
clawteam inbox send my-team 领导者 \
  "认证已完成！所有测试均通过。"

clawteam board attach my-team
# 或者通过 Web 仪表盘
clawteam board serve --port 8080

快速入门

方法一：让代理自主运行（推荐）

安装 ClawTeam，然后向你的代理发出指令：

“构建一个 Web 应用。利用 ClawTeam 将工作分配给多个代理。”

代理会自动创建团队、启动工作节点、分配任务并进行协调——所有这一切都通过 clawteam CLI 实现。

方法二：手动驱动

# 创建团队
clawteam team spawn-team my-team -d "构建认证模块" -n leader

# 启动工作节点——每个节点都将拥有自己的 Git 工作树和 tmux 窗口
clawteam spawn --team my-team --agent-name alice --task "实现 OAuth2 流程"
clawteam spawn --team my-team --agent-name bob   --task "编写认证单元测试"

# 观察它们的工作
clawteam board attach my-team

支持的代理

安装

第一步：先决条件

ClawTeam 需要 Python 3.10+、tmux，以及至少一个 CLI 编程代理（OpenClaw、Claude Code、Codex 等）。

检查你已有的工具：

python3 --version   # 需要 3.10+
tmux -V             # 需要任意版本
openclaw --version  # 或：claude --version / codex --version

安装缺失的先决条件：

如果使用 Claude Code 或 Codex 而不是 OpenClaw，请根据各自文档进行安装。OpenClaw 是默认选项，但并非严格必需。

第二步：安装 ClawTeam

重要提示： 请勿使用 pip install clawteam——该方法会安装 PyPI 上的上游版本，默认使用 claude，且缺少 OpenClaw 的适配。务必从本仓库直接安装。

git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
pip install -e .

可选：P2P 传输（ZeroMQ）

pip install -e ".[p2p]"

第三步：创建 ~/bin/clawteam 符号链接

启动的代理运行在全新的 shell 中，而这些 shell 可能并未将 pip 的 bin 目录添加到 PATH 中。通过在 ~/bin 中创建符号链接，可以确保 clawteam 总是可访问：

mkdir -p ~/bin
ln -sf "$(which clawteam)" ~/bin/clawteam

如果 which clawteam 返回为空，可手动查找二进制文件：

# 常见位置：
# ~/.local/bin/clawteam
# /opt/homebrew/bin/clawteam
# /usr/local/bin/clawteam
# /Library/Frameworks/Python.framework/Versions/3.*/bin/clawteam
find / -name clawteam -type f 2>/dev/null | head -5

随后，确保 ~/bin 已加入你的 PATH 中——如果尚未添加，请将其添加到 ~/.zshrc 或 ~/.bashrc 中：

export PATH="$HOME/bin:$PATH"

第4步：安装OpenClaw技能（仅限OpenClaw用户）

该技能文件通过自然语言，教导OpenClaw代理如何使用ClawTeam。如果您未使用OpenClaw，请跳过此步骤。

mkdir -p ~/.openclaw/workspace/skills/clawteam
cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md

第5步：配置执行审批（仅限OpenClaw用户）

已启动的OpenClaw代理需要具备运行clawteam命令的权限。若未设置此项，代理将在交互式权限提示时被阻拦。

# 确保安全模式为“白名单”（而非“全盘”）
python3 -c "
import json, pathlib
p = pathlib.Path.home() / '.openclaw' / 'exec-approvals.json'
if p.exists():
    d = json.loads(p.read_text())
    d.setdefault('defaults', {})['security'] = 'allowlist'
    p.write_text(json.dumps(d, indent=2))
    print('exec-approvals.json 更新：安全模式已设为“白名单”')
else:
    print('exec-approvals.json 未找到——请先运行一次openclaw，再重新执行本步骤')
"

# 将clawteam添加至白名单
openclaw approvals allowlist add --agent "*" "*/clawteam"

如果openclaw approvals失败，可能是因为OpenClaw网关尚未启动。请先启动网关，然后再重试。

第6步：验证

clawteam --version          # 应输出版本信息
clawteam config health      # 应显示所有状态为绿色

若使用OpenClaw，还需确认技能已成功加载：

openclaw skills list | grep clawteam

自动化安装器

上述第2–6步也可作为单个脚本实现：

git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
bash scripts/install-openclaw.sh

故障排除

使用场景

1. 自主式机器学习研究 — 8 个代理 × 8 块 GPU

基于 @karpathy/autoresearch。只需一个指令，即可在 H100 上启动 8 个研究代理，自主设计 2000 多项实验。

人类：「使用 8 块 GPU 优化 train.py。请阅读 program.md 以获取操作说明。」

领导代理：
├── 启动 8 个代理，每个代理被分配到一项研究方向（深度、宽度、学习率、批量大小……）
├── 每个代理拥有独立的 Git 工作树，用于隔离实验
├── 每隔 30 分钟，检查实验结果，并将最佳配置交叉传播给新代理
├── 当代理完成任务后，会重新分配 GPU——新代理将从已知的最佳配置开始运行
└── 实验结果：val_bpb 从 1.044 降至 0.977（提升 6.4%），涵盖 2430 项实验，耗时约 30 个 GPU 小时

完整实验结果：novix-science/autoresearch

2. 代理式软件工程

人类：「构建一个全栈待办事项应用，包含身份验证、数据库以及 React 前端。」

领导代理：
├── 创建具有依赖链的任务（API 规范 → 身份验证 + 数据库 → 前端 → 测试）
├── 在各自的工作树中启动 5 个代理（架构师、2 名后端开发人员、前端开发人员、测试人员）
├── 依赖关系自动解析：架构师完成任务 → 后端解锁 → 测试人员解锁
├── 代理通过收件箱进行协调：“这是 OpenAPI 规范”、“身份验证接口已就绪”
└── 领导者在所有工作树完成时，将它们合并为一个整体

3. 人工智能对冲基金 — 模板启动

一个 TOML 模板可一键启动一支由 7 个代理组成的完整投资团队：

clawteam launch hedge-fund --team fund1 --goal "分析 AAPL、MSFT、NVDA，预测 2026 年第二季度的表现"

5 位分析师代理（价值分析、增长分析、技术分析、基本面分析、情绪分析）并行开展工作。风险经理综合所有信号，投资组合经理则作出最终决策。

模板为 TOML 文件——您可以根据自身需求自定义模板，适用于任何领域。

功能特性

此外： 还可规划审批流程、实现优雅的生命周期管理、在所有命令中输出 --json 格式的数据、支持跨机器部署（NFS/SSHFS 或 P2P）、多用户命名空间、通过自动回滚进行启动验证、以及利用 fcntl 文件锁来确保并发操作的安全性。

OpenClaw 集成

此分支将 OpenClaw 作为 默认代理。在没有 ClawTeam 的情况下，每个 OpenClaw 代理都处于孤立状态。而 ClawTeam 则将其转变为一个多代理平台。

一旦技能安装完成，您只需在任意频道中与您的 OpenClaw 机器人对话：

  您（Telegram/Discord/TUI）
         │
         ▼
  ┌──────────────────┐
  │  OpenClaw 网关 │  ← 启动 clawteam 技能
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐     clawteam 启动     ┌─────────────────┐
  │  领导者代理    │ ─────────────────────► │  openclaw TUI   │
  │  （openclaw）      │ ──┐                    │  （tmux 窗口）  │
  │                  │   │                    │  Git 工作树   │
  │  管理集群的代理  │   ├──────────────────► ├─────────────────┤
  │  通过 clawteam    │   │                    │  openclaw TUI   │
  │  CLI             │   ├──────────────────► ├─────────────────┤
  └──────────────────┘   │                    │  openclaw TUI   │
                         └──────────────────► └─────────────────┘
                                               所有坐标均通过
                                               ~/.clawteam/ 进行管理（任务、收件箱）

架构

  人类：「优化这个大语言模型」
         │
         ▼
  ┌──────────────┐     clawteam 启动     ┌──────────────┐
  │  领导者      │ ──────────────────────► │  工作员      │
  │  （任意代理）│ ──────┐                │  Git 工作树 │
  │              │       ├──────────────► │  tmux 窗口  │
  │  启动        │       │                ├──────────────┤
  │  创建任务    │       │                │  工作员      │
  │  发送收件箱  │       │                │  Git 工作树 │
  │  显示板      │       └──────────────► │  tmux 窗口  │
  └──────────────┘                        └──────────────┘
                                                 │
                                                 ▼
                                      ┌─────────────────────┐
                                      │    ~/.clawteam/     │
                                      │ ├── teams/   (谁) │
                                      │ ├── tasks/   (做什么)│
                                      │ ├── inboxes/ (交流)│
                                      │ └── workspaces/    │
                                      └─────────────────────┘

所有状态均以 JSON 文件的形式存储于 ~/.clawteam/ 目录下。无需数据库，也无需服务器。通过 fcntl 文件锁进行原子写入操作，确保了数据的崩溃安全。

命令参考

# 团队生命周期
clawteam team spawn-team <team> -d "描述" -n <领导者>
clawteam team discover                    # 列出所有团队
clawteam team status <team>               # 显示团队成员
clawteam team cleanup <team> --force      # 删除团队

# 启动代理
clawteam spawn --team <team> --agent-name <名称> --task "执行此操作"
clawteam spawn tmux codex --team <team> --agent-name <名称> --task "执行此操作"

# 任务管理
clawteam task create <team> "主题" -o <负责人> --blocked-by <ID1>,<ID2>
clawteam task update <team> <ID> --status completed   # 自动解除依赖项的阻塞
clawteam task list <team> --status blocked --owner worker1
clawteam task wait <team> --timeout 300

# 消息传递
clawteam inbox send <team> <收件人> "消息"
clawteam inbox broadcast <team> "消息"
clawteam inbox receive <team>             # 消费消息
clawteam inbox peek <team>                # 无需消费即可阅读消息

# 监控
clawteam board show <team>                # 终端 Kanban
clawteam board live <team> --interval 3   # 自动刷新
clawteam board attach <team>              # 分屏的 tmux 视图
clawteam board serve --port 8080          # Web UI

# 工作空间（Git 工作树管理）
clawteam workspace list <team>
clawteam workspace checkpoint <team> <代理>    # 自动提交
clawteam workspace merge <team> <代理>         # 合并回主分支
clawteam workspace cleanup <team> <代理>       # 移除工作树

# 计划审批
clawteam plan submit <team> <代理> "计划" --摘要 "TL;DR"
clawteam plan approve <team> <计划 ID> <代理> --反馈 "太棒了！"
clawteam plan reject <team> <计划 ID> <代理> --反馈 "请修改 X"

# 生命周期
clawteam lifecycle request-shutdown <team> <代理> --原因 "已完成"
clawteam lifecycle approve-shutdown <team> <请求 ID> <代理>
clawteam lifecycle idle <team>

# 模板
clawteam launch <模板> --team <名称> --目标 "构建 X"
clawteam template list

# 配置
clawteam config show
clawteam config set transport p2p
clawteam config health

每个代理的模型分配（预览）

**分支：feat/per-agent-model-assignment（Per-Agent 模型分配）
该功能目前可在单独的分支上进行早期测试。待配套的 OpenClaw --model 标志正式发布后，该功能将被合并至 main 分支。

为多代理集群中的不同代理角色分配不同的模型，以实现更好的成本与性能权衡。

# 从功能分支安装
`pip install -e "git+https://github.com/win4r/ClawTeam-OpenClaw.git@feat/per-agent-model-assignment#egg=clawteam"`

模板中的每代理模型：

[template]
name = "my-team"
command = ["openclaw"]
model = "sonnet-4.6"              # 所有代理的默认模型
model_strategy = "auto"           # 或者：领导者→强，工人→均衡

[template.leader]
name = "lead"
model = "opus"                    # 为领导者覆盖模型

[[template.agents]]
name = "worker"
model_tier = "cheap"              # 成本层级：强 / 平衡 / 廉价

CLI 标志：

clawteam spawn --model opus                          # 单个代理
clawteam launch my-template --model gpt-5.4          # 覆盖所有代理
clawteam launch my-template --model-strategy auto     # 按角色自动分配

如需了解完整的功能请求与讨论，请参阅 问题 #1。

发展路线

贡献方式

我们热烈欢迎各位的贡献：

• 代理集成——支持更多 CLI 代理
• 团队模板——用于新领域的 TOML 模板
• 传输后端——Redis、NATS 等
• 仪表盘改进——Web UI、Grafana
• 文档——教程与最佳实践

感谢

• @karpathy/autoresearch — 自主式 ML 研究框架
• OpenClaw — 默认的代理后端
• Claude Code 与 Codex — 支持的 AI 编程代理
• ai-hedge-fund — 对冲基金模板灵感来源
• CLI-Anything — 同属项目

许可证

MIT — 免费使用、修改及分发。

ClawTeam-OpenClaw 快速上手指南

ClawTeam-OpenClaw 是一个专为 CLI 编码智能体设计的多智能体集群协调工具。它允许 AI 智能体自动组建团队、拆分任务、协同工作并合并结果，默认深度集成 OpenClaw。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: macOS 或 Linux (Ubuntu/Debian)
• Python: 版本 ≥ 3.10
• 终端复用器: tmux (任意版本)
• 编码智能体: 至少安装一个 CLI 智能体（推荐使用 OpenClaw，也支持 Claude Code, Codex, nanobot 等）

检查现有环境

python3 --version   # 需为 3.10+
tmux -V             # 需已安装
openclaw --version  # 或检查 claude/codex 版本

安装缺失依赖

提示: 如果使用国内网络环境安装 Python 包较慢，可添加清华或阿里镜像源： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple openclaw

2. 安装步骤

重要提示: 请勿直接使用 pip install clawteam，这会安装上游版本（默认使用 Claude 且缺少 OpenClaw 适配）。必须从本仓库源码安装。

第一步：克隆并安装

git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
pip install -e .

(可选) 如需启用 ZeroMQ P2P 传输模式:

pip install -e ".[p2p]"

第二步：配置全局命令路径

新生成的智能体进程可能无法读取 pip 的环境变量。需创建软链接确保 clawteam 命令在任何 shell 中均可用。

mkdir -p ~/bin
ln -sf "$(which clawteam)" ~/bin/clawteam

确保 ~/bin 已加入环境变量 PATH。如果没有，请将以下内容添加到 ~/.zshrc 或 ~/.bashrc：

export PATH="$HOME/bin:$PATH"

然后执行 source ~/.zshrc (或 source ~/.bashrc) 使配置生效。

第三步：配置 OpenClaw 技能与权限 (仅 OpenClaw 用户)

1. 安装技能文件 让 OpenClaw 学会如何使用 ClawTeam：

mkdir -p ~/.openclaw/workspace/skills/clawteam
cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md

2. 配置执行白名单 防止智能体在执行 clawteam 命令时被交互式权限提示阻塞：

# 更新安全模式为 allowlist
python3 -c "
import json, pathlib
p = pathlib.Path.home() / '.openclaw' / 'exec-approvals.json'
if p.exists():
    d = json.loads(p.read_text())
    d.setdefault('defaults', {})['security'] = 'allowlist'
    p.write_text(json.dumps(d, indent=2))
    print('exec-approvals.json updated: security = allowlist')
else:
    print('未找到 exec-approvals.json，请先运行一次 openclaw 生成配置')
"

# 将 clawteam 加入白名单
openclaw approvals allowlist add --agent "*" "*/clawteam"

如果 openclaw approvals 命令失败，请先运行 openclaw gateway 启动网关。

第四步：验证安装

clawteam --version
clawteam config health

若使用 OpenClaw，还可验证技能是否加载：

openclaw skills list | grep clawteam

3. 基本使用

ClawTeam 有两种主要使用方式：由智能体自主驱动（推荐）或手动驱动。

方式一：智能体自主驱动（推荐）

只需向您的主智能体（Leader）发送一条自然语言指令，它会自动创建团队、生成子智能体并分配任务。

示例指令:

"Build a web app. Use clawteam to split the work across multiple agents." （构建一个 Web 应用。使用 clawteam 将工作拆分给多个智能体。）

智能体将自动执行以下操作：

1. 创建团队上下文。
2. 根据任务复杂度生成若干 Worker 智能体。
3. 为每个 Worker 分配独立的 Git Worktree 和 Tmux 窗口。
4. 协调任务进度并合并代码。

方式二：手动驱动

您可以手动创建团队并生成特定的 Worker。

1. 创建团队

clawteam team spawn-team my-team -d "Build the auth module" -n leader

2. 生成 Worker 智能体 每个 Worker 将获得独立的 Git 分支和 Tmux 会话：

clawteam spawn --team my-team --agent-name alice --task "Implement OAuth2 flow"
clawteam spawn --team my-team --agent-name bob   --task "Write unit tests for auth"

3. 监控进度 在终端查看看板，或启动 Web 仪表盘：

# 终端看板
clawteam board attach my-team

# 或启动 Web UI (端口 8080)
clawteam board serve --port 8080

支持的智能体类型

您可以通过不同的命令参数调用不同类型的智能体：

• OpenClaw (默认): clawteam spawn tmux openclaw --team ...
• Claude Code: clawteam spawn tmux claude --team ...
• Codex: clawteam spawn tmux codex --team ...
• nanobot: clawteam spawn tmux nanobot --team ...
• 自定义脚本: clawteam spawn subprocess python --team ...