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

> 先选对 Windows 原生、WSL2 或 Unix 安装路径，再完成登录、最小安全配置和项目内首次只读验证。

- URL: https://blog.laozhang.ai/zh/posts/codex-cli-install
- Published: 2026-08-15
- Updated: 2026-09-01
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: ChatGPT 与 OpenAI
- Tags: Codex CLI, OpenAI, Windows, 开发者工具

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

真正的完成标准也不只是“安装命令没报错”。你应能确认终端调用的是预期的 `codex`、登录到正确的计费账户、从实际项目目录启动，并在保留权限边界的情况下完成一项可核验的小任务。下文依据 2026 年 9 月 1 日的[官方 Codex CLI 文档](https://learn.chatgpt.com/docs/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 指南](https://learn.chatgpt.com/docs/windows/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 CLI 从选择运行环境、官方安装到认证、配置和项目验证的完整流程](https://blog.laozhang.ai/posts/zh/codex-cli-install/img/setup-workflow.webp)

## 登录前先分清计费归属

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

```bash
codex login
codex login status
```

根据 OpenAI 的[认证说明](https://learn.chatgpt.com/docs/auth)，本地 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 文档](https://learn.chatgpt.com/docs/windows/windows-sandbox)把 `elevated` 列为优先模式；它需要管理员批准完成受限用户、文件权限与防火墙设置。公司策略或权限阻止时，`unelevated` 可以让工作继续，但隔离更弱，应把它视为回退而非更省事的默认值。

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

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

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

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

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

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

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

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

```bash
git status --short
```

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

![Codex CLI 在 Windows、WSL2、macOS 与 Linux 上的安装路径、最小配置和故障分层图](https://blog.laozhang.ai/posts/zh/codex-cli-install/img/troubleshooting-map.webp)

## 出错时只修失败的那一层

### `codex` 命令找不到

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

### 能显示版本，但无法登录

运行 `codex login status`，保留终端原始错误。浏览器回调受限或远程主机没有浏览器时，官方认证页提供 device code 等路径。遇到 token exchange 类错误，可继续看[登录与代理分层排查](https://blog.laozhang.ai/zh/posts/codex-token-exchange-failed-403)；复制别人的 `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 才真正完成了安装与配置。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-09-01。

- [官方 Codex CLI 文档](https://learn.chatgpt.com/docs/codex/cli) (learn.chatgpt.com)
- [当前 WSL 指南](https://learn.chatgpt.com/docs/windows/wsl) (learn.chatgpt.com)
- [认证说明](https://learn.chatgpt.com/docs/auth) (learn.chatgpt.com)
- [Windows sandbox 文档](https://learn.chatgpt.com/docs/windows/windows-sandbox) (learn.chatgpt.com)
- [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic) (learn.chatgpt.com)
- [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) (learn.chatgpt.com)