Codex CLI 命令汇总：费曼学习法版

写作原则： 先讲”它是什么”，再讲”怎么用”，最后给” cheat sheet “。
目标读者： 听说过 Codex 但还没用过的人。
核心隐喻： Codex 就像一个”外包程序员”，你只要用自然语言告诉它要做什么，它就会自己改代码、跑测试、提交 commit。

第一部分：Codex 到底是什么？

一句话解释

Codex 是 OpenAI 做的一个命令行 AI 编程助手。 你输入一句话描述，它会：

读取你的代码
理解需求
自动修改文件
跑测试验证
提交 commit

整个过程你只需要说一句人话。

它能做什么？

能力	例子
写新功能	“给这个 API 加一个分页参数”
修 bug	“修复登录时 token 过期的错误”
重构代码	“把这段重复的代码提取成一个函数”
写测试	“给 auth 模块补单元测试”
代码审查	“Review 这个 PR，指出潜在问题”
批量修 issue	同时修 3 个 issue，每个在独立分支

它不能做什么？

不在 git 仓库里跑（必须先 git init）
不保证代码永远正确（需要你 review）
不是 IDE 插件（它是命令行工具）

第二部分：核心概念（三个就够）

概念 1：Exec 模式（一次性任务）

codex exec "你的需求"

就像你雇了一个临时工，说一句话，他干完活就走。

1	codex exec "给 README 加一个安装章节"

概念 2：Sandbox（安全沙箱）

Sandbox 是 Codex 工作时的”隔离房间”。它可以在里面改文件，但不会碰你系统上的其他东西。

模式	权限	什么时候用
`workspace-write`	能改当前项目文件	绝大多数时候用这个
`danger-full-access`	unrestricted	沙箱报错时的 fallback
`--dangerously-bypass-approvals-and-sandbox`	完全无限制	你知道自己在做什么

费曼翻译： Sandbox 就像给 Codex 一个”临时工作室”，它只能在工作室里干活。workspace-write 给它这个工作室的钥匙；danger-full-access 直接把整个房子给它；最危险的那个参数直接把家门钥匙也给它——用的时候要小心。

概念 3：Background（后台跑长任务）

有些任务要跑几分钟，你不用等它，让它后台跑，过一会儿看结果。

1	codex exec --sandbox workspace-write "重构整个 auth 模块"

加上 background=true 参数，它会异步执行。

第三部分：完整命令手册

3.1 安装与登录

# 安装 Codex CLI
npm install -g @openai/codex

# 登录（会打开浏览器让你授权）
codex login

# 验证是否安装成功
codex --version

3.2 基础命令（日常最常用的 5 个）

① 一次性执行：`exec`

# 基本用法
codex exec "你的需求描述"

# 在指定目录执行
codex exec "加一个用户注册 API" --workdir ~/my-project

# 用沙箱模式（推荐）
codex exec --sandbox workspace-write "修一下登录 bug"
# 简写
codex exec -s "修一下登录 bug"

② 代码审查：`review`

# 审查当前分支相对于 main 的改动
codex review --base origin/main

# 审查某个 PR
codex review --base origin/main --pr 42

# 审查指定 diff
codex review --diff "$(git diff origin/main...HEAD)"

③ 交互模式

# 进入交互式对话（像聊天一样连续问）
codex
# 进去之后你可以说：
#   "帮我看看 src/auth.js 有什么问题"
#   "把第 23 行的函数提取出来"
#   它会连续执行你的指令

④ 查看帮助

# 查看所有可用命令
codex --help

# 查看某个子命令的帮助
codex exec --help

3.3 完整参数一览

执行模式参数

参数	全称	作用	默认值
`exec "prompt"`	execute	执行一次性任务	—
`-s, --sandbox workspace-write`	sandbox mode	沙箱模式，自动批准文件修改	off
`--sandbox danger-full-access`	sandbox mode	无沙箱限制（沙箱报错时用）	—
`--dangerously-bypass-approvals-and-sandbox`	bypass all	bypass 一切限制（最危险）	—
`--yolo`	alias	上面那个参数的简写（江湖别名）	—
`-q, --quiet`	quiet	安静模式，少输出	false
`--json`	json output	输出 JSON 格式结果	false

注意： --full-auto 还能用，但官方说它 deprecated 了，建议用 -s 代替。

环境变量

变量	作用	例子
`OPENAI_API_KEY`	OpenAI API key	`export OPENAI_API_KEY=sk-...`
`CODEX_HOME`	Codex 配置目录	`export CODEX_HOME=~/.codex`
`CODEX_TIMEOUT`	超时时间（秒）	`export CODEX_TIMEOUT=600`

3.4 高级用法

在临时目录里跑 Scratch 任务

Codex 必须在 git 仓库里跑，如果你只是想临时测试：

1	cd $(mktemp -d) && git init && codex exec "用 Python 写一个贪吃蛇游戏"

批量修多个 Issue（并行 Worktree 模式）

# 第一步：为每个 issue 创建独立的工作分支
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 第二步：在每个 worktree 里启动一个 Codex
codex exec -s "Fix issue #78: 登录接口返回 500" --workdir /tmp/issue-78
codex exec -s "Fix issue #99: 头像上传失败" --workdir /tmp/issue-99

# 第三步：修完后 push 并创建 PR
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78

# 第四步：清理 worktree
git worktree remove /tmp/issue-78

批量 Review 多个 PR

# 拉取所有 PR 分支
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# 并行 Review
codex exec "Review PR #86: 检查安全问题" --workdir ~/project &
codex exec "Review PR #87: 检查代码风格" --workdir ~/project &

# 把 Review 结果贴到 PR 评论区
gh pr comment 86 --body "$(codex exec '总结 PR #86 的问题')"

后台跑长任务

# 启动后台任务
codex exec -s "重构整个数据库层" --workdir ~/my-project

# 查看正在跑的 Codex 进程
ps aux | grep codex

# 或者用 Hermes 的 process 工具监控
process(action="list")   # 查看所有后台任务
process(action="poll", session_id="xxx")  # 查看某个任务进度
process(action="log", session_id="xxx")   # 查看完整日志
process(action="kill", session_id="xxx")  # 杀掉某个任务

第四部分：常见场景速查表

场景 1：我想让 Codex 加一个功能

1	codex exec "给 /api/users 加一个分页参数 page 和 page_size"

场景 2：我想让 Codex 修一个 bug

1	codex exec "修复登录时 refresh token 不刷新 access token 的问题"

场景 3：我想让 Codex 重构代码

1	codex exec "把 src/utils/ 下的三个重复函数合并成一个通用的"

场景 4：我想让 Codex 写测试

1	codex exec "给 src/auth/ 目录下的所有模块补单元测试，覆盖率要到 80%"

场景 5：我想让 Codex Review 一个 PR

# 先切到 PR 分支
gh pr checkout 42

# 然后 Review
codex review --base origin/main

场景 6：我想批量修 3 个 issue

# 每个 issue 一个 worktree，并行跑
git worktree add -b fix/issue-1 /tmp/issue-1 main
git worktree add -b fix/issue-2 /tmp/issue-2 main
git worktree add -b fix/issue-3 /tmp/issue-3 main

codex exec -s "Fix issue #1: ..." --workdir /tmp/issue-1 &
codex exec -s "Fix issue #2: ..." --workdir /tmp/issue-2 &
codex exec -s "Fix issue #3: ..." --workdir /tmp/issue-3 &

场景 7：沙箱报错了怎么办？

1 2	# 如果 workspace-write 报 bubblewrap/uid map 错误，换这个： codex exec --sandbox danger-full-access "你的任务"

场景 8：Codex 卡住了/没反应

# 1. 确认在 git 仓库内
git rev-parse --git-dir

# 2. 确认已登录
codex login

# 3. 用 --json 模式看详细错误
codex exec --json "你的任务"

第五部分：容易踩的坑（7 个）

坑 1：不在 git 仓库里跑

1
2
3

❌ cd ~/some-random-folder && codex exec "hello"
✅ cd ~/my-project && codex exec "hello"
# 如果没有 git 仓库：cd $(mktemp -d) && git init && codex exec "hello"

坑 2：忘记加 `pty=true`

在 Hermes 里调用 Codex 时，必须加 pty=true，否则 Codex 会卡住不动。

1
2
3

# Hermes terminal 调用
terminal(command="codex exec 'hello'", pty=true)  # ✅
terminal(command="codex exec 'hello'")             # ❌ 会 hang

坑 3：沙箱权限不够

如果看到 bubblewrap / uid map / Permission denied 错误：

1	codex exec --sandbox danger-full-access "你的任务"

坑 4：用了 deprecated 的 `--full-auto`

# 旧写法（还能用，但官方不推荐）
codex exec --full-auto "你的任务"

# 新写法（推荐）
codex exec -s "你的任务"

坑 5：需求描述太模糊

1
2
3

❌ "优化一下"          → Codex 不知道你要优化什么
❌ "修个 bug"          → 哪个 bug？
✅ "把 userService 的查询方法加索引，N+1 查询降到 2 次"

坑 6：长任务没设超时

1 2	# 对于可能跑超过 5 分钟的任务，设超时 terminal(command="codex exec '重构整个项目'", timeout=600)

坑 7：后台任务忘了清理

1
2
3

# 跑完后台任务后记得检查
process(action="list")   # 看看有没有僵尸任务
process(action="kill", session_id="xxx")  # 杀掉不需要的

第六部分：一句话总结

Codex = 说一句话，改一堆代码。
日常用 codex exec -s "你的需求"，90% 的场景这一个命令就够了。
长任务加 background=true，沙箱报错换 danger-full-access，别的没了。

附录：完整命令速查卡

┌─────────────────────────────────────────────────────────┐
│                    CODEX 命令速查卡                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  安装                                                    │
│    npm install -g @openai/codex                          │
│    codex login                                           │
│                                                         │
│  最常用（背这三个就够了）                                   │
│    codex exec "需求"                    → 一次性执行       │
│    codex exec -s "需求"                 → 带沙箱执行       │
│    codex review --base origin/main      → 代码审查        │
│                                                         │
│  高级                                                    │
│    codex exec -s "需求" -q              → 安静模式        │
│    codex exec --json "需求"             → JSON 输出       │
│    codex exec -s "需求" --workdir DIR   → 指定目录        │
│    codex exec -s "需求" --timeout 600   → 设置超时        │
│                                                         │
│  沙箱模式                                                │
│    -s / --sandbox workspace-write      → 推荐默认        │
│    --sandbox danger-full-access        → 沙箱报错时用    │
│    --dangerously-bypass-approvals      → 完全放开（慎用） │
│                                                         │
│  后台任务                                                │
│    用 Hermes terminal(background=true, pty=true)         │
│    用 process(action="list/poll/log/kill") 监控          │
│                                                         │
│  批量修 issue                                            │
│    git worktree add + codex exec + gh pr create          │
│                                                         │
│  常见错误                                                │
│    不在 git 仓库 → 先 git init                           │
│    卡住不动     → 加 pty=true                            │
│    沙箱报错     → 换 danger-full-access                  │
│    需求被误解   → 写更具体的描述                         │
│                                                         │
└─────────────────────────────────────────────────────────┘