1. 为什么单会话的 Claude Code 一到多任务就崩如果你已经用 Claude Code 写过几个小项目大概率经历过这种场景主分支上正在让 Agent 重构一个模块突然线上报了个 bug 要紧急修你只能先中断当前会话切分支、改代码、跑测试等回来时上下文已经乱了Agent 记不清刚才改到哪一步。更麻烦的是如果你同时开两个终端跑 Claude Code两边都在改同一份工作目录git status 会变成一锅粥谁改了哪个文件根本分不清。这就是单会话、单工作目录模式的天然瓶颈。Claude Code 本身是一个状态化的 Agent它的上下文里包含文件快照、工具调用历史、当前任务描述。当多个任务共享同一个工作目录时文件系统层面的冲突会直接污染 Agent 的上下文导致它做出错误判断。我试过在一个仓库里同时让两个会话分别处理前端和后端改动结果两边都在读对方的中间状态最后提交的 diff 里混进了不属于自己的修改。要解决这个问题需要两个能力配合一是hooks让 Agent 在生命周期的关键节点自动执行你定义的逻辑比如会话启动时加载项目规范、执行 bash 前记录审计日志、任务停止时自动提醒继续二是Worktree利用 Git 原生的多工作树能力给每个并行任务分配独立的目录和分支从文件系统层面彻底隔离。这两个能力组合起来才能把 Claude Code 从一个会写代码的终端变成可编排的自动化协作程序员。下面我会先讲清楚前置准备再给出可直接复制的 hooks 配置和 Worktree 初始化命令最后用具体操作验证自动化触发是否真的生效。2. 前置准备TaoToken 接入与 Claude Code 环境确认在配置 hooks 和 Worktree 之前需要先确保 Claude Code 能正常调用模型。这里我用 TaoToken 作为统一接入层它的 API 兼容 OpenAI 格式一套 Key 可以切换不同模型适合在并行任务里按需分配。2.1 获取 API Key 与 Base URL打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。拿到 Key 之后记录两个关键信息Base URLhttps://taotoken.net/apiAPI Key形如sk-xxxxxxxx如果你需要查看当前可用的模型列表和具体调用方式可以访问接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 里面有各模型的 Model ID 对照表。常用的编码模型包括claude-sonnet-4-6、claude-opus-4-6等Worktree 并行任务建议用响应速度较快的 Sonnet 系列复杂重构再切 Opus。2.2 配置 Claude Code 的环境变量Claude Code 通过环境变量读取 API 配置。在~/.zshrc或~/.bashrc中加入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-6保存后执行source ~/.zshrc使其生效。验证配置是否被正确读取echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_MODEL如果输出的是你设置的值说明环境变量已生效。这一步看起来简单但后面 hooks 脚本里会依赖这些变量所以务必先确认。2.3 确认 Git 版本支持 WorktreeWorktree 是 Git 2.5 引入的功能现在主流版本都支持。执行git --version只要版本号大于 2.5 即可。另外确认你的仓库是一个正常的 Git 仓库有至少一次提交否则 Worktree 无法基于分支创建。2.4 理解 hooks 的配置文件位置Claude Code 的 hooks 配置放在项目根目录的.claude/settings.json中也可以放在用户级目录~/.claude/settings.json。项目级配置只对当前仓库生效用户级配置对所有项目生效。多任务并行场景建议用项目级配置这样每个 Worktree 可以有自己的 hooks 行为。配置结构大致如下{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: 你的脚本路径 } ] } ] } }matcher用于匹配触发条件空字符串表示所有情况都触发。type目前支持command即执行一条 shell 命令。理解了这个结构下面就可以写具体的配置了。3. 可复制配置hooks 生命周期编排与 Worktree 初始化这一节给出可以直接复制使用的配置片段。我会先写 hooks 的 settings.json再写 Worktree 的初始化脚本最后说明两者如何配合。3.1 hooks 配置片段在项目根目录创建.claude/settings.json写入以下内容{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: bash .claude/hooks/session-start.sh } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash .claude/hooks/pre-bash.sh } ] } ], PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: bash .claude/hooks/post-edit.sh } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: bash .claude/hooks/on-stop.sh } ] } ] } }这段配置定义了四个生命周期节点会话启动、执行 Bash 前、写文件后、会话停止。每个节点对应一个脚本脚本放在.claude/hooks/目录下。3.2 各 hook 脚本内容创建.claude/hooks/session-start.sh作用是会话启动时自动加载项目规范#!/usr/bin/env bash # 会话启动时输出项目上下文Claude Code 会将其注入到会话中 echo 项目规范 if [ -f CLAUDE.md ]; then cat CLAUDE.md fi echo 当前分支 git branch --show-current echo 最近提交 git log --oneline -5创建.claude/hooks/pre-bash.sh作用是记录所有即将执行的 bash 命令便于审计和回溯#!/usr/bin/env bash # 从 stdin 读取 Claude Code 传入的 JSON提取命令内容 INPUT$(cat) COMMAND$(echo $INPUT | python3 -c import sys,json; print(json.load(sys.stdin).get(tool_input,{}).get(command,)) 2/dev/null) TIMESTAMP$(date %Y-%m-%d %H:%M:%S) echo [$TIMESTAMP] $COMMAND .claude/bash-audit.log创建.claude/hooks/post-edit.sh作用是每次写文件后自动格式化#!/usr/bin/env bash INPUT$(cat) FILE_PATH$(echo $INPUT | python3 -c import sys,json; print(json.load(sys.stdin).get(tool_input,{}).get(file_path,)) 2/dev/null) if [[ $FILE_PATH *.py ]]; then black $FILE_PATH 2/dev/null || true elif [[ $FILE_PATH *.js || $FILE_PATH *.ts ]]; then npx prettier --write $FILE_PATH 2/dev/null || true fi创建.claude/hooks/on-stop.sh作用是会话停止时输出提醒#!/usr/bin/env bash echo 会话已停止。当前工作目录$(pwd) echo 未提交的改动 git status --short给所有脚本加执行权限chmod x .claude/hooks/*.sh3.3 Worktree 初始化命令Worktree 的核心是给每个并行任务分配独立目录和分支。下面是一个初始化脚本放在项目根目录的scripts/new-worktree.sh#!/usr/bin/env bash # 用法bash scripts/new-worktree.sh 任务名 # 例如bash scripts/new-worktree.sh feature-login set -e TASK_NAME$1 if [ -z $TASK_NAME ]; then echo 用法bash scripts/new-worktree.sh 任务名 exit 1 fi REPO_ROOT$(git rev-parse --show-toplevel) WORKTREE_DIR$REPO_ROOT/../worktrees/$TASK_NAME BRANCH_NAMEtask/$TASK_NAME # 如果分支已存在则直接使用否则创建 if git show-ref --verify --quiet refs/heads/$BRANCH_NAME; then echo 分支 $BRANCH_NAME 已存在直接创建 worktree else git branch $BRANCH_NAME fi git worktree add $WORKTREE_DIR $BRANCH_NAME echo Worktree 创建完成$WORKTREE_DIR echo 进入目录cd $WORKTREE_DIR echo 启动 Claude Codecd $WORKTREE_DIR claude执行方式bash scripts/new-worktree.sh feature-login bash scripts/new-worktree.sh bugfix-payment执行后会在仓库同级目录的worktrees/下创建两个独立目录各自绑定task/feature-login和task/bugfix-payment分支。每个目录里都有完整的项目文件但 git 索引和分支是独立的。3.4 在 Worktree 中复用 hooks由于.claude/settings.json是项目级配置每个 Worktree 目录里都会有一份相同的配置因为文件被 git 跟踪。但 hooks 脚本里的相对路径.claude/hooks/在每个 Worktree 中都能正确解析所以不需要额外配置。这样每个并行任务都会自动拥有会话启动加载规范、bash 审计、写文件格式化、停止提醒这一整套行为。如果你希望不同 Worktree 有不同的 hooks 行为可以在各自目录里修改.claude/settings.json但要注意这会导致 git 冲突。更推荐的做法是通过环境变量区分比如在脚本里读取WORKTREE_NAME变量做条件分支。4. 验证请求确认 hooks 与 Worktree 自动化真的生效配置写完了但怎么确认它真的在工作这一节给出具体的验证步骤每一步都有可观察的输出。4.1 验证 hooks 是否被加载进入任意一个 Worktree 目录启动 Claude Codecd ../worktrees/feature-login claude会话启动后观察终端输出。如果session-start.sh生效你应该能看到类似这样的内容 项目规范 CLAUDE.md 的内容 当前分支 task/feature-login 最近提交 abc1234 初始化项目如果没看到这些输出说明 hooks 没有被加载。检查两个地方一是.claude/settings.json的 JSON 格式是否正确可以用python3 -m json.tool .claude/settings.json验证二是脚本是否有执行权限用ls -l .claude/hooks/确认。4.2 验证 PreToolUse 审计日志在 Claude Code 会话中让它执行一条 bash 命令比如请执行 git status执行完成后退出会话查看审计日志cat .claude/bash-audit.log如果看到类似[2025-01-15 10:30:22] git status的记录说明 PreToolUse hook 生效了。每条 Claude Code 执行的 bash 命令都会被记录这在多任务并行时特别有用你可以通过日志追溯哪个 Worktree 执行了什么操作。4.3 验证 PostToolUse 自动格式化在会话中让 Claude Code 创建一个 Python 文件请创建 test_format.py内容是一个故意格式混乱的函数创建完成后查看文件内容cat test_format.py如果black已安装且 hook 生效文件应该已经被格式化成符合 PEP8 的样式。如果没变化检查black是否在 PATH 中可以用which black确认。4.4 验证 Worktree 隔离性这是最关键的一步。在两个 Worktree 中分别创建文件确认互不影响# 在 feature-login 中 cd ../worktrees/feature-login echo login feature feature.txt git add feature.txt git commit -m add login feature # 在 bugfix-payment 中 cd ../worktrees/bugfix-payment ls feature.txt如果ls feature.txt报错说文件不存在说明隔离生效了。bugfix-payment的工作目录里看不到feature-login的改动两个 Agent 的上下文不会互相污染。再验证分支独立性cd ../worktrees/feature-login git branch --show-current cd ../worktrees/bugfix-payment git branch --show-current应该分别输出task/feature-login和task/bugfix-payment。4.5 验证 Stop hook在 Claude Code 会话中按 CtrlC 或输入退出命令观察终端是否输出会话已停止。当前工作目录/path/to/worktrees/feature-login 未提交的改动 git status 的简短输出如果看到这些说明 Stop hook 生效。这个功能在多任务场景下很有用你可以在每个 Worktree 退出时快速确认有没有遗漏的未提交改动。4.6 用 API 直接验证模型连通性如果 hooks 都正常但 Claude Code 调用模型报错可以绕过 Claude Code 直接用 curl 测试 TaoToken 的连通性curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-6, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }如果返回包含choices的 JSON说明 API 层没问题问题出在 Claude Code 的配置或 hooks 脚本上。如果返回 401说明 Key 无效或没正确传入。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易卡住的几个报错这里逐一给出原因和解决方式。5.1 401 Unauthorized这是最常见的错误表现为 Claude Code 启动后立即报 401或者调用模型时返回{error:{message:Invalid API key}}。原因通常有三个一是ANTHROPIC_API_KEY环境变量没设置或拼写错误二是 Key 已经过期或被删除三是 Base URL 写错了比如漏了/api路径。排查步骤# 确认环境变量 echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL # 直接用 curl 测试 curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $ANTHROPIC_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-6,messages:[{role:user,content:hi}],max_tokens:5}如果 curl 成功但 Claude Code 报 401说明 Claude Code 没有读到环境变量。检查你的 shell 配置文件是否被正确加载或者尝试在启动 Claude Code 时显式传入ANTHROPIC_API_KEYsk-你的Key ANTHROPIC_BASE_URLhttps://taotoken.net/api claude5.2 local proxy failed这个报错通常出现在 Claude Code 尝试连接本地代理时。表现为Error: local proxy failed to start或connect ECONNREFUSED 127.0.0.1:xxxx。原因是 Claude Code 默认会启动一个本地代理来转发请求如果端口被占用或代理配置冲突就会失败。解决方式是检查是否有其他进程占用了 Claude Code 需要的端口或者显式禁用本地代理export ANTHROPIC_DISABLE_PROXY1另外确认你的HTTP_PROXY和HTTPS_PROXY环境变量没有指向一个不可用的地址。如果有先 unsetunset HTTP_PROXY unset HTTPS_PROXY5.3 reading choices 报错这个报错完整形式通常是Cannot read properties of undefined (reading choices)意思是代码期望响应里有choices字段但实际返回的结构不对。原因一般是 API 返回了错误信息而不是正常的 completion 结果。比如 Key 无效时返回{error:{...}}没有choices字段Claude Code 解析时就报这个错。排查方式是先用 curl 看原始响应curl -s -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $ANTHROPIC_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-6,messages:[{role:user,content:hi}],max_tokens:5} | python3 -m json.tool如果返回里有error字段根据错误信息处理。如果是model not found说明 Model ID 写错了去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 核对正确的 Model ID。5.4 OAuth 相关报错Claude Code 某些版本会尝试 OAuth 流程如果你用的是 API Key 模式可能会看到OAuth token expired或Failed to refresh OAuth token。解决方式是明确告诉 Claude Code 使用 API Key 而不是 OAuth。设置export ANTHROPIC_AUTH_MODEapi_key如果这个变量不生效检查 Claude Code 版本旧版本可能不支持。升级到最新版npm update -g anthropic-ai/claude-code5.5 hooks 脚本不执行如果配置了 hooks 但脚本没被调用先确认脚本有执行权限ls -l .claude/hooks/每个脚本应该有x权限。如果没有执行chmod x .claude/hooks/*.sh。其次确认.claude/settings.json的 JSON 格式正确python3 -m json.tool .claude/settings.json如果报 JSON 解析错误根据提示修复。常见问题是多了逗号或少了引号。最后确认 Claude Code 的工作目录是项目根目录。hooks 配置是相对于项目根目录解析的如果你在子目录启动 Claude Code可能找不到.claude/settings.json。5.6 Worktree 创建失败执行git worktree add时报错fatal: branch is already checked out说明该分支已经在另一个 Worktree 中被检出。Git 不允许同一个分支在多个 Worktree 中同时检出。解决方式是给新任务用新分支或者先移除旧的 Worktreegit worktree list git worktree remove ../worktrees/旧任务名如果报错fatal: invalid reference说明分支不存在。先创建分支再创建 Worktree或者直接用-b参数git worktree add -b task/新任务 ../worktrees/新任务6. 把并行 Agent 真正跑起来从配置到日常协作配置和验证都通过之后日常使用其实很简单。每个新任务执行一次bash scripts/new-worktree.sh 任务名然后cd进去启动 Claude Code。hooks 会自动加载项目规范、记录 bash 命令、格式化写文件、退出时提醒未提交改动。多任务并行时你可以同时开三个终端分别进入三个 Worktree让三个 Agent 处理不同任务。它们共享同一个 git 仓库的对象库但工作目录和分支完全隔离不会互相干扰。需要合并时正常走 git merge 或 PR 流程即可。如果任务规模很大比如要迁移几百个文件的 API 调用可以结合批量思路先用一个 Worktree 做样板改造确认模式后把文件列表拆分成多份每份分配给一个 Worktree 的 Agent 并行处理。每个 Agent 的 hooks 审计日志会记录它执行的所有命令方便事后回溯。模型选择上日常编码任务用claude-sonnet-4-6就够响应快、成本可控。遇到复杂重构或架构设计再切到claude-opus-4-6。切换方式就是改环境变量ANTHROPIC_MODEL或者在 TaoToken 控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 查看当前可用的模型和配额。如果你还没有 API Key去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys 创建一个。需要长期跑编码 Agent 的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan 的配额更适合高频调用。想先试试模型对话效果可以直接在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchat 里体验。最后提醒一点hooks 脚本里的命令是在你的本地环境执行的写脚本时注意不要引入不安全的操作。审计日志会记录所有 bash 命令定期检查这个日志既能发现 Agent 的异常行为也能帮你回顾整个任务的执行轨迹。