Codex CLI 安装配置教程：Windows / Mac 从零开始
Codex CLI 是面向开发者的命令行编程 Agent。它适合把本地项目目录交给 AI 协助阅读、修改、解释和排查问题，尤其适合想从浏览器问答走向真实代码协作的新手。本文从零开始讲清楚 Windows 和 Mac 的安装路径、登录配置、第一次运行方式，以及常见问题怎么处理。
如果你还不清楚 Codex 是什么，可以先看站内教程 Codex 是什么？OpenAI 编程 Agent 新手入门完整教程；如果想看完整实操流程，也可以继续阅读 Codex 怎么用？从登录到完成第一个代码任务全流程。
一、安装前先准备什么
1. 准备一个可以测试的项目目录
建议先准备一个普通项目文件夹，例如一个前端页面、Python 脚本、WordPress 子主题、插件代码，或者你自己正在学习的小项目。第一次不要直接拿生产环境核心代码测试，先用可回退、可备份的目录熟悉流程。
2. 确认终端工具可用
Windows 推荐使用 PowerShell 或 Windows Terminal；Mac 推荐使用系统自带终端或 iTerm2。终端能正常进入目录、执行命令、查看文件，就是安装 Codex CLI 的基础。
3. 准备 OpenAI 账号或 API Key
Codex CLI 的登录方式会随着官方版本更新而调整。实际配置时，以 OpenAI 官方文档和 GitHub 仓库说明为准。通常你需要可以使用 Codex 的 OpenAI 账号，或按照提示配置 API Key。
二、Windows 安装 Codex CLI
1. 使用官方 PowerShell 安装脚本
在 Windows 上，官方仓库提供了 PowerShell 安装方式。你可以在 OpenAI Codex 官方 GitHub 仓库中复制最新命令，然后在 PowerShell 中运行。这样做的好处是路径、版本和依赖处理更接近官方推荐。
# 示例：请以官方 GitHub 仓库最新命令为准
# 在 PowerShell 中运行官方 Windows 安装命令2. 使用 npm 安装
如果你的电脑已经安装 Node.js，也可以使用 npm 安装 Codex CLI。适合已经在做前端、Node.js 或全栈开发的用户。
npm install -g @openai/codex3. 验证是否安装成功
安装完成后，在终端输入版本检查命令或直接输入 codex。如果终端能识别命令，并出现登录、配置或帮助提示，就说明基础安装已经完成。
codex --version
codex三、Mac 安装 Codex CLI
1. 使用官方 shell 安装脚本
Mac 用户可以参考 OpenAI Codex 官方仓库中的 Mac/Linux 安装命令。复制命令前，建议先打开官方页面确认命令是否有更新，避免使用过期安装脚本。
2. 使用 Homebrew 安装
如果你已经习惯用 Homebrew 管理开发工具，可以优先查看官方仓库是否提供 Homebrew 安装入口。Homebrew 的优势是升级、卸载和路径管理更清晰。
3. 使用 npm 安装
Mac 同样可以用 npm 安装，命令与 Windows 一致。安装后，如果提示权限不足，可以检查 Node.js 安装方式、npm 全局目录权限，或改用官方脚本/包管理器方式安装。
npm install -g @openai/codex四、登录与 API Key 配置
1. 按终端提示登录
首次运行 codex 时，终端通常会提示你完成登录或配置。按提示打开浏览器、授权账号，或输入所需的 API Key。完成后，Codex CLI 会把认证信息保存在本机配置中。
2. API Key 不要写进项目文件
如果需要手动配置 API Key，请优先使用系统环境变量或官方推荐的配置文件位置，不要把 Key 写进项目代码、README、公开仓库或截图里。公开泄露 API Key 可能带来额度损失和账号风险。
3. 多电脑使用时分别配置
Windows 台式机、MacBook、远程服务器是不同环境，每台设备都需要单独安装和配置。不要直接复制整份隐藏配置文件，尤其不要把包含登录令牌的文件发送给别人。
五、完成第一个 Codex CLI 任务
1. 进入项目目录
在终端进入你要处理的项目文件夹。Codex CLI 的价值在于读取当前项目上下文，所以目录选对很重要。
cd 路径/你的项目目录
codex2. 从低风险任务开始
第一次建议让 Codex 做解释、检查、生成说明文档、补充注释、定位报错原因，而不是马上改大量核心代码。你可以这样问：
- 请阅读这个项目，说明主要目录结构和启动方式。
- 请帮我找出这个报错可能来自哪里，先不要修改文件。
- 请为这个函数补充更清晰的注释，并解释为什么这样改。
- 请检查是否有明显的安全风险或配置遗漏。
3. 修改前先看差异
当 Codex 提出修改时，先阅读它说明的修改范围，再查看文件差异。确认没问题后再测试。这个习惯能避免误改配置文件、覆盖本地改动或把实验代码带进正式项目。
六、常见报错与解决办法
1. codex 不是内部或外部命令
这通常是安装没有成功，或者命令所在目录没有加入系统 PATH。可以重新打开终端、检查安装输出、确认 npm 全局目录或官方安装目录是否在 PATH 里。
2. 登录后仍然提示未认证
可以先退出终端重新打开，再重新运行登录流程。如果使用 API Key，检查 Key 是否复制完整、环境变量名称是否正确、当前终端是否已经加载最新环境变量。
3. npm 安装失败
常见原因包括 Node.js 版本过旧、npm 源连接异常、权限不足。可以升级 Node.js，切换网络环境，或改用官方安装脚本和 GitHub Releases 二进制文件。
4. Codex 无法理解项目
先让它阅读 README、package.json、requirements.txt、配置文件和入口文件，再提出具体任务。问题越具体，输出越稳定。你也可以把需求拆成“先分析、再计划、最后修改”三步。
七、适合 Codex CLI 的使用场景
Codex CLI 适合本地代码阅读、脚本修复、文档补全、单元测试生成、配置排查、代码迁移和小型功能开发。如果你正在整理 AI 编程工具，可以继续浏览 AI 工具库；如果想下载配套教程资料，可以查看 资料包下载。
八、FAQ：Codex CLI 新手常见问题
Codex CLI 和网页版 ChatGPT 有什么区别？
网页版更适合问答、写作和轻量代码解释；Codex CLI 更贴近本地项目，可以在终端里读取项目结构、分析文件、提出修改方案，更适合真实开发任务。
Windows 和 Mac 哪个更适合使用 Codex CLI？
两者都可以。Windows 用户建议用 Windows Terminal 和 PowerShell；Mac 用户可以用系统终端、iTerm2、Homebrew 和 npm。关键是保持终端、Git、Node.js 等基础环境稳定。
不会写代码可以用 Codex CLI 吗？
可以，但建议从阅读项目、解释报错、生成注释和写小脚本开始。涉及支付、数据库、权限、服务器配置时，最好先备份，并让有经验的人复核。
Codex CLI 安装失败应该先检查什么？
优先检查网络、安装命令是否来自官方仓库、Node.js/npm 版本、系统 PATH、终端权限和登录状态。不要从陌生网站复制来路不明的安装脚本。
本文配套资料下载
- 完整 PDF 教程
- Word 可编辑版本
- Codex CLI 常用命令清单
- Windows / Mac 安装检查表
- 新手提示词模板
- 常见报错排查清单
官方参考：OpenAI Codex GitHub 仓库、OpenAI Codex 官方文档。安装命令可能随版本更新，请以官方页面为准。
