Codex CLI 安装与使用教程：macOS、Windows、Linux

Codex CLI 是在终端中使用 Codex 的方式。它适合已经有 Git 项目、希望直接阅读和修改本地代码的开发者。本文从环境检查开始，带你完成安装、登录、第一次任务和常见故障排查。

安装前检查

先确认 Node.js 和 npm：node --version、npm --version。不同版本的 Codex 可能会调整最低要求，当前常见环境是 Node.js 20 或更高版本、npm 10 或更高版本。

同时确认三件事：

• 当前项目可以用 Git 管理。
• 你知道项目的测试或构建命令。
• 当前终端有权限安装全局 npm 包。

先进入项目并保存当前状态：git status。如果工作区已经有未提交修改，先记录它们，避免把安装后的实验改动和旧修改混在一起。

macOS 和 Linux 安装

macOS 和 Linux 可以使用 npm 全局安装：npm install --global @openai/codex。

安装后运行 codex --version。如果版本号能正常返回，说明 CLI 已经进入 PATH。

如果出现 command not found: codex，先运行 npm prefix --global，找到 npm 的全局目录，再确认对应的 bin 目录已经加入 PATH。修改 shell 配置后，重新打开终端，再运行版本命令。

macOS 使用 Homebrew 管理 Node.js 时，也要确认当前终端使用的是 Homebrew 对应的 Node 和 npm。运行 which node、which npm，检查路径是否来自你预期的安装位置。

Windows 安装

Windows 可以在 PowerShell 中使用 npm 安装：npm install --global @openai/codex。安装完成后重新打开 PowerShell，再运行 codex --version。

如果你使用 WSL，请把 Node.js、npm 和 Codex 安装在 WSL 环境里，并在 WSL 的项目目录中运行。不要把 Windows 的 Node、WSL 的 npm 和另一套 PATH 混用，否则可能出现“安装成功但找不到命令”或权限不一致的问题。

Windows 下排查 PATH 时，可以运行 Get-Command node、Get-Command npm 和 Get-Command codex，确认三个命令来自同一套环境。

第一次启动

进入项目目录后运行 codex：

cd ~/projects/your-project，然后运行 codex。

第一次启动可能要求登录或选择认证方式。完成认证后，先让 Codex 做只读任务，不要马上修改大量文件：

请阅读项目结构和 package.json，只告诉我启动命令、测试命令和主要业务目录，不要修改文件。

如果返回的信息正确，再开始一个很小的修改任务。比如给已有函数补一个边界测试，并要求运行项目已有测试。

CLI 工作流建议

先看状态，再提任务

运行 git status，确认你知道当前工作区的状态。任务描述里写出目标目录、禁止修改的文件和验证命令。

先分析，再实现

要求 Codex 先列出计划和影响文件。你确认方向后，再让它执行修改。这个步骤能明显减少无关文件变化。

每次任务都检查 diff

使用 git diff --stat 查看修改规模，再使用 git diff 阅读具体内容。修改量明显超过任务范围时，先暂停并让 Codex 解释原因。

让测试成为完成条件

不要只接受“已完成”的文字总结。要求 Codex 运行测试、类型检查或构建，并报告失败命令、首个错误和遗留风险。

常用命令

• codex：进入交互式工作流。
• codex --version：查看 CLI 版本。
• git status：查看工作区状态。
• git diff --stat：查看修改规模。
• git diff：查看具体修改。

不同版本的 CLI 可能提供不同启动参数。需要使用某个参数前，先运行 codex --help 查看当前版本支持的选项，不要直接复制旧教程里的参数。

安装和启动排错

npm 权限错误

全局安装时遇到权限错误，不要直接给整个系统目录开放写权限。优先使用 Node 版本管理器，或按照当前系统的 npm 全局目录方案修复权限。

版本命令正常，但启动失败

记录 codex --version 的版本、操作系统、Node.js 版本和完整错误首行。检查项目目录是否可读，以及当前用户目录下的 Codex 配置是否损坏。

登录后出现 401

401 通常是认证凭据过期、环境变量错误或 Provider 配置冲突。可以参考 Codex CLI 接入第三方 API 和 Codex 401 排障教程。不要把完整 API Key 贴到错误报告中。

Codex 修改了不相关的文件

先用 git diff 检查范围，再回到更小的任务。明确“只修改哪些目录”，并要求 Codex 先输出计划。

安全使用清单

• 不要把 API Key 写进项目文件。
• 不要把 auth.json 提交到 Git。
• 对生产仓库先创建分支或备份。
• 让 Codex 在修改前说明将读取和修改哪些文件。
• 对数据库迁移、权限变更和删除操作增加人工确认。

继续学习

安装完成后，建议阅读 Codex 教程：从安装到完成第一个开发任务，再学习 提示词写法与上下文管理。如果你需要在后端或自动化服务中调用模型，可以继续阅读 Codex API 接入指南。

FAQ

Codex CLI 支持哪些系统？

支持范围会随版本变化。常见使用环境是 macOS、Linux，以及支持的 Windows 环境。安装前应查看当前版本的官方说明。

npm 全局安装和项目本地安装有什么区别？

CLI 通常作为全局工具使用，便于在不同项目中启动。项目依赖应继续使用项目自己的 package manager 管理，不要把 CLI 的全局安装和项目依赖混为一谈。

是否需要先创建 Git 仓库？

不是硬性要求，但强烈建议使用 Git。它能让你检查 diff、撤销错误并保留任务前后的证据。

第一次任务应该多大？

选择 15 到 30 分钟内可以验证的小任务，例如补一个测试、修一个明确报错或解释一个模块。跑通闭环后，再逐步扩大范围。