OpenAI Codex CLI完整实操指南：模型切换、权限管控、AGENTS.md

前言

本文将带你从零开始，一步步掌握 OpenAI Codex 的完整实操应用。Codex 是专为代码开发设计的 AI 工具，它基于 MCP 协议来拓展工具能力。与主流的代码编辑器不同，Codex 使用 TOML 格式来适配参数，这可能是你遇到的第一个新概念，但不用担心，跟着步骤走，你会发现它非常直观。我们将从最基础的模型切换、推理等级设置开始，逐步深入到命令使用、权限管理，再到 AGENTS.md 记忆、上下文压缩、自定义命令等核心特色功能。最后，还会分享一些实用的操作技巧，帮助你快速上手，提升代码开发效率。

一、模型的切换与推理等级

Codex 默认使用的是 OpenAI 为代码场景量身打造的强大模型——gpt-5-codex，其默认的推理等级为中等。这个模型比普通的 GPT-5 在代码任务上表现更优秀，是 Codex 的专属引擎。你可以通过以下截图快速了解默认设置的样子。

你如果在特定任务中需要使用其他模型，可以随时通过 /model 命令进行切换。在 Codex 的交互界面中，输入 /model 后，你会看到一个类似下图的菜单，可以选择不同的模型并调整推理等级。

除了在界面中操作，你也可以通过命令行参数直接指定模型和推理等级。例如，切换到一个名为 gpt-5.3-codex 的模型：

codex --model gpt-5.3-codex -c model_reasoning_effort="medium"

或者使用更简洁的 -m 参数：

codex -m gpt-5.3-codex -c model_reasoning_effort="high"

1. --model gpt-5.3-codex：指定使用 gpt-5.3-codex 模型。
2. -c：这是配置项参数（set config）的缩写。
3. model_reasoning_effort="medium"：将推理强度设为中等。可选值包括：low（低）、medium（中）、high（高）。推理强度越高，模型生成的代码质量通常越好，但也会消耗更多的计算资源。

二、基础入门

2.1 基础命令速查

掌握以下几个核心命令，你就可以开始使用 Codex 了。这些命令覆盖了从简单的交互式对话到复杂的自动化任务。

# 交互式TUI模式
codex

# 带初始提示启动
codex "fix lint errors"

# 非交互式自动化模式
codex exec "explain utils.ts"

# 沙盒自动模式
codex --full-auto "create the fanciest todo-list app"

# 非沙盒自动模式
codex --dangerously-bypass-approvals-and-sandbox "create the fanciest todo-list app"

下面这个表格通过一些实际例子，帮你理解不同命令的具体用法。

✨	提示词	功能
1	codex "Refactor the Dashboard component to React Hooks"	Codex 会重写类组件，运行 npm test，并显示修改前后的差异。
2	codex "Generate SQL migrations for adding a users table"	Codex 会推断你的 ORM 类型，创建迁移文件，并在沙盒数据库中运行它们。
3	codex "Write unit tests for utils/date.ts"	Codex 会生成测试用例，执行测试，并反复迭代直到所有测试通过。
4	codex "Bulk-rename *.jpeg -> *.jpg with git mv"	Codex 会安全地重命名文件并更新相关的导入/使用语句。
5	codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"	Codex 会提供一步步的解释，帮助你理解复杂的正则表达式。
6	codex "Carefully review this repo, and propose 3 high impact well-scoped PRs"	Codex 会仔细审查你的代码库，并建议 3 个有影响力且范围明确的 Pull Request。
7	codex "Look for vulnerabilities and create a security review report"	Codex 会主动发现并解释安全漏洞，生成一份安全审查报告。

2.2 实用技巧

2.2.1 恢复历史会话

当你的工作被打断，或者想继续之前未完成的任务时，Codex 提供了多种恢复会话的方式。

• codex resume
  ：直接输入这个命令，会弹出一个会话选择器，允许你从列表中选择要恢复的历史会话。

• codex resume --last
  ：使用这个命令可以直接恢复你最近一次开启的会话，非常方便。

• codex resume
  ：如果你知道具体的会话 ID，可以通过这种方式恢复特定会话。你可以在 ~/.codex/sessions/ 目录下找到所有会话，或者在 Codex 中使用 /status 命令查看当前会话的 ID。

下面这张图展示了通过 codex resume 命令选择会话的过程。

2.3.2 AGENTS.md 记忆

AGENTS.md 是 Codex 中一个非常重要的特性，它类似于 Claude Code 的 CLAUDE.md，可以让 AI 记住项目特定的指导。你可以把它想象成给 AI 助手的一份“项目说明书”。

# 全局配置
~/.codex/AGENTS.md

# 项目配置
./AGENTS.md

# 子目录配置
./components/AGENTS.md

你可以通过以下方式创建和管理 AGENTS.md 文件：

• 自动生成
  ：在 Codex 中输入 /init 命令，它会自动分析你的项目并生成一个初始的 AGENTS.md 文件。

• 手动创建
  ：你也可以在项目的根目录、子目录或全局配置目录下手动创建 AGENTS.md 文件。Codex 会按照优先级（子目录 > 项目目录 > 全局目录）来读取这些文件中的指令。

Codex 中的

是一个简单又开放的格式，专门用来指导 Codex 更好地干活。你可以把它想象成是给 AI 助手准备的 README，它提供了一个专门的、可预测的地方，用来提供上下文和指令，帮助 AI 编码助手更好地完成你的项目。更多信息可以访问其官网：https://agents.md/

：默认情况下，Codex 生成的 AGENTS.md 文件内容为英文。你可以直接告诉 Codex，把它“翻译成中文”，或者手动编辑文件内容，以便你和团队成员都能更方便地阅读和修改。

2.3 自定义命令

Codex 支持创建自定义的斜杠命令，它被称为自定义提示词。这些自定义命令的存放路径为 ~/.codex/prompts/。

• 文件必须是 Markdown 格式（.md）。
• 文件名作为命令名称，最终的命令格式为 /filename（例如，创建一个名为 review.md 的文件，那么命令就是 /review）。
• 自定义命令不支持额外参数。这意味着你的提示词必须自包含，即它本身已经足够指导 AI 完成任务，不需要用户再输入额外信息。如果任务需要上下文，提示词应指导 AI 自己去寻找相关文件。
• 新建自定义命令后，需要重启 Codex 命令才能生效。

2.4 使用快捷命令

在 Codex 的交互界面中，输入 / 就能调出所有已支持的快捷命令列表，非常方便。

下面这个表格详细解释了每个快捷命令的功能。

指令	功能说明
/model	切换模型与推理强度。
/fast	以 1.5 倍的速度响应，但会消耗更多额度。
/ide	读取 IDE 中选中的内容，或打开文件作为上下文。
/permissions	配置 Codex 的文件系统操作权限。
/keymap	自定义终端中的快捷键。
/vim	开启或关闭 Vim 编辑模式。
/sandbox-add-read-dir <绝对路径>	允许沙箱读取指定文件夹。
/experimental	启用实验性功能。

2.4.1 快速换行

当你输入的提示词很长时，使用下面的快捷键可以快速换行，让代码看起来更清晰。

• Mac
  ：使用 Option + Enter

• Windows/Linux
  ：使用 Control + J

这个技巧在你输入复杂的、多步骤的指令时特别有用，能让你的提示词结构更清晰，也更容易让 AI 理解。

2.4.2 中断请求 / 退出会话

如果 Codex 正在执行一个你觉得没必要或出错的任务，你可以随时中断它。

• 中断当前请求
  ：按 ESC 键或者 Control + C 键。

• 退出当前会话
  ：再次按 Control + C 键，或者输入 /quit 命令。

三、切换授权模式

Codex 的默认授权模式为 auto。在 auto 模式下，Codex 可以自动读取文件、进行编辑并在工作目录中运行命令。不过，当它需要处理工作目录外的文件或访问网络时，会请求你的同意。

如果你只想和 Codex 聊聊天，或者在进行实际操作前先规划一下，可以使用 /permission 命令切换到 Read Only 只读模式。

如果你需要 Codex 在未经你允许的情况下，就能读取文件、编辑内容、运行命令，甚至处理工作目录外的文件或访问网络，那你可以使用 Full Access 完全访问模式。不过，除非你完全信任当前环境，否则请谨慎使用此模式。

下表对比了四种权限模式的差异，方便你选择。

序号	权限模式	中文名称	核心能力	审批行为	适用场景
1	Read Only	只读模式	仅能读取当前工作目录文件	修改文件、联网操作等全部需手动审批	纯代码阅读、安全审计
2	Ask for approval	请求审批模式	可读写当前目录文件、执行命令	访问外网、修改目录外文件需审批	常规开发、受控环境
3	Approve for me	智能自动放行	可读写当前目录文件、执行命令	仅判定有潜在风险时才弹窗，常规操作自动放行	日常开发（推荐）
4	Full Access	完全无限制访问	可编辑工作区以外文件、自由联网	所有操作不再询问	完全信任环境、临时使用（⚠️高危）

另外，你还可以在启动 Codex 时通过 Flags 参数来精细控制权限，这对于自动化脚本或特定场景非常有用。

模式	标志	说明
自动（默认）	无需标志，默认值	Codex 可以读取文件、编辑文件并在工作区运行命令。但运行沙箱外的命令时会请求批准。
只读	--sandbox read-only 和 --ask-for-approval never	Codex 只能读取文件，并且从不请求批准。
自动编辑，但运行不可信命令时需批准	--sandbox workspace-write 和 --ask-for-approval untrusted	Codex 可以读取和编辑文件，但在运行不可信的命令之前会请求批准。
危险的完全访问	--dangerously-bypass-approvals-and-sandbox（别名：--yolo）	没有沙箱、没有批准（不推荐）。

这样，你就可以通过在启动命令中指定这些 Flags 参数，来精确控制 Codex 的权限范围。

3.1 网络搜索

通过启用 网络搜索 功能，Codex 可以访问互联网上的最新信息，帮助你获取最新的 API 文档、解决依赖问题或提供带有出处的答案。要启用此功能，只需在启动时加上 --search 参数：

codex --search

这种方式可以让你仅使用网络搜索，而避免给 AI 助手完全不受限制的网络访问权限，更加安全。

3.2 引用文件

为了更精确地指导 Codex 工作，你可以通过 @ 符号来快速引用项目中的任何文件。例如，在提示词中输入 @utils/helper.ts，Codex 就会知道你想让它关注这个文件。

在 IDE 插件中使用这个功能会更方便，因为它能让你精确地引用特定文件，防止 Codex 改错文件，提高工作效率。

3.3 输入图像

Codex 支持多模态输入，你可以直接把图片粘贴到编辑器里，作为提示词的一部分。例如，你可以粘贴一张 UI 设计图，让 Codex 生成对应的代码。

当然，你也可以通过命令行，使用 -i 或者 --image 参数来附加图片文件：

codex -i screenshot.png "解释一下这个代码"

codex --image img1.png,img2.jpg "总结一下这些图表"

3.4 脚本功能

Codex 支持非交互式操作，你可以使用 exec 命令，在脚本或 CI/CD 流程中直接运行 Codex：

codex exec "修复这个报错的问题"

例如，你可以用它来自动修复代码中的 lint 错误或测试失败。

3.5 上下文压缩

在进行长时间对话后，上下文可能会变得非常长，从而触发 Codex 的上下文限制。此时，可以执行 /compact 命令来压缩上下文，让对话可以继续。

：请注意，多次使用上下文压缩会导致模型丢失部分细节信息，从而降低精度。因此，在关键任务中，应尽量避免频繁压缩。如果发现模型回答不准确，可以尝试恢复到一个更早的、未压缩的会话。

3.6 查看配置和Token的使用量

使用 /status 命令可以随时查看当前会话的配置信息、使用的模型以及 Token 的使用量，帮助你更好地管理资源。

常见问题

问题1：使用 codex resume 时，提示“未找到会话”怎么办？

这通常是因为你的会话历史记录已被清除或从未成功创建。请确保你的 ~/.codex/sessions/ 目录存在且非空。如果该目录不存在，请先启动一次 Codex 并执行一些操作，然后再尝试恢复。另外，如果使用 codex resume ，请确保会话 ID 是正确的。

问题2：我创建了自定义命令，但重启 Codex 后还是无法使用？

请检查以下几点：

1. 确保你的自定义命令文件（.md）放在了 ~/.codex/prompts/ 目录下。
2. 确保文件名就是命令名，例如 review.md 对应命令 /review。
3. 确保文件内容是一个有效的 Markdown 格式，并且提示词是自包含的，即它本身不需要额外参数。
4. 如果以上都正确，请尝试完全关闭终端并重新打开，再次启动 Codex。

问题3：如何避免在 Full Access 模式下误操作导致数据丢失？

强烈建议不要在日常开发中使用 Full Access 模式。如果你确实需要，请务必做好以下准备：

1. 版本控制
   ：确保你的项目已经使用 Git 等版本控制工具，并且所有修改都已提交。

2. 沙盒测试
   ：先在一个测试项目或沙盒环境中试用 Full Access 模式，确认其行为符合预期。

3. 明确指令
   ：在提示词中清晰地说明你的意图，避免模糊的指令，如“随便改改”。

4. 频繁检查
   ：在任务执行过程中，随时使用 ESC 打断，并检查 Codex 正在执行的操作。

总结

本文系统地梳理了 Codex CLI 的完整实战用法，从模型切换、推理强度调节到会话管理、权限分级，再到 AGENTS.md 记忆、上下文压缩等特色功能，覆盖了日常开发中的核心场景。我们深入探讨了四种授权模式的适用场景与启动参数差异，并介绍了文件引用、图像输入、网络搜索等拓展能力，帮助你最大化发挥 AI 辅助开发的价值。同时，文章也点明了多次上下文压缩会降低模型精度等潜在问题。通过掌握这些全面的实操知识点，你将能够规范地使用 Codex，规避常见问题，从而显著提升代码开发效率。