1. 当多个 CLI Agent 抢同一个仓库时，麻烦才刚开始
ClawTeam 是一个框架无关的多智能体协调 CLI 工具，它让 AI 智能体能够自主组织成团队——分配任务、相互通信、协调工作并合并结果。它适合谁？适合已经在用 OpenClaw、Claude Code 这类 CLI 编码代理，并且开始觉得“一个代理干一个仓库”不够用的人。我试过让两个代理同时改同一个项目，结果一个在改auth.py，另一个在重构auth.py的调用方，两边互相覆盖，最后 git status 一片红，谁都不敢提交。
问题的根子不在模型能力，而在工程骨架：多个代理共享一个工作目录，等于让几个人在同一张纸上写字。ClawTeam 给出的解法很直接——每个代理一个独立的 git worktree 加一个独立的 tmux 窗口，分支隔离、会话隔离、消息走文件系统。这样代理之间不再抢文件，而是通过任务和邮箱协作，最后由 leader 合并结果。
这篇会从零搭一套可复制的骨架：先配好 TaoToken 的统一 Key 和 API 通道，再写config.toml，然后用clawteam team spawn-team起团队、clawteam spawn起代理、clawteam board看状态，最后验证协作链路真的跑通。全程命令可直接复制，踩坑点我会单独标出来。
2. 前置：用 TaoToken 统一 Key 打通 OpenClaw 的 API 通道
ClawTeam 本身是协调层，真正干活的是 OpenClaw 这类代理后端。代理一多，最烦的是每个代理都要单独配 Key、单独算额度。TaoToken 在这里的作用是提供一个统一的 API 通道：一个 Key 覆盖多个模型，OpenClaw、Claude Code 兼容的 CLI 都能指向同一个入口，省掉每个代理重复配置的麻烦。
先拿 Key。打开 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制出来。注意这个 Key 只在创建时完整显示一次，先存到安全的地方。
拿到 Key 之后，把它写进环境变量。ClawTeam 的 spawn 系统会把当前环境透传给每个代理，所以只要在启动 ClawTeam 的 shell 里 export 一次，所有代理都能继承：
export TAOTOKEN_API_KEY="sk-你的key" export OPENAI_API_KEY="$TAOTOKEN_API_KEY" export OPENAI_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="$TAOTOKEN_API_KEY" export ANTHROPIC_BASE_URL="https://taotoken.net/api"这里同时设了 OpenAI 和 Anthropic 两套变量，是因为 OpenClaw 和 Claude Code 系的后端读的变量名不一样。统一指向https://taotoken.net/api之后，代理走哪条协议都落到同一个通道上。
注意：
OPENAI_BASE_URL和ANTHROPIC_BASE_URL末尾不要带/v1，TaoToken 的接入层会自己处理路径。多带一层会 404，这个坑我踩过。
想先确认 Key 和通道是通的，不用急着起代理，直接用模型对话页面发一条测试消息最快： https://taotoken.net/models 。能正常返回就说明 Key 有效、通道没问题，再往下搭骨架。
如果你打算长期跑多代理、频繁 spawn，建议顺手看一下 Coding Plan： https://taotoken.net/coding-plan ，按量计费和包月在高频 spawn 场景下差别不小，代理数量一多，成本会明显往一边偏。
3. 可复制配置：config.toml 骨架与 ClawTeam 初始化
ClawTeam 的配置是三层优先级：环境变量 > 配置文件 > 默认值。所以config.toml里写的是“默认值”，需要临时覆盖时用环境变量，不用改文件。
先建数据目录并初始化：
mkdir -p ~/.clawteam clawteam config showconfig show会打印当前生效的每一项配置和它的来源（env / file / default），这是排查配置问题最有用的一条命令。接着写~/.clawteam/config.toml：
# ~/.clawteam/config.toml data_dir = "~/.clawteam" user = "alice" default_team = "dev-team" transport = "file" workspace = "auto" default_backend = "tmux" skip_permissions = true逐项说明一下，这些字段直接对应 ClawTeam 的配置模型：
| 字段 | 作用 | 建议值 |
|---|---|---|
data_dir | 所有状态存储根目录 | ~/.clawteam |
user | 多用户协作时的命名空间 | 你的名字 |
default_team | 省略--team时的默认团队 | 固定一个 |
transport | 消息传输后端 | file（零依赖） |
workspace | 是否自动建 worktree | auto |
default_backend | spawn 后端 | tmux |
skip_permissions | 跳过代理权限审批 | true |
workspace = "auto"是关键：它让 ClawTeam 在 spawn 代理时自动为该代理创建 git worktree 和分支，分支命名规则是clawteam/{team}/{agent}。default_backend = "tmux"则决定代理跑在 tmux 窗口里，你能随时 attach 进去看它在干什么。
改完验证一下配置来源：
clawteam config get workspace clawteam config healthconfig health会检查数据目录可写、git 可用、tmux 可用这些前置条件。如果它报 tmux 找不到，先装 tmux 再继续，否则 spawn 会直接失败。
4. 启动、切换、验证：把协作链路跑通
配置就绪后，进入实操。整个流程分四步：建团队、起代理、看状态、验证消息。
4.1 创建团队并 spawn 两个代理
先在一个 git 仓库根目录下操作，因为 worktree 依赖 git：
cd ~/projects/my-app clawteam team spawn-team dev-team -d "Build auth module" -n leader这条命令创建团队dev-team，并把当前 shell 注册为 leader。接着起两个 worker：
clawteam spawn --team dev-team --agent-name alice --task "Implement login endpoint" clawteam spawn --team dev-team --agent-name bob --task "Write tests for login"每个spawn背后做了几件事：创建clawteam/dev-team/alice分支、在~/.clawteam/workspaces/dev-team/alice建 worktree、开一个名为clawteam-dev-team的 tmux session 并新增alice窗口、把构建好的 prompt 注入进去。prompt 里包含代理身份、工作目录、分支名和协调协议，代理一启动就知道自己该干什么、该用哪条命令汇报。
4.2 切换与观察代理
tmux 会话名固定是clawteam-{team}，窗口名就是代理名，切换很直接：
tmux attach -t clawteam-dev-team # 在 tmux 内用 Ctrl-b + w 列出窗口，选 alice 或 bob # 或者直接指定窗口 tmux select-window -t clawteam-dev-team:alice不想 attach 也可以用终端看板：
clawteam board show dev-team # 一次性快照 clawteam board live dev-team # 自动刷新 clawteam board serve --port 8080 # Web UI，浏览器打开 localhost:8080board live会持续刷新任务状态、成员存活、消息计数。代理挂掉时，存活检查会通过 tmux pane 状态和 PID 双重判断，在面板上标出来。
4.3 验证协作链路
链路是否真的通了，看三件事：任务能流转、消息能送达、worktree 能合并。
先看任务：
clawteam task list dev-team --owner alice clawteam task update dev-team <task-id> --status in_progress任务状态机是pending → in_progress → completed，被依赖阻塞时是blocked。当一个任务完成，依赖它的任务会自动从blocked解锁为pending，这是文件锁保护的原子操作。
再验证消息：
clawteam inbox send dev-team alice "login endpoint 的字段定义发我一下" clawteam inbox peek dev-team bob # 查看不消费 clawteam inbox receive dev-team bob # 接收并消费peek和receive的区别很重要：peek只看不删，适合调试；receive是 FIFO 消费，代理正常汇报走这个。
最后验证 worktree 隔离与合并：
clawteam workspace list dev-team clawteam workspace checkpoint dev-team alice -m "login endpoint done" clawteam workspace merge dev-team aliceworkspace list会显示每个代理的分支名和 worktree 路径。checkpoint相当于在该代理分支上提交一次，merge把它的分支合回目标分支。因为每个代理在独立 worktree 里干活，合并前不会互相污染，冲突只会在 merge 这一步暴露，处理起来可控得多。
5. 本篇常见错排查
spawn 报 “not a git repository”：worktree 必须在 git 仓库内创建。确认你在仓库根目录，或者用git rev-parse --show-toplevel检查当前路径。ClawTeam 会向上找仓库根，但如果你在仓库外，它找不到就报错。
代理起来了但一直不动：多半是 prompt 注入失败或权限提示卡住。attach 到对应 tmux 窗口看屏幕内容。如果是目录信任提示，skip_permissions = true配合自动确认逻辑应该能处理；如果还卡，检查config health里 tmux 版本是否过旧。
消息发了但对方收不到：先clawteam inbox peek dev-team <agent>确认消息在不在收件箱。如果 peek 有、receive 没有，检查是不是被别的进程消费了。多用户场景下收件箱名是{user}_{agent}复合键，user配错会导致消息投到另一个命名空间。
merge 时冲突：这是正常的，worktree 隔离只保证干活时不互相踩，合并时该冲突还是冲突。先workspace checkpoint保存当前进度，再手动解决冲突后重新 merge。别在没 checkpoint 的情况下直接 cleanup，会丢工作。
API 请求 401 或 404：401 是 Key 无效，回 https://taotoken.net/api-keys 确认 Key 没被删；404 通常是 base URL 多带了/v1，改成https://taotoken.net/api即可。改完记得重新 export，因为 spawn 继承的是启动时的环境。
board serve 端口被占：换端口--port 8081。SSE 推送依赖长连接，如果前面有反向代理，记得关掉对/api/events/的缓冲。
6. 把骨架固定下来，再往上加代理
这套骨架跑通之后，加代理就是重复clawteam spawn一条命令的事，每个新代理自动拿到独立 worktree、独立 tmux 窗口、独立收件箱。真正需要你操心的只剩两件：任务怎么拆、结果怎么合。
如果你要长期跑多代理编码或 Agent 流水线，建议把 Key 和通道固定成一套：API Key 在 https://taotoken.net/api-keys 管理，接入细节看文档 https://taotoken.net/doc ，长期高频 spawn 的话 Coding Plan 在 https://taotoken.net/coding-plan 。Claude Code 系后端的接入说明在 https://taotoken.net/claude-code 。控制台总览在 https://taotoken.net/console 。
最后留一个实用习惯：每次大改配置后先跑clawteam config health，再clawteam board show，两步确认环境和状态都正常，再 spawn 新代理。骨架稳了，代理数量才有意义。
