Codex CLI 怎么用？OpenAI 命令行编程实战

30 秒了解：Codex CLI 是什么、为什么值得装

Codex CLI 是 OpenAI 官方的命令行 AI 编程工具，跑在你本机终端里，背后用 GPT-5 codex 变体模型，让 AI 直接读你项目的文件、改代码、跑命令、提 PR。 跟 Claude Code 是同一类东西，差别是模型换成 OpenAI 的、跟 ChatGPT 订阅联动、有些「长任务规划」上的独有特性。

这篇按官方 cookbook 的 prompting guide + 实战经验，从 0 开始把安装、登录、第一次跑、4 个 prompt 技巧、常见错全部走一遍。看完你能立刻在自己项目里跑起来。

如果你完全不知道 Codex 是什么，先看 Codex 是什么再回来。

准备工作：3 件事先备齐

1. 账号：ChatGPT Plus / Pro 或 OpenAI API key

Codex CLI 跑起来要授权，两种方式：

ChatGPT 订阅：Plus（含有限用量）或 Pro（含大量用量）的账号登录，最直接
OpenAI API key：去 platform.openai.com 申请 key，按 token 付费

如果你已经付了 ChatGPT 钱，直接用账号登——等于「白送编程能力」，不用再开订阅。详见 ChatGPT Plus 值不值帮你判断订阅。

2. 网络：必须能稳定连 OpenAI

Codex CLI 每次操作都要请求 OpenAI API，国内开发者需要稳定的海外网络。详见 ChatGPT 国内能用吗。

国内开发者想跳过这一步，看 Kimi Code CLI 怎么用——国产替代，直连不用代理。

3. 系统：macOS、Linux、Windows 都支持

Mac：Terminal、iTerm2、Ghostty 都行
Linux：bash / zsh / fish 任意
Windows：建议 WSL 或 PowerShell

第 1 步：安装 Codex CLI

OpenAI 把 Codex CLI 打包成一个 npm 包，最简单的装法：

npm install -g @openai/codex

装完跑：

codex --version

看到版本号就 OK。

没装 Node.js 怎么办

Codex CLI 依赖 Node 18+。先确认：

node --version

输出 v18.x 或更高即可。低于 18 或没装的话，最快的办法是用 nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

Windows 直接去 nodejs.org 下安装包。

备选：用 brew（Mac）

brew install openai/tap/codex

brew 装法会自动管依赖，升级也方便：brew upgrade codex。

第 2 步：进项目目录启动

cd ~/projects/你的项目
codex

第一次进交互界面，会让你登录。

第 3 步：登录

Codex CLI 启动后会自动弹出登录提示。两种模式：

模式 A：用 ChatGPT 账号登（推荐）

选 “Sign in with ChatGPT”，会自动开浏览器走 OAuth：

浏览器跳到 OpenAI 登录页
用你的 ChatGPT Plus / Pro 账号登
授权 Codex CLI
回到终端看到 Authenticated 字样

完事。

模式 B：用 API key

适合开发者按 token 计费、或不想用 ChatGPT 订阅：

export OPENAI_API_KEY=sk-...

加到 ~/.zshrc 或 ~/.bashrc 长期生效。然后直接启动 codex 会自动用 API key。

远程服务器登录

SSH 上去的机器没图形界面，OAuth 弹不出浏览器。Codex CLI 会自动切手动流程：终端打印一段 URL，你复制到本地浏览器打开、登录、把 token 粘回终端就行。

第 4 步：写 AGENTS.md 给项目装「记忆」

Codex CLI 启动时会自动读项目根目录的 AGENTS.md，作为持久 system context。第一件事：让 Codex 自己生成一份：

/init

它扫描整个项目，输出一份草稿。你通读一遍、删错的加缺的，commit 进 git。

一个合格的 AGENTS.md 长这样：

# 项目说明

Next.js 14 + tRPC + Prisma 的后台管理系统

# 关键命令

- pnpm dev       开发服务器
- pnpm test      跑测试
- pnpm build     构建
- pnpm typecheck TypeScript 检查

# 约定

- commit 用 Conventional Commits
- 新 API 路由放 src/server/api/routers/
- 不要碰 src/legacy/（在迁移中）
- 测试覆盖率不低于 70%

# 常见坑

- 改 prisma schema 后必须跑 pnpm prisma migrate
- 改 .env 后必须重启 dev server

控制在 200 行以内。写法和 CLAUDE.md 怎么写的思路完全通——AGENTS.md 是同一套理念的 OpenAI 版本名。

第 5 步：第一次对话——3 步示范

步骤 A：让 Codex 认识项目

每次跑新任务之前先「热身」一下，让 AI 有上下文：

📋 Prompt 模板

你好。这是这个项目的第一次 Codex 会话。

在动手改文件之前，请先：

列出项目根目录前两层结构
读 AGENTS.md，用一句话总结你接收到的约定
找 README.md / package.json，告诉我这是个什么项目、用什么栈
如果能找到测试命令，跑一下告诉我当前是不是绿的

做完这 4 件事就停，等我下一步指令。

它会按 4 步走，输出项目摘要。这个开场习惯能省掉后续 90% 的「AI 改错地方」问题。

步骤 B：让它改一个小东西

挑一个能验证的小任务试手。先用「看 diff 再批」的模式：

📋 Prompt 模板

帮我看 README.md 里的安装步骤那段，把所有 npm 改成 pnpm。

要求：

改之前先把改动 diff 给我看
我说 OK 你再保存文件
改完用 git diff 验证一下，确认改对了

Codex 默认要你批准每个写操作，跟它说 yes 才会真改文件。养成这个习惯能避免它一上来就乱改。

步骤 C：让它跑命令

跑 ls -la，告诉我有多少个隐藏文件

Codex 会执行 shell 命令、看输出、给你结论。第一次会问你批准，之后同类命令可以一次批准多个。

4 个 prompt 技巧（来自官方 prompting guide）

OpenAI cookbook 里专门有一篇 GPT-5 codex 的 prompting guide。提炼成 4 个最高 ROI 的技巧：

技巧 1：给「明确退出条件」

模糊任务 AI 容易越界。说清楚「做到什么算完」：

📋 Prompt 模板

任务：把 src/components/Button.tsx 改成支持 loading 状态

完成标准（达到 4 条算完）：

Button 多一个 loading: boolean prop
loading 为 true 时按钮变灰、显示 spinner、disabled
已有单测都还过
新加一个测试 case 验证 loading 行为

不要顺手改任何其他文件。

技巧 2：让 AI「先计划再动手」

对复杂任务，先要它写计划：

📋 Prompt 模板

任务：把 src/api/legacy/ 下所有 callback 风格的 API 改成 async/await

先不要动代码。请：

用 grep 找出所有要改的文件
把它们分成 5 批（每批 5 个左右）
用列表给我看
等我说 OK 你再开始第一批

不要一次性全改完。

这是「PLANS.md 模式」的雏形，详见 Codex PLANS.md 写法（待发布）。

技巧 3：用「角色 + 风格」收紧输出

「你是一个 Senior Rust Engineer，特别讲究 error handling 和性能」——这种角色设定能立刻让输出收敛到对的风格。但别滥用，每次开头都设一遍很啰嗦。常用的放进 AGENTS.md。

技巧 4：失败时让 AI 自己 debug

测试挂了别直接说「修一下」。给它工具：

📋 Prompt 模板

pnpm test 挂了，UserService.test.ts 报错。

请按这个顺序排查：

先看完整报错（不要只看第一行）
读 UserService.ts 和 UserService.test.ts
用 git log — src/services/UserService.ts 看最近 3 次改动
形成一个假设：可能是什么导致挂的
把假设和你打算的修法贴给我，等我批

别上来就改。

这种「先诊断再开药」的 prompt 是处理 bug 的标配。

必备命令速查

命令	作用
`/init`	生成 AGENTS.md
`/help`	显示所有命令和快捷键
`/clear`	清空当前会话，开新的
`/compact`	压缩历史，省 token
`/login`	切换登录账号
`/usage`	查看剩余用量
`Ctrl-C` 一次	打断当前回答
`Ctrl-C` 两次 / `Ctrl-D`	退出 CLI

任何时候忘了，/help 一目了然。

5 个最常见的错怎么修

错误 1：装完 `codex: command not found`

原因：npm 全局装的二进制目录没加进 PATH。

解决：

# 看 npm global 路径
npm config get prefix

# 把 {prefix}/bin 加进 PATH
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

错误 2：`Error: 401 Unauthorized`

原因：API key 失效，或 ChatGPT 订阅过期。

解决：

# 用 API key 模式
echo $OPENAI_API_KEY    # 看 key 是不是空或乱了
# 重新去 platform.openai.com 拿新 key

# 用 ChatGPT 账号模式
/login   # 在 CLI 里重新走 OAuth

错误 3：请求超时 / 网络错误

主要是国内网络问题。Codex CLI 走的是 OpenAI API 海外端点。

解决：

确保你的代理工具支持终端透传（很多 GUI 代理不自动给 CLI 用）
在 shell 里手动设代理：export HTTPS_PROXY=http://127.0.0.1:7890
实在不行换 Kimi Code，国内直连

错误 4：用量超限 `Quota exceeded`

ChatGPT Plus 的 Codex 用量有上限，Pro 用量大但也不是无限。

解决：

看 /usage 当前用了多少
等下个周期重置，或升级到 Pro（约 200 美元/月）
切到 API key 模式按 token 计费

详见 ChatGPT Plus 值不值帮你算账。

错误 5：AI 「不听话」乱改文件

原因：prompt 太模糊、AGENTS.md 没写好、没用「先 diff 再批」习惯。

解决：参考上面 4 个 prompt 技巧，特别是「明确退出条件」+「diff 模式」。

Codex CLI vs Claude Code 快速对比

维度	Codex CLI	Claude Code
公司	OpenAI	Anthropic
模型	GPT-5 codex 系列	Claude Opus/Sonnet
登录	ChatGPT 订阅或 API key	Claude 订阅或 API key
持久记忆文件	AGENTS.md	CLAUDE.md
长任务规划	PLANS.md 官方主推	用户自创
跟 IDE 联动	官方 IDE 插件	通过 ACP
国内可用	需海外网络	需海外网络

详细横评看 AI 写代码完全指南。

一个实战：让 Codex 帮你写 GitHub Actions

假设你想给 Node 项目加 CI：

📋 Prompt 模板

任务：给当前 Node.js 项目加 GitHub Actions CI

需求：

在 .github/workflows/ci.yml 配 push 和 PR 触发
跑 3 个 job：lint（pnpm lint）、test（pnpm test）、build（pnpm build）
用 Node 18 和 20 两个版本矩阵
缓存 pnpm store 加速
任一 job 失败整个 CI 红

要求：

先把 ci.yml 内容贴给我审，我说 OK 再写文件
写完跑 actionlint（如果装了）验证语法
输出一句话「你下次 git push 后应该看到 3 个 check」

跑通这个能让你感受到 Codex CLI 的完整工作流：理解需求、写配置、给你审、写文件、验证。

下一步

Codex 整体介绍 → Codex 是什么
用 Codex 改老代码 → Codex 改写老代码（待发布）
Codex 自动修 CI → Codex 修 CI（待发布）
Codex 长任务规划 → Codex PLANS.md 怎么写（待发布）
Codex Code Review → Codex Code Review 工作流（待发布）
ChatGPT 全功能 → ChatGPT 全功能教程
AI 编程全景 → AI 写代码完全指南

常见问题

Q：Codex CLI 是免费的吗？ A：CLI 本身免费下载，但跑起来要付 OpenAI 的钱：要么 ChatGPT Plus / Pro 订阅，要么 OpenAI API 按 token 计费。免费版 ChatGPT 不能用 Codex。

Q：Codex CLI 跟 Codex Web 有啥区别？ A：CLI 跑在你本机终端，操作你本地文件，适合「现在动手干」。Web 跑在云端，你提交任务关掉浏览器去吃饭，回来看结果，适合「跑 1-3 小时的重型任务」。两个能同时用、互补。

Q：能不能离线用？ A：不能。每次操作都要请求 OpenAI API，没网络做不了任何事。

Q：Codex 会不会改坏我代码？ A：会，但默认每个写操作都问你 y/n。养成 3 个习惯：1) 干活前先 git commit 当前状态，2) 看 diff 再批，3) 干完跑测试验证。改坏 git reset --hard HEAD 就回来了。

Q：跟 Cursor 怎么选？ A：喜欢 IDE 图形界面 → Cursor；喜欢命令行/想跟 ChatGPT 订阅联动 → Codex CLI；同时想要 → 两个并存不冲突，Cursor 写代码 + Codex CLI 跑长任务的组合很多人用。

30 秒了解：Codex CLI 是什么、为什么值得装

准备工作：3 件事先备齐

1. 账号：ChatGPT Plus / Pro 或 OpenAI API key

2. 网络：必须能稳定连 OpenAI

3. 系统：macOS、Linux、Windows 都支持

第 1 步：安装 Codex CLI

没装 Node.js 怎么办

备选：用 brew（Mac）

第 2 步：进项目目录启动

第 3 步：登录

模式 A：用 ChatGPT 账号登（推荐）

模式 B：用 API key

远程服务器登录

第 4 步：写 AGENTS.md 给项目装「记忆」

第 5 步：第一次对话——3 步示范

步骤 A：让 Codex 认识项目

步骤 B：让它改一个小东西

步骤 C：让它跑命令

4 个 prompt 技巧（来自官方 prompting guide）

技巧 1：给「明确退出条件」

技巧 2：让 AI「先计划再动手」

技巧 3：用「角色 + 风格」收紧输出

技巧 4：失败时让 AI 自己 debug

必备命令速查

5 个最常见的错怎么修

错误 1：装完 codex: command not found

错误 2：Error: 401 Unauthorized

错误 3：请求超时 / 网络错误

错误 4：用量超限 Quota exceeded

错误 5：AI 「不听话」乱改文件

Codex CLI vs Claude Code 快速对比

一个实战：让 Codex 帮你写 GitHub Actions

下一步

常见问题

错误 1：装完 `codex: command not found`

错误 2：`Error: 401 Unauthorized`

错误 4：用量超限 `Quota exceeded`