Codex 使用手册：从 Claude Code CLI 迁移到 Codex

刚开始使用 Codex 时，很容易把它理解成“另一个 Claude Code CLI”。它们都运行在终端里，都能读取项目、执行命令和修改文件，但真正使用一段时间后会发现：两者更像是两套不同的工程工作台，而不只是换了一个模型。

本文记录我从 Claude Code CLI 迁移到 Codex 时最值得掌握的概念、命令和工作方式。

一、Codex 适合做什么

Codex 的核心定位是工程代理。它不只是输出代码片段，而是可以围绕一个目标完成一段完整的工程工作流：

理解陌生项目；
找到相关代码和配置；
修改实现；
运行构建、测试或检查；
根据失败结果继续修复；
查看最终差异并汇报风险。

因此，下面两种提问方式的效果通常不同：

1
打开 A 文件，搜索 B，然后修改 C。

1
2
修复登录超时后没有回到原页面的问题。
保持现有接口兼容，补充回归测试，并说明验证结果。

第一种是在描述操作步骤，第二种是在描述工程目标。第二种方式给 Codex 留出了定位根因和选择实现方案的空间，也更容易在项目结构变化后继续工作。

二、一次任务的推荐流程

一个稳定的 Codex 任务通常可以分为五个阶段：

1. 先说目标和边界

明确希望改变什么，同时说明哪些东西不能改变：

1
2
3
4
给这个 Hugo 博客增加文章更新时间。
只通过项目级 layouts 覆盖主题，不直接修改 themes/stack。
没有 lastmod 的文章不要显示更新时间。
完成后执行生产构建并检查生成结果。

2. 让它先检查现状

对于陌生项目，先使用只读请求：

1
2
理解这个项目，说明架构、启动方式、关键配置和部署链路。
只做分析，不修改文件。

这样可以先发现项目约定、已有未提交修改和环境限制，避免一开始就进入错误目录或覆盖现有工作。

3. 让它实施最小修改

实现阶段应该明确兼容性和范围：

1
2
实现这个功能，不改变公开接口，不增加运行时依赖。
修改范围保持最小，并保留当前工作区已有的修改。

4. 要求验证

“文件已经修改”不等于“功能已经完成”。应该明确要求运行相关测试、构建或静态检查：

1
2
修改后运行最相关的测试；如果失败，继续定位原因并修复。
最后查看 diff，说明哪些检查成功、哪些检查因环境限制没有执行。

5. 查看最终差异

交付前至少检查：

是否只改了任务相关文件；
是否误改了配置、日期或公开接口；
是否留下生成文件；
测试和构建是否真的执行过；
是否有未解决的环境限制。

三、Codex CLI 常用命令

先查看当前安装版本和完整帮助：

1
2
3
codex --version
codex --help
codex <子命令> --help

Windows PowerShell 如果因为执行策略阻止 codex.ps1，可以使用对应的命令文件：

1
2
codex.cmd --version
codex.cmd --help

启动和恢复会话

1
2
3
4
5
6
7
8
9
codex                         启动交互式 CLI
codex "理解这个项目"           带初始任务启动
codex -C <目录>                指定工作目录
codex -m <模型>                临时指定模型
codex -i <图片>                附加图片输入
codex --search                 启用实时 Web 搜索
codex resume                   从列表恢复历史会话
codex resume --last            恢复最近一次会话
codex fork --last              从最近会话创建分支

非交互任务和审查

1
2
3
4
5
codex exec "<任务>"            非交互执行，适合脚本或 CI
codex review                   执行代码审查
codex apply                    应用云端任务产生的最新 diff
codex doctor                   检查安装、配置、认证和运行环境
codex update                   更新 CLI

配置和扩展

1
2
3
4
5
6
codex login                    登录
codex logout                   清除本地认证
codex mcp                      管理 MCP 服务器
codex plugin                   管理插件
codex completion               生成 shell 自动补全
codex features                 查看功能开关

常用启动参数

1
2
3
4
5
6
7
8
-C, --cd <目录>                设置工作目录
-m, --model <模型>             选择模型
-i, --image <文件>             附加图片
-s, --sandbox <模式>           read-only / workspace-write / danger-full-access
-a, --ask-for-approval <策略>  untrusted / on-request / never
--add-dir <目录>               增加可写目录
-c key=value                   临时覆盖 config.toml
--no-alt-screen                保留终端滚动历史

--dangerously-bypass-approvals-and-sandbox 会绕过授权和沙箱。普通开发机不应该使用它；只有在外部环境已经完成隔离的自动化任务中，才有理由考虑这个选项。

四、交互中的斜杠命令

在 Codex 输入框中输入 /，可以打开当前版本支持的命令菜单。命令会随 CLI 版本、模型和启用的功能变化，所以菜单是最可靠的参考。

最常用的命令包括：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
/status             查看会话 ID、上下文占用和限额
/model              切换当前模型
/reasoning          调整推理强度
/permissions        调整当前会话权限
/compact            压缩长会话上下文
/review             审查未提交修改或比较基准分支
/init               生成 AGENTS.md 脚手架
/plan               切换计划模式
/mcp                查看 MCP 连接状态
/apps               浏览连接器
/plugins            浏览插件
/ps                查看后台终端任务
/agent              查看或切换子代理线程
/fork               从当前对话创建分支
/rename             重命名当前会话
/clear              清空界面并开始新会话
/feedback           提交反馈
/exit               退出 CLI

/compact 和 Claude Code 中的同名命令概念接近：在长会话中压缩上下文并保留关键摘要。使用它之前，最好确认重要的约束已经写入 AGENTS.md，或者在后续请求中重新强调。

部分环境还会提供 /fast、/personality、/hooks、/vim、/keymap、/goal、/cloud 和 /local。如果菜单中没有显示，说明当前版本或配置不支持对应功能。

五、值得记住的快捷键

Enter 和 Tab 的区别

这是 Codex 与普通命令行交互很不一样的地方：

Enter：发送当前输入；Codex 工作时可以向当前轮次注入新指令；
Tab：Codex 工作时把输入排队到下一轮；
Esc 两次：在输入框为空时，编辑上一条用户消息，并从那里创建分支；
Ctrl+C：中断或退出当前会话；
↑ / ↓：浏览输入历史或菜单项目；
Page Up / Page Down：在较长界面中翻页。

简单来说：发现当前方向马上错了，用 Enter 纠正；想让它做完当前步骤后再处理另一件事，用 Tab 排队；想保留现有路线并尝试另一种方案，用双击 Esc 分叉。

如果当前版本支持 /keymap，可以检查和修改 TUI 快捷键；支持 /vim 时，可以把输入框切换为 Vim 编辑模式。

六、`AGENTS.md` 是 Codex 的项目说明书

Claude Code 常用 CLAUDE.md，Codex 使用 AGENTS.md 作为项目级持久说明。它适合保存每次工作都应该遵守的内容：

项目架构和关键目录；
构建、测试和格式化命令；
编码规范；
不应该直接修改的区域；
验证要求；
部署和 Git 约定。

例如，一个 Hugo 项目的 AGENTS.md 可以写成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# AGENTS.md

## Commands

- 本地预览：hugo server --buildFuture
- 生产构建：hugo --minify --buildFuture
- 初始化主题：git submodule update --init --recursive

## Conventions

- 新文章使用 Page Bundle。
- 不直接修改 themes/stack。
- 修改后必须执行生产构建。
- 未经明确要求，不改变文章发布日期。

一次性的要求不要写进 AGENTS.md。例如“这次只修改一个文件”属于当前任务的约束，直接在对话中说明即可。

七、权限和沙箱

Codex 不是在一个完全不受限制的 shell 中工作。常见边界包括：

工作区内文件可以读取和修改；
工作区外写入需要授权；
网络访问可能需要授权；
.git 等目录可能具有单独权限；
删除、大范围移动和绕过安全策略的操作会受到更严格限制。

需要额外权限时，Codex 通常会说明命令和用途。授权前应该看清楚具体目标，而不是把所有命令都当成同一种风险。

权限问题和代码问题要分开判断。一个命令因为没有权限执行，不代表实现本身错误；一个命令执行成功，也不代表结果已经验证。

八、自动模式、沙箱和审批策略

Codex 里经常被称为“自动模式”的能力，实际上由两层配置共同决定：沙箱决定命令能访问和修改什么，审批策略决定什么时候需要用户确认。两者不是同一个开关。

1. 交互中切换权限模式

在会话中输入：

1
/permissions

通常可以选择：

Auto：在当前安全边界内自动执行，适合日常开发；
Read Only：只读分析，不修改文件；
自定义权限配置：按当前环境使用已有的审批配置。

权限模式会影响后续操作，直到再次切换。需要审查代码时可以临时切换到 Read Only；开始实现功能时再切回 Auto。

2. 启动时指定沙箱和审批

日常本地开发可以使用：

1
codex --sandbox workspace-write --ask-for-approval on-request

它允许 Codex 在当前工作区内修改文件，遇到需要越界或高风险的操作时再请求授权。

只读理解项目：

1
codex --sandbox read-only

完全关闭沙箱和审批：

1
codex --sandbox danger-full-access --ask-for-approval never

这个组合风险很高，不适合普通开发机。--dangerously-bypass-approvals-and-sandbox（也常见于旧资料中的 --yolo）会同时绕过审批和沙箱，只应在已经由外部环境隔离的自动化运行器中使用。

--full-auto 是旧的兼容参数，当前版本建议使用 --sandbox workspace-write，不要把旧参数当成首选配置。

3. 三种策略怎么选

1
2
3
4
读代码、做架构分析       read-only
普通功能开发             workspace-write + on-request
无人值守的受控 CI         workspace-write，配合严格的工作区和命令约束
生产机或个人目录          不要使用 danger-full-access

自动模式并不意味着“允许一切”。即便选择 Auto，Codex 仍可能因为工作区边界、操作系统权限、企业加密策略或网络策略而无法完成操作。

4. 常见误解

/plan 是规划模式，不是自动执行模式；
/fast 是速度服务档位，不是权限模式；
/permissions 只改变 Codex 的审批行为，不能让它绕过企业透明加密；
--add-dir 适合增加某个明确目录的权限，不应直接把整个磁盘设为可写；
danger-full-access 和 --ask-for-approval never 叠加后，撤销错误操作会非常困难。

九、会话控制和长任务

1. 让会话保持可控

长任务最好分成几个可以验证的阶段：

1
2
3
先分析，不要改文件。
给出方案后再实施第一步。
完成第一步后运行测试，再继续下一步。

发现方向不对时：

用 Enter 立即注入纠正信息；
用 Tab 把新任务排到当前轮次之后；
双击 Esc 编辑上一条消息，并从那里创建分支；
用 /status 查看上下文和会话状态；
用 /compact 压缩已经很长的上下文。

2. 目标和计划

复杂任务可以使用：

1
/plan

它适合先拆解多步骤任务、记录验证点，再开始实际修改。对于简单的单文件修改，不必为了形式强行使用计划模式。

如果当前版本支持持久目标，也可以使用：

1
/goal 完成迁移并保持全部测试通过

目标适合跨多轮持续推进的工作，但仍然需要在每个阶段查看 diff 和验证结果。

3. 并行和分支

不确定两种实现方案时，可以使用 /fork 保留当前对话，再在分支中尝试另一种方案。涉及不同模块的独立任务，也可以使用 /agent 或 /subagents 查看子代理线程。

并行工作并不自动解决冲突。多个线程同时修改同一文件时，仍需要人工审查最终 diff。

十、配置文件和项目规则

除了 AGENTS.md，Codex 还可以通过用户级配置文件保存默认行为。常见的使用层级是：

1
2
3
4
当前提示词       一次性约束
AGENTS.md        项目长期规则
config.toml      个人默认模型、沙箱和工具配置
profile          针对不同项目或工作流的一组配置

临时覆盖配置可以使用：

1
codex -c model="<model>" -c sandbox="workspace-write"

不要把某一次任务的特殊要求写入全局配置或 AGENTS.md。例如“这次只读审查”属于当前任务；“这个仓库永远不能直接修改主题文件”才适合放入项目规则。

项目规则应该描述可验证的约定，例如构建命令、目录边界和测试要求，不要写成无法判断的泛泛要求。

十一、从 Claude Code CLI 迁移时的实际差异

1. 不要假设工具环境相同

两者虽然都在终端中运行，但启动进程、shell、沙箱、配置文件和工具实现可能不同。同一个 Get-Content 或 git 命令，在两个客户端中读到的内容可能不一样。

2. 规则文件不同

可以同时保留：

1
2
CLAUDE.md    给 Claude Code 使用
AGENTS.md    给 Codex 使用

两者可以共享项目事实，但不要假设某个客户端会自动读取另一个客户端的专属规则文件。

3. 任务描述可以更偏向结果

以前如果习惯给 Claude Code 拆解很多 shell 步骤，在 Codex 中通常可以把提示改成最终目标，再补充边界和验收条件：

1
2
审查当前分支相对 main 的变更。
优先发现真实缺陷、兼容性问题和测试缺口，不要修改文件。

4. 验证要求要明确写出

无论使用哪个客户端，都不要默认“代码生成成功”就是“任务完成”。明确要求测试、构建和 diff 检查，结果会稳定很多。

十二、透明加密环境中的一个陷阱

如果电脑安装了企业透明加密软件，文件在磁盘上可能是密文，而被列入白名单的编辑器可以在进程内看到明文。

这会导致一个很容易误判的现象：

IDE 中打开文件是正常中文；
Claude Code 读取文件也是明文；
Codex 或命令行工具读取到 %TSD-Header-###% 和乱码。

这不是 UTF-8 编码问题，而是不同进程拿到的磁盘视图不同。

遇到这种情况，先确认文件头和读取进程，不要尝试手动把 %TSD-Header-###% 替换回 Markdown 头部，也不要对密文执行格式化、批量替换或重新编码。正确做法是使用管理员批准的明文工作流，或让企业加密软件管理员将实际使用的进程加入可信范围。

一个有趣但需要谨慎理解的现象是：新建文件不一定自动加密。加密策略可能依赖文件类型、目录、创建进程和受控程序，不能因为某一个新文件是明文，就断定整台机器没有加密客户端。

十三、常见故障排查

Codex 读到乱码或 `%TSD-Header-###%`

优先判断为透明加密或进程白名单问题，而不是 UTF-8 编码问题。检查文件头、读取进程和文件所在目录，不要直接改文件头或批量重新编码。

命令提示没有权限

先确认命令的目标是否在工作区内，再决定是否通过 /permissions 或一次性授权放行。需要访问工作区外的单个目录时，优先使用 --add-dir，不要直接打开完全访问。

Codex 修改了文件但没有真正完成

检查它是否执行了构建和测试。可以继续发送：

1
2
现在不要解释，直接运行最相关的验证。
如果失败，继续定位并修复，直到给出明确结果。

上下文太长，回答开始重复

使用 /compact，然后重新强调不可违反的约束、当前失败点和验收标准。长期规则应移动到 AGENTS.md，不要依赖模型记住几十轮之前的对话。

Windows 上 `codex` 不能运行

如果 PowerShell 阻止 codex.ps1，尝试：

1
2
codex.cmd --version
codex.cmd --help

Git 子模块或外部目录无法写入

这通常是 Git 配置目录或沙箱边界的权限问题。先确认目标路径，再请求精确的写入授权；不要用完全访问模式掩盖路径配置错误。

十四、以 Hugo 博客为例的推荐工作方式

对一个 Hugo 博客，我会把一次内容任务写成这样：

1
2
3
4
在 AI 分类下新建一篇 Codex 使用文章。
采用现有文章的 Page Bundle 结构和 TOML front matter。
先作为 draft 保存，不要修改已有文章。
完成后检查 Markdown 结构、内部链接和 front matter；如果 Hugo 可用，再执行生产构建。

如果文章已经确定要发布，还需要同步维护文章索引：

更新 posts-index.md 的文章列表；
重新编号；
刷新总数、日期范围、分类统计和系列统计；
确保 Tags 列与 front matter 一致。

内容工作也应该遵守 Git 工作流：先看 git status，修改后看 git diff，确认无误后再提交和推送。

十五、最后的使用建议

刚开始使用 Codex 时，不必记住所有命令。先掌握下面几个就足够覆盖大部分工作：

1
2
3
4
5
6
7
8
9
codex
codex --help
codex resume --last
codex review
/status
/compact
/review
/permissions
/exit

真正影响结果的，通常不是记住更多快捷键，而是把目标、范围、约束和验收标准说清楚，并要求 Codex 给出验证证据。

可以把 Codex 当成一个能够操作工程环境的协作者，而不是只会输出代码片段的聊天机器人：让它先理解真实项目，再进行小范围修改，最后用构建、测试和 diff 证明工作确实完成。

参考：