1. Codex 报错 local proxy failed 到底卡在哪一步你大概率是在 VS Code 或者终端里跑 Codex本来对话好好的突然某次切到 git worktree 目录之后请求就挂了日志里蹦出一行local proxy failed。这个报错字面意思是「本地代理失败」但它跟网络代理没有半点关系它说的是 Codex CLI 自己起的一个本地转发层没跑起来或者跑起来了但拿不到可用的上游凭证。先把 Codex 的调用链拆开看。Codex 这类编码 Agent 在本地运行时通常有三层最上面是你敲命令的 CLI 或 IDE 插件中间是它自己维护的一个本地服务进程负责拼请求、管会话、做流式转发最底下才是真正发往模型 API 的出口。local proxy failed报的是中间那层。它失败的原因无非两类一是本地服务进程根本没起来端口被占、进程残留、权限问题二是进程起来了但它读不到有效的鉴权配置于是每次转发都在出口处被拒CLI 把这种「转发层无法完成一次完整请求」统一报成 local proxy failed。那为什么偏偏在 git worktree 场景下高发因为 Codex 读取配置的路径很多版本是跟「当前工作目录」或「项目根」绑定的。你git worktree add出一个新目录它是个全新的检出路径.codex/或者用户级的~/.codex/auth.json如果没被正确继承Codex 在新目录里就相当于一个没配钥匙的新人。它照样尝试起本地转发但转发时找不到 Key于是报错。很多人第一反应是「我网络是不是被墙了」然后去折腾网络设置方向完全错了。我试过在一个 monorepo 里同时开三个 worktree 并行改不同模块结果只有主工作树能正常调 Codex另外两个一律 local proxy failed。当时排查了半天网络最后cat ~/.codex/auth.json才发现问题根本不在网络上——是配置读取路径的事。这个坑很典型所以这篇就按「先定位配置、再统一通道、最后逐步验证」的顺序讲清楚。你需要先建立一个判断local proxy failed 出现时先别动网络先确认三件事——Codex 进程在不在、auth.json 读的是哪一份、当前 worktree 目录下有没有覆盖配置。这三件事查完八成问题就定位了。下面第二节先讲怎么把 Key 和 API 通道统一到一处从根上消掉「换个目录就失效」的问题。2. 用 TaoToken 统一 Key 与 API 通道的前置准备Codex 在 worktree 里报 local proxy failed本质是「配置漂移」主目录有一份能用的凭证新 worktree 读不到或者读到了旧版本。要根治思路不是每个 worktree 都手动配一遍而是把凭证收敛到一个全局位置让所有工作树都指向同一份。TaoToken 在这里扮演的角色是给你一个统一的 API 出口和一把统一的 Key。你不需要在每个项目、每个 worktree 里维护不同的上游地址和密钥只要让 Codex 的 auth.json 指向 TaoToken 的 API 地址、填上同一把 Key那么无论你在哪个 worktree 目录下运行读到的都是同一套可用配置。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 出口是 https://taotoken.net/api 注意 API 地址不带任何查询参数配置里就写这个干净的地址。前置准备分三步。第一步拿到 Key。进控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建完先复制存好后面 auth.json 要用。第二步确认你要用的模型 ID。Codex 这类工具通常需要显式指定模型你在模型对话页可以先确认可用模型地址 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 把模型 ID 记下来比如常见的编码模型标识。第三步确认 Codex 版本和它的配置读取规则。不同版本的 Codex 对 auth.json 的字段名要求不完全一样有的用OPENAI_API_KEY有的用api_key有的还要求base_url。你得先codex --version看一眼再决定字段怎么写。这里有个关键认知auth.json 不是「配一次就永远对」的文件。Codex 升级、你换机器、你新建 worktree都可能让它读不到。所以正确做法是把它放在用户级目录通常是~/.codex/auth.json而不是项目级目录。用户级目录对所有 worktree 都可见项目级目录只对当前检出有效。很多人图省事在项目里放一份结果一开 worktree 就失效就是这个原因。另外提醒一句TaoToken 是合规的 API 接入服务配置时只填官方给的 API 地址和 Key 即可不要在里面塞任何来路不明的转发地址。你如果之前配过别的地址先把 auth.json 备份一份再改避免改坏了回不去。备份命令很简单cp ~/.codex/auth.json ~/.codex/auth.json.bak。这一步花十秒能省后面半小时。准备好 Key、模型 ID、确认好 Codex 版本之后就可以进入第三节直接改 auth.json 了。第三节给的是可复制片段你照着填自己的 Key 和模型 ID 就行。3. 可复制的 auth.json 配置片段与 worktree 适配这一节是全文最核心的操作部分。Codex 的 auth.json 通常长这样字段名以你本地版本为准下面给的是最常见的一种结构。路径固定用用户级的~/.codex/auth.json这样所有 worktree 都能读到同一份。{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api, model: 你的模型ID, provider: openai }如果你的 Codex 版本用的是下划线风格或者嵌套结构参考这个变体{ api_key: sk-你的TaoToken密钥, base_url: https://taotoken.net/api, default_model: 你的模型ID }两个片段的核心就三样Base URL 填https://taotoken.net/apiKey 填你在控制台创建的那把Model ID 填你在模型页确认的标识。这三件套缺一不可尤其 Base URL很多人只填 Key 不填地址Codex 就默认往官方地址发结果 Key 对不上照样 local proxy failed。改完之后worktree 适配的关键动作是「确认没有项目级覆盖」。Codex 读取配置一般有优先级项目级.codex/auth.json会覆盖用户级。你如果之前在某个项目里放过一份旧的新 worktree 继承了这个项目配置就会读到旧 Key。检查命令find . -name auth.json -path *codex* 2/dev/null在项目根跑一遍如果除了~/.codex/auth.json之外还有别的先把它挪走或更新成同一套配置。我踩过的坑就是项目里留了一份半年前的 auth.jsonKey 早过期了主目录能用是因为主目录读的是用户级worktree 读的是项目级两边不一致排查时特别迷惑。如果你用的是 Codex 的 coding-plan 模式或者接了 Claude Code 这类工具配置入口可能不在 auth.json而在各自的 settings 文件里。比如 Claude Code 的配置在~/.claude/settings.json字段是env下面挂ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。这类工具的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各工具的字段对照照着填就行。核心原则不变Base URL 用https://taotoken.net/apiKey 用同一把Model ID 显式指定。配置写完别急着跑 Codex。先做一次静态校验python -m json.tool ~/.codex/auth.json能正常输出说明 JSON 没写坏。JSON 写坏是 local proxy failed 的另一个高频原因一个多余的逗号就能让整个配置读不出来而 Codex 的报错不会告诉你「JSON 语法错」只会笼统报转发失败。所以这一步别省。配置就绪后进入第四节做真实验证。4. 验证请求与成功结果确认配置改完验证要分两层先验证 Key 和 API 通道本身通不通再验证 Codex 在 worktree 里能不能正常调。第一层直接用 curl 打一次 TaoToken 的 API确认 Key 有效、地址可达。命令如下curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json如果返回里能看到模型列表说明 Key 和 Base URL 都没问题。这一步把「网络问题」和「配置问题」彻底分开了curl 通说明通道没问题Codex 还报错就是 Codex 自己的配置读取问题curl 不通再回头查 Key 和地址。这个二分法能帮你省掉大量瞎猜。第二层在 worktree 目录里跑 Codex。先cd到你的 worktree 路径然后codex --version codex 用一句话说明当前目录是什么项目观察输出。如果 Codex 正常返回内容说明 local proxy failed 已经解决。如果还报错看报错细节是连接被拒本地服务没起来还是 401Key 没读到还是 reading choices 之类的解析错返回格式不对。不同报错指向不同环节下一节专门讲。成功的结果长这样Codex 在 worktree 里能连续对话你让它读文件、改代码、跑命令它都能正常响应日志里不再出现 local proxy failed。这时候你可以再开第二个 worktree 验证一遍确认配置是全局生效的而不是只对某一个目录有效。两个 worktree 都能用才说明你的统一配置真正到位了。验证时有个细节Codex 有时会缓存上一次的配置。如果你改完 auth.json 后 Codex 还报旧错先完全退出 Codex 进程再重开。残留进程会占着旧配置不放这也是 local proxy failed 反复出现的原因之一。查残留进程ps aux | grep -i codex有的话 kill 掉再重试。这一步在 worktree 场景下尤其重要因为多个 worktree 可能各自起了一个 Codex 进程互相抢端口或抢配置。验证通过后建议把这次可用的 auth.json 再备份一份命名带日期比如auth.json.20260313。以后 Codex 升级出问题直接回滚这一份比重配快得多。5. 本篇常见报错逐条排查这一节按真实报错逐条对照你遇到哪条查哪条。401 Unauthorized。这是最常见的一条含义是 Key 没被识别。排查顺序先cat ~/.codex/auth.json确认 Key 字段名对不对有的版本要OPENAI_API_KEY有的要api_key写错字段名等于没填再确认 Key 本身有没有多余空格或换行复制时很容易带上最后确认 Base URL 是不是https://taotoken.net/api地址写错会导致请求发到别处Key 自然不认。三件套Base URL Key Model ID任何一件错位都会 401。local proxy failed 且伴随 connection refused。这是本地转发进程没起来。原因通常是端口被占或进程残留。先ps aux | grep -i codex清残留再检查有没有别的程序占了 Codex 默认端口。worktree 场景下多个 worktree 同时跑 Codex 容易撞端口建议一次只在一个 worktree 里跑或者给不同 worktree 配不同端口。reading choices 相关解析错。这个报错说明请求发出去了、也返回了但返回结构 Codex 解析不了。常见原因是 Model ID 填错或者 Base URL 指向了一个不兼容 OpenAI 格式的端点。确认你填的 Model ID 在模型页里真实存在Base URL 用https://taotoken.net/api这个标准出口。OAuth 相关报错。如果你之前用 OAuth 方式登录过 Codexauth.json 里可能残留 OAuth token 字段跟 API Key 字段冲突。解决办法是清掉 OAuth 相关字段只保留 Key 方式。备份后重写一份干净的 auth.json 最省事。改了配置但报错不变。九成是进程缓存或项目级覆盖。先 kill 所有 Codex 进程再find . -name auth.json -path *codex*确认没有项目级文件在捣乱最后重开 Codex。worktree 里能用、主目录不能用。反过来也一样说明配置读取路径不一致。统一用用户级~/.codex/auth.json清掉所有项目级配置让两边读同一份。排查时记住一个原则先 curl 验证通道再查 Codex 配置最后查进程和缓存。这个顺序能把问题范围一步步缩小不会东一榔头西一棒子。如果你排查到一半不确定配置字段直接翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各工具的最新字段对照比猜快。6. 把配置固定下来让 worktree 不再翻车Codex 在 worktree 里报 local proxy failed说到底不是网络问题是配置一致性问题。你只要把 Key、Base URL、Model ID 这三件套收敛到用户级的~/.codex/auth.json让所有 worktree 读同一份这个报错基本就绝迹了。给你一套可以直接固化的动作清单。新建 worktree 后第一件事不是马上跑 Codex而是先确认配置cat ~/.codex/auth.json看一眼三件套在不在find . -name auth.json -path *codex*确认没有项目级覆盖。确认完再跑 Codex能省掉大量「为什么这个目录不行」的困惑。如果你团队多人协作把这段检查写进项目的 CONTRIBUTING.md新人拉 worktree 就不会踩同样的坑。长期做编码 Agent 的话可以考虑用 Coding Plan 把调用额度固定下来地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合需要持续跑 Codex 做重构、批量改代码的场景。Key 管理统一在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要新建或轮换 Key 都在这里。API Key 的创建入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置时对照着填就不会错。最后留一个实用习惯每次 Codex 升级后先跑一次 curl 验证通道再在 worktree 里跑一次 Codex 冒烟测试。升级经常改配置字段提前发现比写到一半报错强。配置这东西稳定比花哨重要一份能用的 auth.json 加一个固定的检查流程比每次出问题再救火省心得多。