1. 从旧会话 fork 进 worktree 卡在创建子线程问题到底出在哪如果你正在做 AI 编码助手、会话式 Agent 或者任何带「从上一轮对话继续」功能的产品大概率会遇到这个场景用户点一下「从这轮对话 fork 出一个新工作区」程序需要把当前会话状态复制一份切到一个独立的 git worktree 里继续跑。听起来很干净但实际跑起来进程会在「还没真正创建子线程」的地方直接卡死日志停在creating child thread之前CPU 不飙、内存不涨就是不动。这个现象在社区里被反复报告过典型描述是「Fork from earlier turn into worktree stalls before creating child thread」。它的根因不在 worktree也不在 git而在fork()本身。POSIX 的fork()有一个非常容易被忽略的语义子进程只复制「调用 fork 的那个线程」父进程里其它线程不会出现在子进程中。但内存是整块复制的包括锁的状态。于是就会出现一种致命组合——父进程里线程 A 正持有一把全局锁 L主线程此时调用fork()子进程里 L 的状态是「已锁定」可持有它的线程 A 根本不存在于子进程。子进程后面任何想L.lock()的代码都会永远等下去。这就是为什么卡点总是出现在「创建子线程之前」创建线程、切目录、初始化日志、import 模块这些动作背后都可能去拿某把锁。锁是悬空的等待就是永久的。本文会把这个根因拆开讲清楚并给出四种可落地的规避方案配合最小复现脚本和真实报错排查让你能直接定位自己项目里的阻塞点。适合正在做会话 fork、worktree 隔离、多进程 Agent 调度的开发者。2. TaoToken 统一 Key 通道fork 场景下的前置准备在讲 fork 与线程安全之前先把「模型调用通道」这件事理顺。因为 fork 进 worktree 之后新工作区里的子进程通常还要继续调用大模型完成编码任务如果每个 worktree、每个子进程都各自维护一套 Key 和 Base URL排查 fork 卡死的时候你会被两件事同时干扰到底是 fork 死锁还是 Key 配错了。所以我的做法是先把模型通道统一成一条再专心排 fork。TaoToken 在这里扮演的就是「统一 Key 通道」的角色。它提供兼容 OpenAI 风格的接口你只需要一个 API Key 和一个 Base URL就能在父会话、fork 出来的子进程、worktree 里的 worker 之间共用同一套凭证。这样 fork 排查时模型调用层是稳定的常量变量只剩进程模型本身。具体来说你需要准备三样东西我把它称为「三件套」配置项值说明Base URLhttps://taotoken.net/api兼容 OpenAI 的接口地址注意不要带 UTM 参数API Key在控制台创建统一 Key父子进程共用Model ID按需选择例如编码场景常用的模型标识获取 Key 的入口在控制台创建后复制一次即可。如果你用的是 Claude Code 这类工具或者 Cline、Codex 这类需要写配置文件的客户端三件套要写全Base URL、Key、Model ID 一个都不能少缺一个就会出现 401 或者模型找不到的报错和 fork 死锁混在一起非常难查。提示把 Key 放在环境变量里而不是硬编码进 fork 出来的子进程参数。子进程通过os.environ继承既统一又不会因为序列化状态文件而泄露。统一通道之后fork 排查的边界就清晰了模型调用是通的卡住一定是进程模型的问题。这一步看起来和 fork 无关但它决定了你后面能不能快速收敛问题。3. 可复制配置worktree 初始化参数与 spawn 启动片段这一节给你可以直接抄的配置。核心思路是不要用 fork 复制多线程进程改用 spawn 启动全新进程状态通过文件传递。下面分三块会话状态文件、worktree 初始化参数、以及 spawn 启动片段。先看会话状态文件。fork 的本质需求是「把旧会话的状态带到新工作区」那就把它序列化成 JSON而不是靠内存复制{ session_id: sess_20241024_001, parent_turn: 12, worktree_path: /repo/.worktrees/feat-login, branch: feat/login, base_url: https://taotoken.net/api, model_id: your-model-id, messages: [ {role: user, content: 继续实现登录校验}, {role: assistant, content: 好的我先看下现有中间件} ] }注意这里没有放 API KeyKey 走环境变量。状态文件只放「可序列化、可传递」的业务数据。再看 worktree 初始化参数。git worktree 的创建本身是子进程调用和 fork 死锁无关但参数要写对否则新工作区起不来会伪装成「卡住」git worktree add /repo/.worktrees/feat-login -b feat/login origin/main如果你希望 worktree 基于当前会话所在的分支而不是 maingit worktree add /repo/.worktrees/feat-login -b feat/login HEAD关键参数说明add后面第一个是路径-b指定新分支名最后一个参数是起点。路径建议统一放在.worktrees/下并加进.gitignore避免污染主工作区。最后是 spawn 启动片段。这是替代 fork 的核心用multiprocessing显式指定 spawnimport multiprocessing as mp import json import os def worktree_worker(state_path, worktree_path): with open(state_path, r, encodingutf-8) as f: state json.load(f) os.chdir(worktree_path) # 这里可以安全地创建子线程、调用模型 print(worker started in, worktree_path) if __name__ __main__: ctx mp.get_context(spawn) p ctx.Process( targetworktree_worker, args(/tmp/session_state.json, /repo/.worktrees/feat-login), ) p.start() p.join()get_context(spawn)是关键。spawn 会重新 import 主模块、重建进程不会继承父进程的多线程锁状态所以子进程里创建线程、加锁都是安全的。macOS 和 Windows 默认就是 spawnLinux 默认是 fork所以显式指定 spawn 才能跨平台一致。如果你用的是 Claude Code 或 Cline 这类带 MCP 配置的工具配置文件里同样要写全三件套。以 MCP 的 JSON 配置为例{ mcpServers: { worktree-agent: { command: python, args: [-m, myapp.worktree_worker], env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: ${TAOTOKEN_API_KEY}, OPENAI_MODEL: your-model-id } } } }Base URL、Key、Model ID 三件套齐全子进程启动后模型调用才不会报错。Codex 的auth.json同理把 base URL 和 key 写进去模型 ID 在配置里指定。4. 验证请求最小复现脚本与成功结果光看配置不够得能复现问题、也能验证修复。先给你一个最小复现脚本它能在几秒内稳定卡死让你亲眼看到 fork 悬空锁import os import threading import time lock threading.Lock() def holder(): with lock: time.sleep(1000) def child_wants_lock(): lock.acquire() print(child got lock (never reached)) lock.release() if __name__ __main__: t threading.Thread(targetholder, daemonTrue) t.start() time.sleep(0.1) pid os.fork() if pid 0: child_wants_lock() else: print(parent continues) time.sleep(2) print(child should be stuck)运行后你会看到父进程打印parent continues然后子进程永远停在lock.acquire()。这就是 fork 悬空锁的完整复现。注意holder线程持有锁后 sleep主线程 fork子进程里锁是「已锁定」但持有者不存在。现在验证修复方案。把上面的 fork 换成 spawnimport multiprocessing as mp import threading import time def worker(): lock threading.Lock() with lock: print(worker acquired its own lock, no deadlock) print(worker done) if __name__ __main__: ctx mp.get_context(spawn) p ctx.Process(targetworker) p.start() p.join() print(parent done)运行结果应该是worker acquired its own lock, no deadlock worker done parent done子进程里的锁是它自己新建的和父进程没有任何共享所以不会死锁。这就是 spawn 方案的核心价值。再验证模型通道是否通。在 worker 里加一段调用import os from openai import OpenAI client OpenAI( base_urlos.environ[OPENAI_BASE_URL], api_keyos.environ[OPENAI_API_KEY], ) resp client.chat.completions.create( modelos.environ[OPENAI_MODEL], messages[{role: user, content: ping}], ) print(resp.choices[0].message.content)如果返回正常内容说明 fork 修复和模型通道都通了。如果这里报错先看第 5 节的排查清单别急着怀疑 fork。5. 本篇常见错排查401、local proxy failed、reading choices、OAuthfork 场景下的报错经常混在一起我按真实遇到过的顺序列出来你对照日志定位。401 Unauthorized。这几乎都是 Key 没传进子进程。spawn 启动的新进程不会自动继承你 shell 里临时 export 的变量必须在启动前确保环境变量已经写入。检查方式在 worker 第一行打印os.environ.get(OPENAI_API_KEY)是否存在。如果为空说明父进程启动时没带上或者用了env参数但拼错了键名。三件套里 Key 是最容易漏的。local proxy failed。这个报错通常出现在客户端配置了本地代理端口但代理没起来或者 Base URL 写成了本地地址。如果你用的是统一通道Base URL 应该是https://taotoken.net/api不要写成http://localhost:xxxx。另外检查环境里有没有残留的HTTP_PROXY、HTTPS_PROXY指向一个不存在的本地端口spawn 出来的子进程会继承这些变量导致请求发不出去。reading choices 相关报错。典型形式是KeyError: choices或者reading choices of undefined。这说明请求发出去了但返回体不是预期的 OpenAI 格式。常见原因有两个一是 Model ID 写错服务端返回了错误对象而不是补全结果二是 Base URL 少了/api或者多了斜杠。先打印完整响应体再解析不要直接取choices。OAuth 相关报错。如果你用的是 Claude Code 这类走 OAuth 的工具fork 出来的子进程可能拿不到父进程的登录态。OAuth token 通常存在用户目录下的凭证文件里spawn 的新进程如果换了 HOME 或者工作目录就找不到。解决办法是把凭证路径通过环境变量显式传给子进程或者改用 API Key 方式三件套写全绕开 OAuth 的会话依赖。卡在创建子线程之前但没有任何报错。这就是本文的主线问题fork 悬空锁。特征是没有异常、没有超时、CPU 空闲。排查方法在 fork 前后各打一条日志如果 fork 后、创建线程前的日志没出来基本可以确认。用py-spy dump --pid 子进程pid能看到它停在某个lock.acquire()上。注意不要用strace去追锁输出量太大。优先用py-spy或者直接在可疑的加锁点前后加日志。把这几类报错分开之后你会发现真正和 fork 相关的只有最后一类其余都是配置问题。先修配置再修进程模型顺序不要反。6. 长期编码与 Agent 场景把统一通道和 spawn 固化下来如果你只是偶尔 fork 一次上面的方案够用了。但如果你在做长期的编码 Agent、多 worktree 并行开发就需要把「统一 Key 通道 spawn 启动」固化成工程习惯否则每次加功能都会重新踩一遍。第一件事把模型通道收敛到一个配置模块。所有进程不管是父会话还是 worktree worker都从这个模块读 Base URL、Key、Model ID。这样 fork 排查时你永远知道模型层是稳定的。TaoToken 的兼容接口在这里的好处是你不需要为不同客户端维护不同的 SDK 适配一套 OpenAI 风格调用走到底。第二件事把「禁止在多线程态 fork」写进代码规范。可以在项目里加一个检查调用os.fork()之前断言当前线程数等于 1。如果团队里有人不小心在后台线程跑着的时候 fork测试阶段就能拦住。第三件事worktree 的生命周期和进程生命周期解耦。worktree 是磁盘上的目录进程是内存里的执行体两者不要绑死。spawn 出来的 worker 干完活就退出worktree 保留下次可以再 spawn 一个新 worker 进去。这样即使某个 worker 崩了也不会留下悬空锁影响下一次。第四件事日志里带上pid和thread name。fork 死锁最难查的地方就是「不知道是哪个线程持有的锁」。日志里带上这两个字段配合py-spy定位速度会快很多。我实测下来把这几条固化之后fork 进 worktree 的卡死问题基本不再出现。真正剩下的报错都是配置类按第 5 节清单几分钟就能解决。如果你还在用 fork 复制多线程会话状态建议尽早换成 spawn状态走文件传递这是投入产出比最高的一次重构。需要统一 Key 通道的话可以从控制台创建 Key接入文档里有各客户端的完整配置示例想先验证模型是否通直接用模型对话跑一条 ping 最快如果是长期编码或 Agent 场景Coding Plan 更适合把通道和额度一起管起来。