OpenAI Codex CLI 完整教程：安装、订阅、额度和国内使用避坑

最近我重新把 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 适合谁？

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

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

如果你还在比较各种 AI 编程工具，可以顺手看我之前写的《GitHub Copilot Free 够用吗？和 Cursor / Claude Code 免费方案怎么选（2026）》和《2026 年 AI 编程 IDE 免费额度攻略：Claude、Gemini、Copilot、Cursor 正规白嫖指南》，那两篇更偏横向对比；本文只盯着 Codex CLI 落地。

Codex CLI 是什么？

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

这点很关键：

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

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

codex

然后告诉它：

帮我找一下为什么 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：

node -v
npm -v

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

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

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。

我的建议：

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

这点和我之前写《OpenClaw Windows 安装教程（2026）：PowerShell 和 WSL2 完整指南》时的判断类似：Windows 不是不能跑，但开发环境越复杂，WSL2 越少玄学问题。

Codex CLI 安装步骤

macOS / Linux 安装

官方 npm 安装命令：

npm i -g @openai/codex

装完检查：

codex --version

启动：

codex

升级到最新版：

npm i -g @openai/codex@latest

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

Windows 原生安装

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

node -v
npm -v

然后：

npm i -g @openai/codex
codex

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

winget install OpenJS.NodeJS.LTS

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

Windows 上需要特别注意两点：

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

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

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

Windows + WSL2 安装

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

PowerShell 管理员运行：

wsl --install
wsl

进入 WSL 后：

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/：

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 登录

第一次运行：

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 的本地消息额度。

我的建议：

无头服务器怎么登录？

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

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

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，只是额度、模型和功能不同。

个人套餐大致怎么理解？

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 会话里用：

/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。

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

codex -m gpt-5.5

或者在会话里用：

/model

我自己的选择逻辑如下：

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

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

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

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

进入项目目录：

cd ~/code/my-project
codex

第一次可以这样问：

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

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

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

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

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

权限和安全：别让 Agent 裸奔

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

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

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

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

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

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

/permissions

然后选择 read-only。

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

codex --sandbox danger-full-access

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

这和我在《OpenClaw 权限设置教程（2026）：exec、shell、危险操作怎么限制》里反复说的一样：Agent 能跑命令是生产力，也是风险源。先限制边界，再逐步放权。

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

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

坑 1：npm 安装很慢或失败

症状：

npm i -g @openai/codex

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

处理思路：

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

查看 registry：

npm config get registry

临时使用 npm 官方源：

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

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

坑 2：ChatGPT 登录打不开

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

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

解决思路：

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

设备码：

codex login --device-auth

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

ssh -L 1455:localhost:1455 user@remote

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

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

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

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

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

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 示例：

$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 订阅额度。

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

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 慢、测试慢、权限怪。

建议：

mkdir -p ~/code
cd ~/code

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

坑 7：让 Codex 一次性改太多

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

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

帮我优化整个项目。

这类指令很容易造成：

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

更好的写法：

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

或者：

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

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

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

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

比如设置默认模型：

model = "gpt-5.5"

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

model = "gpt-5.4-mini"

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

[sandbox_workspace_write]
network_access = true

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

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

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

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

第一步，进入项目：

cd ~/code/my-project
codex

第二步，让它只读分析：

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

第三步，让它跑测试：

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

第四步，限定修复范围：

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

第五步，让它总结 diff：

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

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

Codex CLI 和 Claude Code、Cursor 怎么选？

简单说：

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

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

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

常见报错和处理思路

command not found: codex

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

检查：

npm bin -g

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

echo $PATH

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

npm install 权限错误

不要急着 sudo。

优先用 nvm 重装 Node：

nvm install 22
npm i -g @openai/codex

登录后 CLI 没反应

检查几件事：

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

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

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

VPS 登录失败

优先试：

codex login --device-auth

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

额度掉得太快

按顺序排查：

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

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

我给新手的最佳实践

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

1. 先读后改

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

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

2. 每次只给一个小任务

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

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

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

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

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

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

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

6. Plus 用户优先 ChatGPT 登录

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

7. 大任务拆成 checklist

比如：

我们分三步做：
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。

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

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

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