Codex CLI troubleshooting

Codex CLI 装不上、登录失败、连不上时先查什么

很多 Codex CLI 问题看起来像“命令坏了”，但实际原因通常在不同层：安装路径、运行环境、登录状态、代理、证书、本地状态目录或网络连通性。排障时先分层，能避免反复复制无关命令。

第一层：命令是否真的可执行

先确认终端能找到 codex。如果出现 command not found，重点看安装目录是否加入 PATH、当前 shell 是否重新加载配置、Node/npm 的全局安装目录是否和当前用户一致。Windows、macOS、Linux、WSL2 的 PATH 生效方式不同，先不要把它归类为网络问题。

第二层：版本和运行环境

确认 Node、npm、Codex CLI 的版本。版本信号不是为了追新，而是为了判断你遇到的是安装残留、旧版本行为还是当前环境不兼容。多个 Node 管理器同时存在时，终端里实际运行的版本可能和你以为的不一致。

第三层：登录方式和本地状态

登录失败时不要公开发送认证文件。你只需要确认：是否使用了预期的官方登录方式、浏览器回调是否成功、本地状态目录是否存在、是否误把另一个用户或另一个 shell 的状态当作当前状态。

第四层：代理、自定义 CA 和 TLS 拦截

公司网络、校园网、代理软件、抓包工具和自定义根证书都可能影响连接。排查时只需要确认相关变量“是否存在”，不应该把代理地址、证书内容或完整配置贴到公开 issue。

第五层：官方端点连通性

如果安装和登录都正常，再查 DNS、HTTPS、代理出口和官方端点可达性。连接失败不等于账号一定有问题，也不等于 CLI 一定损坏。把错误归类后再改配置，风险更低。

隐私边界

不要发送密码、验证码、API Key、访问令牌、Cookie、身份资料、auth.json、完整配置、完整日志、项目代码或远程控制权限。公开求助时只提供脱敏后的错误摘要和你已经验证过的层级。

常见问题

Codex CLI command not found 应该先查什么？

先确认安装目录是否加入 PATH、当前 shell 是否重新加载配置、Node/npm 全局目录是否和当前用户一致。这个错误通常先归类为本地路径问题。

Codex CLI 登录失败可以公开发 auth.json 吗？

不可以。不要公开发送认证文件、API Key、访问令牌、Cookie、完整配置、完整日志或源码。只发送脱敏后的错误摘要和已经验证过的层级。

代理和自定义 CA 问题怎么安全排查？

只确认相关变量是否存在，不公开变量值、代理地址、证书内容或完整配置。先区分安装、登录、TLS、DNS 和端点可达性，再改配置。