如果你最近在命令行里跑 Codex大概率会遇到这样一幅画面明明安装时一切正常结果真正敲下第一条指令终端却只给你一个冷冰冰的报错或者干脆卡在reconnecting上不动。我最近在 Windows 和 Linux 两台机器上分别折腾了一遍 Codex 终端把几个高频的“不可用问题”都摸了一遍踩坑踩到怀疑人生。这篇文章就是把这些排查思路和解决办法整理出来给同样被 Codex 终端搞到头大的朋友一份可以直接对照操作的清单。文章不会涉及太虚的原理全部围绕实际报错和环境问题展开适合刚接触 Codex 的开发者也适合已经用了很久但偶尔被终端问题卡住的用户。1. 先把问题拆清楚Codex 终端不可用到底指什么1.1 终端不可用的三种形态很多人一说“Codex 终端不可用”第一反应是软件坏了。其实 Codex 作为一款跑在命令行里的 AI 编程助手绝大多数“不可用”并不是程序本身崩溃而是周围的环境没伺候好。我实际遇到过的“不可用”基本可以分成三类一是终端启动后没有任何输出光标一直闪像死机一样二是在对话过程中突然断掉提示auth token is unavailable或者local proxy failed三是安装的时候就没走完Windows 上最常见的是windows installation failed或者help_failed这种让人摸不着头脑的提示。这三类问题看起来很不一样但根子上都指向同一个事实Codex 不是独立软件它依赖 Node.js 运行时、本地配置目录、认证信息文件以及一个可以访问到 API 端点的网络链路。任何一个环节出问题表现到终端上就是“不可用”。所以我一直跟朋友说排查 Codex 问题不要盯着终端窗口本身要看终端背后的配置和日志。1.2 为什么明明是“终端工具”却总在装环境Codex 之所以这么吃环境是因为它的定位是命令行代理类工具。你在终端里输入自然语言它要把请求转发到远端模型服务然后再把结果拉回来渲染到终端。这个过程中有几步不是它自己能完成的第一步它要读取本地认证信息验证你有没有权限调用接口第二步它要根据配置文件里的模型名和地址把请求发到正确的端点第三步如果代码执行需要沙箱它可能还会调用 Docker 容器。也就是说Codex 终端不可用通常不是“Codex 坏了”而是它的认证、配置、网络、沙箱这四个环节里有至少一个没对上。理解了这一点后面所有排查动作就都有方向了。我建议每个人在开始折腾之前先记住这句话不要凭感觉改配置先看日志再动手。2. 从日志入手排错的第一步永远是看输出2.1 日志在哪看怎么把日志调出来Codex 终端并不是没有日志而是默认不主动展示。想看到详细输出最直接的方式是在启动命令前加上环境变量。以我常用的 bash 和 PowerShell 为例Linux 或 macOS 下可以这样CODEX_LOG_LEVELdebug codexWindows 的 PowerShell 里可以这样$env:CODEX_LOG_LEVELdebug codex设置成 debug 级别之后终端会输出大量内部请求信息包括配置文件加载路径、认证文件读取结果、每次请求的目标地址、返回的状态码等。这个信息量确实很大但排查问题的时候非常管用。我之前遇到过一次local proxy failed不看日志根本不知道它访问的是哪个地址看了日志才发现是配置文件里的 base_url 写成了一个本地端口而这个端口根本没有服务在听。除了运行日志Codex 还会在配置目录下写入一些状态文件。在 Linux 和 macOS 下通常是~/.codex/Windows 下一般在%USERPROFILE%\.codex\。这里面通常有config.toml、auth.json以及一些日志文件。你可以先检查这个目录是否存在、权限是否正确。如果目录都没有那终端不可用就太正常了它连往哪写配置都不知道。2.2 三个高频报错信息拆解第一类auth token unavailable。这个报错的意思是 Codex 在本地没有找到可用的认证令牌或者找到了但已经失效。常见原因包括登录流程没走完、token 被手动清掉、多账号切换工具覆盖了认证文件、系统时间不对导致令牌校验失败。这个报错通常不会影响 Codex 启动但只要你一输入指令它就会立刻中断。第二类cc switch local proxy failed while handling codex endpoint /responses。这个报错要拆成两半看。cc switch是很多玩家用来快速切换 Codex 配置的小工具它本质上是在帮你修改 Codex 的配置中心包括模型名、接口地址、认证方式等。后半句local proxy failed while handling codex endpoint /responses的意思是Codex 在处理/responses这个 API 端点时本地转发失败了。也就是说请求到了某一个本地代理服务但这个服务要么没启动要么地址写错要么返回了非预期结果。出现这个错误时重点排查的不是 Codex 本身而是你配置里的本地转发地址。第三类model is not supported when using codex with a...。这个报错通常出现在配置文件里写了一个当前版本不支持的模型名或者模型名和 API 供应商不匹配。比如你把某个自定义模型名写进了config.toml但/models接口返回的列表里根本没有这个模型Codex 就会直接拒绝继续。这种问题看似简单但因为模型名拼写错误、大小写不对、或者配置被cc switch覆盖实际排查起来也得花一点时间。3. 安装阶段最容易踩的坑3.1 Node.js 版本和 npm 全局安装权限Codex 终端通常通过 npm 安装npm install -g openai/codex。如果你发现安装完以后codex命令找不到或者一运行就报Cannot find module大概率是 Node.js 版本太旧。Codex 对 Node 版本有要求至少需要 Node 18 以上推荐 20 LTS。版本太低的时候很多新语法和 API 都不支持程序启动到一半就直接退出终端上看起来就是“无响应”。npm 全局安装权限也是一个大坑。Linux 和 macOS 上如果用了系统自带 Node执行全局安装时经常遇到EACCES: permission denied。很多教程会直接让你加sudo npm install -g我不建议这么做因为这会改变全局目录的文件归属以后升级或者卸载会越来越麻烦。更干净的办法是配置用户级 npm 全局目录。比如在 bash 里mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc然后重新安装 Codex。这一步做完很多安装路径导致的“终端不可用”会自动消失。Windows 用户比较少见权限问题但如果你用 nvm-windows 管理 Node 版本记得切换完版本后重新执行一次全局安装否则codex指向的还是旧版本的安装路径。3.2 Windows 上“安装未完成”和 help_failed 的处理Windows 上的 Codex 终端不可用很大一部分发生在安装阶段。常见的提示是codex windows installation failed或者带一个help_failed的报错。这通常是安装器在尝试写注册表、创建快捷方式、或者下载某个辅助组件时失败了。我遇到过一次非常典型的场景Windows 的当前用户目录是中文名Codex 在解析路径时处理不当导致安装进行到一半就退出终端完全没有可用的命令。另一个高频原因是没有安装 Visual C Redistributable。Codex 在 Windows 上并不是纯 Node 应用某些组件依赖系统级的 C 运行库。如果系统缺少这个库安装时不会明确告诉你而是会在某个阶段突然失败然后给你一个非常不友好的错误码。解决方式是先去微软官网下载最新的 Visual C Redistributable 安装包装完以后重启终端再重新执行安装命令。如果还失败可以把 npm 缓存清掉再试npm cache clean --force npm install -g openai/codex3.3 Docker 权限异常导致终端“假死”Codex 的代码执行功能可以选择在 Docker 容器里运行这样你的本地环境不会被 AI 生成的命令搞乱。但 Docker 本身也是一个很容易让 Codex 终端“不可用”的变量。我在 Linux 上安装完 Docker 以后直接用codex启动对话结果第一条指令发出去后就一直转圈没有任何响应。查了日志才发现Codex 尝试调用 Docker 创建容器但当前用户不在docker用户组里权限不足创建失败后终端又没有立刻弹出错误就表现为“卡死”。解决办法很简单把当前用户加入 docker 组然后重新登录终端sudo usermod -aG docker $USER newgrp docker如果你不想用 Docker也可以在 Codex 配置里关闭沙箱执行直接让它在当前环境运行。但不建议这么做因为 AI 生成的代码是不可预测的可能执行危险命令。宁可花点时间把 Docker 权限配好也不要图省事把安全边界拆掉。4. 登录与认证失效高发但最好修4.1 token 存哪了为什么读不到Codex 的认证信息默认会存在~/.codex/auth.json里。无论是通过 ChatGPT 登录还是用 API Key最终都会落到这个文件。如果你打开这个文件发现内容为空或者根本没有这个文件那终端不可用就太正常了。Codex 启动时会先读取这个文件来判断你是否已登录读不到就相当于没有认证自然无法发起任何请求。有时候文件存在内容也有但 Codex 依然提示auth token unavailable。这时候优先检查文件权限。在 Linux 下如果auth.json的权限是 666 或者对当前用户不可读Codex 会拒绝使用它。建议把它设置成只有当前用户可读写chmod 600 ~/.codex/auth.jsonWindows 下一般不会刻意遇到权限问题但如果你的用户目录被杀毒软件或安全策略锁定也可能导致 Codex 读不到认证信息。这时可以打开资源管理器进入%USERPROFILE%\.codex\确认auth.json真实存在并且大小不为 0。4.2 重新登录的正确姿势很多人在遇到认证问题后第一反应是手动去改auth.json或者把网上别人的 token 复制过来。我非常不建议这么做一是 token 和账号绑定换了环境大概率无效二是自己手改文件很容易把 JSON 格式写坏反而引入新问题。正规做法是重新走一遍登录流程。在终端里执行codex login如果是 ChatGPT 账号登录它会生成一个链接让你在浏览器里完成授权。授权完成后浏览器会尝试唤起 CLI。如果唤起失败通常是因为浏览器阻止了自定义协议跳转。这种情况不算 Codex 本身的问题但也表现为终端不可用。解决方式是在浏览器设置里允许 Codex 的自定义协议或者复制浏览器显示的验证码回到终端里粘贴。如果登录后立刻又提示 token 不可用可以退一步检查系统时间。系统时间和真实时间偏差太大OAuth 令牌会立刻失效因为令牌校验里的exp字段是按时间戳走的。我以前在虚拟机里遇到过系统时间慢了两个小时折腾了半天才发现是这个原因。4.3 多账号/切换工具带来的串扰现在很多人会通过社区写的cc switch之类的配置切换工具在不同模型供应商之间来回切换。这类工具的好处是方便坏处也明显它可能会同时修改config.toml和auth.json。我今天就遇到过这种情况之前用cc switch切换到某个第三方兼容端点切换完以后 Codex 一直报auth token unavailable。用 debug 日志一看Codex 读取的认证 key 已经变成了那个第三方端点需要的 key而我原来的 API Key 还在但没被读到。这种串扰的排查逻辑很简单先看一眼当前配置里到底引用了哪个模型供应商再对应检查认证文件。在config.toml里通常会有类似model_provider的配置。如果它指向的是某个第三方供应商那auth.json里的认证字段也要和它对上。搞不清楚的时候最简单粗暴的方法是切回默认配置重新登录一次cc switch reset codex login如果不想用工具也可以把~/.codex/下的config.toml和auth.json备份一份然后删掉再重新登录。这样至少能排除配置串扰带来的问题。5. local proxy failed 的排查思路5.1 先看 base_url 和 model_provider 配置cc switch local proxy failed while handling codex endpoint /responses这个报错很多人一看到proxy就头大其实不用慌。Codex 配置文件里有一个base_url字段它决定了请求要发到哪个地址。在正常使用官方接口时它通常是https://api.openai.com/v1。但有些人会在本地跑一个 API 转发服务或者把自己公司的内网网关地址填进去这时候base_url就变成了http://127.0.0.1:xxxx/v1之类的本地地址。如果你的配置里填的是本地地址那么 Codex 每次对话都会先请求这个本地服务。只要这个本地服务没启动、端口被占用、或者返回的响应格式不符合 Codex 预期终端就会显示出local proxy failed。我之前踩过的一个坑是本地服务的端口已经换了但config.toml里的地址还是旧端口Codex 请求过去直接被拒绝却又没有把连接被拒绝的原始错误直接抛出来只告诉用户“proxy failed”。所以遇到这个报错时你的第一动作不是改 Codex 的配置而是确认你配置里指向的那个本地服务到底还活着没有。5.2 本地转发服务配置错了会怎样假设你在config.toml里配置了base_url http://127.0.0.1:8080/v1那你就得有一个进程监听 8080 端口。检查方式很简单curl http://127.0.0.1:8080/v1/models如果没有返回 JSON说明这个本地服务要么没起来要么路径不对。此时你去把服务进程启动起来Codex 大概率就好了。如果这个本地服务本身也需要认证你还需要检查它的 token 配置是否和 Codex 的认证信息匹配。很多第三方兼容服务和 Codex 的认证字段并不一致cc switch切换过去以后本地服务认的 key 和 Codex 发的 key 不是同一个于是接口返回 401Codex 也会把它归类为local proxy failed。另外如果你用的本地服务是某个公司内部网关可能还需要额外设置请求头或配置环境变量。这些信息在服务提供方的文档里都会有Codex 侧能做的只是把base_url写对把认证信息填对。配置完之后我建议先用 curl 手动测试一遍确认通了再回到 Codex 里操作这样能把“服务问题”和“Codex 问题”快速分开。5.3 如何一步步验证链路如果不想被这种报错反复折磨我有一个固定的排查顺序。第一步看config.toml里base_url指向的是官方地址还是本地地址。第二步如果是本地地址直接用浏览器或 curl 访问该地址的健康检查接口或/models接口确认服务可用。第三步确认认证信息在服务端日志里看有没有收到 Codex 的请求如果有且返回 401就说明 key 不匹配。第四步回到 Codex 的 debug 日志看它最终发出去的目标 URL 是什么和预期是否一致。这套流程每次都能帮我定位到问题所在。实际上很多所谓的“终端不可用”根本不是 Codex 的问题而是链路里的中间层配置有误。Codex 只是把错误信息粗糙地抛给了用户。把它想象成快递配送Codex 是下单的人快递员是本地转发服务收货方是远端模型 API。快递员罢工或者地址写错你总不能怪下单系统吧。排查的关键是把责任分清楚。6. 模型与长对话还有两个隐藏坑6.1 模型名写错导致的 not supported这类报错的完整文案一般是这样的the xxx model is not supported when using codex with a ...。看到这个报错不用怀疑就是当前配置的模型名在 Codex 当前支持的模型列表里不存在。原因可能是你手动改了配置把模型名写成了一个不存在或者尚未开放的型号也可能是cc switch切换到了某个还不兼容的作者提供的新模型名而 Codex 版本太旧不认识。解决办法不复杂。第一更新 Codex 到最新版本因为新版本通常会增加对新模型的支持。第二检查模型名拼写注意大小写和连字符。第三如果你确实要用某个第三方模型先确认它是否兼容 Codex 的responses接口。有的模型只在旧的completions接口下可用放到 Codex 里就会直接报 not supported。这种情况下要么换一个兼容接口的模型要么调整 Codex 的配置让它走兼容模式。不要硬填一个不存在的模型名Codex 不会自动帮你找替代品。6.2 对话太长变慢时的处理办法还有一个常见的“终端不可用”场景是对话进行到一半Codex 响应越来越慢最后像是卡死。这个不一定是网络问题而是上下文太长token 数量太大接口处理和返回都需要更长时间。Codex 的免费用户或者普通 API 调用如果超时终端会一直转圈最后可能直接断开。我个人的做法是每过一段时间就开一个新的会话或者用 Codex 的压缩历史功能把长对话精简后再继续。毕竟终端工具不是拿来无限聊天的它的定位是完成一个个明确的任务。如果确认是网络抖动导致的超时可以检查 Codex 配置里是否有超时时间设置把它适当调大。不过我不建议一次性调得太大因为超时时间太长会让终端看起来像卡死。我一般从默认值调大到 120 秒左右然后观察几次请求的耗时再决定是否继续提高。7. 高频问题速查表错误信息可能原因解决动作codex: command not found全局安装目录不在 PATH 中按 3.1 节配置 npm 全局目录EACCES: permission deniednpm 全局目录无权限改用用户级 npm 前置目录windows installation failed缺少 C 运行库或路径有中文安装 Visual C Redistributableauth token unavailable认证文件缺失/权限异常/系统时间偏差按 4.2 节重新登录或调校时间local proxy failed本地转发服务未启动/配置错误按 5.3 节验证链路model is not supported模型名不存在或接口不兼容升级 Codex 并检查模型名对话中途无响应上下文过长或超时开新会话并调大超时时间Docker 容器创建失败当前用户不在 docker 组执行usermod -aG docker配置切换后报认证错误cc switch配置与认证文件不匹配重置配置并重新登录终端一直转圈网络请求未返回或本地端口不通开 debug 日志确认目标地址这张表只是快速索引实际排查时还是建议按对应章节的详细步骤走。因为同一个错误信息背后可能对应好几种原因只靠“对号入座”容易踩漏。最后再分享一个我自己的习惯在终端里跑 Codex 之前先确认好三件事——配置文件里有没有指向本地转发服务认证文件是否完整Docker 是否可用。这三件事确认完我一天下来基本不会碰到莫名其妙的不可用问题。如果你现在正被某个 Codex 报错搞到头大先别急着重装打开 debug 日志按照链路一层层去看多数问题都能在自己手里解决掉。
