启动 codex 前，需要先执行 cd 进入项目根目录，否则可能出现“no repository found”。同时应确认目录下已有 package.json、src/ 等项目标识。首次运行时，程序会自动扫描项目内容，并按照 .gitignore 规则处理；如果扫描耗时较长，可通过 --exclude 参数进一步过滤范围。完成登录认证后，才能正常访问文件系统；若仍未成功，可检查 ~/.codex/auth.json 的状态是否正常。

想在终端里用Codex分析、修改或运行本地项目代码，必须让Codex准确识别当前项目的根目录和文件结构，否则它会报“no repository found”或读取到空目录。

确认项目目录结构

打开终端，执行 ls -la 查看当前目录是否包含 package.json、src/、README.md 或 .git/ 等典型项目标识。Codex依赖这些信号判断是否进入有效项目上下文。

如果看到的是空白列表或只有 Desktop、Downloads 这类系统目录名，说明你还没进对地方——【必须先 cd 到项目根目录，再启动 codex】。

启动 Codex CLI 并绑定当前项目

在已确认的项目根目录下，直接输入：

codex

首次运行会自动检测本地 Git 仓库状态、扫描 src/ 和 lib/ 目录，并尝试加载 .gitignore 规则。这个过程通常耗时 2～8 秒，取决于项目规模。

若卡在 “Loading repository…” 超过 15 秒，大概率是项目里存在超大二进制文件（如 node_modules/.bin/chromedriver）被误扫描。此时按 Ctrl+C 中断，改用带过滤的启动方式：

codex --exclude="node_modules,*.log,dist"

登录认证并激活上下文

第一步：终端弹出提示后，复制给出的授权 URL 到浏览器，用 ChatGPT 账号登录。

第二步：授权完成后，页面跳转至 localhost 回调地址，终端同步显示 “✅ Authenticated successfully”。这一步不可跳过，未认证状态下 Codex 拒绝访问任何文件系统操作。

第三步：回到终端，再次输入 codex ——这次它会立即加载项目快照，底部状态栏显示 “Project: your-project-name | Files indexed: 142”，表示已就绪。

注意：如果第二次输入仍跳转登录页，说明浏览器授权未成功写入 ~/.codex/auth.json，可手动检查该文件是否存在且含有效 access_token 字段。