Codex CLI 安装指南：从安装、认证到首次项目验证

•2026年8月15日•11 分钟阅读•AI

给准备使用 Codex CLI 的中文开发者：先确认平台、账户与地区条件，再完成命令验证、认证和项目内首次只读任务。

安装 Codex CLI 不该以“安装程序完成”或“npm 没有报错”为终点。真正可用至少要同时满足四件事：终端能找到 codex 命令、账户能完成认证、OpenAI 服务在你所在地区受到支持，以及 CLI 能在实际项目目录中读取项目并完成一项小任务。

本文按 OpenAI 截至 2026 年 8 月 15 日公开的安装、认证和地区资料整理，只覆盖 OpenAI 官方使用路径，不把代理、自定义 base_url 或第三方模型供应商混进安装步骤。若官方页面后来更新，应以链接中的当前说明为准。

安装前先判断：你的条件能否走到首次运行

Codex CLI 官方文档当前提供 Windows 独立安装程序，并列出适用于相应环境的 npm 与 Homebrew 安装方法。选择方法之前，依次完成三项判断：

先确认操作系统与 shell。 判断当前使用的是 Windows、macOS 还是 Linux，以及命令将在哪个 shell 中运行。只采用官方文档中与你的平台相符的方法。
再确认安装方法的依赖。 npm 路径需要可用的 Node.js 与 npm，Homebrew 路径需要已有 Homebrew。不要为了照抄命令同时安装多个包管理器，选择一条自己能够持续维护的路径。
最后确认账户与地区条件。 明确准备使用 ChatGPT 认证还是 OpenAI API Key，并核对所在地区是否在对应服务的支持清单中。不满足时，先处理账户、组织权限或地区条件，再继续认证。

地区支持与“软件能不能下载”是两回事。截至 2026 年 8 月 15 日，ChatGPT 支持地区清单列有台湾、未列中国大陆，并提示从清单之外访问可能导致账户被封禁或暂停；OpenAI API 支持地区页同样列有台湾、未列中国大陆，并说明未列地区不受支持。

这是一项会变化的政策边界，也不能据此判断某个具体账户的状态。如果你位于中国大陆，应先查看当日官方清单，不要把更换网络、代理或第三方网关当作 OpenAI 官方安装步骤。本文不提供绕过地区限制的方法。

按平台选择一条安装路径

不要在同一台机器上同时用 npm、Homebrew 和独立安装程序反复覆盖。先选一条，安装后立即验证终端实际调用的版本；以后也尽量沿同一路径更新。

macOS 或 Linux：使用 npm

如果 node --version 与 npm --version 都能正常返回版本号，可执行：

bash
npm install -g @openai/codex

-g 表示全局安装，目的是让新的终端会话能够直接调用 codex。命令结束后不要急着登录，先运行：

bash
codex --version

看到 Codex CLI 的版本号，才说明“包已安装”与“终端能找到命令”这两关都通过了。

macOS：使用 Homebrew

已经用 Homebrew 管理开发工具的 macOS 用户，可以选择：

bash
brew install --cask codex

随后同样验证：

bash
codex --version

如果你此前用 npm 安装过 Codex CLI，先确认终端能找到几个同名可执行文件，再决定保留哪种安装方式，避免后续出现“更新了一个，运行的却是另一个”。在常见的 macOS 或 Linux shell 中可用：

bash
type -a codex

Windows：使用官方独立安装程序

Windows 用户应从Codex CLI 官方文档进入当前的独立安装程序下载入口，并遵循页面上的版本与系统要求。不要继续照搬“Codex CLI 只支持 macOS/Linux”的旧教程。

安装完成后，关闭并重新打开 PowerShell，再执行：

powershell
codex --version
Get-Command codex

第一条用于确认 CLI 能启动并返回版本，第二条显示 PowerShell 实际找到的程序位置。若安装器显示成功而这两条命令失败，问题仍在本机安装或 PATH，还没有进入账户认证阶段。

完成认证，再从项目目录启动第一次任务

本地 Codex CLI 可以通过 ChatGPT 订阅或 OpenAI API Key 两种方式认证。API Key 使用按标准 API 费率计费；依赖 ChatGPT workspace 或云服务的部分能力，还可能受到计划、workspace 权限和组织策略限制。具体入口与适用边界见 OpenAI 的认证文档。

如果只是想完成首次验证，不必先修改 config.toml。进入一个你熟悉的项目目录，再启动 CLI：

bash
cd /path/to/your/project
codex

Windows PowerShell 中同样先 cd 到项目目录，再运行 codex。首次启动时，按照终端显示的官方认证流程选择适合你的入口。不要把 API Key 粘贴到聊天提示、项目源码或任何会被提交到版本库的文件中。

认证完成后，第一次任务宜小而可观察。如果测试项目使用 Git，先运行 git status --short 记录原有工作区状态，再向 Codex 提出只读任务，例如：

text
只读取当前项目，不修改文件。说明入口文件、主要目录和本地启动命令；不确定的地方明确标注。

这一步的成功标准不是回答有多长，而是：CLI 确实从当前项目读取了上下文，返回内容与真实目录和文件相符，并且没有发生你未授权的修改。任务结束后再次检查：

bash
git status --short

把输出与任务前记录的状态对照；新增或变化的文件都需要逐项确认。如果项目没有使用 Git，可以改在一个可丢弃的测试目录完成首次运行。不要拿包含生产凭据、客户数据或未备份改动的目录做第一次试验。

用失败发生的位置定位问题

把所有错误都归为“Codex 装不上”会浪费很多时间。按下面顺序排查，一旦前一关没有通过，就不要继续处理后一关。

安装或 PATH 阶段： 现象是出现 codex: command not found，或 PowerShell 无法识别命令。优先确认是否选对平台方法、是否已重开终端，以及实际可执行文件位置是否进入当前 shell 的 PATH。
认证阶段： codex --version 已可用，但首次启动无法完成登录。检查认证入口是否适合当前账户，以及 workspace、组织策略或浏览器登录是否受限。
服务可用性阶段： 已完成认证，但请求被拒绝或服务不可用。检查官方地区清单、账户状态、产品权限与网络错误；不要直接改成非官方代理配置。
工作目录阶段： CLI 能回答，但没有读取预期项目。检查启动前的目录是否正确，以及项目文件权限是否允许读取。
任务边界阶段： CLI 运行了非预期操作。立即停止会话，对比任务前后的 git status --short 并检查差异，再用更小、更明确的只读任务重新验证。

命令找不到时

macOS 或 Linux 先运行：

bash
command -v codex
npm config get prefix

若第一条没有输出，而你使用的是 npm，第二条可帮助确认全局安装前缀。不要从搜索结果中复制一条通用的 PATH 修改命令就执行；不同 shell、Node.js 安装方式和用户权限对应的目录可能不同。应按当前 Node.js/npm 安装方式，把其全局可执行文件目录加入你实际使用的 shell 配置。

Windows 可先运行：

powershell
Get-Command codex -ErrorAction SilentlyContinue

没有结果时，先重开终端并核对独立安装程序的安装位置；不要用管理员权限反复安装来掩盖路径问题。

认证失败时

先确认你是在官方 CLI 显示的流程中操作，并重新核对认证方式及其限制。ChatGPT 认证失败不等于 API Key 一定可用，反过来也一样；账户计划、组织策略、workspace 权限、计费状态和地区都可能影响结果。

命令可用但服务不可用时

这说明软件安装大概率已经完成，继续重装通常无助于解决问题。记录终端中的原始错误文本，检查当日的 ChatGPT 或 API 地区清单、当前账户状态和组织权限。只有明确错误发生在哪一层，才能决定是修本机环境、调整合法的账户设置，还是停止使用。

更新后重新做最小验证

使用 npm 安装时，可以沿原路径获取当前版本：

bash
npm install -g @openai/codex@latest

使用 Homebrew 时，可运行：

bash
brew upgrade --cask codex

Windows 独立安装程序的版本与更新方式可能变化，应回到官方 CLI 文档查看当前说明。更新后至少重新执行 codex --version，并在测试项目中完成一次小型只读任务。版本号变化只证明程序已更新，不证明认证、地区支持和项目权限仍然有效。

当这四项都通过——命令可调用、认证完成、服务在当前条件下可用、项目内只读任务能被准确执行且工作区状态符合预期——Codex CLI 才算走完从安装到首次验证的闭环。之后若需要调整 config.toml、比较订阅与 API Key，或估算 token 成本，应分别进入对应主题，不要在尚未完成首次验证时增加配置变量。

#Codex CLI#OpenAI#命令行工具#开发者工具

分享文章: