1. 多分支并行开发时Claude Code 的上下文为什么总打架同一个仓库里你正在feature-auth分支上让 Claude Code 帮你补登录逻辑突然线上main有个紧急 bug 要修。你顺手git checkout main编辑器里的文件全变了Claude Code 会话里还残留着刚才 auth 模块的上下文它开始对着main的文件名讲feature-auth的事。等你修完 bug 切回来发现未提交的改动被搅在一起只能git stash再git stash pop运气不好还会冲突。这个问题的根子不在 Claude Code而在 Git 本身一个仓库默认只有一个工作目录checkout是「换文件」而不是「开新房间」。你切分支磁盘上的文件跟着换任何正在读这些文件的进程编辑器、语言服务、Claude Code 会话都会看到一份被换掉的内容。多任务并行时这种「共享同一份文件」的模型天然会互相干扰。Git Worktrees工作树就是为解决这件事设计的。它允许你在同一个仓库下挂载多个独立的工作目录每个目录绑定自己的分支文件互不影响。Claude Code 从较新版本开始原生支持--worktree参数把「创建 worktree 启动独立会话」合成一条命令。这样你可以开两个终端一个跑功能开发一个修 bug两边文件、分支、会话上下文完全隔离。这篇内容面向已经在用 Claude Code、并且经常需要同时处理多条分支的开发者。我会从 worktree 的创建讲起给出 Claude Code 会话绑定、.worktreeinclude配置、依赖安装、清理策略的完整可复制命令最后用两个分支同时改动的实测步骤验证隔离效果。如果你还没配好 Claude Code 的接入环境第 2 节会先带你用 TaoToken 把 Base URL、Key、Model ID 三件套配齐再进入 worktree 部分。核心检索词先明确Claude Code Worktrees 是 Claude Code 结合 Git 工作树实现多分支并行隔离开发的机制适合需要同时维护 feature、bugfix、hotfix 多条分支的团队和个人。它解决的不是「怎么切分支」而是「怎么让多条分支同时活着且互不打扰」。2. 前置准备用 TaoToken 配好 Claude Code 接入三件套Worktree 解决的是文件隔离但 Claude Code 要能正常跑起来得先有可用的模型接入。这一节把接入配置讲清楚后面所有 worktree 命令都建立在这个基础上。Claude Code 走的是 Anthropic 兼容协议配置的核心是三件套Base URL、API Key、Model ID。我用 TaoToken 作为接入端点它的 API 地址是https://taotoken.net/api兼容 Anthropic 的/v1/messages接口。你需要先去控制台拿一个 Key再确认要用的模型 ID。拿 Key 的入口在控制台的 API Keys 页面创建后复制那串sk-开头的字符串。模型 ID 根据你的套餐选择比如claude-sonnet-4-5这类标识具体以控制台模型列表为准。这两样加上 Base URL就是全部需要的东西。配置方式有两种选一种即可。第一种是环境变量适合临时测试export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-5第二种是写进 Claude Code 的 settings 文件适合长期使用。文件路径在~/.claude/settings.jsonmacOS/Linux或%USERPROFILE%\.claude\settings.jsonWindows。内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意ANTHROPIC_BASE_URL只写到/api不要自己拼/v1/messagesClaude Code 会按协议补全路径。Key 不要提交到 Git建议放在全局 settings 而不是项目内 settings。配完后验证一下运行claude进入交互模式随便问一句「你好」能正常返回就说明三件套生效。如果报 401多半是 Key 复制时带了空格或换行如果报连接失败检查 Base URL 是否写成了https://taotoken.net/api/末尾斜杠有时会导致路径拼接异常去掉更稳。这一步做完你就有了一台能正常对话的 Claude Code。接下来才是 worktree 的主场。如果你还想在接入前先确认模型响应质量可以到模型对话页面手动发几条请求对比一下确认没问题再写进配置。3. 可复制配置worktree 创建、会话绑定与 .worktreeinclude这一节是全文的操作核心所有命令都可以直接复制。我按「创建 → 绑定会话 → 配置复制 → 依赖安装」的顺序走一遍。3.1 用 --worktree 创建独立工作目录Claude Code 的--worktree参数会在.claude/worktrees/名称/下创建独立工作目录并自动创建对应分支。指定名称claude --worktree feature-auth执行后会发生三件事在.claude/worktrees/feature-auth/下生成工作目录自动创建分支worktree-feature-auth在该目录中启动一个独立的 Claude Code 会话。你在这个会话里做的所有文件改动都落在feature-auth这个工作目录跟主仓库当前分支无关。如果不指定名称直接claude --worktree它会自动生成一个随机名形如bright-running-fox适合临时起意的任务。也可以在会话中直接说「work in a worktree」让 Claude Code 帮你创建它会根据当前任务内容起一个语义化的名字。3.2 两个终端并行功能开发 bug 修复这是最典型的用法。开两个终端窗口# 终端 1功能开发 claude --worktree feature-auth # 终端 2同时修 bug claude --worktree bugfix-123两个会话各自绑定一个工作目录和分支文件系统层面就是两个独立文件夹。终端 1 里改src/auth/login.ts终端 2 里改src/api/handler.ts互不覆盖。Claude Code 的会话上下文也各自独立不会出现「在 bugfix 会话里讨论 auth 逻辑」的串味。3.3 .worktreeinclude把环境配置带进新工作目录新建的 worktree 是干净目录.env、密钥文件这些不会自动带过去。在项目根目录创建.worktreeinclude文件列出需要复制的文件.env .env.local config/secrets.jsonClaude Code 创建 worktree 时会读取这个清单把对应文件复制到新工作目录。注意这些文件本身应该在.gitignore里.worktreeinclude只是控制「复制哪些」不改变 Git 追踪状态。3.4 把 .claude/worktrees/ 加进 .gitignoreworktree 目录是本地工作产物不该进版本库。在.gitignore里加一行.claude/worktrees/不加的话git status会看到一堆 worktree 目录容易误提交。3.5 每个 worktree 独立装依赖这是最容易踩的坑。worktree 是独立目录node_modules不会共享。进入新 worktree 后要重新装依赖cd .claude/worktrees/feature-auth npm installPython 项目同理需要重建虚拟环境。这一步不做Claude Code 在 worktree 里跑测试或构建会直接报模块找不到。3.6 手动用 Git 创建 worktree 再进 Claude Code如果你想要更细的控制也可以绕过--worktree用原生 Git 命令git worktree add ../my-feature -b my-feature cd ../my-feature claude这种方式 worktree 放在仓库外层的../my-feature适合你想把工作目录和主仓库物理分开的场景。Claude Code 在哪个目录启动就绑定哪个目录所以cd进去再claude即可。3.7 子代理隔离isolation: worktree在 Agent 工具配置里可以给子代理指定isolation: worktree让它在独立 worktree 中执行任务完成后自动清理。适合那种「跑一个实验性改动不想污染主工作区」的场景。配置片段{ isolation: worktree }子代理结束后对应 worktree 和临时分支会被回收不需要你手动删。4. 验证请求两个分支同时改动确认互不干扰配置讲完得实测一遍才算数。这一节用两个分支同时改同一个文件的不同部分验证 worktree 隔离是否真的生效。4.1 准备一个测试仓库mkdir worktree-demo cd worktree-demo git init echo line1 shared.txt echo line2 shared.txt git add shared.txt git commit -m init4.2 开两个 worktree 会话终端 1claude --worktree feature-a终端 2claude --worktree feature-b4.3 在两个会话里分别改 shared.txt在终端 1 的 Claude Code 会话里输入把shared.txt的第一行改成line1-from-feature-a。在终端 2 的会话里输入把shared.txt的第二行改成line2-from-feature-b。4.4 检查两个工作目录的文件内容分别查看两个 worktree 里的文件cat .claude/worktrees/feature-a/shared.txt cat .claude/worktrees/feature-b/shared.txt预期结果feature-a目录里第一行是line1-from-feature-a第二行还是line2feature-b目录里第一行还是line1第二行是line2-from-feature-b。两个目录的文件内容各自独立没有互相覆盖。再回到主仓库根目录看shared.txt它应该还是最初的line1/line2完全没被两个 worktree 的改动影响。这就是隔离生效的直接证据。4.5 验证分支状态git worktree list会列出主工作目录和两个 worktree 的路径及对应分支。每个 worktree 绑定的分支不同git status在各自目录里也只反映自己的改动。4.6 退出时的清理行为Claude Code 退出 worktree 会话时会根据改动状态决定行为如果没有任何改动自动删除 worktree 和分支如果有改动或提交会提示你选择保留还是删除。这个设计避免了「随手开一个 worktree 结果攒了一堆垃圾目录」的问题。实测下来两个会话同时跑文件层面零冲突会话上下文也各管各的。唯一需要手动处理的是依赖安装第一次进 worktree 记得npm install。5. 常见报错排查401、local proxy failed、reading choices、OAuthWorktree 本身不复杂但接入层和会话层容易出问题。这一节按真实报错逐条排查。5.1 401 Unauthorized最常见。原因通常是 Key 无效或 Base URL 写错。检查顺序先确认ANTHROPIC_API_KEY是完整的sk-字符串没有多余空格再确认ANTHROPIC_BASE_URL是https://taotoken.net/api没有拼成/v1/messages或带多余路径。如果用的是 settings.json注意 JSON 里字符串不能有尾随逗号。5.2 local proxy failed这个报错说明 Claude Code 尝试走本地代理但没连上。检查环境变量里有没有残留的HTTP_PROXY/HTTPS_PROXY指向一个没启动的本地端口。清掉这些变量再试unset HTTP_PROXY HTTPS_PROXY同时确认ANTHROPIC_BASE_URL指向的是可直连的地址不要填成localhost之类。5.3 reading choices 相关报错这类报错通常出现在响应解析阶段提示读取choices字段失败。原因是返回体格式跟预期不符多半是 Base URL 指向了非 Anthropic 兼容的端点。确认你用的是 Anthropic 协议端点模型 ID 也在服务端支持列表里。如果模型 ID 拼错服务端可能返回一个结构不同的错误体触发解析异常。5.4 OAuth 相关报错如果你之前用 OAuth 方式登录过 Claude Code环境变量和 OAuth 凭证可能冲突。表现是提示 token 无效或重复认证。解决方式是明确用 API Key 模式确保ANTHROPIC_API_KEY已设置并且没有同时存在 OAuth 的凭证文件。必要时清理~/.claude/下的旧凭证再重新配置。5.5 worktree 里模块找不到这不是接入问题是依赖没装。进 worktree 目录跑一次npm install或对应的依赖安装命令。记住每个 worktree 都是独立目录依赖不共享。5.6 三件套对照表出现配置类报错时对照这张表逐项检查配置项正确值常见错误Base URLhttps://taotoken.net/api多写/v1/messages、末尾多余斜杠API Keysk-开头的完整字符串带空格、换行、复制不全Model ID控制台模型列表中的标识拼写错误、用了不支持的模型名排查顺序建议先看 401认证再看连接类proxy最后看解析类choices。大部分问题出在 Base URL 和 Key 这两个字段上。6. 把 worktree 用进日常清理策略与长期编码建议Worktree 的价值在于「让多条分支同时活着」。日常用法上我建议按任务类型分配功能开发一个 worktreebug 修复一个 worktree实验性改动用子代理的isolation: worktree自动回收。这样主工作目录始终保持干净随时能切回main做发布。清理方面Claude Code 退出时会自动处理无改动的 worktree。有改动的会提示你选择别习惯性点删除先确认改动是否已经合并或提交。手动清理可以用git worktree remove .claude/worktrees/feature-auth git branch -d worktree-feature-auth如果 worktree 目录被手动删了但 Git 还记着用git worktree prune清理元数据。长期编码场景下如果你经常开多个 worktree 并行跑 Agent 任务可以考虑用 Coding Plan 这类按周期计费的方案避免每次会话都单独计费。接入文档里有完整的协议说明和参数列表配置遇到不确定的字段可以先查文档。需要确认模型响应质量时模型对话页面可以手动发请求对比。最后提醒一个容易忽略的点.worktreeinclude里列的文件如果包含密钥确保它们本来就在.gitignore里否则 worktree 复制过去后可能被误提交。worktree 是本地隔离机制不是安全边界敏感文件的管理还是要靠 Git 忽略规则。把上面这些跑通你就能在同一台机器上同时推进多条分支Claude Code 的会话上下文和文件改动各归各的切换成本从「stash checkout 重开会话」降到「开一个新终端」。