> ## Content Index
> Fetch the complete content index at: https://tbbbk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# OpenAI Codex CLI 完整教程：安装、订阅、额度和国内使用避坑
- URL: https://tbbbk.com/openai-codex-cli-install-subscription-usage-china-guide-2026/
- Published: 2026-05-21T04:03:34.000Z
- Updated: 2026-05-21T04:03:34.000Z
- Description: 2026 最新 OpenAI Codex CLI 完整教程：从安装登录、ChatGPT Plus/Pro 订阅额度、模型选择，到国内网络、代理、Windows/WSL2 和 API Key 避坑一次讲清。
- Author: TuBaiBai
- Tags: OpenAI, Codex CLI, AI编程, ChatGPT, 教程, #Import 2026-07-20 07:13

最近我重新把 OpenAI Codex CLI 摸了一遍，结论挺直接：它已经不是早期那个“命令行里陪你聊天写代码”的小工具了，而是 OpenAI 正式推到本地终端、IDE、云端任务、代码审查里的编程 Agent 入口。

如果你平时已经在用 Cursor、Claude Code、GitHub Copilot，Codex CLI 值不值得装？我的判断是：**值得，但不要把它当成万能 IDE。它更适合放在项目目录里，让它改代码、跑测试、解释报错、做小范围重构。**

这篇我按国内用户最关心的几个问题来写：

- Codex CLI 到底是什么，和 ChatGPT 网页版有什么区别？
- macOS / Linux / Windows 怎么安装？
- 用 ChatGPT Plus 能不能用？Free 能不能用？API Key 怎么算钱？
- GPT-5.5、GPT-5.4、GPT-5.4-mini、GPT-5.3-Codex 怎么选？
- 国内登录、网络、额度、代理、权限有哪些坑？
- 新手第一次用，哪些设置必须先改？

我会尽量讲实操，不堆概念。

## 先说结论：Codex CLI 适合谁？

我先把结论放前面，免得你装完才发现不适合。

| 人群                    | 是否推荐     | 我的建议                                         |
| --------------------- | -------- | -------------------------------------------- |
| 已经有 ChatGPT Plus 的开发者 | 推荐       | 直接装，优先用 ChatGPT 登录，不用一开始就折腾 API Key          |
| 偶尔写脚本的小白              | 可以试      | 用 Free / Plus 轻量体验，别一上来让它改大项目                |
| 重度 Claude Code 用户     | 值得备用     | Codex CLI 在 OpenAI 生态、模型选择和本地 Agent 工作流上值得补位 |
| Windows 用户            | 推荐但注意环境  | 原生 PowerShell 可用，复杂开发更建议 WSL2                |
| 国内网络环境用户              | 可以用但要有准备 | 登录、npm 安装、模型请求都可能受网络影响，最好提前准备稳定代理            |
| 想完全免费高强度使用的人          | 不太现实     | Free 可以体验，真正高频工作还是 Plus / Pro / API Key      |

一句话：**Codex CLI 不是“白嫖无限编程神器”，而是一个能接入你本地项目的 OpenAI 编程 Agent。** 它真正的价值在于读项目、改文件、跑命令、根据测试反馈继续修，而不是单纯生成一段代码。

如果你还在比较各种 AI 编程工具，可以顺手看我之前写的《[GitHub Copilot Free 够用吗？和 Cursor / Claude Code 免费方案怎么选（2026）](https://tbbbk.com/github-copilot-free-vs-cursor-vs-claude-code-2026/)》和《[2026 年 AI 编程 IDE 免费额度攻略：Claude、Gemini、Copilot、Cursor 正规白嫖指南](https://tbbbk.com/ai-coding-ide-free-tier-guide-2026/)》，那两篇更偏横向对比；本文只盯着 Codex CLI 落地。

## Codex CLI 是什么？

按 OpenAI 官方说法，Codex CLI 是一个可以在本地终端运行的 coding agent。它可以在你选定的目录里读取代码、修改文件、运行命令，并根据执行结果继续处理问题。

这点很关键：

> ChatGPT 网页版更像“你复制代码给它看”；Codex CLI 更像“你把它放进项目目录，让它自己看、自己改、自己跑”。

比如你在一个 Node.js 项目里运行：

```bash
codex
```

然后告诉它：

```text
帮我找一下为什么 npm test 失败，修复后再跑一遍测试。
```

它理论上会做几件事：

1. 读取当前项目结构；
2. 查看 package.json、测试文件、报错日志；
3. 修改相关代码；
4. 执行测试命令；
5. 如果失败，继续根据错误调整；
6. 最后给你汇报改了什么。

这就是 Agent 和普通聊天机器人的区别。

OpenAI 现在把 Codex 做成了几条入口：Codex CLI、IDE Extension、Codex App、Codex Cloud、GitHub Code Review 等。本文重点讲 CLI，因为它最适合折腾，也最容易被国内用户拿来和 Claude Code 对比。

## 安装前准备：Node.js、npm、系统选择

Codex CLI 官方推荐的安装方式很简单：npm 全局安装。

但我建议你先检查三件事。

### 1\. 检查 Node.js 版本

先看本机有没有 Node：

```bash
node -v
npm -v
```

如果没有，先装 Node.js。Linux/macOS 用户可以用 nvm，Windows 用户可以用 winget 或官方安装包。

我个人更推荐 nvm，因为以后升级、切版本方便：

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install 22
node -v
npm -v
```

如果你在国内机器上执行 curl 经常卡住，先别怀疑 Codex，本质上是 GitHub/raw.githubusercontent.com 的网络问题。这个坑在装很多 CLI 工具时都会遇到。

### 2\. macOS / Linux / Windows 怎么选

Codex CLI 支持 macOS、Linux、Windows。

我的建议：

| 系统             | 推荐方式                       | 原因                          |
| -------------- | -------------------------- | --------------------------- |
| macOS          | 原生终端 + npm                 | 体验最顺，权限和开发工具链都成熟            |
| Linux VPS / 桌面 | 原生终端 + npm                 | 最适合跑自动化和长期任务                |
| Windows 11     | PowerShell 原生可用，复杂项目用 WSL2 | 原生沙箱更方便，但 Linux 项目放 WSL2 更稳 |
| Windows 10 老版本 | 优先 WSL2                    | 控制台、权限、沙箱兼容性更容易踩坑           |

OpenAI 官方 Windows 文档里也提到，Windows 原生可以跑 Codex，也可以在 WSL2 里跑。我的经验是：**如果你的项目本来就是前端、Node、Python、Docker 这些偏 Linux 的工具链，直接 WSL2 更省心。**

这点和我之前写《[OpenClaw Windows 安装教程（2026）：PowerShell 和 WSL2 完整指南](https://tbbbk.com/openclaw-windows-install-guide-2026/)》时的判断类似：Windows 不是不能跑，但开发环境越复杂，WSL2 越少玄学问题。

## Codex CLI 安装步骤

### macOS / Linux 安装

官方 npm 安装命令：

```bash
npm i -g @openai/codex
```

装完检查：

```bash
codex --version
```

启动：

```bash
codex
```

升级到最新版：

```bash
npm i -g @openai/codex@latest
```

如果遇到权限错误，比如 EACCES，不建议直接 sudo 硬装。更稳的方式是用 nvm 管理 Node，这样全局 npm 包会装在用户目录，不容易把权限搞乱。

### Windows 原生安装

Windows 可以在 PowerShell 里装。先确认有 Node.js 和 npm：

```powershell
node -v
npm -v
```

然后：

```powershell
npm i -g @openai/codex
codex
```

如果你是新机器，可以先用 winget 装 Node：

```powershell
winget install OpenJS.NodeJS.LTS
```

然后重新打开 PowerShell，再执行 npm 安装。

Windows 上需要特别注意两点：

1. 终端最好用 Windows Terminal，不要用很老的控制台；
2. 项目路径尽量不要放在奇怪的中文目录、网盘同步目录、权限很乱的目录里。

比如下面这种路径就容易少踩坑：

```text
C:\Users\你的用户名\code\my-project
```

### Windows + WSL2 安装

如果你选择 WSL2，流程是：先在 Windows 里安装 WSL，再进 Ubuntu 装 Node 和 Codex。

PowerShell 管理员运行：

```powershell
wsl --install
wsl
```

进入 WSL 后：

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install 22
npm i -g @openai/codex
codex
```

项目建议放在 WSL 的 Linux home 目录，不要放在 `/mnt/c/`：

```bash
mkdir -p ~/code
cd ~/code
git clone https://github.com/your/repo.git
cd repo
codex
```

原因很简单：`/mnt/c/` 文件 IO 慢，权限和软链接也更容易出怪问题。很多“AI 工具怎么这么慢”的锅，其实不是 AI，是 Windows 挂载路径。

## 登录方式：ChatGPT 订阅 vs API Key

Codex CLI 支持两种 OpenAI 登录方式：

1. 用 ChatGPT 账号登录；
2. 用 OpenAI API Key 登录。

这两个差别很大。

### 方式一：ChatGPT 登录

第一次运行：

```bash
codex
```

它会提示你登录。默认路径通常是打开浏览器，完成 ChatGPT 登录授权，然后回到 CLI。

这种方式适合大多数个人用户，因为 Codex 的订阅权益跟你的 ChatGPT 套餐走。OpenAI 官方文档明确写了：ChatGPT Free、Go、Plus、Pro、Business、Edu、Enterprise 都包含 Codex，只是额度和能力不同。

如果你已经有 Plus，优先用这个方式，不要一上来就用 API Key 烧钱。

### 方式二：API Key 登录

API Key 更适合自动化、CI/CD、服务器脚本、团队共享环境。

你可以从 OpenAI Platform 后台创建 API Key，然后在 Codex 里登录使用。API Key 模式下，费用按 OpenAI API 标准 token 价格计算，不吃 ChatGPT Plus 的本地消息额度。

我的建议：

| 场景                  | 推荐登录方式                                  |
| ------------------- | --------------------------------------- |
| 个人日常写代码             | ChatGPT 登录                              |
| 已经买了 Plus / Pro     | ChatGPT 登录                              |
| GitHub Actions / CI | API Key                                 |
| 公司内网自动化             | API Key 或 Enterprise access token       |
| VPS 无浏览器环境          | device code 或复制 auth cache，实在不行 API Key |

### 无头服务器怎么登录？

很多国内用户会把 Codex 装在 VPS 上，这时浏览器登录可能打不开。官方给了几个方案，我实际更推荐这三个：

第一，优先试设备码登录：

```bash
codex login --device-auth
```

它会给你一个链接和一次性 code，你在本地浏览器打开登录即可。

第二，如果设备码不可用，可以在本地电脑登录后，把 `~/.codex/auth.json` 复制到服务器。但注意：这个文件相当于登录凭证，别发群里，别提交 Git，别贴到工单。

第三，如果只是跑自动化任务，用 API Key 更干净。

## 订阅和额度：Free、Plus、Pro、API Key 到底差在哪？

这一段是很多人最关心的。

OpenAI Codex 现在不是单独卖一个“Codex CLI 会员”，而是包含在 ChatGPT 套餐里。官方定价页写得比较清楚：Free、Go、Plus、Pro、Business、Edu、Enterprise 都包含 Codex，只是额度、模型和功能不同。

### 个人套餐大致怎么理解？

| 套餐      | 官方定位                         | 我的理解              |
| ------- | ---------------------------- | ----------------- |
| Free    | 快速 coding tasks 体验           | 能试，但别指望高强度开发      |
| Go      | 轻量 coding tasks              | 部分地区套餐，国内用户不一定常见  |
| Plus    | 每周几个 focused coding sessions | 最适合普通开发者入门        |
| Pro     | 比 Plus 高 5x / 20x 额度         | 重度用户、长期项目、专业开发更适合 |
| API Key | 按 token 付费                   | 自动化和 CI 好用，但要控制成本 |

Plus 是我认为最适合个人用户的起点。它包括 Codex Web、CLI、IDE extension、iOS，也能用较新的模型，比如 GPT-5.5、GPT-5.4、GPT-5.3-Codex，以及更高额度的 GPT-5.4-mini。

Pro 则是给重度用户准备的。官方写的是可以选择比 Plus 高 5x 或 20x 的额度，价格从每月 100 美元起。这个对个人来说门槛不低，但如果你每天都让 Codex 跑大项目、做 code review、拆任务，确实会比 Plus 更稳。

### 额度不是固定“多少次”

很多人会问：Plus 到底能发多少条 Codex？

官方没有给一个永久固定数字，因为消耗取决于：

- 你选的模型；
- 项目上下文大小；
- 是本地消息还是云端任务；
- 是否跑长任务；
- 是否启用图片生成、fast mode 等更耗额度的功能；
- AGENTS.md、MCP server 等额外上下文有多大。

OpenAI 定价页给了一个按 5 小时窗口估算的范围。比如 GPT-5.5、GPT-5.4、GPT-5.4-mini、GPT-5.3-Codex 的本地消息额度范围不同，小模型通常更耐用。

实操上你只需要记住三句话：

1. **复杂大项目比小脚本更耗额度；**
2. **大模型比小模型更耗额度；**
3. **上下文越臃肿，额度掉得越快。**

如果你想看当前剩余额度，可以去 Codex usage dashboard，也可以在 Codex CLI 会话里用：

```text
/status
```

### 额度用完怎么办？

官方方案主要有几个：

- 等下一个额度窗口恢复；
- Plus / Pro 用户购买额外 credits；
- 切到更小模型，比如 GPT-5.4-mini；
- 本地额外任务改用 API Key，按 API token 计费。

我的建议是：**不要等额度快爆了才优化。** 一开始就养成小任务、小上下文、明确指令的习惯，Codex 会更省也更准。

## 模型怎么选：GPT-5.5、GPT-5.4-mini、GPT-5.3-Codex

OpenAI 官方模型页目前推荐 Codex 优先从 GPT-5.5 开始。它定位是复杂 coding、computer use、知识工作、研究工作流。GPT-5.4-mini 则是更快、更省的轻量模型，适合 routine coding tasks 和 subagents。

你可以临时指定模型启动：

```bash
codex -m gpt-5.5
```

或者在会话里用：

```text
/model
```

我自己的选择逻辑如下：

| 任务                | 推荐模型                    | 原因                 |
| ----------------- | ----------------------- | ------------------ |
| 新项目理解、复杂 bug、架构调整 | GPT-5.5                 | 稳，理解上下文更强          |
| 普通函数、脚本、小修小补      | GPT-5.4-mini            | 快、省额度              |
| 代码审查、复杂工程任务       | GPT-5.3-Codex / GPT-5.5 | 更偏 coding agent 场景 |
| 高频轻量迭代            | 小模型优先                   | 不要把大模型额度浪费在琐事上     |

如果你刚开始用，别纠结太久。先用默认模型，觉得额度掉太快，再切小模型。

## 第一次使用：我建议这样跑

装好以后，不要一上来把 Codex 扔到一个几十万行的祖传项目里，然后让它“全面优化”。这是新手最容易翻车的姿势。

我建议先找一个小项目，或者在大项目里限定范围。

进入项目目录：

```bash
cd ~/code/my-project
codex
```

第一次可以这样问：

```text
先阅读这个项目，不要修改文件。请总结项目结构、启动方式、测试命令，以及你建议我接下来从哪里开始排查。
```

这一步很重要：让它先读，不要马上改。

确认它理解没问题后，再给小任务：

```text
只修改 src/api/user.ts，修复 npm test 里和 user service 相关的失败测试。修改后运行对应测试，不要改其它模块。
```

这比“帮我修一下项目”靠谱得多。

## 权限和安全：别让 Agent 裸奔

Codex CLI 的一个核心设计是 sandbox 和 approval。简单说：它不是默认想干嘛就干嘛。

官方文档里写得很明确：Codex CLI / IDE extension 默认会通过系统级沙箱限制它能碰什么，通常写权限限制在当前 workspace，网络访问默认关闭；需要越界写文件、访问网络、执行某些高风险操作时，会触发 approval。

默认比较常见的模式类似：

```bash
codex --sandbox workspace-write --ask-for-approval on-request
```

这代表它可以在工作区内读写和运行命令，但遇到越界或需要批准的行为会问你。

如果你只是想让它读项目、给建议，可以切只读模式：

```text
/permissions
```

然后选择 read-only。

我非常不建议新手直接上：

```bash
codex --sandbox danger-full-access
```

或者类似“绕过审批和沙箱”的模式。不是说一定会出事，而是你还没建立判断力时，让 Agent 拥有过大权限，风险收益比很差。

这和我在《[OpenClaw 权限设置教程（2026）：exec、shell、危险操作怎么限制](https://tbbbk.com/openclaw-permissions-exec-shell-dangerous-ops-guide-2026/)》里反复说的一样：Agent 能跑命令是生产力，也是风险源。先限制边界，再逐步放权。

## 国内使用避坑：网络、登录、npm、API、付款

这一节才是重点。国内用户用 Codex CLI，真正卡的往往不是命令，而是环境。

### 坑 1：npm 安装很慢或失败

症状：

```text
npm i -g @openai/codex
```

长时间卡住、timeout、registry 请求失败。

处理思路：

1. 先检查 npm registry；
2. 必要时临时切换镜像；
3. 如果包安装成功但运行时访问 OpenAI 失败，镜像并不能解决模型请求问题。

查看 registry：

```bash
npm config get registry
```

临时使用 npm 官方源：

```bash
npm config set registry https://registry.npmjs.org/
```

如果你本地 npm 官方源太慢，也可以临时用国内镜像安装。但我建议安装完再切回官方源，避免一些包版本同步问题。

### 坑 2：ChatGPT 登录打不开

Codex CLI 默认会打开浏览器做 ChatGPT 登录。国内环境常见问题：

- 浏览器页面打不开；
- 登录后无法回跳本地 callback；
- VPS 上没有浏览器；
- 本地代理只代理浏览器，不代理终端。

解决思路：

- 本机使用全局代理或确保终端走代理；
- VPS 优先试 device code；
- SSH 环境可以做 localhost callback 转发；
- 实在不行，用 API Key。

设备码：

```bash
codex login --device-auth
```

如果你用的是远程服务器，还可以考虑 SSH 端口转发官方提到的 localhost callback。思路类似：

```bash
ssh -L 1455:localhost:1455 user@remote
```

然后在这个 SSH 会话里运行 `codex login`。

### 坑 3：浏览器能访问 ChatGPT，但终端不能用 Codex

这是国内用户非常常见的坑。

很多代理软件默认只接管浏览器，不接管终端。你浏览器能打开 ChatGPT，不代表 `codex` 这个进程能访问 OpenAI。

你可以给终端设置代理环境变量：

```bash
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890
```

PowerShell 示例：

```powershell
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"
```

端口不一定是 7890，看你的代理客户端设置。Clash、Mihomo、Surge、Quantumult X、sing-box 都可能不同。

### 坑 4：API Key 和 ChatGPT Plus 不是一回事

这点一定要讲清楚。

你买了 ChatGPT Plus，不代表 OpenAI API 免费。你用 API Key 登录 Codex，消耗的是 Platform API 账单；你用 ChatGPT 登录 Codex，消耗的是 ChatGPT/Codex 订阅额度。

所以普通用户优先级应该是：

```text
ChatGPT Plus 登录 > 不够用再买 credits / 升 Pro > 自动化场景再用 API Key
```

不要因为“API Key 看起来更专业”，一上来就把所有 Codex 任务都切到 API Key。大项目一跑，账单可能比 Plus 贵多了。

### 坑 5：把 auth.json 发给别人

Codex 登录后会缓存凭据。官方文档提到，CLI 可能把登录信息存到 `~/.codex/auth.json` 或系统 credential store。

如果使用文件存储，这个文件很敏感。

不要：

- 发群里让别人帮你排查；
- 提交到 GitHub；
- 贴到博客；
- 放进公开 Docker 镜像；
- 复制给不可信服务器。

如果你要在 VPS 上复制 auth cache，只在自己的可信机器之间做。

### 坑 6：Windows 项目放错位置

WSL2 用户最常见错误：项目放在 `/mnt/c/Users/...`，然后抱怨 Codex 慢、npm 慢、测试慢、权限怪。

建议：

```bash
mkdir -p ~/code
cd ~/code
```

把项目放 Linux home 目录。需要从 Windows 访问时，通过 `\\wsl$\Ubuntu\home\你的用户名\code` 访问。

### 坑 7：让 Codex 一次性改太多

这不是网络坑，是使用姿势坑。

很多人第一次用 Agent 都喜欢说：

```text
帮我优化整个项目。
```

这类指令很容易造成：

- 上下文爆炸；
- 额度消耗快；
- 修改范围不可控；
- review 成本比自己写还高；
- 最后你不知道它到底改了什么。

更好的写法：

```text
只阅读 src/payment 目录，找出可能导致订单重复扣款的逻辑问题。先给分析，不要修改文件。
```

或者：

```text
只修改 tests/user.test.ts 和 src/user.ts，让当前失败的 user 相关测试通过。每次修改后运行 npm test -- user。
```

Agent 越强，越需要你给边界。

## 推荐配置：让 Codex 更省额度、更安全

Codex CLI 和 IDE extension 使用同一个 `config.toml` 配置文件。官方文档里可以设置默认模型、沙箱、网络权限、凭据存储等。

比如设置默认模型：

```toml
model = "gpt-5.5"
```

如果你想更省，可以把默认模型设成 mini，把复杂任务再临时切大模型：

```toml
model = "gpt-5.4-mini"
```

网络权限方面，默认 workspace-write 沙箱通常不开放网络。如果你确实需要让命令访问网络，可以配置：

```toml
[sandbox_workspace_write]
network_access = true
```

但我建议不要无脑开。比如让 Codex 跑测试、改代码，不一定需要网络。只有安装依赖、查远程接口、调用外部服务时才需要。

如果你想限制网络访问范围，官方还提供 network\_proxy 相关配置，可以做域名 allow/deny。对个人用户来说不一定一开始就要上，但团队环境值得研究。

## 一个实际工作流：让 Codex 修 bug

假设我有一个项目测试失败，我会这样用：

第一步，进入项目：

```bash
cd ~/code/my-project
codex
```

第二步，让它只读分析：

```text
请先不要修改文件。阅读 package.json 和测试目录，告诉我这个项目如何运行测试，并判断当前最小可执行的测试命令是什么。
```

第三步，让它跑测试：

```text
运行最小范围测试，记录失败信息。不要修改无关文件。
```

第四步，限定修复范围：

```text
只修复和 user login 失败测试相关的问题。允许修改 src/auth.ts 和 tests/auth.test.ts。修改后重新运行对应测试。
```

第五步，让它总结 diff：

```text
总结你修改了哪些文件、为什么这么改、还有哪些风险需要我人工 review。
```

这个流程看起来麻烦，但比一句“帮我修 bug”稳太多。

## Codex CLI 和 Claude Code、Cursor 怎么选？

简单说：

| 工具             | 更适合                       | 我的评价                 |
| -------------- | ------------------------- | -------------------- |
| Codex CLI      | 终端、本地项目、OpenAI 生态、CLI 自动化 | 适合喜欢命令行和 Agent 工作流的人 |
| Claude Code    | 长上下文、工程理解、终端协作            | 依然是强力竞争者             |
| Cursor         | IDE 内写代码、补全、编辑体验          | 更适合把 AI 融进日常编辑器      |
| GitHub Copilot | 补全、轻量问答、GitHub 生态         | 稳定省心，但 Agent 感没那么强   |

我不会说 Codex CLI 一定替代谁。更现实的组合是：

- Cursor / Copilot 负责日常补全；
- Codex CLI 负责项目级任务、测试修复、命令行自动化；
- Claude Code 作为另一个强 Agent 备用；
- OpenClaw 这类个人助理工具负责跨应用、跨渠道自动化。

如果你关注的是“让 AI 不只写代码，还能接入消息、浏览器、VPS、自动化任务”，可以看《[现在 AI 自动化到底能帮普通人做什么？我筛掉了那些纯噱头玩法](https://tbbbk.com/ai-automation-for-ordinary-people-practical-use-cases-guide-2026/)》和《[OpenClaw 国内使用完整指南：模型选择、网络配置、常见报错一次说清](https://tbbbk.com/openclaw-china-mainland-setup-guide/)》。Codex CLI 是编程 Agent，OpenClaw 更像个人数字助理，两者不是同一个层级。

## 常见报错和处理思路

### command not found: codex

通常是 npm 全局 bin 目录没进 PATH。

检查：

```bash
npm bin -g
```

然后看这个目录是否在 PATH：

```bash
echo $PATH
```

如果你用 nvm，重新打开终端通常能解决。

### npm install 权限错误

不要急着 sudo。

优先用 nvm 重装 Node：

```bash
nvm install 22
npm i -g @openai/codex
```

### 登录后 CLI 没反应

检查几件事：

- 终端是否能访问 OpenAI；
- 本地代理是否接管命令行；
- 是否被公司网络/TLS 代理拦截；
- 是否需要设置自定义 CA。

企业网络如果用了 TLS proxy，官方支持 `CODEX_CA_CERTIFICATE`：

```bash
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login
```

### VPS 登录失败

优先试：

```bash
codex login --device-auth
```

不行再考虑复制 auth cache 或 API Key。

### 额度掉得太快

按顺序排查：

1. 是否用了大模型处理小任务；
2. 是否让它读取整个大项目；
3. AGENTS.md 是否太长；
4. MCP server 是否挂太多；
5. 是否频繁让它生成图片或跑 fast mode；
6. 是否每次都给一大段无关上下文。

解决方法也很简单：小模型、小范围、短指令、先分析后修改。

## 我给新手的最佳实践

最后整理一份我自己的 Codex CLI 使用规则。

### 1\. 先读后改

第一次进入项目，先让它总结结构，不要直接改：

```text
先阅读项目，不要修改文件。总结结构、启动方式、测试方式和潜在风险。
```

### 2\. 每次只给一个小任务

不要“全面优化”。要说清楚目录、文件、测试命令、禁止修改范围。

### 3\. 让它跑测试，但你要 review diff

Agent 跑过测试不代表代码一定没问题。测试覆盖不到的地方，还是要人工看。

### 4\. 敏感文件不要随便给权限

比如 `.env`、生产密钥、数据库备份、用户数据。能不让 Agent 读就不读。

### 5\. 国内用户先解决终端代理

浏览器能上 ChatGPT 不等于 CLI 能上。这个坑能浪费你半天。

### 6\. Plus 用户优先 ChatGPT 登录

不要一上来 API Key。API Key 是按 token 烧钱的，适合自动化，不适合无脑日常试错。

### 7\. 大任务拆成 checklist

比如：

```text
我们分三步做：
1. 先定位失败测试原因，不改文件；
2. 我确认后，只修改最小文件；
3. 跑测试并总结 diff。
```

Codex 这类 Agent 最吃“任务边界”。你边界给得越清楚，它越像同事；你边界不给，它就像一个手很快但不知道轻重的实习生。

## 总结：Codex CLI 值不值得用？

我的答案是：**如果你已经有 ChatGPT Plus，Codex CLI 很值得装；如果你是重度开发者，它甚至值得作为 Claude Code / Cursor 之外的固定工具。**

它的优势是：

- OpenAI 官方维护；
- CLI、IDE、Cloud、Code Review 生态正在打通；
- 支持 ChatGPT 订阅和 API Key 两种登录；
- 本地项目读写、命令执行、测试修复体验完整；
- GPT-5.5 / GPT-5.4-mini 等模型选择比较灵活。

它的坑也很现实：

- 国内网络和登录环境要自己处理；
- 额度不是无限，复杂任务消耗明显；
- API Key 和 Plus 不是同一套账；
- Windows 原生可用，但复杂项目 WSL2 更稳；
- 权限给太大、任务给太宽，容易改出一堆你不敢合并的 diff。

所以我建议的入门路径是：

```text
先用 ChatGPT Plus 登录 → 小项目试用 → 默认沙箱不乱放权 → 学会 /status 和 /model → 再考虑 Pro / API Key / 自动化
```

别把 Codex CLI 当神，也别只把它当聊天窗口。它最舒服的位置，是你项目目录里的第二双手：你给目标、给边界、给测试，它负责快速尝试；最后合不合并，还是你说了算。