版本基准：codex-cli 0.146.0（2026-11，Windows 10）。文中每条命令都在本机真实跑过，输出是截的真实结果；界面措辞可能随版本微调，逻辑不变。

你需要：一个 ChatGPT 账号（Plus / Pro / Business / Edu / Enterprise 任一），或者一个 OpenAI API Key。20 分钟能跑通第一次对话。

---

0. 先搞清楚：Codex 是什么，不是什么

很多人第一次听说 Codex 会以为它是"补全插件"。不是。

补全是你在注释里写一句，它猜你下一行。
Codex 是 agent：你把需求说清楚，它自己决定读哪些文件、改哪一行、跑哪条命令，改完把 diff 摆给你看，你点同意它才执行。

它现在有四个入口，别搞混：

形态	怎么进	适合谁
CLI（本教程）	终端里敲 codex	想在任意目录、任意语言上用的人
IDE 插件	VS Code / Cursor / Windsurf 装 OpenAI 插件	已经习惯在编辑器里干活的人
桌面 App	codex app	想要图形界面、多任务面板的人
Codex Web	chatgpt.com/codex	想让它在云端跑长任务、不占本机的人

四个入口共用同一个账号和同一套配置，所以先学会 CLI，另外三个基本不用重新学。

---

1. 安装：三选一，别装两遍

方式 A：官方脚本（推荐，最省事）

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

macOS / Linux：

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

方式 B：npm（我用的这个，方便跟版本）

npm install -g @openai/codex

方式 C：Homebrew（macOS）

brew install --cask codex

三种方式不要混着装。混装的典型症状是：where codex 出来两个路径，你升级了 A，运行时用的还是 B。

验证装好了

codex --version
# codex-cli 0.146.0

然后跑一次自检

这是我认为整个 CLI 里最被低估的命令：

codex doctor

它会把环境、安装方式、沙箱、搜索工具、Git、终端逐项打勾。真机输出（节选）：

Codex Doctor v0.146.0 · windows-x86_64

Notes
   ↑ updates      0.167.0 available (current 0.146.0)

Environment
  ✓ system       zh-CN
  ✓ runtime      npm ... version 0.146.0
  ✓ install      consistent
  ✓ search       file exists (bundled rg.exe)
  ✓ git          git version 2.50.1.windows.1
  ✓ terminal     unknown

看懂这几行就够了：

行	意思	出问题怎么办
updates	有新版本	codex update，或 npm i -g @openai/codex@latest
install consistent	没有混装	显示 inconsistent 就卸掉多余那份
search	自带 rg.exe，检索不用你装 ripgrep	缺失就重装
git	找到了 git	找不到就装 Git for Windows 并重启终端
terminal	是否在真终端里	在 CI / 管道里跑会显示 false，正常

---

2. 登录：两种方式，先想清楚用哪种

方式一：ChatGPT 账号（推荐给个人）

codex

首次启动会让你选登录方式，选 Sign in with ChatGPT，浏览器会自动打开授权页，登录后回到终端即可。

也可以用命令行触发：

codex login

方式二：API Key（推荐给公司环境 / 走代理 / 按量计费）

$env:OPENAI_API_KEY | codex login --with-api-key

注意是从 stdin 读，不是把 key 当参数传——这样 key 不会留在命令历史里。

查登录状态 / 退出

codex login status
# Logged in using an API key - sk-df206***f6d36     ← 会自动打码

codex logout

两个真实坑

1. 公司网络会卡浏览器回调。 表现是浏览器授权完了，终端一直等。直接改用 API Key 方式，别在那等。
2. 没有浏览器的机器（远程服务器、容器）加 --device-auth，它会给你一个码，你在手机上输入。

钥匙别乱贴：login status 之所以打码，就是因为 token 一旦进聊天记录、进 issue、进截图，就等于泄露。我在写这篇时就在某份配置里看到过硬编码的 key，这种一定要换成环境变量。

---

3. 第一次跑通：5 分钟，从零到看到 diff

先建一个练习目录，不要拿生产仓库练手：

mkdir D:\code\codex-demo
cd D:\code\codex-demo
git init
@'
def add(a, b):
    return a - b   # 这里有个 bug
'@ | Set-Content calc.py -Encoding UTF8

然后启动：

codex

第一次进来它会提示你信任这个目录（因为不是它记录过的项目），选信任即可。

说第一句话

坏例子（它只能瞎猜）：

帮我看看代码有什么问题

好例子（给它可验证的目标）：

calc.py 里 add(a, b) 返回的是 a-b，这是 bug。
请改成正确的加法，并补一个 pytest 用例覆盖正数、负数和 0。
改完跑一遍测试确认通过。

好的指令有三个特征：指明文件、说清期望、给一个能自证的验收标准（跑测试）。

接下来你会看到三步

阶段	它做什么	你要做什么
读	自己 ls、cat、搜索，不需要你批准	看它读得对不对
改	生成补丁，终端里以 diff 形式展示	看 diff，这时候还没落盘
跑	要执行命令（pytest、git diff 之类）	弹审批，你选同意或拒绝

审批弹窗通常给三个选择，含义是：

选项	意思	什么时候选
同意（一次）	只批准这一条命令	默认就选这个
同意，且本会话不再问同类	放行这一类操作	你确认过它一直在做安全的事
拒绝并说明	不执行，同时告诉它哪里不对	命令有破坏性、或者方向错了

拒绝时一定要写一句原因（“不要用 rm，用 git clean -n 先看”），它下一轮就会改，这是它比补全强的地方。

收尾

/diff      # 看当前工作区相对 git 的全部改动（含未跟踪文件）
/review    # 让它自己审一遍这次改动
/quit      # 退出

跑通这一次，你就掌握了 90% 的日常用法。剩下的都是在这条主线上加参数。

---

4. 四个必须懂的概念（不懂会一直踩坑）

4.1 沙箱：它能碰什么

启动参数 -s / --sandbox，三档：

档位	能读	能写	能联网	典型场景
read-only	✅	❌	取决于配置	第一次读陌生仓库，只让它分析不动手
workspace-write	✅	✅ 仅当前工作区	取决于配置	日常开发，默认就用这个
danger-full-access	✅	✅ 整个磁盘	✅	只在你确信的隔离环境（容器 / 虚拟机）里用

codex -s read-only      # 只读模式进仓库，先摸结构
codex -s workspace-write

4.2 审批：它什么时候问你

参数 -a / --ask-for-approval：

档位	行为	适合
untrusted	只有 ls、cat 这类"安全命令"自动跑，其余全部问你	第一次用、跑别人的脚本
on-request	模型自己判断什么时候需要问你	最常用，日常默认
never	从不问，失败直接返回给模型自己修	只能配合隔离环境用

两档组合起来就是你的"安全等级"：

组合	等于	建议
read-only + untrusted	保险柜模式	审别人代码、看陌生仓库
workspace-write + on-request	正常开发	90% 的场景
workspace-write + never	半自动	任务很明确、且你有 git 兜底
danger-full-access + never	全自动	只在一次性容器里，别在本机

还有个核弹开关，名字就很诚实：

--dangerously-bypass-approvals-and-sandbox

它同时关掉沙箱和审批。官方文档写得很直白：只用于"已经被外部沙箱隔离"的环境。本机绝对不要用。

4.3 上下文：它为什么会"变笨"

Codex 每次回答都要把"仓库结构 + 读过的文件 + 对话历史"塞进上下文窗口。窗口满了，它会开始忘事、改错文件。

三个动作能救命：

动作	什么时候做
/compact	聊了很久、任务没做完：把历史压成摘要，接着干
/new	换任务了：开新对话，别在一个线程里做三件不相关的事
/status	看当前用掉多少 token、用的什么模型

一句话原则：一个对话只做一件事。修 bug 和写文档放两个线程。

4.4 AGENTS.md：给这个仓库立规矩

这是 Codex 最值得花 10 分钟的功能。在仓库根目录放一个 AGENTS.md，它每次都会先读，相当于"项目说明书"。

在对话里直接：

/init

它会扫一遍仓库，自动生成一份初稿。然后你改成这样（真实可用的模板）：

# AGENTS.md

## 怎么跑
- 装依赖：`pnpm install`
- 跑测试：`pnpm test`（提交前必须绿）
- 类型检查：`pnpm typecheck`

## 代码风格
- TypeScript strict，禁止 `any`
- 组件放 `src/components/`，一个文件一个组件
- 不要新增依赖，除非我明确同意

## 禁区
- 不要改 `migrations/` 下的历史迁移
- 不要动 `.env*`
- 不要 force push

为什么值：新会话、换机器、换同事，规矩都在文件里，不用每次重讲。

同时要警惕：AGENTS.md 是会被当作指令执行的。你 git clone 别人的仓库后第一次用 Codex，先读一遍它的 AGENTS.md，确认没有"把 token 发到某地址"这种句子。这类攻击叫 prompt injection，2026 年已经是真实存在的供应链手法。

---

5. 每天都会用到的 12 个斜杠命令

Codex 的斜杠命令有几十个（输入 / 会弹出完整列表），但日常就这 12 个：

命令	作用	我的使用频率
/model	切换模型和推理强度（reasoning effort）	高
/permissions	当场调沙箱 / 审批档位，不用退出重启	高
/diff	看当前所有改动（含未跟踪文件）	每次提交前
/review	让它审自己的改动	每次提交前
/init	生成 AGENTS.md	每个新仓库一次
/compact	压缩历史，防止上下文爆掉	长任务中途
/new	开新对话	换任务时
/resume	恢复之前的会话	隔天接着干
/status	看模型、token 用量	排查"为什么变笨"
/plan	切到计划模式：先出方案不动代码	大改动之前
/skills	列出可用技能（可复用的操作手册）	有重复劳动时
/mcp	看已接入的 MCP 工具	接外部系统后

/plan 值得单独说：让它先说清楚要改哪几个文件、为什么，你确认了再让它动手。复杂重构前用这一步，能省掉一半返工。

常用快捷键（不同版本的键位可能微调，用 /keymap 查看和修改）：

键	作用
Esc	打断正在跑的生成
Ctrl+C 连按	退出
↑ / ↓	翻历史输入

---

6. 配置文件：~/.codex/config.toml

路径（Windows）：C:\Users\<你的用户名>\.codex\config.toml

这是全局配置，所有项目共用。一份带注释的最小配置：

# 模型与推理强度：不写就用默认；具体有哪些模型先跑 /model 看
model_reasoning_effort = "medium"   # low / medium / high

# 全局默认的安全等级
approval_policy = "on-request"       # untrusted / on-request / never
sandbox_mode = "workspace-write"     # read-only / workspace-write / danger-full-access

# 项目信任：第一次进某个目录它问你"是否信任"，答案记在这里
[projects."D:\\code\\demo"]
trust_level = "trusted"

# Windows 专属：沙箱用哪种权限跑
[windows]
sandbox = "unelevated"

用 profile 管多套配置

想同时有"稳妥模式"和"放开模式"，不要改来改去，用 profile：

# ~/.codex/fast.config.toml
model_reasoning_effort = "low"
approval_policy = "never"

# ~/.codex/safe.config.toml
approval_policy = "untrusted"
sandbox_mode = "read-only"

codex -p fast        # 套用 fast.config.toml
codex -p safe

profile 是叠加在基础配置之上的，所以只写差异项就行。

接第三方 / 自建模型（很多人真正需要的）

Codex CLI 支持把模型指向任何兼容 OpenAI 协议的端点，比如公司内网网关、或第三方模型服务：

model = "你的模型名"
model_provider = "myprovider"

[model_providers.myprovider]
name = "My Provider"
base_url = "https://api.example.com/v1"
wire_api = "responses"          # 有些中转只支持 "chat"，按服务商说明填
env_key = "MYPROVIDER_API_KEY"  # 从环境变量读，不要写死在文件里

配合环境变量使用：

$env:MYPROVIDER_API_KEY = "sk-..."
codex

如果这个端点不需要 ChatGPT 账号，还可以加两行跳过登录流程：

preferred_auth_method = "apikey"
forced_login_method = "api"

安全提醒（血的教训）：config.toml 里如果直接写 experimental_bearer_token = "sk-..." 这种明文 key，任何一次备份、截图、同步、给同事看配置，都会泄露。只用 env_key + 环境变量，并且定期轮换。

---

7. 三种真实工作流（照抄就能用）

工作流 A：修一个 bug

复现步骤：跑 `pnpm test src/cart.test.ts` 会挂，报 expected 99 got 100。
先定位原因，只改必要的地方，改完跑通这个文件和我列的另外两个：
src/cart.test.ts、src/price.test.ts、src/order.test.ts。
不要顺手重构别的文件。

要点：给复现命令、给验收清单、明确"不要顺手改"。最后一句能省掉大量无关 diff。

工作流 B：读一个陌生仓库

codex -s read-only

这个仓库是做什么的？用 200 字说清楚。
然后给我：1) 顶层目录各自职责 2) 一条从 HTTP 入口到数据库的调用链
3) 三个最容易改坏的地方。不要改任何文件。

read-only 很关键：它连写都写不了，你完全不用担心被误改。

工作流 C：批量改造 + 自动审核

把 src/api/ 下所有 fetch 调用换成项目里的 request() 封装（lib/request.ts）。
要求：路径不变、错误处理保持现状、每改完一个文件跑一次 tsc。
全部改完以后，用 /review 审一遍，把风险点列出来。

改完自己审，是把"AI 改错"的成本压到最低的做法。

---

8. 非交互模式：脚本和 CI 里怎么用

交互模式适合人，codex exec 适合流水线：

codex exec "给 src/utils/date.ts 的 formatDate 补单元测试，覆盖时区和闰年" -o result.md

几个常用参数：

参数	作用
--json	输出 JSONL 事件流，方便程序解析
-o, --output-last-message <文件>	只把最后一条回复写到文件
--output-schema <schema.json>	要求最终回复符合指定 JSON Schema
--ephemeral	不落盘会话文件（CI 里推荐）
--skip-git-repo-check	允许在非 git 目录跑
-C <目录>	指定工作根目录，不用先 cd

代码审查也能非交互跑：

codex review --uncommitted      # 审当前未提交的改动
codex review "重点看并发和错误处理"

CI 里的两条铁律：

1. 不要用 --dangerously-bypass-approvals-and-sandbox，除非这个 job 本身就在一次性容器里；
2. 给 codex exec 明确的验收命令（跑测试、跑 lint），否则它无法自证改对了。

---

9. 省钱 + 提速：6 条实测有效

1. 别一直开最高推理强度。 改个变量名用 low，架构设计才用 high。/model 里就能切。
2. 一次只给一个目标。 "修 bug + 写文档 + 升级依赖"三件事一起说，它会三件都做一半。
3. 让它先读 AGENTS.md 和目录树，再动手。跳过这一步的返工率明显更高。
4. 别让它整篇读大文件。 说"只看 src/pay/ 下的文件"，比让它自己 grep 整个仓库省得多。
5. /compact 要主动用。 感觉它开始重复问同样的问题，就是上下文该压了。
6. 同一个问题失败三次就换思路。 继续逼它只会烧 token，把报错原文贴回去 + 缩小范围，比"再试一次"有效。

---

10. Windows 专属的 6 个坑

1. 沙箱是 Windows 受限令牌（restricted token），不是 UNIX 那套。 配置里 [windows] sandbox = "unelevated" 就是这个意思：它用一个没有管理员权限的令牌跑命令。
2. 需要管理员权限的命令一定失败。 装服务、改注册表、动 Program Files，报 Access denied 是正常的，别怀疑装错了。真要做这些，退出 Codex 手动执行。
3. PowerShell 引号。 提示词里含 " 或 $ 时用单引号包，或者写进文件用 codex exec - 从 stdin 读。
4. 中文路径能用，但个别工具会挂。 老版本 MSBuild、部分 Python 包对非 ASCII 路径不友好，报错会指向编译而不是路径。仓库尽量放英文路径。
5. 什么时候必须上 WSL：需要 Linux 工具链（make、gcc、apt）、需要 root、或者项目本来就跑在 Linux 容器里。wsl 里装一遍 Codex 是最省心的。
6. where codex 出现两个路径 = 混装了。卸载一个（npm uninstall -g @openai/codex 或删掉安装脚本那份），再 codex doctor 确认 install consistent。

---

11. 报错急救表

现象	原因	处理
command not found: codex	PATH 没生效	重开终端；npm bin -g 看路径是否在 PATH
一直卡在登录	浏览器回调被拦	改用 --with-api-key
stream error / 401	key 过期或套餐额度用完	codex login status → 重新登录；/status 看用量
改完文件没生效	改的是 diff 预览，没确认	看 /diff；确认审批里点了同意
它反复读同一个文件	上下文接近上限	/compact 或 /new
Access denied	沙箱挡了	换 -s workspace-write；需要管理员就手动跑
中文乱码	终端编码	chcp 65001，或用 Windows Terminal
CI 里报不是 git 仓库	默认要求 git	加 --skip-git-repo-check

---

12. 七天练习计划

天	做什么	目标
D1	装 + codex doctor + 登录	环境绿了
D2	在玩具仓库跑通"改 bug + 跑测试"	看懂审批和 diff
D3	/init 生成 AGENTS.md 并改到能用	以后不用重复讲规矩
D4	-s read-only 读一个真实开源仓库，让它画调用链	建立"先看再改"的习惯
D5	用 /plan 做一次跨 3 个文件的重构	学会先方案后动手
D6	codex exec + --json 写一个小脚本	把重复劳动自动化
D7	codex review --uncommitted 审自己一周的改动	建立"AI 自查 + 人复核"的闭环

七天之后你会有两个变化：一是改代码前先想"这个需求能不能描述成可验收的指令"，二是代码提交前会习惯性跑一次 review。

---

13. 边界：这些事别让它干

• 生产数据库、线上服务器：沙箱再严也挡不住你自己点"同意"。
• git push --force：写进 AGENTS.md 的禁区，并让它用 git push（不带 force）。
• 删目录：宁可让它 git clean -n 列出来，你自己删。
• 跑别人仓库的 AGENTS.md 之前不读一遍：那是可执行的指令，不是文档。
• 把 key 写进配置文件：用环境变量 + 轮换。
• 在 --dangerously-bypass-approvals-and-sandbox 下跑不认识的代码：这个开关是为容器设计的，不是为你本机设计的。

---

最后

Codex 的上手成本主要在前 20 分钟：装、登录、看懂那三次审批。过了这一关，后面的收益是复利的——你写指令的能力，直接决定它交付的质量。

一个判断标准：如果你发现自己在反复跟它说同样的话，说明那句话该进 AGENTS.md 了。

有问题欢迎在评论区贴你的报错，尤其是 codex doctor 的输出，那个信息量最大。