首页 / 阶段二 / Codex

Codex：把同一件事搬进终端

OpenAI 的编码 agent，装在终端里。你在 ZCode 里做过的三件事——开目录、提需求、审 diff——这里一模一样，只是界面变成了纯文字。它没有「最强的模型」这种绝对优势，但它是理解「agent 到底怎么工作」最直接的一课：你会亲眼看到它读文件、跑命令、报错、自己修。

命令行需境外网络 ChatGPT 订阅或 API Key 开源仓库 openai/codex

一句话定位

终端里的结对程序员。适合已经能看懂一点代码、或者要批量改文件的人。完全没碰过代码的人也能用，但学习曲线比 ZCode 陡。

01装之前确认两件事

检查项	为什么
Node.js 已装（`node -v` 有输出）	npm 安装方式依赖它。见第 0 课。
能访问 `chatgpt.com` 和 `registry.npmjs.org`	安装包和登录都走这两个地方。第 0 课有自检命令。
有一个 ChatGPT 账号（付费）或 OpenAI API Key	两种认证方式选一种，后面讲。

02安装

三种方式，选一种就行。不要同时装多个，容易互相覆盖。

方式一：npm（最通用，Windows 上也走这条）

Windows PowerShell / macOS Terminal全局安装

npm install -g @openai/codex

国内网络建议先换 npm 镜像（第 0 课），否则这个包会下很久。装完后如果提示 codex 不是内部或外部命令，是 npm 全局 bin 目录不在 PATH——运行 npm config get prefix 查看路径，把它加进系统环境变量。

方式二：Homebrew（仅 macOS）

macOS Terminal装的是 cask 版本

brew install --cask codex

方式三：官方安装脚本（macOS / Linux / WSL）

macOS / Linux / WSL从 chatgpt.com 拉取安装脚本

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

Windows 用户的现实情况

Codex 的主支持平台是 macOS、Linux 和 WSL。原生 Windows 上通过 npm 安装通常能跑起来，但遇到「命令执行异常、路径解析怪怪的」这类问题，优先换成 WSL 里装（在 WSL 里它和 Linux 上一模一样）。这不是玄学，是官方支持的边界问题。

验证

两个系统都一样能打印版本号就成功

codex --version

03登录：两种方式

方式 A：账号登录（推荐）

终端会打开浏览器让你登录 ChatGPT 账号

codex login

如果这条命令提示不存在，说明你的版本用的是另一种写法，直接跑 codex --help 看当前版本支持哪些子命令——这一步比记命令重要，因为这类 CLI 的子命令时不时会改名。

用账号登录时，额度按你的 ChatGPT 订阅走。免费账号可能能用但额度很少，具体以官方说明为准。

方式 B：API Key

Windows PowerShell当前窗口生效，关了就没了

$env:OPENAI_API_KEY = "sk-你的key"

macOS / Linux写进 ~/.zshrc 才能永久

export OPENAI_API_KEY="sk-你的key"

Key 在 OpenAI 平台的 API Keys 页面创建，创建时只显示一次，务必当场存好。按 token 计费，agent 一次任务可能调用几十次，先去后台设一个消费上限再开始用。

04基本用法：一条最重要的规矩

先 cd 进项目目录，再运行 codex

它不是「打开就能用」的程序。它把当前目录当成工作范围。在 C:\Users\你 里直接敲 codex，它看到的范围是整个用户目录——这是很危险的操作。正确顺序永远是：cd 到项目 → 再 codex。

标准启动流程以 Windows 为例，路径换成你的

# 1. 进项目目录
cd D:\projects\my-site

# 2. 确认目录对了（能看到你的文件）
ls

# 3. 启动交互会话
codex

进入之后就是一个对话界面：你输入需求，它读文件、给方案、改代码、跑命令，每一步通常要你确认。输入 /help 或在会话里问「你有哪些可用命令」，可以列出当前版本的全部操作。

非交互用法：一条命令干一件事

示例（子命令名以 codex --help 为准）适合写进脚本、定时任务

codex exec "把 src 目录下所有 console.log 删掉，改完列出改了哪些文件"

这种「一句话进、结果出」的模式，是后面 OpenClaw 定时任务的基础形态。先在这里试通，再搬到别处。

05进阶：让它少犯错的三件事

1. 给它一份「项目规矩」

在项目根目录放一份说明文件（官方 README 里的名字是 AGENTS.md），写清楚：这个项目是干什么的、代码风格、不要动哪些目录、跑测试用什么命令。它每次启动都会读，等于把「新人入职手册」交给了 agent。

AGENTS.md 里值得写的内容越具体越有用

# 项目说明
这是一个静态站点，只有 html/css，没有构建步骤。

## 约定
- 不要引入任何 npm 依赖
- 修改前先说明你要改哪几个文件
- 所有文案用简体中文，不要用 emoji

## 不要碰
- assets/original/ 下是原始素材，只读

2. 控制审批与权限

默认它会为写文件、跑命令请求你确认。不要为了「顺手」把全部审批关掉。真嫌烦，就限定范围：让它只在一个子目录里工作，而不是放开全盘。

3. 用 Git 当安全网

开工前先存档，出事一条命令回滚比任何「撤销」功能都可靠

cd D:\projects\my-site
git init
git add -A
git commit -m "使用 agent 前的存档"

# 出问题想全部还原
git checkout .

06三个实战

实战一：给旧项目补文档

「读这个目录下的所有代码，写一份 README：项目是做什么的、怎么运行、每个目录负责什么。不确定的地方标『待确认』，不要编。」 这类「只读 + 产出文档」的任务风险最低，适合作为第一次真跑。

实战二：批量修改（最能体现价值）

「把 8 个 html 页面里的联系电话统一改成 138xxxx，改完给我一份清单，列出每个文件改了几处。」 手工改要半小时，它两分钟，而且有清单可核对。关键是那句「给我清单」——没有清单你就没法验收。

实战三：让它自己修 bug

「运行 npm run build，看报错，修掉。修完再跑一次确认通过。不要改业务逻辑，只修让它能构建的问题。」 给它一个可验证的终点（构建通过），比「修一下这个 bug」有效得多。

07踩坑与排错

现象	原因与处理
`codex` 命令找不到	npm 全局 bin 不在 PATH。跑 `npm config get prefix`，把输出路径加进环境变量后重开终端。
登录时浏览器打不开	网络问题。确认能访问 chatgpt.com；必要时改用 API Key 方式。
提示额度不足 / 401	账号套餐不含该功能，或 key 无效/欠费。换认证方式试。
它在错误的地方改文件	启动前没 cd 到项目目录。退出，重新 cd 再启动。
中文路径/文件名出问题	换纯英文路径下的项目副本试一次，能区分是工具问题还是环境问题。
装了两个版本，行为不一致	`which codex`（macOS）或 `where.exe codex`（Windows）看它实际用的是哪个，卸载多余的。

08边界

它不会「理解你的业务」。上下文全靠你给的：哪个文件、什么约束、验收标准。
它可能自信地做错。所以「看 diff」和「跑验证」这两步永远不能省。
它不替你负责。生产环境的操作，人必须在场。

这一课学到的通用能力

--help 自查、cd 限定范围、Git 兜底、给可验证的终点。这四条在任何命令行 agent 上都成立，包括下一页的 Claude Code。

官方安装脚本：https://chatgpt.com/codex/install.sh · 源码仓库：github.com/openai/codex
子命令与参数会随版本变化。任何命令报「不存在」时，先跑 codex --help 看当前版本支持什么，不要照抄过时的教程。