使用 Codex 时，必须先进入项目根目录再执行 codex 命令，否则 AI 无法正确识别 src、tests 等目录结构；同时需要先确认 Node.js 版本 ≥ 22、Codex CLI 已正确安装并可正常使用，然后再 cd 到包含 pyproject.toml 等项目标识文件的目录中启动。

如果你想在本地项目目录里启动 Codex，让 AI 更准确地理解代码结构、自动读取源文件，并精准定位报错位置，最关键的一步就是：先切换到目标项目的根目录，再执行启动命令。如果直接在桌面或用户主目录中输入 codex，它只会把当前路径当作项目目录，因此无法识别你真正需要处理的 src 或 tests 文件夹。

确认已安装 Codex CLI 并检查版本

先打开终端，输入 codex --version 查看返回结果。如果显示类似 v0.12.3 的版本号，说明 Codex CLI 已成功安装；如果出现 command not found，则需要先完成安装。你可以使用 npm install -g @openai/codex，也可以执行 brew install codex，其中在 macOS 环境下通常更推荐后者。

【Node.js 版本必须 ≥ 22】，如果版本低于 22，安装过程可能会失败，而且往往没有明显报错信息，因此务必提前运行 node -v 进行验证。

进入你要分析的项目根目录

使用 cd 命令切换到你的项目文件夹，例如：cd ~/projects/typer。这一步非常重要，不能省略——Codex 不会自动向下扫描子目录，它只会把你当前 cd 进入的路径识别为项目根目录。

接着执行 ls，确认当前目录下存在 pyproject.toml、package.json 或 README.md 这类标志性文件。如果缺少这些文件，Codex 可能无法准确判断项目类型，后续在分析代码时也可能遗漏关键上下文信息。

启动 Codex 并绑定当前目录

在项目根目录中直接运行：codex。

终端通常会输出类似 ? Project root: /Users/you/projects/typer 的提示，这表示 Codex 已成功将当前目录加载为工作空间。此后，相关对话、文件读取、写入操作以及命令执行都会严格限制在这个路径下，从而避免误操作到其他本地项目文件。

如果启动后停留在登录界面，但你已经配置好了 API 密钥，请检查 ~/.codex/auth.json 是否存在，并确认内容为 {"OPENAI_API_KEY":"sk-..."}；如果你使用的是第三方后端（例如 Ace Data Cloud），还需要确认 ~/.codex/config.toml 中的 model_provider 和 env_key 是否配置正确。