Codex 使用指南

Codex 是一个运行在终端里的 AI 工程代理——能读取项目、执行命令、修改文件，围绕一个目标完成一段完整的工程工作流。刚接触时容易把它当成“另一个 Claude Code CLI”，但用一段时间会发现：两者更像是两套不同的工程工作台，而不只是换了一个模型。

本文整理 Codex 的核心概念、常用命令和推荐工作方式，并标注它和 Claude Code 的关键差异。

一、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
/status             查看会话 ID、上下文占用和限额
/model              切换模型（并调整推理强度）
/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 能否执行一条命令，不是由单独一个“权限开关”决定的。至少要分清三层：

1
2
3
4
5
操作系统与运行环境        进程本身能访问什么
        ↓
Codex 沙箱               命令允许读写哪些路径、是否允许网络访问
        ↓
审批策略                 哪些操作可以直接执行，哪些必须先征得用户同意

操作系统权限是最外层边界。例如，当前用户本来就无权访问某个目录，调整 Codex 的会话模式也不会凭空获得管理员权限。

1. 权限配置文件决定“能做什么”

新版 Codex CLI 正在引入 Beta 权限配置文件（permission profiles）。一个配置文件可以同时规定文件系统的 read、write、deny 规则，以及命令能够访问哪些网络域名。内置配置文件有三个：

权限配置文件	文件访问能力	典型用途
`:read-only`	本地命令只读	阅读代码、架构分析、代码审查
`:workspace`	可写当前工作区根目录和系统临时目录	日常开发
`:danger-full-access`	移除本地沙箱限制	已有外部强隔离的专用环境

这里的冒号是名称的一部分。:workspace 不代表工作区内所有位置都必然可写，例如它默认仍会保护工作区中的 .git、.codex 等敏感目录。组织管理员还可以限制用户能够选择哪些配置文件。

“工作区”通常是启动 Codex 时指定的目录。可以用 -C 改变工作目录，也可以用 --add-dir 增加某个明确的可写目录：

1
codex -C C:\Projects\MyApp --add-dir C:\Projects\Shared

不要为了访问一个子目录就把整个磁盘加入可写范围。网络、.git 目录及其他敏感位置也可能受到配置文件或运行环境的额外限制，具体以会话状态和审批提示为准。

2. 新旧两套配置不要混用

权限配置文件是新版机制，旧版 CLI 使用 sandbox_mode、sandbox_workspace_write 以及 --sandbox。两套机制不能叠加：

使用新版时，在 config.toml 中设置 default_permissions 和 [permissions.<name>]；
使用旧版兼容方式时，使用 sandbox_mode 或命令行参数 --sandbox；
只要加载的配置中出现 sandbox_mode、启动时传入 --sandbox，或所选 profile 设置了 sandbox_mode，Codex 就会采用旧版沙箱设置，而不是 default_permissions。

因此，看到 :workspace 和 workspace-write 时不要认为它们是两个可以组合的选项：前者是新版内置 permission profile，后者是旧版 --sandbox 的取值。

3. 审批策略决定“何时问你”

审批策略不扩大沙箱边界，它只决定命令在什么情况下需要用户确认：

策略	行为
`untrusted`	只有被判定为可信的低风险命令直接运行，其他命令请求批准
`on-request`	由 Codex 判断何时需要申请额外权限，适合交互式开发
`never`	不弹出审批；命令若被沙箱拦截，失败结果直接返回给 Codex

这里最容易误解的是 never：它表示“永不询问”，并不表示“拥有全部权限”。在旧版兼容配置中，workspace-write + never 仍受工作区沙箱约束，只是越界时不会弹窗申请放行。

4. 看懂一次授权请求

命令需要越过当前边界时，Codex 会展示待执行命令及申请理由。确认前至少检查：

命令准备访问或修改哪个路径；
是否包含安装依赖、联网、删除、提交或推送等副作用；
批准仅适用于这一次操作，还是会记住某类命令前缀；
实际目标是否仍在当前任务范围内。

授予执行权限不等于授权所有业务动作。例如允许调用 git，不等于允许任意提交、改写历史或推送；这类规则仍应写进 AGENTS.md，由 Codex 在执行前单独确认。

权限问题和实现问题也要分开判断：命令被沙箱拦截，不代表代码有错；命令成功执行，也不代表构建、测试和结果检查已经完成。

八、查看、切换与配置权限模式

当前会话的实际权限来自所选 permission profile（或旧版 sandbox）及审批策略。/permissions 显示的是面向用户的 Model Permissions 预设，不应该与 --sandbox 的底层取值混为一谈。

1. 查看当前模式

在交互会话中输入：

1
/status

它会显示当前会话信息。查看其中的 permissions、sandbox 和 approval 相关字段，确认生效的是新版 permission profile 还是旧版 sandbox，以及当前审批策略。不要只根据启动参数推断，因为配置文件、命令行覆盖项和组织策略都可能改变最终结果。

输入 /permissions 会打开权限选择界面，当前选中的配置也能帮助确认会话模式：

1
/permissions

两者的用途不同：/status 适合只查看，/permissions 用于查看并切换。当前没有通用的固定快捷键可以一键轮换权限模式；最快的稳定入口仍是 /permissions，具体按键绑定可以查看 /keymap（如果当前版本提供该命令）。

2. `/permissions` 到底有哪些选项

在 Codex CLI 0.147.0 中，执行 /permissions 会打开 Update Model Permissions，默认提供四个预设：

选项	实际行为	适合场景
`Read Only`	可以读取当前工作区；修改文件或访问互联网前需要批准	阅读代码、代码审查、排查问题
`Ask for approval`	可以读取和修改当前工作区并执行命令；访问互联网或修改工作区外文件前需要批准	普通本地开发，稳妥的默认选择
`Approve for me`	由自动安全审查判断操作风险，只对检测为可能不安全的操作询问	希望减少弹窗、又不想完全放开权限的开发任务
`Full Access`	无需询问即可修改工作区外文件并访问互联网	仅用于你明确接受风险的受控环境

菜单会在当前项后显示 (current)。例如：

1
2
3
4
5
6
Update Model Permissions

  1. Read Only
› 2. Ask for approval (current)
  3. Approve for me
  4. Full Access

四档的核心区别是两个问题：能否直接越过当前工作区 ，以及谁来批准高风险操作 。其中 Approve for me 不是“自动批准一切”，而是把审批交给 Codex 的自动安全审查；Full Access 才是允许工作区外写入和联网且不再询问的高风险模式。

这张菜单仍可能随 CLI 版本、实验功能、permission profiles 和组织管理策略变化。官方文档有时只用 Auto、Read Only 举例，那是对预设的概括，不一定等于特定版本界面的完整菜单。最可靠的依据始终是本机 /permissions 实际显示的内容。

切换只影响后续操作，不会撤销此前已经产生的文件修改。选择完成后，Codex 会提示权限策略已经更新。

3. 新版：用 permission profile 配置默认权限

新版配置文件的最小用法是在 config.toml 中选择一个内置 profile：

1
default_permissions = ":workspace"

另外两个内置值是 :read-only 和 :danger-full-access。还可以定义具名配置文件，例如允许修改工作区、禁止读取 .env，并只允许访问 OpenAI API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
default_permissions = "project-edit"

[permissions.project-edit]
description = "修改项目，但保护环境文件并限制网络目标"
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

启用并允许使用具名 profile 后，它也可能出现在 /permissions 选择器中。权限配置文件目前仍是 Beta，格式和行为可能继续演进。

4. 旧版兼容方式：启动时指定 sandbox

普通本地开发推荐：

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

只读理解项目：

1
codex --sandbox read-only --ask-for-approval on-request

无人值守但已有严格工作区隔离的任务，可以考虑：

1
codex --sandbox workspace-write --ask-for-approval never

完全绕过沙箱和审批的组合风险极高：

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

它只适合外部已经完成强隔离、输入和命令范围也受到控制的自动化运行器，不适合个人开发机、生产服务器或包含重要资料的目录。

5. 配置的选择与覆盖

权限配置可能来自多个位置，理解优先级有助于排查“为什么实际模式和预期不同”：

1
2
3
4
新版：default_permissions + [permissions.<name>]
旧版：sandbox_mode / sandbox_workspace_write / --sandbox
审批：approval_policy / --ask-for-approval
会话中：/permissions

新版 permission profiles 与旧版 sandbox 设置二选一，不能按普通“覆盖层”理解为同时生效。实际结果以 /status 为准。临时需要多写一个目录时可用 --add-dir；需要精确控制路径和网络时，使用具名 permission profile。

6. 推荐选择

场景	推荐方式
阅读代码、架构分析、审查	`/permissions` 选择 `Read Only`，或使用 `:read-only`
普通功能开发	`/permissions` 选择 `Ask for approval`
希望减少人工确认	选择 `Approve for me`，同时保留自动风险审查
需要限定网络域名	自定义 permission profile，配置域名 allowlist
受控 CI 或临时自动化	严格限定工作区或自定义 profile，再按需使用 `never`
生产机、个人目录	避免 `Full Access`、`:danger-full-access` 和绕过安全参数

最后记住几个互不相关的概念：/plan 改变的是工作方式，/fast 改变的是服务速度档位，/permissions 才用于权限配置。Approve for me 仍有自动安全审查，只有 Full Access 才会在工作区外写入和联网时不再询问。

九、会话控制和长任务

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_mode="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 检查，结果会稳定很多。

十二、常见故障排查

命令提示没有权限

先确认命令的目标是否在工作区内，再决定是否通过 /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 证明工作确实完成。

参考：