Codex CLI 常用命令与实战用法总结

Codex CLI 是 OpenAI 推出的终端 AI 编程工具。它可以在本地代码仓库中读取项目、修改文件、运行命令、生成补丁、解释代码、修复 bug，并支持交互式和非交互式两种使用方式。官方仓库对它的定位是：一个运行在本地电脑上的轻量级编程 Agent。(GitHub)

如果你习惯在终端里写代码，Codex CLI 很适合用来做这些事：

阅读和理解代码库
修复 bug
添加小功能
重构代码
生成测试
解释报错
检查 Git diff
做代码 review
批量修改文件

一、安装 Codex CLI

官方推荐两种安装方式。(GitHub)

npm 安装

npm install -g @openai/codex

Homebrew 安装

brew install --cask codex

安装完成后，进入项目目录，直接运行：

codex

首次使用时，可以选择使用 ChatGPT 账号登录。官方建议 Plus、Pro、Business、Edu、Enterprise 等 ChatGPT 计划用户通过 ChatGPT 登录使用 Codex；也可以使用 API Key，但需要额外配置。(GitHub)

二、最常用命令速查

下面是日常最常用的一组命令。

codex

启动 Codex 交互式终端界面。

codex "Explain this codebase to me"

启动 Codex，并直接给它一个初始任务。官方文档也给出了类似用法，用于让 Codex 解释当前代码库。(OpenAI 开发者)

codex -C ./my-project

指定工作目录后启动 Codex。-C 或 --cd 用来设置 agent 开始处理请求前的工作目录。(OpenAI 开发者)

codex -m gpt-5.4

指定本次使用的模型。-m 或 --model 可以覆盖配置文件中的模型设置。(OpenAI 开发者)

codex -s read-only

以只读沙箱启动，适合只想让 Codex 阅读、解释、分析代码时使用。--sandbox 支持 read-only、workspace-write、danger-full-access。(OpenAI 开发者)

codex -s workspace-write

允许 Codex 在当前工作区内写文件，适合让它修改代码。

codex -a on-request

设置审批策略。--ask-for-approval 可以控制 Codex 什么时候需要暂停并请求人工确认。官方文档中列出的值包括 untrusted、on-request、never。(OpenAI 开发者)

codex resume

恢复之前的交互式会话。官方文档说明，codex resume 可以通过会话 ID 继续，也可以恢复最近一次对话。(OpenAI 开发者)

codex exec "Run tests and fix failing cases"

非交互式执行任务，适合脚本或 CI 场景。codex exec 也可以简写为 codex e。(OpenAI 开发者)

codex update

检查并更新 Codex CLI。官方命令参考中列出 codex update 用于在当前安装版本支持自更新时检查并应用更新。(OpenAI 开发者)

三、两种核心使用模式

Codex CLI 最重要的是两种模式：

交互式模式：codex
非交互式模式：codex exec

四、交互式模式：适合日常开发

进入项目目录：

cd my-project
codex

进入后，你可以像和一个结对程序员对话一样下指令。

例如：

请阅读这个项目，告诉我整体架构。

请找出用户登录流程相关的代码，并解释调用链路。

请修复当前测试失败的问题，修改前先给出计划。

请帮我为 auth 模块补充单元测试。

官方文档说明，交互式模式会启动全屏终端 UI，Codex 可以读取仓库、修改文件、运行命令，并让用户实时审查它的操作。(OpenAI 开发者)

适合交互式模式的任务

理解陌生项目
定位 bug
小范围重构
补测试
解释报错
代码 review
逐步实现功能

推荐工作方式

我建议每次让 Codex 写代码前，先让它给计划：

请先阅读相关文件，给出修改计划。不要立刻改代码。

确认计划后再说：

按这个方案修改代码，并在修改后运行测试。

这样可以减少它误改代码的概率。

五、非交互式模式：适合自动化和批处理

非交互式模式使用：

codex exec "你的任务"

或者简写：

codex e "你的任务"

官方文档说明，codex exec 用于脚本化或 CI 风格的运行，适合不需要人工交互、执行完就结束的任务。(OpenAI 开发者)

示例一：解释项目

codex exec "Summarize this repository: architecture, entry points, and key modules."

示例二：运行测试并修复

codex exec "Run the test suite, identify failures, and fix them. Keep changes minimal."

示例三：生成变更说明

codex exec "Read the current git diff and write a concise changelog entry."

示例四：批量检查代码风格

codex exec "Review the codebase for inconsistent error handling and suggest improvements."

从 stdin 传入任务

官方文档中提到，codex exec 的 prompt 可以是字符串，也可以用 - 从 stdin 读取。(OpenAI 开发者)

cat task.md | codex exec -

这适合把较长的任务说明写进文件，再交给 Codex 执行。

六、常用参数详解

1. 指定工作目录：-C / --cd

codex -C ./frontend

适合在 monorepo 中只处理某个子项目。

也可以用于 exec：

codex exec -C ./backend "Fix the failing API tests"

2. 指定模型：-m / --model

codex -m gpt-5.4

适合不同任务切换模型。

一般建议：

复杂重构、疑难 bug：用更强模型
简单解释、生成注释：用更快模型

3. 设置沙箱权限：-s / --sandbox

codex -s read-only

只读模式，适合分析代码。

codex -s workspace-write

允许修改当前工作区，适合正常开发任务。

codex -s danger-full-access

高风险模式，除非你非常确定，否则不建议使用。

官方文档也特别提醒，--dangerously-bypass-approvals-and-sandbox 会绕过审批和沙箱，只应在外部已经隔离加固的环境中使用。(OpenAI 开发者)

4. 设置审批策略：-a / --ask-for-approval

codex -a on-request

让 Codex 在需要时请求人工确认。

codex -a never

不请求审批，适合 CI 或自动化任务，但风险更高。

建议日常开发使用：

codex -a on-request -s workspace-write

这样既能让 Codex 修改工作区，又不会完全失控。

5. 附加图片：-i / --image

codex -i screenshot.png "根据这个截图修复页面样式"

--image 可以把一张或多张图片附加到初始 prompt 中。官方文档说明，多张图片可以用逗号分隔，也可以重复传入该参数。(OpenAI 开发者)

适合这些场景：

根据 UI 截图修样式
分析报错截图
对照设计稿改前端页面

6. 启用搜索：--search

codex --search "Check whether our usage of this library matches current docs"

--search 会启用实时 Web 搜索，官方说明它会把 web_search 设置为 live。(OpenAI 开发者)

适合：

查最新 API 文档
确认库的最新用法
排查新版本 breaking change

7. 使用配置 Profile：-p / --profile

codex -p frontend

--profile 用来加载 ~/.codex/config.toml 中的配置 profile。官方文档说明，Codex CLI 的大多数默认值来自 ~/.codex/config.toml，命令行中的 -c key=value 会覆盖当前调用的配置。(OpenAI 开发者)

适合给不同项目准备不同配置：

frontend profile
backend profile
readonly profile
ci profile

七、交互式 Slash Commands

进入 codex 交互界面后，可以输入 / 打开 slash command 菜单。官方文档说明，slash commands 可以在不离开终端的情况下切换模型、调整权限、压缩长对话、查看状态等。(OpenAI 开发者)

最常用的有这些。

/status

查看当前会话状态，包括模型、审批策略、可写目录和上下文容量等。(OpenAI 开发者)

/status

建议每次重要修改前看一眼，确认当前权限和模型。

/model

切换当前模型。官方文档说明，可以通过 /model 选择活跃模型，并用 /status 验证切换结果。(OpenAI 开发者)

/model

适合从快速模型切到更强模型处理复杂问题。

/permissions

调整 Codex 可以不经确认执行哪些操作。官方文档说明，/permissions 用于在会话中放宽或收紧审批要求。(OpenAI 开发者)

/permissions

建议在不同阶段切换：

阅读代码阶段：Read Only
修改代码阶段：Auto 或 workspace-write
危险操作阶段：要求确认

/plan

切换到计划模式，让 Codex 先给方案再执行。官方文档说明，/plan 适合在开始实现前让 Codex 提出执行计划。(OpenAI 开发者)

/plan

推荐在复杂任务前使用：

/plan 请给出修复支付回调重复扣款问题的排查和修改方案。

/diff

查看当前 Git diff，包括未被 Git 跟踪的文件。官方文档说明，/diff 适合在提交或运行测试前审查 Codex 的修改。(OpenAI 开发者)

/diff

这是最常用、也最重要的命令之一。

/review

让 Codex review 当前 working tree。官方文档说明，/review 可在 Codex 完成工作后运行，也可以用作本地变更的第二双眼睛。(OpenAI 开发者)

/review

适合在 commit 前使用。

/compact

压缩当前可见对话，释放上下文。官方文档说明，/compact 会总结当前对话，避免长会话撑爆上下文窗口。(OpenAI 开发者)

/compact

长时间调试时很有用。

/mention

把具体文件或目录加入对话上下文。官方文档说明，/mention 用于指出希望 Codex 接下来检查的文件或文件夹。(OpenAI 开发者)

/mention

适合精确控制上下文：

请重点阅读 src/auth/login.ts 和 tests/auth.test.ts。

/clear、/new、/quit

/clear

清空终端并开始新聊天。

/new

在同一个 CLI 会话里开始新对话。

/quit

退出 Codex。官方文档也说明 /quit 和 /exit 都可以退出 CLI。(OpenAI 开发者)

八、推荐的日常开发流程

我个人推荐这套流程。

第一步：先让 Codex 理解项目

codex

然后输入：

请阅读这个项目，说明：
1. 项目主要功能
2. 技术栈
3. 入口文件
4. 关键模块
5. 本地开发和测试命令
不要修改代码。

第二步：给出明确任务

请修复用户登录失败时错误提示不准确的问题。先定位相关文件，给出修改计划，不要立刻改代码。

第三步：确认计划后再执行

按这个计划修改。要求：
1. 保持改动最小
2. 不要重构无关代码
3. 修改后运行相关测试

第四步：查看 diff

/diff

第五步：让 Codex 自查

/review

第六步：自己确认后提交

git add .
git commit -m "fix: improve login error message"

这套流程的核心是：

先理解
再计划
再修改
再看 diff
再 review
最后提交

不要一上来就让 Codex “直接帮我改”。

九、常见任务 Prompt 模板

1. 解释代码库

请阅读当前代码库，输出：
1. 项目用途
2. 技术栈
3. 目录结构
4. 核心模块
5. 启动命令
6. 测试命令
7. 新人最应该先读的 5 个文件
不要修改代码。

2. 修复 bug

请修复这个 bug：

现象：
xxx

期望：
xxx

要求：
1. 先定位原因
2. 给出修改计划
3. 经确认后再改代码
4. 保持改动最小
5. 补充或更新测试

3. 添加功能

请实现这个功能：

功能描述：
xxx

要求：
1. 先阅读相关模块
2. 给出实现方案
3. 尽量复用现有代码风格
4. 添加必要测试
5. 最后说明修改了哪些文件

4. 重构代码

请重构这个模块：

目标：
xxx

限制：
1. 不改变外部行为
2. 不修改公共 API
3. 每一步改动尽量小
4. 修改后运行测试
5. 输出重构前后的主要变化

5. 生成测试

请为这个模块补充测试：

目标文件：
xxx

要求：
1. 覆盖正常路径
2. 覆盖边界情况
3. 覆盖错误输入
4. 使用项目现有测试框架和风格
5. 不引入不必要依赖

6. 代码 Review

请 review 当前 git diff，重点检查：
1. 潜在 bug
2. 安全问题
3. 边界条件
4. 性能问题
5. 测试是否充分
6. 是否有不必要的复杂度

十、安全使用建议

Codex CLI 很强，但也要谨慎使用。

1. 默认不要给最高权限

优先使用：

codex -s read-only

或：

codex -s workspace-write -a on-request

不要轻易使用：

codex --dangerously-bypass-approvals-and-sandbox

官方文档明确提醒，这个参数会在没有审批和沙箱的情况下运行所有命令，只应在外部已经加固的环境中使用。(OpenAI 开发者)

2. 修改前先 commit

使用 Codex 前，建议保持工作区干净：

git status
git add .
git commit -m "checkpoint before codex"

这样即使 Codex 改错，也可以回滚。

3. 每次都看 diff

/diff

不要不看改动就直接提交。

4. 让 Codex 少改无关代码

Prompt 里明确写：

保持改动最小，不要重构无关代码。

5. 涉及生产数据、密钥、部署命令要人工确认

尤其是这些命令：

删除文件
修改数据库
执行迁移
推送代码
发布生产环境
处理密钥

都不应该完全交给 AI 自动执行。

十一、我的常用命令组合

只读分析项目

codex -s read-only "Explain this repository architecture. Do not modify files."

安全修改代码

codex -s workspace-write -a on-request

非交互式修复测试

codex exec -s workspace-write -a never "Run tests and fix failures. Keep changes minimal."

这个更适合隔离环境或 CI，不建议在重要本地工作区直接无脑使用。

指定目录处理

codex -C ./packages/web -s workspace-write

附带截图修 UI

codex -i ./screenshot.png "Fix the UI to match this screenshot."

恢复上次会话

codex resume --last

官方文档说明，codex resume --last 默认在当前工作目录范围内恢复最近会话，--all 可以包含其他目录的会话。(OpenAI 开发者)

十二、总结

Codex CLI 最适合的定位，不是“自动替你写完整个项目”，而是一个在终端里的 AI 结对程序员。

它最常用的命令可以分成几类：

启动交互：codex
指定任务：codex "..."
非交互执行：codex exec
恢复会话：codex resume
指定目录：-C / --cd
指定模型：-m / --model
控制权限：-s / --sandbox
控制审批：-a / --ask-for-approval
查看状态：/status
查看改动：/diff
代码审查：/review
压缩上下文：/compact
退出会话：/quit

最推荐的使用原则是：

复杂任务先 plan
修改前先 checkpoint
执行中控制权限
修改后看 diff
提交前做 review

把 Codex CLI 用好，不是让它无限制地自动写代码，而是让它在可控权限、清晰任务和明确边界下，提高你理解代码、修改代码和验证代码的效率。