ClawTeam-OpenClaw 安装中文笔记
一、这个项目是什么？
ClawTeam-OpenClaw 是 HKUDS/ClawTeam 的一个 fork 版本，重点做了 OpenClaw 深度适配：把 openclaw 设为默认 agent，并补充了每个 agent 的会话隔离、exec approval 自动配置，以及更稳的 spawn 后端。它也支持 Claude Code、Codex、nanobot、Cursor 等 CLI agent。(GitHub)
这个项目的核心作用，是把原本“单兵作战”的 CLI 智能体，变成一个可以 自动分工、并行协作、互相通信、最后汇总结果 的多智能体团队。(GitHub)
二、安装前先知道的重点
最重要的一点：不要直接执行 pip install clawteam。 因为这样装到的是 PyPI 上游版本，默认 agent 是 claude，并且不包含这个仓库针对 OpenClaw 做的适配。正确方式是：从这个 GitHub 仓库源码安装。(GitHub)
三、安装前的环境要求
这个项目要求你本机至少具备下面几个条件：
Python 3.10 或更高版本
tmux
至少一个可用的 CLI coding agent，例如：
OpenClaw
Claude Code
Codex 等
仓库 README 给出的检查命令如下：(GitHub)
python3 --version
tmux -V
openclaw --version
# 或者：claude --version / codex --version
如果你缺少依赖，可以按 README 里的方式安装： 在 macOS 上可使用 brew install python@3.12、brew install tmux； 在 Ubuntu / Debian 上可使用 sudo apt update && sudo apt install python3 python3-pip、sudo apt install tmux。 OpenClaw 则可直接 pip install openclaw。(GitHub)
四、推荐安装方式一：手动安装（最适合教程演示）
第 1 步：克隆仓库
git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
这是 README 指定的安装入口。(GitHub)
第 2 步：从当前仓库源码安装
pip install -e .
这里使用的是 editable mode（可编辑安装），适合开发、调试和后续更新。README 明确要求从当前仓库安装，而不是从 PyPI 安装。(GitHub)
如果你还想启用 P2P 传输（ZeroMQ），可以安装扩展依赖：
pip install -e ".[p2p]"
对应的 pyproject.toml 里，p2p 可选依赖使用的是 pyzmq。(GitHub)
第 3 步：创建 ~/bin/clawteam 软链接
README 特别强调，spawn 出来的 agent 会运行在新的 shell 中，这些新 shell 不一定能自动拿到 pip 的 bin 路径。 所以推荐创建一个固定软链接，保证 clawteam 在任何新 shell 里都能找到。(GitHub)
执行：
mkdir -p ~/bin
ln -sf "$(which clawteam)" ~/bin/clawteam
如果 which clawteam 没返回结果，可以手动查找：
find / -name clawteam -type f 2>/dev/null | head -5
README 里还列出了一些常见路径，例如：
~/.local/bin/clawteam
/opt/homebrew/bin/clawteam
/usr/local/bin/clawteam
/Library/Frameworks/Python.framework/Versions/3.*/bin/clawteam (GitHub)
第 4 步：确保 ~/bin 已加入 PATH
如果你的 shell 环境里还没有 ~/bin，需要把它加入 PATH。README 建议把下面这一行写入 ~/.zshrc 或 ~/.bashrc：(GitHub)
export PATH="$HOME/bin:$PATH"
写完后执行：
source ~/.zshrc
如果你用的是 bash，则执行：
source ~/.bashrc
第 5 步：安装 OpenClaw skill（仅 OpenClaw 用户需要）
如果你是用 OpenClaw 来驱动这个多智能体系统，那么还需要把仓库里的 SKILL.md 复制到 OpenClaw 的技能目录中。 这个 skill 的作用，是让 OpenClaw agent 能通过自然语言学会使用 clawteam。(GitHub)
执行：
mkdir -p ~/.openclaw/workspace/skills/clawteam
cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md
如果你不用 OpenClaw，而是用 Claude Code / Codex，这一步可以跳过。(GitHub)
第 6 步：配置 exec approvals（仅 OpenClaw 用户需要）
README 明确说明： spawn 出来的 OpenClaw agent 需要有权限执行 clawteam 命令，否则它们会卡在交互式权限确认上。(GitHub)
先确保 OpenClaw 的安全模式是 allowlist，而不是 full：
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 not found — run openclaw once first, then re-run this step')
"
然后把 clawteam 加入 allowlist：
openclaw approvals allowlist add --agent "*" "*/clawteam"
如果这条命令失败，README 提示通常是因为 OpenClaw gateway 没启动，需要先启动 gateway 再重试。(GitHub)
第 7 步：验证安装是否成功
README 给出的验证命令是：(GitHub)
clawteam --version
clawteam config health
如果你使用 OpenClaw，还可以进一步确认 skill 是否已加载：
openclaw skills list | grep clawteam
能查到 clawteam，说明 skill 安装成功。(GitHub)
五、推荐安装方式二：一键脚本安装
仓库还提供了一个自动安装脚本 scripts/install-openclaw.sh，README 里给出的用法是：(GitHub)
git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
bash scripts/install-openclaw.sh
这个脚本会自动做很多事情，包括：
检查 Python 版本是否 ≥ 3.10
检查 tmux
检查 openclaw
从当前本地仓库安装 clawteam
自动寻找 clawteam 二进制位置
自动创建 ~/bin/clawteam 软链接
检查 ~/bin 是否在 PATH 中
自动复制 OpenClaw 的 SKILL.md
尝试修改 exec-approvals.json
尝试执行 openclaw approvals allowlist add --agent "*" "*/clawteam"
最后验证 clawteam --version 是否正常 (GitHub)
所以如果你是新手，或者想录一个“开箱即用”的安装教程，这条脚本路线会更省事。(GitHub)
六、安装完成后，怎么快速测试？
README 给了两种启动方式。
方式 1：直接让 agent 驱动（推荐）
安装完后，你可以直接对 agent 说：
Build a web app. Use clawteam to split the work across multiple agents.
项目会自动创建 team、spawn worker、分配任务并协同完成。(GitHub)
方式 2：手动创建 team 测试
你也可以手动执行以下命令测试：
clawteam team spawn-team my-team -d "Build the auth module" -n leader
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"
clawteam board attach my-team
这会创建一个团队、生成两个 worker，并通过 tmux 面板监控它们。(GitHub)
七、常见报错与解决方法
1）clawteam: command not found
原因通常是 pip 的 bin 目录没有进 PATH，或者 spawned shell 找不到 clawteam。 解决方式：
重新执行软链接步骤
确认 ~/bin/clawteam 存在
确认 ~/bin 已加入 PATH (GitHub)
2）spawn 出来的 agent 找不到 clawteam
这也是 README 特别提到的问题。 根源在于：新开的 shell 不一定继承你当前终端的 pip PATH。 解决方式还是一样：固定创建 ~/bin/clawteam 软链接。(GitHub)
3）openclaw approvals 执行失败
README 明确提示：OpenClaw gateway 可能没启动。 先启动 gateway，再重新执行 allowlist 配置命令。(GitHub)
4）exec-approvals.json not found
说明你还没有真正运行过 OpenClaw。 README 和安装脚本都提示：先运行一次 openclaw，生成配置文件后，再重新执行 approvals 配置步骤。(GitHub)
5）agent 卡在权限确认界面
大概率是 OpenClaw 的 exec approval 安全模式仍然是 full，不是 allowlist。 把 exec-approvals.json 中的 security 改成 allowlist，再加入 clawteam allowlist。(GitHub)
6）pip install -e . 失败
README 提示，可能是缺少构建依赖。 可以先手动安装：
pip install hatchling
再重新执行：
pip install -e .
因为这个项目的 pyproject.toml 里，build-system 指定的就是 hatchling。(GitHub)
八、最省事的安装命令汇总
如果你想把它整理成“复制即用”的教程，可以直接给用户这一段：
# 1. 克隆仓库
git clone https://github.com/win4r/ClawTeam-OpenClaw.git
cd ClawTeam-OpenClaw
# 2. 安装项目
pip install -e .
# 3. 创建 clawteam 软链接
mkdir -p ~/bin
ln -sf "$(which clawteam)" ~/bin/clawteam
# 4. 加入 PATH（按需）
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 5. 安装 OpenClaw skill
mkdir -p ~/.openclaw/workspace/skills/clawteam
cp skills/openclaw/SKILL.md ~/.openclaw/workspace/skills/clawteam/SKILL.md
# 6. 配置 approvals
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 not found — run openclaw once first, then re-run this step')
"
openclaw approvals allowlist add --agent "*" "*/clawteam"
# 7. 验证
clawteam --version
clawteam config health
openclaw skills list | grep clawteam
九、一句话总结
正确安装 ClawTeam-OpenClaw 的关键，不是 pip install clawteam，而是：从这个 fork 仓库源码安装 + 创建 ~/bin/clawteam 软链接 + 给 OpenClaw 配好 skill 和 exec allowlist。 只要这三步做对，后面多智能体协作基本就能跑起来。
