Codex 常见问题排查：安装、登录、项目与测试

Codex 常见问题排查应从实际现象开始。同样的“任务失败”，可能是安装路径、账号状态、目录权限、项目依赖或测试自身的问题。先缩小范围，再选择修复手段，可以避免反复重装却没有解决根因。

一、记录排查信息

至少保留客户端类型与版本、操作系统、发生错误的步骤，以及去除敏感信息后的错误原文。CLI 用户可以运行：

codex --version
codex --help

不要分享 API Key、访问令牌或完整的私有配置。需要展示配置时，只保留相关键，并替换敏感值。

二、Codex 安装后命令不可用

如果提示 command not found，先确认安装是否成功，再检查当前终端是否使用了安装时的 Node.js 环境。重新打开终端后仍失败，检查全局可执行目录与 PATH 配置。

不要同时用多种安装方式反复覆盖。先对照 安装教程与当前官方说明，确认一种明确的安装路径。

三、登录或连接异常

检查系统时间、正常网络访问、当前账号状态与组织工作区策略，再查看 OpenAI 服务状态。状态页可以帮助判断是否存在广泛故障，但不能解释每个账号的问题。

区分网页登录、客户端鉴权和 API 请求错误。它们可能属于不同路径；能够打开网页并不能证明客户端连接已经成功。保留错误码比只截取一个“失败”提示更有用。

四、Codex 无法访问项目

确认选择的是仓库目录而不是快捷方式，文件确实在本地，系统权限允许访问。如果项目位于云盘中，先确认需要的文件已同步完成。

用一个不含敏感数据的小型本地仓库验证是否也会失败。如果只有一个项目出错，优先检查该项目的路径、权限和文件状态。更多说明见 权限与安全边界。

五、测试失败或无法执行

要求 Codex 明确列出实际运行的命令、工作目录、退出状态与关键错误。区分以下情况：

现象	下一步
找不到测试命令	核对项目脚本和 README，不猜测命令
缺少依赖	确认包管理器、锁文件和安装要求
需要外部服务	明确测试所需的本地服务与配置
断言失败	比较输入、预期与实际结果，定位回归
权限被拒绝	检查操作目标与权限策略，不直接关闭隔离

测试没有成功执行时，应记录“未验证”，而不是“应该通过”。如果当前失败在改动前就存在，也应明确区分已有问题与新增回归。

六、组织一份最小复现

客户端及版本：
操作系统：
问题开始时间：
复现步骤：
预期结果：
实际结果与错误原文（已脱敏）：
已经尝试的检查：

Codex 常见问题排查的结果未必是立刻修复，也可能是准确定位到缺少的账号权限、系统条件或外部服务。把已知事实写清楚，才能让下一步处理有依据。