Codex CLI 安装与配置：Windows、macOS、Linux 一次跑通

现在安装 Codex CLI，Windows 不必先装 WSL，也不必先装 Node.js：OpenAI 已提供 PowerShell 独立安装脚本。macOS 和 Linux 也有独立安装脚本；npm 与 Homebrew 是可选路线，不是所有平台的共同前提。

真正的完成标准也不只是“安装命令没报错”。你应能确认终端调用的是预期的 codex、登录到正确的计费账户、从实际项目目录启动，并在保留权限边界的情况下完成一项可核验的小任务。下文依据 2026 年 9 月 1 日的官方 Codex CLI 文档整理；命令或支持范围变化时，以官方页面为准。

先决定 Codex 要在哪套环境里工作

macOS 和 Linux 的选择通常很直接。Windows 要先回答一个问题：你的代码与日常工具链究竟位于 Windows 文件系统，还是 WSL2 的 Linux 环境？

• 仓库在 C:\...，日常使用 PowerShell、Visual Studio 或 Windows 原生工具：优先原生 Windows 安装。
• 仓库在 ~/code/...，编译器、包管理器和终端都运行在 WSL2：进入 WSL 后按 Linux 路径安装。
• 不要为了安装 Codex 才把一个 Windows 项目迁入 WSL。反过来，也不要从 PowerShell 安装后期待它自动继承 WSL 内的 PATH、配置与项目目录。

OpenAI 的当前 WSL 指南把 WSL2 定位为 Linux-native 工具链、仓库本来就在 WSL，或原生 Windows sandbox 不适合时的选择。WSL1 从 Codex 0.115 起不再受支持。若走 WSL2，仓库放在 Linux home（例如 ~/code/app）通常比 /mnt/c/... 有更好的文件 I/O 与权限行为。

使用官方命令安装

只选一条与你的环境匹配的路径。混用 standalone、npm 与 Homebrew 容易留下多个同名可执行文件，之后出现“更新成功但运行的还是旧版本”。

Windows：PowerShell 独立安装

打开 PowerShell，执行官方当前命令：

powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

关闭并重新打开 PowerShell，然后检查：

powershell
codex --version
Get-Command codex

第一条应返回 CLI 版本；第二条显示 PowerShell 实际解析到的可执行文件。若安装脚本完成但 Get-Command 没有结果，问题仍在本机安装或 PATH，还没到登录阶段。

macOS 或 Linux：独立安装

在终端执行：

bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh

重新打开终端后验证：

bash
codex --version
command -v codex

已经使用 Node.js：npm 也可以

如果你本来就用 npm 管理全局 CLI，可执行：

bash
npm install -g @openai/codex

macOS 用户也可以沿现有 Homebrew 工作流安装：

bash
brew install --cask codex

无论选哪条路径，先以 codex --version 为安装验收。npm 安装失败时才需要检查 node --version、npm --version 和全局 prefix；standalone 路线本身不要求你先配置 npm。

登录前先分清计费归属

在项目目录运行 codex，没有有效会话时会出现登录流程。你也可以明确运行：

bash
codex login
codex login status

根据 OpenAI 的认证说明，本地 CLI 主要有两类入口：

• Sign in with ChatGPT：使用 ChatGPT 账户与所在 workspace 的 Codex 权限。
• API key：使用 OpenAI Platform 组织/项目，按标准 API 费率计费。

两者不是同一笔余额。ChatGPT 订阅并不会自动替某个 API key 的调用买单；API key 登录也不等于获得 ChatGPT workspace 的全部能力。首次使用通常直接运行 codex login 并完成浏览器流程即可。只有你明确要走 Platform 按量计费时，才使用 API key 路线。

不要把 key 写进仓库、聊天提示或 config.toml。认证缓存可能位于 ~/.codex/auth.json，也可能进入系统凭据存储；文件型 auth.json 含敏感凭据，不能提交、发送工单或与他人共用。

写一份够用且不过度放权的 config.toml

用户级配置位于 ~/.codex/config.toml。一个适合初次使用的起点可以只保留权限与搜索边界：

toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

这些设置的关系比字段数量更重要：workspace-write 让命令写入限制在工作区边界内，on-request 在需要更高权限时保留询问，cached 使用 OpenAI 维护的搜索缓存。不要为了“省一次确认”就把首次运行改成 full access 或绕过 sandbox。

原生 Windows 还可以在同一用户级文件中设置 sandbox 实现：

toml
[windows]
sandbox = "elevated"

Windows sandbox 文档把 elevated 列为优先模式；它需要管理员批准完成受限用户、文件权限与防火墙设置。公司策略或权限阻止时，unelevated 可以让工作继续，但隔离更弱，应把它视为回退而非更省事的默认值。

受信任项目可以在仓库内增加 .codex/config.toml，只覆盖确实属于该项目的设置。provider、认证、profile、通知与 telemetry 等机器级键不能由项目配置覆盖，应留在用户层。临时测试某个值时，可用 codex -c key=value 只影响本次启动。完整优先级与字段含义见Config basics和Configuration Reference。

如果你已经改了配置却没有生效，先确认改的是哪个用户、哪个 CODEX_HOME、是否从受信任项目启动，以及命令行是否覆盖了文件值；再进入 Codex config.toml 排障，不要先删除整个 .codex 目录。

在真实项目里完成第一次安全验证

进入一个你熟悉、已提交或可丢弃的测试仓库：

bash
cd /path/to/your/project
git status --short
codex

第一次任务先只读，例如：

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

完成后退出或暂停会话，再检查：

bash
git status --short

通过标准有三条：回答引用了当前项目真实存在的文件；没有出现未授权改动；你能从会话中看到命令与权限请求发生在哪一步。这样才证明 CLI、认证、工作目录与权限配置共同生效。

出错时只修失败的那一层

codex 命令找不到

Windows 运行 Get-Command codex；macOS/Linux 运行 command -v codex。重开终端仍无结果时，回到原安装方式修 PATH 或重新执行对应官方 installer。不要换三种包管理器轮流覆盖。

能显示版本，但无法登录

运行 codex login status，保留终端原始错误。浏览器回调受限或远程主机没有浏览器时，官方认证页提供 device code 等路径。遇到 token exchange 类错误，可继续看登录与代理分层排查；复制别人的 auth.json 不是修复方法。

配置生效，但 Windows 命令失败

先看 Codex 显示的是 elevated 还是 unelevated sandbox、工作目录是否可读、企业策略是否阻止本地用户/防火墙设置。缺少工作区外目录的只读权限时，应按官方提示精确授权目录，而不是切换到无限制模式。

问题仍跨越多层

当前 CLI reference 提供 codex doctor，可检查安装、配置、认证、Git 与运行环境。诊断内容可能包含本机路径和环境信息；分享前先移除敏感数据。

更新沿用原安装路线

standalone 用户重新执行对应官方安装脚本即可更新；npm 与 Homebrew 用户分别运行：

bash
npm install -g @openai/codex
brew upgrade --cask codex

部分 release build 也支持 codex update。更新后重新检查 codex --version、codex login status，并在测试项目完成一次只读任务。版本变化只证明二进制变了；登录、配置、sandbox 与项目边界仍需要分别成立。

如果你现在能够明确回答“哪条安装路径拥有这个 codex、哪个账户负责计费、哪层配置正在生效、首次任务是否保持工作区干净”，这套 Codex CLI 才真正完成了安装与配置。