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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 出口是 https://taotoken.net/api ，注意 API 地址不带任何查询参数，配置里就写这个干净的地址。

前置准备分三步。第一步，拿到 Key。进控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，创建完先复制存好，后面 auth.json 要用。第二步，确认你要用的模型 ID。Codex 这类工具通常需要显式指定模型，你在模型对话页可以先确认可用模型，地址 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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/api，Key 填你在控制台创建的那把，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.json，Key 早过期了，主目录能用是因为主目录读的是用户级，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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各工具的字段对照，照着填就行。核心原则不变：Base URL 用https://taotoken.net/api，Key 用同一把，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 已经解决。如果还报错，看报错细节：是连接被拒（本地服务没起来），还是 401（Key 没读到），还是 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 方式登录过 Codex，auth.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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，适合需要持续跑 Codex 做重构、批量改代码的场景。Key 管理统一在控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，需要新建或轮换 Key 都在这里。API Key 的创建入口在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，配置时对照着填就不会错。

最后留一个实用习惯：每次 Codex 升级后，先跑一次 curl 验证通道，再在 worktree 里跑一次 Codex 冒烟测试。升级经常改配置字段，提前发现比写到一半报错强。配置这东西，稳定比花哨重要，一份能用的 auth.json 加一个固定的检查流程，比每次出问题再救火省心得多。