1. 多仓库 worktree 的真实痛点为什么单仓库方案一上多仓就散架先说清楚我们在解决什么问题。Git Worktree 本身不复杂它允许你在同一个 Git 仓库上挂出多个工作目录每个目录有独立的分支、索引和 HEAD但共享同一份对象库。对 Coding Agent 来说这意味着你可以让两个会话同时改两份代码互不干扰。单仓库场景下git worktree add ../REQ-001 -b req-001 origin/master一条命令就完事Agent 切进去就能干活。但一旦项目采用多仓库架构事情立刻变味。我们内部的 LLM Arena 平台就是典型父仓库versus通过 Git Submodule 挂载versus-server和versus-fe两个子仓库。你在父仓库上执行git worktree add得到的只是父仓库的工作目录子模块目录要么是空的要么停在某个未初始化的状态。想让这个 worktree 变成能直接开发的环境还得进去跑git submodule sync --recursive和git submodule update --init --recursive把每个子模块按父仓库记录的 Gitlink 检出到对应 commit。问题就出在这里。假设你要并行开发 REQ-001 和 REQ-002理想目录结构是这样. ├── versus/ # 主仓库 │ ├── versus-server/ │ └── versus-fe/ ├── versus-REQ-001/ # REQ-001 的 worktree │ ├── versus-server/ │ └── versus-fe/ └── versus-REQ-002/ # REQ-002 的 worktree ├── versus-server/ └── versus-fe/每个 worktree 都要独立初始化子模块每个 worktree 还要分配独立端口后端 9000N、前端 4000N否则两个 Agent 同时起服务必然端口打架。更麻烦的是如果你让 Coding Agent 每次临时推理下一步该执行什么命令它不仅要消耗额外 token还会因为上下文差异产生不稳定行为——同一个需求两次执行可能走两条不同的路径。我试过让 Agent 自由发挥结果就是子模块漏初始化、端口撞车、REQ-ID 重复三连击。所以核心思路很明确把确定性的操作固化成脚本Agent 只负责理解意图和编排流程。这就是worktree-manager的由来也是本文要讲的多仓库 Git Worktree 与 Submodule 协同管理方案。适合正在用 Codex、Claude Code 等 Coding Agent 做并行开发、且项目采用 Submodule 多仓架构的团队参考。2. TaoToken 前置准备统一 Key 与 API 通道让多 Agent 会话复用同一套鉴权多仓库 worktree 一旦跑起来你会同时开好几个 Agent 会话每个会话都要调用模型。如果每个会话各自配置 endpoint 和 Key管理成本会迅速失控Key 散落在不同配置文件里换一次通道要改 N 个地方排查问题时根本不知道哪个会话用的是哪套配置。所以第二步是把 endpoint 与鉴权统一到 TaoToken 的 API 通道上。TaoToken 在这里扮演的角色是统一的模型调用入口。你只需要在官网注册后拿到一个 API Key然后在所有 Agent 会话里复用同一套 Base URL 和 Key。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 通道地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时直接用这个。具体要准备三样东西我把它叫做三件套配置项值说明Base URLhttps://taotoken.net/api所有会话统一填这个API Key控制台生成的sk-开头字符串建议一个项目一个 Key便于归因Model ID按需选择如claude-sonnet-4-5等与你的 Coding Agent 兼容的模型标识Key 的生成入口在控制台的 API Keys 页面路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成后先复制保存页面刷新后就看不到完整 Key 了。这里有个容易踩的坑很多人以为把 Key 填进一个地方就全局生效实际上不同的 Coding Agent 读的是不同的配置文件。Claude Code 读~/.claude/settings.jsonCodex 读~/.codex/auth.jsonCline 这类插件读的是自己的 MCP 配置。所以统一到 TaoToken不是改一处而是把这几处的 Base URL 和 Key 都指向同一套值。下面第 3 节我会给出可直接复制的配置片段。另外提醒一句TaoToken 是模型调用通道不是代码编辑器也不是 Git 托管服务。它解决的是多个 Agent 会话如何用同一套鉴权稳定调用模型worktree 和 Submodule 的管理仍然由 Git 和你的脚本负责两者职责不要混淆。3. 可复制配置worktree-manager 脚本 三件套 settings 片段这一节是全文最核心的部分给你可以直接抄的配置。分两块worktree 管理脚本wt.sh以及把 endpoint 和鉴权改到 TaoToken 的配置文件片段。3.1 worktree-manager 脚本骨架脚本的设计目标很明确每个需求一个独立 worktree独立端口不改业务代码端口和代理只在 worktree 内本地改并用assume-unchanged忽略。核心函数包括创建、列出、切换、删除、查看详情。#!/usr/bin/env bash # scripts/wt.sh - 多需求并行开发 worktree 管理脚本 # 用法: # ./scripts/wt.sh new id # 创建 worktree # ./scripts/wt.sh list # 列出所有 worktree 端口 状态 # ./scripts/wt.sh go id # 切换需 shell-init 的 function # ./scripts/wt.sh remove id # 删除 worktree # ./scripts/wt.sh info id # 查看单个 worktree 详情 set -euo pipefail ROOT_DIR$(cd $(dirname $0)/.. pwd) WT_ROOT${WT_ROOT:-$ROOT_DIR/..} # worktree 存放根目录 WT_META_DIR$ROOT_DIR/.wt # 注册表目录.gitignore 已忽略 write_meta() { local id$1 path$2 branch$3 be$4 fe$5 req_id${6:-} mkdir -p $WT_META_DIR { echo WT_PATH$path echo WT_BRANCH$branch echo WT_BE_PORT$be echo WT_FE_PORT$fe echo WT_REQ_ID$req_id } $WT_META_DIR/$id.meta } allocate_req_id() { # 扫描已有元数据取最大编号 1 local max0 for f in $WT_META_DIR/*.meta; do [ -e $f ] || continue local n n$(grep -oP WT_REQ_IDREQ-\K[0-9] $f 2/dev/null || echo 0) [ $n -gt $max ] max$n done printf REQ-%03d $((max 1)) } cmd_new() { local id$1 local req_id req_id$(allocate_req_id) local wt_path$WT_ROOT/versus-$id local branchfeat/$id local be_port$((9000 RANDOM % 100)) local fe_port$((4000 RANDOM % 100)) echo [1/6] 创建 Git Worktree基于 master... if ! git -C $ROOT_DIR worktree add -b $branch $wt_path master 21; then echo 创建 worktree 失败分支 $branch 可能已存在 2 exit 1 fi echo [2/6] 初始化子模块... git -C $wt_path submodule sync --recursive git -C $wt_path submodule update --init --recursive echo [3/6] 写入端口与环境配置... write_meta $id $wt_path $branch $be_port $fe_port $req_id echo [4/6] 本地改端口并 assume-unchanged... # 示例修改 worktree 内的本地配置文件不提交 sed -i s/9000/$be_port/g $wt_path/versus-server/config.local.yaml 2/dev/null || true git -C $wt_path update-index --assume-unchanged versus-server/config.local.yaml 2/dev/null || true echo [5/6] 完成。worktree: $wt_path echo [6/6] REQ-ID: $req_id, 后端端口: $be_port, 前端端口: $fe_port } cmd_list() { git -C $ROOT_DIR worktree list echo --- 元数据 --- for f in $WT_META_DIR/*.meta; do [ -e $f ] || continue echo $(basename $f .meta) cat $f done } case ${1:-} in new) shift; cmd_new $ ;; list) cmd_list ;; *) echo 用法: $0 {new|list|go|remove|info} id ;; esac这个脚本的关键点allocate_req_id先扫元数据再分配git worktree add -b用分支创建做互斥保护——如果分支已存在命令直接失败上层 Agent 识别冲突后重新分配编号重试。这样即使两个会话同时算出同一个 REQ-ID也只有一个能成功。3.2 把 endpoint 与鉴权改到 TaoToken下面给出三个常见 Coding Agent 的配置片段路径与原文一致直接替换成你的 Key 即可。Claude Code 的~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Codex 的~/.codex/auth.json{ OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的TaoTokenKey, model: gpt-5-codex }Cline / MCP 类插件的配置以 MCP server 形式接入{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的TaoTokenKey, TAOTOKEN_MODEL: claude-sonnet-4-5 } } } }三件套Base URL Key Model ID在每一处都要写全缺一个都会导致请求失败。配置完成后所有 worktree 里的 Agent 会话都复用同一套鉴权换通道时只改这几处不用逐个会话去翻。4. 验证请求创建/切换 worktree、Submodule 同步、Agent 会话复用检查配置写完必须验证否则你永远不知道是脚本问题还是鉴权问题。这一节给出完整的验证动作和预期结果。4.1 创建并切换 worktreecd versus ./scripts/wt.sh new REQ-001 ./scripts/wt.sh list预期输出里能看到versus-REQ-001这个 worktree 路径、feat/REQ-001分支、分配的后端和前端端口以及WT_REQ_IDREQ-001。如果git worktree add报分支已存在说明编号冲突脚本会退出重新跑一次会分配新编号。切换进 worktreecd ../versus-REQ-001 git status git submodule status --recursivegit submodule status每行前面应该是一个 commit hash没有-前缀-表示未初始化。如果看到-说明子模块没初始化成功回到脚本第 2 步排查。4.2 跨仓库 Submodule 同步验证在 worktree 里改一个子模块的文件然后检查父仓库是否感知到 Gitlink 变化cd versus-server git checkout -b test-submodule-sync echo // test main.go git add main.go git commit -m test submodule sync cd .. git status父仓库应该显示versus-server有 modified 内容Gitlink 指向的 commit 变了。这一步验证的是多 worktree 下 Submodule 的检出和同步是否正常。注意 Git 官方文档明确说过多 worktree 场景下 Submodule 支持仍不完整不推荐对 superproject 做多重检出所以这套方案要结合实际 Git 版本验证不能当通用方案。4.3 Agent 会话复用检查开两个终端分别进入两个 worktree各起一个 Agent 会话让它们同时发一次模型请求。验证点是两个会话都能正常返回且用的是同一套 TaoToken 鉴权。# 终端 1 cd versus-REQ-001 claude 列出当前目录的 git 分支 # 终端 2 cd versus-REQ-002 claude 列出当前目录的 git 分支如果两个会话都正常返回说明 endpoint 和 Key 配置生效会话复用没问题。如果其中一个报 401说明那个会话读的配置文件没改到回去检查对应的 settings 路径。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来每个都给出定位思路。401 Unauthorized最常见。原因通常是 Key 没填、填错或者 Base URL 写成了带 UTM 的官网地址而不是 API 地址。检查三件套Base URL 必须是https://taotoken.net/apiKey 必须是sk-开头且未过期Model ID 必须是通道支持的模型。三个里错一个都可能报 401 或 404。local proxy failed这个报错通常出现在 Agent 试图走本地代理但代理没起来或者环境变量里残留了旧的代理配置。检查~/.claude/settings.json和 shell 的env确认没有指向本地端口的*_PROXY变量。把 Base URL 直接指向 TaoToken 的 API 地址即可不需要额外代理层。reading choices 相关报错这类报错一般出现在响应解析阶段说明返回的 JSON 结构不符合 Agent 预期。常见原因是 Model ID 填了一个通道不支持的模型或者请求被路由到了不兼容的接口。换一个确认可用的 Model ID 重试比如先用模型对话页面验证一下模型是否可用。OAuth 相关报错如果你用的是 Claude Code 或 Codex 的 OAuth 登录流程同时又配了 API Key两者可能冲突。解决方式是明确走 API Key 模式把 OAuth 相关的 token 缓存清掉确保配置文件里只有ANTHROPIC_AUTH_TOKEN或OPENAI_API_KEY这一套。排查顺序建议先确认三件套完整再用模型对话页面单独验证 Key 是否可用最后回到 Agent 会话里验证。这样能把通道问题和Agent 配置问题分开定位。6. 把 worktree 管理接入 Coding Plan让多 Agent 编排稳定跑起来前面几节把脚本、配置、验证、排障都走了一遍。最后说编排层面的收尾。当你有 7 个 Sub-Agent 要协作时每次手动输入开启 N 个 Agent 协作实现 XXX既容易漏步骤也不利于状态恢复。我们的做法是把 worktree-manager 作为流水线的第 0 步放在 requirement-designer 之前确保每个需求先拿到隔离的 worktree 和独立端口再进入 PRD、编码、测试环节。如果你要长期跑这种多 Agent 并行开发建议把模型调用也纳入统一管理用 Coding Plan 来承载长期的编码和 Agent 任务入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这样 Key 管理、额度归因、会话复用都在一个地方不用在多个配置文件之间来回切换。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各 Agent 的完整配置示例。模型可用性可以先在模型对话页面验证地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实操建议把wt.sh的list输出接到你的 Agent 启动脚本里每次开新会话前先跑一次确认没有残留的 worktree 占着端口。多仓库 worktree 的坑八成出在以为清理干净了其实没有上。
1. 多仓库 worktree 的真实痛点为什么单仓库方案一上多仓就散架先说清楚我们在解决什么问题。Git Worktree 本身不复杂它允许你在同一个 Git 仓库上挂出多个工作目录每个目录有独立的分支、索引和 HEAD但共享同一份对象库。对 Coding Agent 来说这意味着你可以让两个会话同时改两份代码互不干扰。单仓库场景下git worktree add ../REQ-001 -b req-001 origin/master一条命令就完事Agent 切进去就能干活。但一旦项目采用多仓库架构事情立刻变味。我们内部的 LLM Arena 平台就是典型父仓库versus通过 Git Submodule 挂载versus-server和versus-fe两个子仓库。你在父仓库上执行git worktree add得到的只是父仓库的工作目录子模块目录要么是空的要么停在某个未初始化的状态。想让这个 worktree 变成能直接开发的环境还得进去跑git submodule sync --recursive和git submodule update --init --recursive把每个子模块按父仓库记录的 Gitlink 检出到对应 commit。问题就出在这里。假设你要并行开发 REQ-001 和 REQ-002理想目录结构是这样. ├── versus/ # 主仓库 │ ├── versus-server/ │ └── versus-fe/ ├── versus-REQ-001/ # REQ-001 的 worktree │ ├── versus-server/ │ └── versus-fe/ └── versus-REQ-002/ # REQ-002 的 worktree ├── versus-server/ └── versus-fe/每个 worktree 都要独立初始化子模块每个 worktree 还要分配独立端口后端 9000N、前端 4000N否则两个 Agent 同时起服务必然端口打架。更麻烦的是如果你让 Coding Agent 每次临时推理下一步该执行什么命令它不仅要消耗额外 token还会因为上下文差异产生不稳定行为——同一个需求两次执行可能走两条不同的路径。我试过让 Agent 自由发挥结果就是子模块漏初始化、端口撞车、REQ-ID 重复三连击。所以核心思路很明确把确定性的操作固化成脚本Agent 只负责理解意图和编排流程。这就是worktree-manager的由来也是本文要讲的多仓库 Git Worktree 与 Submodule 协同管理方案。适合正在用 Codex、Claude Code 等 Coding Agent 做并行开发、且项目采用 Submodule 多仓架构的团队参考。2. TaoToken 前置准备统一 Key 与 API 通道让多 Agent 会话复用同一套鉴权多仓库 worktree 一旦跑起来你会同时开好几个 Agent 会话每个会话都要调用模型。如果每个会话各自配置 endpoint 和 Key管理成本会迅速失控Key 散落在不同配置文件里换一次通道要改 N 个地方排查问题时根本不知道哪个会话用的是哪套配置。所以第二步是把 endpoint 与鉴权统一到 TaoToken 的 API 通道上。TaoToken 在这里扮演的角色是统一的模型调用入口。你只需要在官网注册后拿到一个 API Key然后在所有 Agent 会话里复用同一套 Base URL 和 Key。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 通道地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时直接用这个。具体要准备三样东西我把它叫做三件套配置项值说明Base URLhttps://taotoken.net/api所有会话统一填这个API Key控制台生成的sk-开头字符串建议一个项目一个 Key便于归因Model ID按需选择如claude-sonnet-4-5等与你的 Coding Agent 兼容的模型标识Key 的生成入口在控制台的 API Keys 页面路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成后先复制保存页面刷新后就看不到完整 Key 了。这里有个容易踩的坑很多人以为把 Key 填进一个地方就全局生效实际上不同的 Coding Agent 读的是不同的配置文件。Claude Code 读~/.claude/settings.jsonCodex 读~/.codex/auth.jsonCline 这类插件读的是自己的 MCP 配置。所以统一到 TaoToken不是改一处而是把这几处的 Base URL 和 Key 都指向同一套值。下面第 3 节我会给出可直接复制的配置片段。另外提醒一句TaoToken 是模型调用通道不是代码编辑器也不是 Git 托管服务。它解决的是多个 Agent 会话如何用同一套鉴权稳定调用模型worktree 和 Submodule 的管理仍然由 Git 和你的脚本负责两者职责不要混淆。3. 可复制配置worktree-manager 脚本 三件套 settings 片段这一节是全文最核心的部分给你可以直接抄的配置。分两块worktree 管理脚本wt.sh以及把 endpoint 和鉴权改到 TaoToken 的配置文件片段。3.1 worktree-manager 脚本骨架脚本的设计目标很明确每个需求一个独立 worktree独立端口不改业务代码端口和代理只在 worktree 内本地改并用assume-unchanged忽略。核心函数包括创建、列出、切换、删除、查看详情。#!/usr/bin/env bash # scripts/wt.sh - 多需求并行开发 worktree 管理脚本 # 用法: # ./scripts/wt.sh new id # 创建 worktree # ./scripts/wt.sh list # 列出所有 worktree 端口 状态 # ./scripts/wt.sh go id # 切换需 shell-init 的 function # ./scripts/wt.sh remove id # 删除 worktree # ./scripts/wt.sh info id # 查看单个 worktree 详情 set -euo pipefail ROOT_DIR$(cd $(dirname $0)/.. pwd) WT_ROOT${WT_ROOT:-$ROOT_DIR/..} # worktree 存放根目录 WT_META_DIR$ROOT_DIR/.wt # 注册表目录.gitignore 已忽略 write_meta() { local id$1 path$2 branch$3 be$4 fe$5 req_id${6:-} mkdir -p $WT_META_DIR { echo WT_PATH$path echo WT_BRANCH$branch echo WT_BE_PORT$be echo WT_FE_PORT$fe echo WT_REQ_ID$req_id } $WT_META_DIR/$id.meta } allocate_req_id() { # 扫描已有元数据取最大编号 1 local max0 for f in $WT_META_DIR/*.meta; do [ -e $f ] || continue local n n$(grep -oP WT_REQ_IDREQ-\K[0-9] $f 2/dev/null || echo 0) [ $n -gt $max ] max$n done printf REQ-%03d $((max 1)) } cmd_new() { local id$1 local req_id req_id$(allocate_req_id) local wt_path$WT_ROOT/versus-$id local branchfeat/$id local be_port$((9000 RANDOM % 100)) local fe_port$((4000 RANDOM % 100)) echo [1/6] 创建 Git Worktree基于 master... if ! git -C $ROOT_DIR worktree add -b $branch $wt_path master 21; then echo 创建 worktree 失败分支 $branch 可能已存在 2 exit 1 fi echo [2/6] 初始化子模块... git -C $wt_path submodule sync --recursive git -C $wt_path submodule update --init --recursive echo [3/6] 写入端口与环境配置... write_meta $id $wt_path $branch $be_port $fe_port $req_id echo [4/6] 本地改端口并 assume-unchanged... # 示例修改 worktree 内的本地配置文件不提交 sed -i s/9000/$be_port/g $wt_path/versus-server/config.local.yaml 2/dev/null || true git -C $wt_path update-index --assume-unchanged versus-server/config.local.yaml 2/dev/null || true echo [5/6] 完成。worktree: $wt_path echo [6/6] REQ-ID: $req_id, 后端端口: $be_port, 前端端口: $fe_port } cmd_list() { git -C $ROOT_DIR worktree list echo --- 元数据 --- for f in $WT_META_DIR/*.meta; do [ -e $f ] || continue echo $(basename $f .meta) cat $f done } case ${1:-} in new) shift; cmd_new $ ;; list) cmd_list ;; *) echo 用法: $0 {new|list|go|remove|info} id ;; esac这个脚本的关键点allocate_req_id先扫元数据再分配git worktree add -b用分支创建做互斥保护——如果分支已存在命令直接失败上层 Agent 识别冲突后重新分配编号重试。这样即使两个会话同时算出同一个 REQ-ID也只有一个能成功。3.2 把 endpoint 与鉴权改到 TaoToken下面给出三个常见 Coding Agent 的配置片段路径与原文一致直接替换成你的 Key 即可。Claude Code 的~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Codex 的~/.codex/auth.json{ OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的TaoTokenKey, model: gpt-5-codex }Cline / MCP 类插件的配置以 MCP server 形式接入{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的TaoTokenKey, TAOTOKEN_MODEL: claude-sonnet-4-5 } } } }三件套Base URL Key Model ID在每一处都要写全缺一个都会导致请求失败。配置完成后所有 worktree 里的 Agent 会话都复用同一套鉴权换通道时只改这几处不用逐个会话去翻。4. 验证请求创建/切换 worktree、Submodule 同步、Agent 会话复用检查配置写完必须验证否则你永远不知道是脚本问题还是鉴权问题。这一节给出完整的验证动作和预期结果。4.1 创建并切换 worktreecd versus ./scripts/wt.sh new REQ-001 ./scripts/wt.sh list预期输出里能看到versus-REQ-001这个 worktree 路径、feat/REQ-001分支、分配的后端和前端端口以及WT_REQ_IDREQ-001。如果git worktree add报分支已存在说明编号冲突脚本会退出重新跑一次会分配新编号。切换进 worktreecd ../versus-REQ-001 git status git submodule status --recursivegit submodule status每行前面应该是一个 commit hash没有-前缀-表示未初始化。如果看到-说明子模块没初始化成功回到脚本第 2 步排查。4.2 跨仓库 Submodule 同步验证在 worktree 里改一个子模块的文件然后检查父仓库是否感知到 Gitlink 变化cd versus-server git checkout -b test-submodule-sync echo // test main.go git add main.go git commit -m test submodule sync cd .. git status父仓库应该显示versus-server有 modified 内容Gitlink 指向的 commit 变了。这一步验证的是多 worktree 下 Submodule 的检出和同步是否正常。注意 Git 官方文档明确说过多 worktree 场景下 Submodule 支持仍不完整不推荐对 superproject 做多重检出所以这套方案要结合实际 Git 版本验证不能当通用方案。4.3 Agent 会话复用检查开两个终端分别进入两个 worktree各起一个 Agent 会话让它们同时发一次模型请求。验证点是两个会话都能正常返回且用的是同一套 TaoToken 鉴权。# 终端 1 cd versus-REQ-001 claude 列出当前目录的 git 分支 # 终端 2 cd versus-REQ-002 claude 列出当前目录的 git 分支如果两个会话都正常返回说明 endpoint 和 Key 配置生效会话复用没问题。如果其中一个报 401说明那个会话读的配置文件没改到回去检查对应的 settings 路径。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来每个都给出定位思路。401 Unauthorized最常见。原因通常是 Key 没填、填错或者 Base URL 写成了带 UTM 的官网地址而不是 API 地址。检查三件套Base URL 必须是https://taotoken.net/apiKey 必须是sk-开头且未过期Model ID 必须是通道支持的模型。三个里错一个都可能报 401 或 404。local proxy failed这个报错通常出现在 Agent 试图走本地代理但代理没起来或者环境变量里残留了旧的代理配置。检查~/.claude/settings.json和 shell 的env确认没有指向本地端口的*_PROXY变量。把 Base URL 直接指向 TaoToken 的 API 地址即可不需要额外代理层。reading choices 相关报错这类报错一般出现在响应解析阶段说明返回的 JSON 结构不符合 Agent 预期。常见原因是 Model ID 填了一个通道不支持的模型或者请求被路由到了不兼容的接口。换一个确认可用的 Model ID 重试比如先用模型对话页面验证一下模型是否可用。OAuth 相关报错如果你用的是 Claude Code 或 Codex 的 OAuth 登录流程同时又配了 API Key两者可能冲突。解决方式是明确走 API Key 模式把 OAuth 相关的 token 缓存清掉确保配置文件里只有ANTHROPIC_AUTH_TOKEN或OPENAI_API_KEY这一套。排查顺序建议先确认三件套完整再用模型对话页面单独验证 Key 是否可用最后回到 Agent 会话里验证。这样能把通道问题和Agent 配置问题分开定位。6. 把 worktree 管理接入 Coding Plan让多 Agent 编排稳定跑起来前面几节把脚本、配置、验证、排障都走了一遍。最后说编排层面的收尾。当你有 7 个 Sub-Agent 要协作时每次手动输入开启 N 个 Agent 协作实现 XXX既容易漏步骤也不利于状态恢复。我们的做法是把 worktree-manager 作为流水线的第 0 步放在 requirement-designer 之前确保每个需求先拿到隔离的 worktree 和独立端口再进入 PRD、编码、测试环节。如果你要长期跑这种多 Agent 并行开发建议把模型调用也纳入统一管理用 Coding Plan 来承载长期的编码和 Agent 任务入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这样 Key 管理、额度归因、会话复用都在一个地方不用在多个配置文件之间来回切换。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各 Agent 的完整配置示例。模型可用性可以先在模型对话页面验证地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实操建议把wt.sh的list输出接到你的 Agent 启动脚本里每次开新会话前先跑一次确认没有残留的 worktree 占着端口。多仓库 worktree 的坑八成出在以为清理干净了其实没有上。
