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 排查时，模型调用层是稳定的常量，变量只剩进程模型本身。

具体来说，你需要准备三样东西，我把它称为「三件套」：

获取 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 Key，Key 走环境变量。状态文件只放「可序列化、可传递」的业务数据。

再看 worktree 初始化参数。git worktree 的创建本身是子进程调用，和 fork 死锁无关，但参数要写对，否则新工作区起不来会伪装成「卡住」：

git worktree add /repo/.worktrees/feat-login -b feat/login origin/main

如果你希望 worktree 基于当前会话所在的分支，而不是 main：

git worktree add /repo/.worktrees/feat-login -b feat/login HEAD

关键参数说明：add后面第一个是路径，-b指定新分支名，最后一个参数是起点。路径建议统一放在.worktrees/下并加进.gitignore，避免污染主工作区。

最后是 spawn 启动片段。这是替代 fork 的核心，用multiprocessing显式指定 spawn：

import multiprocessing as mp import json import os def worktree_worker(state_path, worktree_path): with open(state_path, "r", encoding="utf-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( target=worktree_worker, args=("/tmp/session_state.json", "/repo/.worktrees/feat-login"), ) p.start() p.join()

get_context("spawn")是关键。spawn 会重新 import 主模块、重建进程，不会继承父进程的多线程锁状态，所以子进程里创建线程、加锁都是安全的。macOS 和 Windows 默认就是 spawn，Linux 默认是 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(target=holder, daemon=True) 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 换成 spawn：

import 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(target=worker) 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_url=os.environ["OPENAI_BASE_URL"], api_key=os.environ["OPENAI_API_KEY"], ) resp = client.chat.completions.create( model=os.environ["OPENAI_MODEL"], messages=[{"role": "user", "content": "ping"}], ) print(resp.choices[0].message.content)

如果返回正常内容，说明 fork 修复和模型通道都通了。如果这里报错，先看第 5 节的排查清单，别急着怀疑 fork。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

fork 场景下的报错经常混在一起，我按真实遇到过的顺序列出来，你对照日志定位。

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 更适合把通道和额度一起管起来。