1. Codex 多工作树协作永久工作树、派生与分叉到底差在哪Codex 这类 AI 编程客户端把 Git 的 worktree 概念搬进了会话管理解决的是一个很具体的痛点让 AI 改代码时既能多任务并行又不会把主仓库搅乱。我试过同时开三个会话改同一个项目一个修紧急 Bug、一个写新功能、一个做重构实验如果没有工作树隔离三个会话的文件读写会互相覆盖最后连 git status 都看不懂。先把三个概念用一句话钉死后面所有操作都围绕它们展开创建永久工作树是项目级操作在本地硬盘上真正生成一个独立的 Git 工作区目录长期存在直到你手动移除。派生到本地是会话级操作以当前对话历史为基础在当前目录切出新方向AI 的改动直接落在你正在编辑的文件上。派生到新工作树同样是会话级操作但会同时开辟一个干净的隔离目录AI 的所有读写和命令都在里面跑。分叉是最细粒度的消息级操作从 AI 某一步执行历史切出平行分支把后面的错误步骤甩掉。适合谁用如果你只是偶尔让 AI 补个函数用不上这些。但只要你开始让 Codex 连续做多步改动、或者同时推进两条以上开发线工作树和派生就是必须掌握的隔离手段。下面我会先讲清楚三者的边界再把 Codex 的 auth.json 鉴权入口改到 TaoToken 统一通道最后给出验证隔离是否生效的检查动作。核心检索词先明确Codex 工作树、派生到新工作树、分叉 Fork、auth.json 配置、Git worktree 隔离。这几个词贯穿全文你按需跳读即可。Git worktree 本身的机制值得先补一句。普通 git clone 是把整个仓库复制一份占双倍磁盘、双份 .git。worktree 则是共享同一个 .git 对象库只额外检出工作区文件所以创建快、省空间分支之间互不干扰。Codex 的「永久工作树」本质就是帮你执行了git worktree add只是把它包装成了右键菜单。理解这一点很关键永久工作树对应的是 Git 层面的物理隔离派生到新工作树对应的是「会话 物理隔离」分叉对应的是「会话历史层面的逻辑隔离」。三者粒度从粗到细用途完全不同。很多人混淆是因为它们都带「新」字但一个动磁盘、一个动会话、一个动历史节点。2. TaoToken 前置把 Codex auth.json 的鉴权入口统一到一条通道在动工作树之前先把鉴权理顺否则你派生出一堆工作树每个都因为 Key 问题报 401排查起来会疯。Codex 的鉴权信息默认写在 auth.json 里路径通常在用户配置目录下Linux/macOS 一般是~/.codex/auth.jsonWindows 在%USERPROFILE%\.codex\auth.json。这个文件决定了 Codex 请求往哪个 Base URL 发、用哪个 Key、调哪个 Model ID。TaoToken 在这里扮演的角色是统一 API 通道你不需要为每个模型单独申请 Key也不用在不同客户端之间来回切换配置。官网入口 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置里填干净的这个就行。为什么要在工作树场景下特别强调鉴权统一因为 Codex 的每个工作树会话理论上会读取同一份 auth.json。如果你在派生到新工作树之后发现新目录里的请求失败第一反应往往是「工作树没建好」但实际八成是 auth.json 路径或 Key 没生效。把鉴权入口先固定到 TaoToken后面所有工作树共享同一套凭证隔离的是文件而不是配置排查维度就少了一个。拿 Key 的路径进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建。创建时建议按用途命名比如codex-worktree-main、codex-fork-experiment这样后面哪个工作树出问题你能快速定位是哪把 Key。Key 只在创建时完整显示一次复制后立刻存到密码管理器。模型 ID 这块Codex 配置里需要填具体的模型标识。你可以在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先确认当前可用的模型名再写进 auth.json。不要凭记忆填模型 ID 拼错会直接报 model not found而且报错信息不一定直白。如果你打算长期跑编码任务或者 Agent 类工作流Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 有更细的额度说明适合多工作树并行消耗的场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段有疑问时以文档为准。前置工作就三件拿到 Key、确认 Model ID、知道 auth.json 在哪。做完这三件再进下一节改配置。3. 可复制配置auth.json 片段与工作树创建/派生命令这一节全是能直接抄的东西。先给 auth.json 的配置片段再给 Git 工作树的创建和派生命令最后用对照表把三者边界钉死。3.1 auth.json 配置片段Codex 的 auth.json 结构大致如下把 Base URL、Key、Model ID 三件套填进去{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: 你的模型ID, provider: openai-compatible }路径确认Linux/macOS 是~/.codex/auth.jsonWindows 是%USERPROFILE%\.codex\auth.json。如果目录不存在先手动创建.codex文件夹。改完保存不要留尾随逗号JSON 对格式很敏感。如果你用的是 TOML 风格的配置部分 Codex 版本支持对应写法[provider] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model 你的模型ID注意 base_url 结尾不要多加/v1除非接入文档明确要求。多写一层路径会导致 404而且报错信息经常只显示 not found不告诉你是路径问题。3.2 永久工作树创建命令在项目根目录执行给项目加一个长期并行的第二工作区# 在项目根目录执行创建名为 feature-experiment 的工作树 git worktree add ../myproject-feature-experiment -b feature/experiment # 查看当前所有工作树 git worktree list # 用完手动移除不会删分支 git worktree remove ../myproject-feature-experimentgit worktree add的第一个参数是新工作区的路径-b指定新分支名。执行完你会看到硬盘上真的多了一个目录里面有完整的项目文件但.git是指向主仓库的引用文件不是完整副本。这就是「永久」的含义它一直在直到你git worktree remove。3.3 派生到本地 vs 派生到新工作树这两个是 Codex 会话菜单里的操作底层对应不同的 Git 行为# 派生到本地本质是在当前分支继续不新建目录 # Codex 界面操作无独立命令效果等同于在当前 worktree 继续 commit # 派生到新工作树Codex 会帮你执行类似下面的命令 git worktree add ../myproject-fork-$(date %s) -b fork/experiment-$(date %s)派生到本地时AI 的改动直接进你当前打开的文件git status立刻能看到变化。派生到新工作树时Codex 在后台建了一个隔离目录AI 在里面随便折腾你当前目录纹丝不动。3.4 三者对照表维度创建永久工作树派生到本地派生到新工作树分叉 Fork操作层级项目级会话级会话级消息级是否新建磁盘目录是否是否是否复制对话历史否是是从指定节点起AI 改动落点新目录当前目录新隔离目录新对话分支典型用途长期双线开发当前方向微调激进实验/重构回退错误步骤隔离强度物理隔离无隔离物理隔离逻辑隔离这张表建议截图存着。实际用的时候先问自己「我要隔离的是文件、会话还是历史节点」答案直接对应到某一列。3.5 分叉 Fork 的操作位置分叉不在项目菜单也不在会话菜单而是鼠标悬停在 AI 某一步执行历史的消息卡片上时出现的图标。点它Codex 会从那一秒的状态切出新对话分支后面的错误步骤留在旧分支。这个操作不新建目录、不复制整个会话只复制到分叉点为止的上下文。4. 验证请求确认鉴权生效与工作树隔离是否真的起作用配置改完、工作树建完别急着让 AI 干活先做两组验证。第一组验证鉴权通道通不通第二组验证工作树隔离是否真的生效。4.1 验证鉴权最直接的方式是在 Codex 里发一条最小请求比如让它读一个文件并返回第一行。如果 auth.json 配置正确你会看到正常返回如果报 401说明 Key 或 Base URL 有问题。也可以用 curl 直接打 TaoToken 的 API 端点绕过 Codex 客户端单独确认通道curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: ping}], max_tokens: 10 }返回里如果有choices字段和正常内容说明 Key、Base URL、Model ID 三件套都对。如果返回 401检查 Key 是否复制完整、有没有多余空格。如果返回 model not found回模型对话页面核对 Model ID 拼写。4.2 验证工作树隔离隔离验证的核心动作在派生出的新工作树里让 AI 改一个文件然后回主工作树看那个文件有没有被动过。# 在主工作树查看当前状态 cd ~/myproject git status # 切到派生出的新工作树 cd ~/myproject-fork-1234567890 git status # 在新工作树里改一个文件 echo # test isolation README.md git status # 回主工作树确认 README.md 未被修改 cd ~/myproject git status如果主工作树的git status显示 README.md 没有变化说明隔离生效。如果主工作树也出现了改动那要么你派生到了本地而不是新工作树要么两个目录指向了同一个 worktree。再补一个检查git worktree list会列出所有工作树及其对应分支。确认新工作树的分支名和主工作树不同且路径是独立的。4.3 验证分叉分叉的验证稍微抽象一点。让 AI 连续做三步改动在第三步之后点分叉回到第二步然后看新分支的对话历史里第三步是否消失。如果新分支从第二步重新开始且旧分支仍保留完整三步说明分叉生效。这一步不需要命令行纯界面操作但建议在测试项目上先练一遍别拿生产代码试。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。每个报错给出触发场景和排查顺序你对着自己的终端输出找。5.1 401 Unauthorized触发场景auth.json 里 Key 写错、Key 被撤销、Base URL 指向了需要不同鉴权方式的端点。排查顺序先确认 auth.json 路径对不对Codex 读的是不是你改的那份。然后确认 Key 没有多余空格或换行。再用上面的 curl 命令单独测通道。如果 curl 通但 Codex 报 401说明 Codex 读的 auth.json 不是你改的那份检查是否有多个配置目录。5.2 local proxy failed触发场景Codex 配置了本地代理端口但代理进程没起来或者端口被占用。排查顺序检查 auth.json 里有没有 proxy 相关字段如果有确认代理服务在运行。如果不需要代理把 proxy 字段删掉让请求直连 Base URL。这个报错和工作树无关但多工作树并行时容易因为端口冲突触发。5.3 reading choices 相关报错触发场景API 返回结构不符合 Codex 预期常见于 Base URL 路径写错、Model ID 不存在、或者返回了错误对象而非正常响应。排查顺序先用 curl 确认返回里有choices数组。如果没有看返回的 error 字段写了什么。如果是 model not found核对 Model ID。如果是路径 404检查 base_url 是否多写了/v1。5.4 OAuth 相关报错触发场景Codex 尝试走 OAuth 流程但配置里写的是 API Key 模式或者反过来。排查顺序确认 auth.json 里的 provider 字段和你的鉴权方式匹配。用 API Key 就填openai-compatible之类的值不要留 OAuth 相关字段。如果之前登录过 OAuth清掉旧的 token 字段避免 Codex 优先读旧凭证。5.5 工作树相关报错fatal: xxx is already checked out同一个分支不能在两个工作树同时检出。给新工作树换个分支名。fatal: invalid reference-b指定的分支名不合法或者基础分支不存在。先git branch确认当前分支。git worktree remove报 dirty工作树里有未提交改动。先 commit 或 stash再 remove或者加--force。排查时记住一个原则鉴权报错先测 curl工作树报错先看git worktree list。两条线分开查不要混在一起猜。6. 把工作树和鉴权通道固定成你的默认工作流走到这里你应该已经能把三个概念分清楚了。最后给一套我实际在用的固定动作你直接套。新项目上手时先建一个永久工作树专门跑实验性改动主工作树保持干净只做 review 和合并。这样 AI 在主工作树里只做小修小补大改动全丢到实验工作树出问题直接git worktree remove删掉主分支零污染。会话层面需要 AI 做激进重构时一律用「派生到新工作树」不要用「派生到本地」。派生到本地适合的是「在当前方向上再改两行」这种小动作。分叉留给「AI 某一步改错了」的场景回退到正确节点重新引导比推翻重来省时间。鉴权层面auth.json 只维护一份所有工作树共享。Key 按用途命名方便排查。Base URL 固定填 https://taotoken.net/api Model ID 从模型对话页面确认后再写。需要长期跑编码任务时去 Coding Plan 页面看额度说明避免多工作树并行时额度不够用。配置字段有疑问就翻接入文档不要凭记忆改。API Keys 在控制台管理定期清理不用的 Key。这套流程跑顺之后多工作树协作会变成很自然的操作而不是需要反复查文档的事。