Codex 上手教程：是什么、安装、登录与首次实战

先说结论：Codex 不用单独订阅

很多人第一次找 Codex，会去搜"Codex 多少钱一个月"——其实搜不到单独的价格。Codex 是 OpenAI 的终端编程 Agent，已经打包进了 ChatGPT 的订阅里：只要你有一个能登录的 ChatGPT 账号，登进去就能用，额度直接走你订阅档位的池子，不另外计费。

所以真正要决定的不是"买不买 Codex"，而是"ChatGPT 订阅买哪一档"。下面按官方信息，把 Codex 是什么、怎么装、怎么登录、首次怎么用、撞到 401/429/登录失败怎么排查、各档对 Codex 的定位，一次讲清楚。

Codex 到底是什么

把 Codex 理解成"住在你终端里的一个编程助手"最直观。它不是一个网页聊天框，而是一个能直接读你项目目录、改文件、跑命令的 Agent。你用自然语言描述要做的事，它把任务拆成步骤，自己读代码、写代码、运行验证，再把结果交回给你确认。

Codex 现在主要有三种形态，背后是同一份 ChatGPT 订阅额度：

终端 CLI：主力形态，装在本地命令行里，直接对着你的代码仓库干活。本文重点讲这一条。
IDE 插件：在 VS Code、Cursor 这类编辑器里以侧边栏形式出现，改动能直接落到当前打开的文件上。
Codex 网页版 / 云端任务：把任务丢到云端跑，适合耗时长、不需要盯着的活。

关键一点：这三处共用同一个订阅额度池。你在 CLI 里跑了一批任务，网页版那边能用的额度也跟着减少——它们算的是同一份钱，不是各发各的。理解这点，后面规划额度才不会算错。

哪一档够用

Codex 跟着 ChatGPT 的订阅走，主流是这几档（以下为 OpenAI 官方定价，2026 年 6 月；最终以官方实时页面为准）：

Free（$0）：能体验，额度很小，跑两三个任务就到顶，只适合先看看是不是你要的东西。
ChatGPT Plus（$20/月）：官方给的是一个范围而非固定值，5 小时窗口内大致是几十个本地消息、外加一批云端任务，单人日常开发够用。
Pro 5x（$100/月）：额度按官方说法约为 Plus 的 5 倍，适合一天大半时间都在让 AI 写代码的人。
Pro 20x（$200/月）：再往上一档，官方口径约为 $20 档的 20 倍上限，团队或重度用量才用得满。

有一点要先说清楚：这些档位的差别，主要体现在重度、编程、Codex、API 这类高强度场景上。如果你只是在网页或 App 里聊聊天、偶尔问点问题，不同档位的体感差别不大；真正吃档位的，正是 Codex 这种连续跑任务、动辄几十轮上下文的用法。所以"要不要升档"这个问题，对纯聊天用户和重度 Codex 用户的答案完全不同。

各档对 Codex 的定位

换个角度，按"你打算怎么用 Codex"来对：

档位	官方月费	对 Codex 的典型定位
Free	$0	只够试水，跑几个任务就撞顶，不能当生产力
Plus	$20	个人开发者主力档，单人一天写代码基本压得住
Pro 5x	$100	重度日更、几乎全天挂着 Codex 的人
Pro 20x	$200	团队协作或多项目并行的极重度用量

选档的判断很简单：先上 Plus，真碰到天天撞额度上限、等窗口刷新影响干活，再往 Pro 升。别一上来就买顶档，多数个人开发者 Plus 就压得住。具体每档实际能跑多少，官方给的是区间、还会随负载浮动，不写成绝对承诺，以官方实时说明为准。

装到本地：三种系统都能装

Codex 的主力形态是终端 CLI，装一次就能在命令行里跑。官方提供两种安装方式，挑顺手的一条即可。

方式一：用 npm（Windows / Mac / Linux 通用）

有 Node.js（官方建议 22 以上）的话，一条命令全平台通用：

npm install -g @openai/codex

包名是 @openai/codex，带 @openai 前缀——npm 上那个不带前缀的 codex 是 2012 年的无关老包，装错了会一脸懵、还以为是 Codex 坏了，这是最常见的坑之一。装前先用 node -v 确认 Node 版本到位，版本太老 CLI 起不来。

方式二：Mac 用 Homebrew

Mac 用户嫌装 Node 麻烦，也可以走 Homebrew 直接装：

brew install --cask codex

装完先验一下

不管走哪条，装完都先验证版本，能打印出版本号就说明装好了：

codex --version

如果提示 command not found，多半是 npm 的全局 bin 目录没进 PATH，或者 Homebrew 装完没刷新终端。重开一个终端窗口、或检查一下全局安装路径有没有加进 PATH，通常就好了。Windows 上如果在普通 CMD 里不认，换 PowerShell 或确认 npm 全局路径已配好。

登录：用 ChatGPT 账号还是 API Key

第一次运行 codex 会让你登录，主要两条路。

用 ChatGPT 账号（推荐）

选 "Sign in with ChatGPT"，CLI 会在本机起一个本地回调端口（默认 localhost:1455），同时浏览器弹出 OpenAI 的官方登录页。你用平时那个 ChatGPT 账号登进去、授权，浏览器把令牌送回 CLI，终端这边就提示登录成功了。整个过程走的是官方 OAuth，不需要你手动复制任何 Key。

一旦登录成功，你的 ChatGPT 订阅额度就在 CLI、IDE 插件、Codex 网页版之间共用一个池子，三处算同一份额度。

如果你是在远程服务器、没有图形浏览器的环境里（比如 SSH 上去的 Linux VM），浏览器弹不出来，可以走设备码（device code）登录：CLI 给一段码，你在另一台有浏览器的机器上输码授权即可；或者把远端的 localhost:1455 端口转发回本地浏览器。这条是无头环境的标准解法（部分账号需先在账号安全设置里开启设备码登录）。

用 API Key

如果你自己单独管理 API 计费，也可以走 Key 认证。但要知道这条路按用量另算钱，和你的 ChatGPT 订阅额度是两套账，且部分功能（如云端任务）受限，不适合纯订阅用户。

对绝大多数订阅用户来说，第一条就是正解——不用碰 Key，登录即同步。

首次使用：从打开到第一个任务

登录完就能让它干第一件活了，基本流程：

进到你的项目目录再起 Codex。Codex 默认以当前目录为工作区，进错目录它就读不到你想改的代码。
用一句话描述任务。比如"读一下 main.py，告诉我这段为什么慢"，或者"给 utils 里的 format_date 补几个测试"。描述越具体，它来回确认的次数越少、越省额度。
看它的改动建议，再决定要不要执行。Codex 在动你的文件、跑命令前一般会先征求确认，别一路盲按同意，尤其是删改文件、跑安装命令这种动作，扫一眼它要干啥再放行。
跑不对就接着说。它给的版本未必一遍到位，把问题指出来让它继续改，比自己从头写快。

有个习惯值得一开始就养成：随时用 /status 看一眼当前额度用量和窗口刷新时间，做到心里有数，别等撞限了才发现窗口空了。

能拿它干什么

真实用下来，Codex 最顺手的是这几类活：

读代码、定位问题：丢一段跑得慢的函数过去，让它指出瓶颈在哪、给出改写版本，比自己逐行盯快。
修 bug、做重构：把报错信息连同代码贴给它，或直接说"把这个 for 循环改成 map"，文字能讲清的改动它基本一遍能给到位。
从零写脚本：批量重命名、数据清洗这类一次性小工具，描述需求让它整段生成，连基本的错误处理都会带上。对标准库和主流框架的调用，准确度通常较高，但生成结果仍建议自己跑一遍再用，别直接上生产。
补测试：给个函数签名，它能铺出多个测试场景，边界值和异常输入也会覆盖一部分，省掉手写测试的体力活。

常见卡点：401 / 429 / 登录失败

新手装好之后最容易卡在这三类报错上，逐个说清怎么看、怎么处理。

401 Unauthorized：登录态出问题了

表现通常是 CLI 报 "No auth credentials found" 或 "exceeded retry limit, last status: 401 Unauthorized"，明明浏览器里 Codex 能用，CLI 这边却不认。这是登录凭据没拿到或失效，不是你账号坏了。常见处理：

重新登录一次：退出 Codex，重新跑登录流程，让它刷新本地凭据，多数情况这一步就解决。
清掉过期的本地凭据：登录信息存在本地配置文件里，旧令牌过期没被刷新就会持续 401。可以先把旧的凭据文件备份挪走，再重新登录生成新的。
远程 / VM 环境特别容易中招：没有图形界面的 Linux 服务器上，登录写凭据和后台进程读凭据有时序问题，会出现"密钥明明对、却一直 401"。这种环境优先走设备码登录，少踩坑。

429 Too Many Requests：撞额度上限了

如果 Codex 前面还好好的，突然开始 429，基本就是撞到了 5 小时窗口的额度上限。这不是 bug，是档位到顶了。报错里通常会带一个 reset time（恢复时间）：

等窗口刷新：额度会自己恢复，看报错里的 reset time，到点就能继续。
换号或升档：手上有别的可用 ChatGPT 账号可以切过去；如果是天天撞限，说明该考虑从 Plus 升 Pro 了。
先用 /status 确认：撞限前用 /status 看用量，别凭感觉，能提前知道还剩多少。

登录失败 / 浏览器弹不出来

登录环节卡住，常见几种：

浏览器没自动弹：把 CLI 给出的那段授权链接手动复制到浏览器打开即可；远程环境直接走设备码登录。
端口被占：本地回调端口（默认 1455）被别的程序占了，登录回调收不到。关掉占用的程序，或按官方说明换端口重试。
账号开了高级安全设置：部分开了 security key 等高级账户安全的账号，CLI 登录可能多一步验证。按提示走完即可，反复失败时换浏览器登录流程试试。

省额度：实战里最容易踩的坑

前面说的 5 小时窗口，新手最容易栽的地方是把额度浪费在"碎问题"上——一个 bug 问一次、改个空格再问一次，几轮下来窗口就空了，正经活还没干。几个省额度的实战习惯：

攒着批量问：有 3 个函数要优化，写成一条"按下面要求优化这 3 个函数"，别拆成 3 次。
一次说清再让它改：它给的代码未必一遍完美，把所有要调的地方列全了一起提，而不是改一点问一点。
非紧急任务错峰跑：能离线、不赶时间的活挪到深夜这类低峰时段，排队短、重试少。
本地能跑的别占云端：Codex 本地和云端任务都支持，可离线的非关键任务走本地，少消耗云端额度。

另外要心里有数：官方给的额度是一个区间、不是死数，实际还会随负载浮动，撞限前用 /status 看一眼比凭感觉猜稳。

新手避坑清单

把前面散落的坑点收成一张清单，第一次上手对着过一遍：

包名别装错：一定是 @openai/codex，不带前缀的 codex 是另一个无关老包。
Node 版本要够：官方建议 22 以上，太老的 Node 起不来，先 node -v 看一眼。
认清额度是共用的：CLI、IDE 插件、网页版共一个池子，别以为各发各的。
别一上来买顶档：个人开发者先 Plus，撞限再升，多数人 Plus 就够。
动文件前看一眼：改文件、跑命令前 Codex 会确认，别盲按同意，尤其删改和安装类。
生成结果先自己跑：准确度高不等于零错，上生产前自己验一遍。
远程环境走设备码：没图形界面的服务器别死磕浏览器弹窗，直接设备码登录。

和 Claude Code 怎么选

这两个是目前第一梯队的终端编程 Agent。粗略说，Codex 的优势在背靠 ChatGPT 生态、订阅相对便宜、对主流框架熟；Claude Code 则以分析深度和长上下文见长。真要选，主要看你手上已经在养哪个大模型的订阅——别为了用工具再多开一份会员。按预算怎么配，展开对比见下方延伸阅读。