Codex CLI：权威技术参考指南

**简而言之：**Codex 是一款多界面编程智能体：它能够读取代码库、在操作系统级沙箱中运行命令、修改文件，并将任务委派到云端。掌握五大系统——config.toml、沙箱与审批模型、AGENTS.md、MCP 和 skills——便能让它成为效率倍增器。**模型选择：**OpenAI 的模型文档目前建议将复杂编程和智能体任务交给 GPT-6.1 Sol（gpt-6.1-sol，自 v0.159.1 起成为 CLI 的内置默认模型），将最棘手的端到端任务交给 GPT-6-Astra，并将目标明确、可重复的任务交给 GPT-6 Luna。可用性取决于套餐、客户端和工作区设置；GPT-6 Sol 和 GPT-5.6 系列模型仍会保留在模型选择器中，而通过 ChatGPT 登录 Codex 时，GPT-5.5 将于 2026年10月14日停止提供。^139164171 初次使用？可直接前往安装和快速入门。想要跟踪版本发布？最新稳定版为 v0.162.1（2026年10月9日），在 v0.162.0 的基础上包含两项修复；v0.162.0 默认启用了即时中断功能。版本亮点首先概述当前状态（哪些功能已默认启用，哪些仍处于实验阶段），随后逐一介绍各个版本；更新日志则列出了本指南的每次更新。^116171175176

Codex 是一款多界面编程智能体，而非仅仅会编写代码的聊天机器人。CLI 能够读取代码库、在沙箱中执行命令、修改文件、通过 MCP 连接外部服务，并将长时间运行的任务委派到云端。它在本地运行，却能统筹全局；同一种智能能力可根据工作方式服务于五个不同界面，其中包括浏览器扩展（支持 Chrome、Edge、Brave、Opera 和 Vivaldi），让 Codex 在浏览器中运行，同时不会接管浏览器。⁹⁰¹²⁷

**能否高效使用 Codex，关键在于五大核心系统。**掌握这些系统，Codex 便能成为效率倍增器：

1. 配置系统：通过 config.toml 控制行为
2. 沙箱与审批模型：限制 Codex 可执行的操作
3. AGENTS.md：定义项目级运行约定
4. MCP 协议：将能力扩展至外部服务
5. Skills 系统：封装可复用的领域专业知识

我花了数月时间，在生产代码库、CI/CD 流水线和团队工作流中同时使用 Codex 与 Claude Code。本指南将这些经验凝练为一份完整参考手册——正是我初次使用时求之不得的资料。每项功能都附有实际语法、真实配置示例，以及即使经验丰富的用户也容易踩到的坑。

要点概览

• 5种使用界面，同一个核心：CLI、桌面应用、IDE扩展、云端任务以及浏览器扩展（支持Chrome、Edge、Brave、Opera和Vivaldi）均使用同一模型系列，因此请选择最契合自身工作流的界面。⁹⁰
• 操作系统级沙箱：Codex在内核层面实施文件系统和网络限制（macOS使用Seatbelt，Linux使用Landlock + seccomp），而非依赖容器内部的限制机制。
• AGENTS.md可跨工具使用：您的项目指令可用于Codex、Cursor、Copilot、Amp、Jules、Gemini CLI、Windsurf、Cline、Aider、Zed以及60,000多个开源项目。一次编写，处处使用。
• 配置文件可减少上下文切换开销：定义命名配置预设（fast、careful、auto），并通过--profile在它们之间切换。
• 上下文管理至关重要：Codex内置模型目录为GPT-6.1 Sol、GPT-6 Astra、Sol、Luna以及GPT-5.6系列提供272K上下文窗口（API中列出的GPT-6.1 Sol、GPT-6 Sol和Luna为1.05M）；在GPT-5.5于2026年10月14日退出Codex之前，其上下文窗口为400K。使用/compact、聚焦明确的提示词和@file引用，主动管理token预算。^83112171

如何使用本指南

这是一份超过3,300行的参考指南——请根据您的经验水平选择起点：

文末的快速参考卡以便于快速浏览的形式汇总了所有主要命令。

版本亮点：近期更新内容

以下按版本逐一记录 Codex 的发布进展，最新版本在前，便于读者持续跟踪。初次接触？请直接跳至“快速入门”；要顺利上手，无需了解以下内容。验证详情（版本比较、提交列表、文档检查）见脚注。

当前状态

截至2026年10月14日的 Codex CLI

• **稳定版：**v0.162.1（10月9日，npm latest），包含2项修复；此前的 v0.162.0（10月8日）默认启用 instant_interrupt，并新增 worktree 工具、Command Center 置顶和对话记录复制功能；v0.161.0（10月7日）则新增 /mcp login、语音设备选择、默认启用基于 API 密钥的模型发现，以及可选择启用的 Daybreak 标志。
• **Alpha：**npm alpha 为 0.163.0-alpha.11（10月14日），前一版本 alpha.10 发布于10月13日；0.163 系列尚未发布稳定版。
• **自 v0.159.1 起的默认模型：**GPT-6.1 Sol，取代 GPT-6-Astra，Amazon Bedrock 亦是如此。如需继续使用其他模型，请在 config.toml 中设置 model。v0.162.1 的内置模型目录与 v0.159.1 所列模型相同。
• 自 v0.162.0 起默认启用：instant_interrupt，因此新输入会抢占模型响应（在 [features] 下设置 instant_interrupt = false 可将其关闭）；该标志仍被标记为开发中。
• **自 v0.161.0 起默认启用：**基于 API 密钥的模型发现（在 [features] 下设置 api_key_model_discovery = false 可将其关闭）。
• **自 v0.158.0 起默认启用：**向提权终端输入内容时需要审批（在 [features] 下设置 write_stdin_approval = false 可将其关闭），全屏 TUI 还支持选中即复制和右键粘贴（在 [tui] 下分别设置 copy_on_select = "never"、right_click_paste = "off" 可将其关闭）。Guardian 线程上下文始终启用；thread_context 会被忽略。
• **自 v0.157.0 起默认启用：**全屏对话记录（在 [tui] 下设置 fullscreen_transcript = false 可将其关闭）和后台服务器自动启动（在 [features] 下设置 daemon_auto_start = false，或使用 --no-daemon）。
• 自 v0.156.0 起默认启用：/voice、托管 worktrees、Guardian 父级压缩结果复用。
• **可选择启用或实验性功能：**Codex Cloud、代码模式及其排序工具搜索（code_mode_tool_search，v0.162.0）、Daybreak（cli_daybreak，v0.161.0）、Guardian 历史记录检索（guardian_conversation_history_tools，v0.160.0）。实验性上下文管理目前不可用。
• **模型：**GPT-6.1 Sol 适合复杂编码，GPT-6-Astra 适合难度最高的工作，GPT-6 Luna 适合可重复任务。GPT-6 Sol 和 Luna 默认采用 Fast（消耗2.5倍额度）；GPT-6.1 Sol 则不会。GPT-5.5 将于2026年10月14日退出 Codex。
• 固定版本：npm install -g @openai/codex@0.162.1，然后运行 codex --version。^{169171179180181182}

v0.162.1（2026年10月9日）

**在 v0.162.0 基础上新增3次提交，包含2项修复。**异步问题包含多行内容时导致 TUI 崩溃的问题已修复，同时保留换行和完整的超链接目标地址。部分 v0.162.0 用户遇到的启动失败问题也已解决：此前，正在运行的后台服务器功能设置与 CLI 默认值存在差异，便会触发该问题；现在，兼容性检查仅应用于明确指定的命令行功能覆盖项。默认设置、配置键和模型均未发生变化。

建议操作：升级。若早期版本的后台服务器仍在运行时 v0.162.0 拒绝启动，则尤其应当升级。¹⁸¹

v0.162.0（2026年10月8日）

**instant_interrupt 默认启用。**v0.159.0 首次提供该标志时需要选择启用，它允许新输入抢占模型响应，或让运行时间较长的代码模式调用让出控制权。从此版本开始，该功能面向所有用户启用（PR #51812，于10月7日合并）；不过仍被标记为开发中。若要恢复旧行为，即让键入的输入等待响应完成，请在 [features] 下设置 instant_interrupt = false。

TUI 新增功能：启用 worktrees 功能后，模型可以使用相关工具，从受信任的本地项目中自行创建和列出托管 Git worktrees（#50148）；在代理 Command Center 中按 p 可置顶任务，当服务器支持时，置顶任务会保留在共享的“已置顶”组中（#51500）；/copy 可在对话记录块之间导航，Ctrl+Insert 可复制选中内容，tui.mouse_scroll_speed（有限正数，默认为1.0）可调节鼠标滚轮的滚动速度（#50434、#50215、#50209）；审批标题、问题、MCP 提示、警告和横幅中的 URL 均可点击，跨行链接同样如此。新建 TUI 线程会遵循服务器的模型和推理摘要默认设置，同时保留启动时明确指定的覆盖项。codex doctor 会报告配置的 TUI 模式；账户更新后，/status 会再次显示账户电子邮件地址。

提供商和模型：兼容 Responses 的自定义提供商可以在 [model_providers.<name>.capabilities] 下声明 external_web_access 和 remote_compaction（#50459）。ultrafast_mode 功能随版本启用，因此当模型目录公布 Ultra Fast 层级时（例如 Amazon Bedrock 的 Astra 模型，#50472），即可独立于 Fast 模式提供该层级；此标签附带的目录中尚未列出此类层级。代码模式新增 JavaScript 辅助工具，用于流式返回 promise 结果，并提供可选择启用的排序工具搜索（code_mode_tool_search）。apply_patch 现在始终保留现有的 CRLF 行尾，同时移除 apply_patch_preserve_line_endings 标志。可重试的 Responses 和 WebSocket 失败会遵循服务器的 Retry-After 建议。

沙箱和平台：修复了存在多个拒绝访问文件时 Linux 沙箱的启动问题；不再允许写入沙箱构建可执行文件；ripgrep 配置也无法再削弱拒绝 glob 掩码。Windows 10 恢复了常规的盘符文件访问；沙箱临时目录权限与子进程保持一致；PowerShell 7 模块路径下的归档校验和验证恢复正常；Windows 发行版还提供经过签名的 PowerShell 安装程序。

建议操作：升级；若您依赖提前键入内容且不希望中断模型，请设置 instant_interrupt = false。¹⁸⁰¹⁸²

v0.161.0（2026年10月7日）

此版本基于 0.161.0-alpha.13.1 构建，并新增1次发布提交，比 v0.160.1 多155次提交。其发行说明将 GPT-6.1 Sol 列为新的默认模型（#49318、#49339），但相关目录变更已随 v0.159.1 发布：此标签附带的 models.json 与 v0.160.1 的文件逐字节完全相同，因此对于使用 0.159.1 或更高版本的用户而言，没有任何变化。

新增：/mcp login <name> 可从正在运行的终端会话登录 MCP 服务器（#49290）。**语音设备选择：**为 /voice 对话选择麦克风、扬声器和麦克风输入通道，偏好设置会保存在本地（#49437、#49836）。基于 API 密钥的模型发现默认启用（api_key_model_discovery 已升级为稳定功能，#49807）：使用 OpenAI API 密钥登录支持此功能的端点后，Codex 会通过 API 刷新模型目录，不再仅依赖内置列表；在 [features] 下设置 api_key_model_discovery = false 可将其关闭，变更会在新会话中生效。Amazon Bedrock 在兼容模型上支持多代理 V2 和 Ultra 推理，Bedrock Mantle 也支持 AWS GovCloud 区域（#49345、#49813）。

**Daybreak（可选择启用）。**新增的 cli_daybreak 标志默认关闭且仍处于开发阶段，可为 CLI 添加 Daybreak 控件：包括 /daybreak 开关、状态指示以及 Cyber 访问计划的自动路由。该功能适用于通过 OpenAI 提供商登录 ChatGPT，且账户和模型目录均声明支持此功能的情况。可使用 --enable cli_daybreak，或在 [features] 下设置 cli_daybreak = true 将其启用；仅保存 daybreak = true 偏好设置不会产生任何效果。与此功能相互独立，codex exec --cyber-access-program <standard|daybreak_blue|daybreak_red>（以及 TypeScript SDK 的 cyberAccessProgram）可以请求仅在单轮中使用某个 Cyber 访问计划，无论是否启用该标志均可，并且不会改变已保存的选择（#49856 至 #49861、#49939、#51207）。内置目录已包含隐藏的 gpt-daybreak-blue-latest 和 gpt-daybreak-red-latest 条目。

修复：获批的文件系统权限提升可以授予更广泛的写入权限，同时继续执行读取拒绝和网络限制；后台任务会保留其来源轮次的权限；明确指定的启动权限在终端重新连接后仍然有效；提权后的 Windows 终端会话可以通过嵌入式服务器启动；粘贴检测超时后，按 Enter 可提交缓冲输入，Vim 插入模式同样适用；恢复线程时会包含最近提交的历史记录，启动阶段也会更早发现可恢复的 SQLite 损坏，并将受损数据库保留为备份；Responses 重试以及 WebSocket 到 HTTP 的回退会遵循服务器的重试指引。身份验证文档现在说明，凭据可能存储在密钥环中，而非始终保存在 auth.json 内。

建议操作：升级。除非您使用 API 密钥登录，否则此处不会改变任何明显可感知的默认行为；若使用该密钥登录，请通过 /model 检查发现的模型目录。¹⁷⁹¹⁸²

v0.160.1（2026年10月5日）

修复了 Windows 上的远程 MCP 服务器问题。 当 macOS 或 Linux 主机上的 Codex 在远程 Windows 执行器上启动 stdio MCP 服务器，并且该服务器的配置明确设置了远程环境变量时，Codex 现在还会一并传递 SYSTEMROOT、TEMP 和 TMP，确保 Windows 进程保留启动所需的环境。未请求的变量（包括机密信息）仍会被排除。此版本是在 v0.160.0 基础上加入的一项向后移植，不会更改任何默认值、配置键或模型。

操作建议：如果您通过 Unix 主机在 Windows 执行器上运行远程 stdio MCP 服务器，请升级。¹⁷⁶

v0.160.0（2026年10月1日）

0.160 系列的稳定版本，基于 0.160.0-alpha.6.1 并加入一项向后移植。默认值没有变化。 此标签中随附的模型目录与 v0.159.1 和 v0.159.2 在字节级完全一致，因此 GPT-6.1 Sol 仍是默认模型，两个新功能标志默认均为关闭状态。向后移植（#49763）将早于 v0.159.1 分支出来并已冻结的 0.160 候选版本同步到了 0.159 维护线：包括 v0.159.3 中的 GPT-6.1 Sol 随附目录、Amazon Bedrock 目录和账户安全提醒。若无此项移植，0.160 将不会包含 GPT-6.1 Sol。

可选择启用的 Guardian 新增功能（两者均处于开发阶段，默认关闭）：

• Guardian 可以读取较早的用户消息。 在 [features] 下设置 guardian_conversation_history_tools = true。启用 Apps 后，审查器可通过父会话自身的 Apps 连接使用 user_message.search_messages 和 user_message.read_messages，从而在批准会产生副作用的操作前，核查较早的指令、限制和已撤销的权限。每次调用都会重新检查父会话当前的应用和工具策略。响应默认限制为估算的 4,000 个 token（auto_review.conversation_history_max_output_tokens），而 auto_review.experimental_conversation_history_prompt 可替换内置的检索指令。
• 可感知移交的根上下文（guardian_root_handoff_context）：当 Guardian 审查工作代理的操作时，会选取每次向该工作代理或其上级代理移交前的 3 条根消息，以及最新的 3 条根消息，确保近期的取消指令仍然可见。

始终启用：经过加密的代理消息现在会按顺序出现在 Guardian 记录中，不再被丢弃。

TUI 变化：在既没有项目配置也没有已保存信任决定的文件夹中，新会话可以使用 workspace-write 权限和细粒度审批启动，但前提是本地执行、您的配置及托管策略均允许如此。恢复的会话会还原已保存的权限，除非您将其覆盖；/cd 也可以请求文件夹信任，并提供“保留当前目录”选项。代理命令中心新增“显示更多”行，每次可加载 10 个较早的任务。在本地 Linux X11 终端上（不包括 Wayland、SSH、tmux、WSL 或 VS Code），全屏记录中的选定内容会进入主选择区，单击鼠标中键则会将其粘贴到编辑器中。空间充足时，全屏状态行会显示 Plan mode (shift+tab to cycle)。Pro 套餐层级现在会在 /status 和分析功能中显示为“Pro 100”“Pro 200”和“Pro 500”。启动提示会指向适用于您所在平台的桌面应用，而不是推广套餐或 Fast 模式；从未发送的排队消息会在重新连接后恢复，且不会重复。

提供商和连接：TUI 会保留应用服务器的提供商、推理摘要和详细程度设置，在恢复与分支历史记录中显示正确的会话，并针对服务器连接隐藏 /status 中的推理摘要设置。明确指定模型目录（model_catalog_url）的提供商现在只会获得该目录：不再合并随附模型，元数据会与确切的模型 ID 匹配；刷新失败时会丢弃缓存条目，而非继续复用；若启动时没有可用模型，则会报告配置错误，除非已设置 model。当内容过滤器中止响应时，重试指令会要求模型解释限制、提供允许的替代方案，并继续完成其他工作。

修复内容：Windows 沙盒的 PowerShell 后备方案、长运行时路径的 ACL 修复，以及防止后台辅助程序弹出控制台窗口；子代理会保留仍在启动的环境；SQLite 不再卡在连接设置阶段，并会报告初始化错误而非超时。日志数据库会在后台回收未使用的空间，插件加载过程则会缓存已解析的清单并复用 HTTP 连接。提供商文档现在说明，requires_openai_auth 凭据使用由 cli_auth_credentials_store 选择的后端，而 env_key 表示保存 API 密钥的环境变量名称。

操作建议：请升级。如果自定义提供商设置了 model_catalog_url，请确保其目录列出您选择的每个模型。¹⁷⁵

v0.159.3（2026年9月30日）

可选的账户安全提醒。 使用 OpenAI 提供商并通过 ChatGPT 登录的本地 TUI 会话可以显示一条可关闭的横幅，提示您完成账户安全设置，并提供一个用于打开 chatgpt.com 的按钮。由服务器决定向哪些用户显示；CLI 会在后台获取通知，不会阻塞当前轮次；状态未知时不显示任何内容，并会跳过远程工作区和 FedRAMP 账户。关闭状态会跨线程和重新连接保留。用量横幅的优先级更高。这是该版本唯一的变化，v0.160.0 也包含相同代码。

操作建议：无需操作。此提醒为可选项。¹⁷⁷

v0.159.2（2026年9月29日）

修复了 Windows 控制台窗口闪烁问题。 在 Windows 上，Codex 启动后台进程时不再每次都打开控制台窗口。涉及的场景包括 shell 工具命令、hooks、Git 和 npm 调用、无终端运行的 Amazon Bedrock 凭据刷新、doctor 检查、沙盒设置刷新，以及旧版 Windows 沙盒中的命令。需要使用终端的命令仍会继承其控制台。此版本向后移植了主分支中的两项修复，于 v0.159.1 发布约 3.5 小时后推出。它不会更改任何默认值、配置键或模型，新启动辅助程序在 macOS 和 Linux 上的行为也与以往一致。

操作建议：如果 Codex 工作时控制台窗口频繁闪烁，尤其是在安装了后台服务器的情况下，请在 Windows 上升级。¹⁷³

v0.159.1（2026年9月29日）

GPT-6.1 Sol 成为默认模型。 当 config.toml 未设置模型时，CLI 现在会使用 GPT-6.1 Sol（gpt-6.1-sol）启动，而非 GPT-6-Astra；在 Amazon Bedrock Mantle 和 Runtime 目录中，GPT-6.1 Sol 也取代 GPT-6 Sol 成为默认模型。/model 选择器会将其列在首位，并描述为“适用于编码和日常工作的最新主力模型”；其后依次为 GPT-6-Astra、GPT-6 Sol（现描述为“上一代主力模型”）、GPT-6 Luna 和更早的模型。已保存的选择不会迁移：配置中若指定 gpt-6-sol 或 gpt-6-astra，仍会继续使用该模型；针对较早 GPT-5 选项的迁移提示也仍会指向 GPT-6 Sol 或 GPT-6 Luna。

OpenAI 文档于同日加入了该模型，目前建议将其用于复杂编码和代理式工作流：“以低于 Astra 的成本，为复杂工作提供接近 Astra 的性能。”每 100 万个输入 token 收费 50 个积分（缓存输入 2.5 个积分，输出 250 个积分），Plus 档位可发送 15–160 条消息。其目录信息有两点与 GPT-6 Sol 不同：它没有默认服务层级，因此会话会以 Standard 速度而非 Fast 速度启动；其默认推理强度为 low，而非 medium。首发范围涵盖 Plus、Pro、Business、Enterprise 和 Edu；Enterprise 和 Edu 在管理员启用前仍保持关闭，Free 和 Go 则不在首发范围内。

操作建议：升级后在 /status 中检查模型。如果您的账户尚未获得 GPT-6.1 Sol，请在 config.toml 中通过 model 或使用 -m 固定为账户已有的模型。¹⁷¹

v0.159.0（2026年9月29日）

基于 0.159.0-alpha.13 构建，于 v0.158.0 发布约 27 小时后推出。其发行说明中的若干项目已通过向后移植提前在 v0.158.0 中发布：Windows 控制台窗口和启动器修复、保留 Markdown 格式的复制功能、欢迎屏幕与轮次提示，以及登录修复。说明中列为已移除的 tui.prompt_suggestions 设置从未出现在任何稳定版本中。

此版本新增：

• instant_interrupt（可选启用，处于开发阶段）：新输入可以抢占模型响应，或让长时间运行的代码模式调用让出控制权。在 [features] 下设置 instant_interrupt = true 即可试用。从 v0.162.0 起默认启用。
• 警告查看器关闭时会清除您已经查看的警告；按 k 可保留某条警告供日后查看。
• 在决定是否实施计划时，可以滚动浏览记录。
• Mermaid 渲染支持更多流程图边、标签和节点组。
• 切换任务时，空白会话会保留草稿；线程也可以在首次轮次开始前归档。
• /status 采用无边框渲染，并会自动换行显示较长的值。
• 应用服务器客户端可以从特定项目开始，对线程历史记录进行分页。 沙箱变更：已获批准的命令仍会保留明确的文件系统拒绝规则；可写根目录下的.aws目录默认受到保护（明确规则仍可覆盖此行为）；启用网络的macOS沙箱允许进行TLS信任评估；需要代理的执行环境现在会自动获得代理配置。捆绑的plugin-creator skill已被移除。

操作建议：如果沙箱任务需要写入.aws目录，除非添加明确规则，否则预计会被阻止。¹⁷⁰

v0.158.0（2026年9月28日）

0.158系列的稳定版本，基于0.158.0-alpha.15.4构建：包含alpha.15以及16项向后移植，其中包括v0.157.1中的4项Windows修复。该版本比v0.157.0领先207次提交。

发生变化的默认设置：

• 终端输入审批现已启用。 当Codex向具有提升权限的运行中命令发送输入时（包括额外权限授予、绕过沙箱，或命令启动后策略发生变化），必须先获得批准。仅限运行时的权限授予（例如插件用于指标收集的权限）不再触发审查。若要关闭此功能，请在[features]下设置write_stdin_approval = false。
• 全屏记录中的选择即复制：释放鼠标按键时，所选内容会被复制。默认值auto会跳过能够自行转发复制快捷键的直接终端（Ghostty 1.2+、macOS上的Kitty、Windows Terminal，以及Windows上的VS Code）。复制内容会保留Markdown格式。请在[tui]下设置copy_on_select = "never"（或"always"）。
• Windows、WSL和Linux全屏TUI中的右键粘贴。若要关闭，请在[tui]下设置right_click_paste = "off"；设置为"on"则还会在macOS上启用。
• Guardian线程上下文始终启用。 v0.157.0中的关闭开关已被移除：[features.guardianv2]下的thread_context会被忽略，包括配置文件中的设置；Codex会显示通知，要求您将其删除。

模型与套餐：GPT-5.4已从捆绑目录和Bedrock目录中移除，已保存的GPT-5.4选择仍会收到迁移至GPT-6 Sol的提示。Codex现在可识别Pro Max套餐，并将各Pro层级标记为“Pro”“Pro (More)”和“Pro (Max)”。推理快捷方式最高可达到Max。

其他新增功能：支持需要预注册OAuth客户端密钥的MCP服务器（codex mcp add --oauth-client-secret）；exec-server的WebSocket连接支持不记名令牌；生成的图像支持透明背景；/ps中支持多行命令预览。修复内容涵盖Windows沙箱故障（普通Windows 10路径、被拒绝的已存储凭据、大型权限策略）、具有嵌套可写根目录时的Linux沙箱启动问题、跨可写根目录的Git元数据保护、补丁审批中的macOS路径别名，以及在审查期间发送消息时会重试而非中止的Guardian审查。

操作建议：如果自动化工具向提升权限的命令发送按键输入，预计会出现审批提示；也可以关闭此功能。同时，请从配置中删除thread_context。¹⁶⁹

v0.157.1（2026年9月26日）

一项Windows补丁，包含从主分支向后移植的4项修复。Codex启动代码模式主机或本地stdio MCP服务器时，不再打开控制台窗口。当Windows将进程置于外层作业对象内时，后台服务器现在可以正常启动；分离的后台服务器也不再持续占用启动器的输出管道，否则即使启动器已退出，调用命令仍可能继续等待。GitHub发布说明和变更日志条目仅称“无法确定”亮点；上述列表来自该版本的提交记录。

操作建议：如果您在Windows上运行Codex，请升级。上述4项修复仅适用于Windows。¹⁶⁷

v0.157.0（2026年9月25日）

此版本又调整了3项默认设置。

• 全屏记录现已默认启用。 v0.156.0通过/tui提供的全屏UI现在会在会话启动时自动打开，即使配置中没有[tui]部分也是如此。若要保留终端回滚缓冲区，请在/tui中选择Scrollback，或在[tui]下设置fullscreen_transcript = false；--no-alt-screen和tui.alternate_screen = "never"仍具有更高优先级。现在按住Shift并单击可扩展记录中的选区。
• 后台服务器会自动启动，适用于符合条件的交互式启动，并且该选项已移出/experimental。使用--no-daemon、--oss、--profile或大多数-c覆盖项启动时，不会使用后台服务器。如果运行中服务器的设置与会话不匹配，Codex会提供以下选项：不使用服务器继续运行、使用所需设置重启服务器，或取消（默认选项）。若要关闭自动启动，请在[features]下设置daemon_auto_start = false。
• Guardian线程上下文默认启用，同步和异步审查均是如此，不受Guardian v2的enabled开关影响。若要关闭，请在[features.guardianv2]下设置thread_context = false。

模型：首次随v0.156.1发布的GPT-6 Sol和Luna也包含在此版本中，Amazon Bedrock目录现在同样提供这些模型，并由GPT-6 Sol取代GPT-5.6 Sol成为Bedrock默认模型。GPT-5.6 Sol不再提供ultrafast服务层级，仅保留Fast。捆绑目录不再将GPT-6-Astra标记为支持实验性上下文管理（请参阅上下文管理）。

其他新增功能：按f可派生在另一应用中打开的对话，同时保留草稿和排队中的提示词；/import可用于远程会话和后台服务器会话；终端可渲染Unicode项目符号、复选框和对齐公式。修复内容包括：切换线程后语音对话仍能继续；在一轮交互结束时恢复尚未发送的回答；遵循tmux鼠标设置；通过已配置的代理路由实时连接和独立网页搜索；以5分钟超时重试暂时失败的文件上传；以及在重定向、开放HTTP连接和WebSocket连接中全面执行网络限制。在Windows上，沙箱对象访问仅限于运行程序的登录会话。¹⁶⁷

v0.156.1（2026年9月23日）

此补丁仅包含一项变更：将GPT-6 Sol和GPT-6 Luna引入稳定版CLI。两者现在会显示在/model选择器中的GPT-6-Astra下方；GPT-6-Astra仍居首位，并且在config.toml未设置模型时仍是捆绑的默认模型。选择器将GPT-5.6系列重新标记为旧版模型（GPT-5.6 Sol显示为“用于复杂工作的旧版编程模型”），并将GPT-5.5标记为“传统编程模型”。接近速率限制时，切换提示现在会建议使用gpt-6-luna，而非gpt-5.6-luna。

如果配置中指定了旧版模型，预计会出现一次性迁移提示：已保存的gpt-5.6-sol、gpt-5.6-terra、gpt-5.5和gpt-5.4选择会指向GPT-6 Sol，而gpt-5.6-luna和gpt-5.4-mini会指向GPT-6 Luna。Amazon Bedrock目录在此版本中没有变化：其中不包含GPT-6 Sol或Luna，GPT-5.6 Sol仍是Bedrock默认模型。

文档未提及一项成本细节：捆绑目录将Fast（priority）设为GPT-6 Sol和Luna的默认服务层级。因此，未设置service_tier的TUI会话可能以Fast模式启动；通过ChatGPT登录时，该模式按Standard积分的2.5倍计费。使用/fast status检查；/fast off可切换至Standard。

操作建议：升级后，在熟悉的任务上尝试codex -m gpt-6-sol。可用性取决于您的套餐、工作区设置和发布进度；Enterprise管理员必须先启用新模型。¹⁶⁴

v0.156.0（2026年9月22日）

此版本一次调整了3项默认设置；文档变更日志在同一天公布了前两项。

• 语音功能默认启用。 在受支持的构建版本中，/voice无需进入/experimental即可开始实时对话。同时新增：可配置的F8切换键、用于选择后续对话语音的/voice settings选择器、适用于Linux和Windows的捆绑语音运行时，以及减少动态效果支持。
• 托管worktrees默认启用。 --worktree和/worktree不再需要功能标志。Worktree会话可以连接现有的本地daemon，也可以从agents概览中创建。
• Guardian父级压缩复用默认启用： 当Guardian重启审查会话时，可以复用父线程的加密压缩内容。

每项功能的关闭方法请参阅斜杠命令表中的/voice和/worktree条目，以及Guardian部分。

其他新增功能：可通过/tui选择的可选全屏TUI，支持记录搜索、鼠标选择与复制、右键复制、可点击链接和警告查看器；/theme选择器提供6种捆绑主题；新增/usage分析仪表板；可在终端中渲染Mermaid图表和TeX数学公式，并可分别切换；新增/daemon菜单和--no-daemon标志；新TUI线程默认关闭推理摘要。安全修复封堵了Windows沙箱中与入站流量、特权套接字和只读文件句柄相关的漏洞；codex doctor也不再在错误信息中回显配置值。缺陷修复包括：在交互失败或中断后保留流式回答；修复tmux和SSH中的剪贴板转发；恢复会话时还原Plan mode；以及允许通过系统代理恢复登录。¹⁶²

v0.155.1（2026年9月18日）

一个仅含单项修复的热修复版本。在0.155.0中，如果配置未设置model_reasoning_summary，新的本地TUI线程会请求detailed摘要，而不支持推理摘要的提供商会直接拒绝该请求。0.155.1恢复以none作为回退值，因此未设置此键时不会请求摘要。显式设置的auto、concise和detailed始终都会生效，现在依然如此。同一处单行修改也已合入主分支，并随0.156.0发布。

应对措施：如果0.155.0中的新TUI会话在使用非OpenAI或自托管提供商时失败，请升级版本。如需摘要，请显式设置该键（请参阅配置参考）。¹⁵¹

v0.155.0（2026年9月17日）

语音功能作为实验性的选择启用功能进入稳定版TUI：在受支持的构建版本中通过/experimental启用后，/voice可开启实时对话，并提供流式文字记录和麦克风控制；静音快捷键可配置，macOS软件包中还包含签名的语音资源。五天后，v0.156.0将其默认启用。此版本中的托管worktrees仍默认关闭。

0.155.0还包括：

• **MCP用户验证：**在受支持的Mac上，本地TUI会话可通过Touch ID验证MCP请求，由Secure Enclave签名；同时提供工作区范围的身份限制，并在MCP工具续接流程中执行原生验证。
• Windows的/sandbox-add-read-dir slash command已移除。
• **Worktree管理：**可在代理概览中隐藏、归档和删除worktree会话，查看所有权详情，并在删除干净的托管worktree前进行确认。
• 实时推理摘要会显示在TUI状态行中，工作完成后还会显示完成时间戳。
• **守护进程：**支持配置更新计划，新增codex app-server daemon update命令，并可在守护进程重启后恢复线程。
• 新增Amazon Bedrock AWS凭据命令，并使Python SDK发布与稳定版CLI保持一致。

安全修复封堵了WSL互操作逃逸问题和shell快照凭据泄露问题。Memory v2仅提供存储和整合方面的基础能力，尚不可实际使用。¹⁴⁹

v0.154.0（2026年9月9日）

此版本大致在0.154.0-alpha.6节点发布，因此首次出现在alpha.7中的所有功能（实时TUI语音、MCP用户验证、Memory v2、守护进程自动更新配置、推理强度固定）均延后至0.155。

已移除：codex mcp-server和独立的codex-mcp-server二进制文件。请将集成迁移到app-server协议或适用于Claude Code的Codex插件；用于将Codex连接到外部MCP服务器的codex mcp不受影响（请参阅“将Codex作为MCP服务器运行”）。旧版Guardian审批审查路径也已移除；当新的用户指令使审批失效时，系统现在会拒绝该审批。

新增功能：

• 实验性托管worktrees：可通过--worktree或/worktree使用，支持codex exec并提供TUI worktree浏览器。
• **异步用户消息：**Codex继续工作时，您可以回答行内问题，且不会丢失草稿。
• **Windows服务支持：**包括沙箱预配、Windows上的app-server守护进程，以及托管的守护进程更新。
• 远程权限配置文件：从app server发现，并可在TUI中按名称选择。
• Vim R替换模式、实时上下文压缩状态，以及在会话启动时根据模型能力启用的实验性上下文管理。

安全方面：在工作区信任关系建立之前不再运行PATH辅助程序，并强化macOS沙箱，防止终端输入注入。MCP连接会协调OAuth令牌刷新；远程恢复和分叉会保留已保存的权限；恢复已在其他应用中打开的对话时，会显示只读文字记录。语音功能仅以运行时基础设施的形式发布，首批Daybreak代码引用也已加入，但尚无公开文档。¹⁴⁵¹⁴⁶

v0.153.3和v0.153.4（2026年9月4日）

这两个同日发布的补丁将GPT-6-Astra的发布带入CLI。v0.153.3将Astra加入Amazon Bedrock目录（GPT-5.6 Sol仍是Bedrock的默认模型），并修正了Astra的异步澄清指导。v0.153.4将Astra加入模型选择器，使其成为未配置模型时的内置默认模型，并根据工具可用性限定异步提问指导。

应对措施：从v0.153.1开始，可通过-m gpt-6-astra使用Astra；从v0.153.4开始，它会出现在模型选择器中。文档未注明最低CLI版本，因此可将这两个版本分别视为最低要求。如果您的账户无权使用内置默认项所选择的模型，请在config.toml中显式设置model，不要依赖默认值。^138139140141

v0.153.1和v0.153.2（2026年9月3日）

v0.153.1使Guardian的计算机操作评分遵循模型要求：仅当活动模型的元数据设置了node_repl_auto_review_required时，才会运行仅限计算机操作的评分和快速审批决策。如果切换到跳过评分的模型，先前或正在进行的评分将失效，因此切换回来也无法恢复过期审批。发布说明中只列出了向后移植的GPT-6-Astra目录条目，可通过API配置；模型选择器和默认模型直到v0.153.4才发生变化。v0.153.2将Astra Fast层级的说明从“1.5倍”更正为“2倍速度，用量增加”（仅修改显示文本）。¹³⁵¹³⁶

v0.153.0（2026年9月3日）

• Vim撤销与重做：u和Ctrl+R可恢复完整的编辑器草稿，包括粘贴的内容和图像附件；vim_normal.redo是可配置的键位映射操作。
• **远程插件市场：**插件CLI可列出、安装和移除远程插件，codex plugin list会显示来源、版本、安装策略和身份验证策略。
• tui.auto_recap = false可关闭自动回顾；手动/recap仍然可用。
• 更早向Plus和Team发出速率限制警告：在大约五小时的窗口内，剩余额度不足一半时即发出警告；其他套餐仍采用75%、90%和95%的阈值。
• **Guardian范围遵循审批模式：**Full Access会跳过仅需确认操作的Guardian审查，User审批模式会跳过后台评分和预热。
• features.context_management.experimental_mode（默认关闭）为Codex后端上符合条件的Plus、Pro和Pro Lite会话启用令牌预算上下文、历史记录注释和new_context工具。
• tui.disable_paste_burst取代顶层键，后者仍可作为回退配置使用。

修复内容：app-server连接中断后，TUI会话可在保留草稿的情况下重新连接；Guardian审查历史记录可在压缩、重启和分叉后保留；记住的MCP审批仅适用于所选账户。¹³³

v0.152.0和v0.152.1（2026年9月1日）

update_plan改为选择启用：tools.update_plan.enabled默认为false；关闭时，内置的update_plan指导会从模型、协作模式、多代理、压缩、预热和目标续接提示中移除（请参阅“计划模式与协作”）。其他新增内容包括：Vim可通过/和?进行搜索，并使用n/N跳转，还可与操作符组合使用；新草稿默认从Insert模式开始；可操作的速率限制横幅；凭据刷新进度，包括Amazon Bedrock重新验证；软件包式MCP服务器名称（允许使用:、@、/和.）；MCP openai/elicitation表单请求；按工具设置的MCP output_token_limit；将云任务凭据限制为仅供受信任的来源使用；可配置的thread/shellCommand超时；以及通过模型元数据默认启用令牌预算。v0.152.1允许Guardian审批审查从模型元数据获取其Node REPL策略。¹³¹¹³²

v0.151.0（2026年8月29日）

• /recap可按需总结对话，Codex还会自动回顾符合条件、处于空闲且未聚焦的对话。
• 代码模式主机移除WebSocket传输方式（仅保留stdio和gRPC）。
• 在存储支持的情况下，持久线程默认采用分页历史记录。
• persistent推理强度随时钟工具和内置主动性指导一同推出。
• Guardian v2默认使用带图像的计算机操作审查。
• Vim新增f/F/t/T查找和“直到”移动操作，以及gg/G。
• 向提升权限的终端输入内容时可要求重新审批（write_stdin_approval，默认关闭）。
• 为可选MCP服务器提供可配置的宽限期（mcp_optional_startup_grace_ms，默认1,000毫秒），扩展还可检查或替换MCP工具结果。

修复内容可防止/cd削弱沙箱限制，也可防止权限变更后过期的Guardian分类继续授权操作。发布说明仅列出最后几个PR；完整变更集请参阅版本比较。[^221]¹²⁸

v0.150.0和v0.150.1（2026年8月26日至27日）

Hooks 新增 Interrupt 事件，在活动的顶层轮次被中断时运行（默认超时为1秒，上限为3秒，永远不会针对子代理运行）。/copy 会打开选择器，可选择完整响应、单个代码块或块引用。任务现在可通过 @ 提及进行寻址，代理可以读取、创建任务并向任务发送消息，/rename 则会建议一个可编辑的标题。Markdown 链接会呈现为可点击的标签，快捷键可以循环切换权限模式，Vim 新增 . 重复操作，并且不受信任的项目不再提供项目级 AGENTS.md 指令。features.network_proxy.credential_broker 和 Guardian v2 的 review_scope.computer_use_only 作为可配置且默认关闭的功能界面推出。v0.150.1 会将保留的图像计入远程压缩的 token 预算。[^218][^219]

v0.149.0 和 v0.149.1（2026年8月20日至24日）

untrusted 审批策略已停用；请将指定该策略的配置迁移到 on-request。新增功能包括：交互式 codex agents 仪表板、/cd、/pwd 和 /cwd，用于向现有本地或远程会话发送消息的 codex queue，更多 Vim 修改动作，以及功能更全面的 codex doctor（端点保护、网络和代理故障、桌面应用状态、更新连接情况）。SDK中还新增了 max/ultra 推理强度。恢复和分叉的线程会还原其权限配置文件。v0.149.1 新增 codex exec --thread-source <SOURCE>（可选值为 user、subagent、memory_consolidation 或功能名称；在 TypeScript SDK中对应 threadSource）。

同期定价变化：从8月21日起，OpenAI 将 GPT-5.6 Sol 的价格下调超过20%，为期3个月（至少持续至2026年11月21日）；Sol 每100万个输入 token、缓存 token 和输出 token 对应的 Codex 积分费率，也从125/12.5/750降至100/10/500。^120121126

v0.147.0 和 v0.148.0（2026年8月7日至18日）

v0.147.0 移除了 codex exec --full-auto（自v0.128起已弃用）；请改用 --sandbox workspace-write，并搭配审批标志或配置文件。此版本还新增了 --approve-for-me、支持跨目录搜索的可移植 Agent Plugins、可选择启用的 MCP 2026-07-28 协议，以及对话分区。v0.148.0 新增将内容导出为 Markdown 的 /export、codex exec fork、/status 中的预估积分或费用、作为内置提供商的 Amazon Bedrock Runtime、异步及调用 MCP 的 hooks，以及在路径遭拒或无法读取时以封闭方式失败的沙箱限制。¹¹⁶¹¹⁸

早期版本（2026年5月至7月）

• **v0.146.0 和 v0.146.1（7月29日、8月5日）：**配置的代理覆盖所有传输方式；新增 Agent Plugins 清单以及 Amazon Bedrock 和 Claude Code 市场；支持会话命名和线程置顶；支持由执行器提供的 skills；强化了具备网络安全能力模型的自动审查默认设置。¹¹⁴¹¹⁵
• **v0.145.0（7月21日）：**支持从 Cursor 和 Claude Code 执行 /import；语音功能以流式实时 V3 对话形式回归；可选择启用的多代理 v2 体验趋于稳定；新增实验性分页线程历史记录和 Amazon Bedrock 登录；捆绑的 GPT-5.4 选项迁移至 GPT-5.6 Terra 和 Luna。v0.144.6 将 GPT-5.6 上下文窗口设为272,000个 token。¹¹¹¹¹²
• **v0.140.0（6月15日）：**新增 /usage、codex delete 和 /delete、从 Claude Code 执行 /import、统一的 @ 提及菜单、Amazon Bedrock API 密钥身份验证，以及对 CLI 和 MCP OAuth 凭据进行加密的本地存储；旧版 /realtime 语音控制已移除。¹⁰²
• **v0.139.0（6月9日）：**代码模式可直接调用网络搜索，工具架构保留 oneOf/allOf，codex doctor 会报告编辑器和分页器详情，市场来源会显示在 JSON 输出中。¹⁵⁸
• v0.138.0（6月8日）：/app 可将 CLI 会话移交给桌面应用，多代理 v2 会加密从父代理发送给子代理的任务文本。¹⁵⁹¹⁰⁸
• **v0.137.0（6月4日）：**新增多代理 v2、F13-F24 TUI 键绑定和 v1 skills 扩展。¹⁶⁰
• **v0.132.0 至 v0.135.0（5月20日至28日）：**新增本地对话历史搜索；将 --profile 作为主要配置文件选择器；默认启用目标；支持权限配置文件继承及托管的 requirements.toml；支持启动和停止 codex remote-control；增强 codex doctor 和 /status；新增 Vim 文本对象；在 /permissions 中支持命名权限配置文件；新增 Python SDK 身份验证和 Sandbox 预设；新增 codex exec resume --output-schema。5月21日的应用更新新增了 Appshots、正式发布的目标模式，以及可选择启用的锁定式 Computer Use。^{96979899100101185}

旧版 --full-auto 已于v0.147.0移除，js_repl 仍处于移除状态。^86878991116

**稳定性说明：**稳定且有文档记录的功能界面包括：核心 CLI 和 TUI、沙箱和审批策略、config.toml、AGENTS.md、skills、hooks、插件、多代理工具、目标、权限配置文件、/voice 和托管 worktrees（自v0.156.0起默认启用）、全屏记录和后台服务器自动启动（自v0.157.0起默认启用）、终端输入审批、选中即复制和右键粘贴（自v0.158.0起默认启用），以及即时中断（自v0.162.0起默认启用，但仍标记为开发中）。浏览器、Computer Use 和 Appshots 是有文档记录的面向用户功能，其可用性取决于平台和套餐。实验性或开发中的功能包括：Codex Cloud、代码模式及代码模式工具搜索、Memory v2、本地代理留言板、Daybreak（cli_daybreak，v0.161.0）、Guardian 历史记录和交接上下文标志（v0.160.0），以及本指南中标为 [EXPERIMENTAL] 或列在 /experimental 下的任何功能；这些功能可能随版本变化。根据配置参考，实验性上下文管理“当前不可用”。已移除的功能包括：--full-auto（v0.147.0）、untrusted 审批策略（v0.149.0）、codex mcp-server（v0.154.0）、Guardian thread_context 退出选项（v0.158.0）以及 js_repl。

**Alpha 渠道：**alpha 构建每天会发布数次，alpha 版本线上的发布说明仅为占位内容，并且经常出现基于较旧基础版本制作的带外构建。npm alpha 标签至少有两次指向了此类构建，因此通过 @alpha 安装到的版本比 latest 更旧。0.158版本线从0.158.0-alpha.2（9月23日）延续至alpha.15（9月25日）；其稳定版v0.158.0（9月28日）基于带外构建0.158.0-alpha.15.4制作，即alpha.15加上16项回移提交，并一直作为npm latest，直至27小时后v0.159.0发布。0.159版本线从alpha.1（9月25日）延续至alpha.13（9月28日），并基于alpha.13发布为v0.159.0。0.160版本线推进至0.160.0-alpha.6（9月29日）后便冻结于此；0.161.0-alpha.1仅在alpha.6基础上更改了版本号。9月30日，0.160.0-alpha.6.1在alpha.6基础上加入了此前缺少的一个v0.159.2 Windows 控制台修复。同一天，0.159版本线又发布了一个补丁v0.159.3。随后，0.160版本线发布稳定版v0.160.0（10月1日），它基于alpha.6.1并增加一项回移提交；v0.160.1则于10月5日发布。0.161版本线已产生多个alpha和带外回移版本，最新为0.161.0-alpha.13.1（10月6日），但尚无稳定版；由于尚未有更高版本发布稳定版，因此不能称其为已跳过。alpha 现在指向0.162.0-alpha.16。如果您跟踪alpha版本，请检查 npm view @openai/codex dist-tags，并安装确切版本，而不要使用 @alpha。^{169172174178 166}记录了近期alpha版本线如何演变为稳定版，并按日期列出了历史。0.161版本线于10月7日从0.161.0-alpha.13.1发布为v0.161.0（在其基础上增加了一个发布提交）；随后，v0.162.0于10月8日从0.162.0-alpha.18.1发布，而0.162.0-alpha.20比该稳定版分支点领先52个提交；v0.162.1于10月9日增加了3个提交；10月10日，alpha 为0.163.0-alpha.5，10月13日依次推进至alpha.8、alpha.9和alpha.10，截至10月14日为0.163.0-alpha.11。^182183184

Codex 的工作原理：心智模型

在深入了解各项功能之前，首先需要理解 Codex 的架构如何影响您使用它的方方面面。该系统横跨5个交互界面运行，背后由共享智能层提供支持：

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │ Browser  │  Signed-in browser workflows              │
│  │Extension │  (launched May 2026)                      │
│  └──────────┘                                           │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │     │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                 │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (on-request → never)       │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions             │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                             │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens         │
└─────────────────────────────────────────────────────────┘

核心层：一切功能均由 GPT 模型系列驱动。截至2026年9月29日，当前一代为 GPT-6：gpt-6.1-sol 适用于复杂编码和智能体工作（自 v0.159.1 起，未配置模型时作为内置 CLI 默认模型），gpt-6-astra 适用于难度最高的端到端工作，gpt-6-luna 适用于目标明确的大批量任务，此外还有上一代 gpt-6-sol。GPT-5.6 模型（Sol、Terra、Luna）在逐步发布期间仍然可用；gpt-5.5（在 Codex 中提供400K上下文，在 API 中提供1M上下文）将于2026年10月14日停止支持通过 ChatGPT 登录使用 Codex，gpt-5.4 则已于2026年8月31日从 Codex 中退役。^{83117139141142164171} 它会读取文件、编写补丁、执行 shell 命令，并对代码库进行推理。当上下文占满时，Codex 会压缩对话以释放空间。此层会消耗 token。

安全层：Codex 运行的每条命令都要经过操作系统级沙箱。在 macOS 上，Apple 的 Seatbelt 框架负责实施内核级限制。在 Linux 上，Landlock + seccomp 会过滤文件系统和系统调用访问。沙箱在内核级运行，而非容器内部。随后，批准策略决定何时请求人工确认。

扩展层：MCP 用于连接外部服务（GitHub、Figma、Sentry）。skills 将可复用工作流打包，供 Codex 按需加载。Apps 用于连接 ChatGPT 连接器。Web 搜索则从互联网补充实时上下文。

交互界面层：CLI 面向终端高级用户和自动化场景。Desktop app 用于多线程项目管理。IDE extension 适用于编辑、编译和测试的紧密循环。Cloud 用于运行彼此独立的异步任务。

关键认识：大多数用户只使用一个交互界面。高级用户则会综合运用全部5个：使用 Cloud 处理长时间运行的任务，使用 CLI 执行确定性的代码库操作，使用 IDE extension 完成紧密的编码循环，使用 desktop app 进行规划与协调，并使用 browser extension 处理需要登录的浏览器工作流。

目录

1. 如何安装 Codex？
2. 快速入门：您的第一次会话
3. 核心交互界面
4. 深入解析配置系统
5. 应该选择哪个模型？
6. Codex 的费用是多少？
7. 决策框架
8. 沙箱与批准系统如何运作？
9. AGENTS.md 如何运作？
10. Hooks
11. 什么是 MCP（Model Context Protocol）？
12. Code Mode
13. JavaScript REPL 运行时
14. 什么是 Skills？
15. Plugins
16. Plan Mode 与 Collaboration
17. Memory 系统
18. 会话管理
19. 非交互模式（codex exec）
20. Codex Cloud 与后台任务
21. Codex Desktop App
22. GitHub Action 与 CI/CD
23. Codex SDK
24. 性能优化
25. 如何调试问题？——包括 codex doctor
26. 企业部署
27. 最佳实践与反模式
28. 工作流范例
29. 迁移指南
30. 快速参考卡
31. 变更日志
32. 参考资料

如何安装 Codex？

包管理器

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

如何更新、降级或卸载 Codex CLI？

从v0.128.0开始，Codex提供自更新命令；其他操作均通过安装时所用的包管理器执行。⁸⁶ 从v0.146.0开始，发布构件、渠道元数据和安装程序别名均由OpenAI托管的发布基础设施提供，并以GitHub作为后备来源。¹¹⁴ 如果您的网络允许列表已放行GitHub以供Codex安装和更新，也请添加OpenAI发布主机。后备机制意味着，如果允许列表未命中，服务会悄然降级，而不是直接报错失败。

# Check what you are running
codex --version                          # -> codex-cli 0.162.1
npm view @openai/codex version           # Latest published version

# Update
codex update                             # Built-in self-update (v0.128.0+)
npm install -g @openai/codex@latest      # Or update via npm
brew upgrade --cask codex                # Or via Homebrew

# Pin or downgrade to an exact version
npm install -g @openai/codex@0.144.6

# Uninstall
npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

当新版本导致故障时，固定版本才是明智之举。 Codex采用快速迭代的稳定版本线，因此安装指定版本是最快的回滚方式——提交问题、固定版本，然后继续工作。请使用codex --version确认回滚是否生效，因为如果PATH中存在另一个优先级更高的安装项，系统仍会悄然运行旧版二进制文件（codex doctor会在环境部分明确指出此问题）。

卸载软件包不会删除您的状态数据。 身份验证信息、配置和会话历史记录 均位于~/.codex/中。保留该目录可在重新安装后继续使用登录信息和历史记录； 仅在确实需要从头开始时才将其删除——rm -rf ~/.codex还会一并删除config.toml、 auth.json以及所有已存储的会话。

直接安装脚本（v0.106.0及更高版本）

对于macOS和Linux，可以使用作为GitHub发布资产提供的单行安装脚本：⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

该脚本会自动检测您的平台和架构，下载正确的二进制文件，并将其放入您的PATH中。

二进制文件下载

对于没有npm或Homebrew的环境，请从GitHub Releases下载对应平台的二进制文件¹：

系统要求

• macOS：Apple Silicon或Intel（通过Seatbelt提供完整的沙箱支持）
• Linux：x86_64或arm64（通过Landlock + seccomp实现沙箱）
• Windows：使用受限令牌的原生沙箱（自v0.100.0起由实验性功能转为正式功能）。同时支持WSL²

身份验证

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

提供2种身份验证方式：

1. ChatGPT账户（推荐）：使用现有的Plus、Pro、Team、Business、Edu或Enterprise订阅登录。可使用包括云端任务在内的全部功能。
2. API密钥：通过CODEX_API_KEY环境变量或codex login --with-api-key进行设置。部分功能（云端线程）可能无法使用。

专家提示：可以通过config.toml中的cli_auth_credentials_store配置凭据存储方式。可选值包括：file（默认）、keyring（操作系统钥匙串）或auto（如果钥匙串可用则使用它，否则回退到文件）。

Amazon Bedrock登录（v0.145.0，实验性）： 对于通过Amazon Bedrock获取模型访问权限的团队，系统提供了一条支持自定义端点和身份验证的实验性登录路径。此外，现有的托管API密钥身份验证（v0.140.0及更高版本）和AWS凭据链仍然可用（请参阅自定义模型提供商）。GPT-5.6 Sol是默认的Bedrock模型。¹¹² v0.150.0修复了Amazon Bedrock模型的对话压缩和多代理兼容性问题。[^218] v0.151.0为符合条件的TUI登录流程添加了受功能开关控制的Amazon Bedrock选项：引导流程会发现现有的AWS配置文件和环境凭据，支持手动设置配置文件、访问密钥、环境变量和Bedrock API密钥，收集AWS区域信息，在输入时遮蔽机密信息，并在提供商变更后重启嵌入式服务器。¹²⁸ v0.152.0会显示凭据刷新进度：当模型提供商刷新过期凭据时，TUI和codex exec会显示进度，其中包括Amazon Bedrock会话的重新身份验证。此功能由稳定的modelProvider/authRecoveryStarted和modelProvider/authRecoveryCompleted应用服务器通知提供支持，通知中包含线程、轮次、提供商以及面向用户的消息。¹³¹

Shell自动补全

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

验证安装

codex --version
# codex-cli 0.162.1

快速开始：您的首次会话

只需5分钟，即可从零开始高效工作。

1. 安装并进行身份验证：

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. 进入项目目录：

cd ~/my-project                  # Any git repo works

3. 启动Codex：

codex

您将看到交互式TUI。Codex会自动读取项目结构。

4. 提出问题：

> What does this project do? Summarize the architecture.

Codex会读取关键文件并说明代码库。此类问题不会产生任何更改——只有在您提出更改请求时，Codex才会修改文件；沙箱和批准策略则决定它何时必须先征得您的同意。

5. 进行更改：

> Add input validation to the login endpoint

Codex会以差异形式提出编辑建议。使用y审查并批准，或使用n拒绝。

6. 使用slash command：

> /plan Refactor the database layer to use connection pooling

Codex会创建计划，但不会执行。请先审查计划，再批准并开始执行。

7. 检查您的工作：

> /diff

查看Codex在当前会话中所做的全部更改。

接下来： - 使用项目说明设置AGENTS.md（请参阅AGENTS.md如何工作？） - 为您的工作流程配置配置文件（请参阅配置文件） - 尝试使用codex exec进行非交互式自动化（请参阅非交互模式）

核心交互界面

Codex 提供5种由同一智能系统驱动的独立界面。每种界面都针对不同的工作流模式进行了优化。

1. 交互式 CLI（终端 UI）

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-6-sol          # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

终端 UI 是一个全屏应用程序，包含：

• 编辑器：输入提示词、使用 @ 附加文件、使用 ! 前缀运行 shell 命令
• 输出窗格：流式显示模型响应、工具调用和命令输出
• 状态栏：显示模型、token 使用量、git 分支和沙箱模式

主要 TUI 快捷键：

状态行变更（v0.121.0）： 状态行中原有的上下文窗口计量器已替换为上下文百分比指示器，用于显示上下文窗口的占用程度。如果您的脚本或 hooks 会解析状态行，请留意此次格式变更。⁸² 新版本发布时，Codex 还会显示 CLI 更新通知。

TUI 中可用的 Slash commands：

工作流选择器重新设计（v0.129.0）： 经过重新设计的选择器让恢复和派生操作更易访问；新增的原始回滚模式允许在需要逐字复制命令或模型输出时滚动查看未经渲染的转录内容。此功能非常适合排查冗长的调试会话，或将输出通过管道传递给其他工具。⁸⁹

统一的 @ 提及菜单（v0.140.0）： 现在，在编辑器中输入 @ 默认会打开统一的提及菜单，涵盖文件、插件和 skills，取代原先仅支持文件的附加流程——只需一次按键，即可引用任意项目资源。¹⁰²

2. Codex Desktop App（macOS + Windows）

codex app                    # Launch desktop app (auto-installs if missing)

桌面应用提供了 CLI 所不具备的功能：

• 多任务处理：同时在不同项目中运行多个并行 agents
• Git worktree 隔离：每个线程都在仓库的隔离副本中工作
• 内联 diff 审查：无需离开应用即可暂存、还原和提交更改
• 集成终端：每个线程都有独立的命令运行终端
• 对话派生：创建对话分支以探索不同方案
• 浮动弹出窗口：将对话分离为可移动窗口
• 自动化：安排周期性任务（问题分类、CI 监控、警报响应）
• Appshots：将 Mac 最前端应用窗口的截图及可用文本附加到线程
• 应用内浏览器评论：预览本地或公开页面，针对元素或区域留下评论，并让 Codex 根据精准的视觉反馈进行处理
• Computer Use：允许 Codex 操作获准的 Mac 应用以完成限定范围的 GUI 工作；对于符合条件的远程 Mac Computer Use 轮次，锁定状态下的使用需主动选择启用

由 GPT-Live 驱动的 ChatGPT Voice（桌面版 26.715，2026年7月23日）：现在可以通过语音操控桌面应用——无需打字，即可讨论工作，并在 Chat、Work 和 Codex 之间协调任务。在 macOS 上，启用 Screen context 后，会将最前端窗口的 appshot 分享到对话中，因此可以直接询问眼前所见，无需另行描述。此功能面向 Plus、Pro、Business、Edu 和 Enterprise 套餐开放，可在桌面应用以及 iOS 上的 Remote 中使用。这是桌面界面的语音功能。CLI 提供独立的语音功能：TUI 中的 /voice 实时对话（自 v0.156.0 起默认启用）和空格键听写（在 v0.105.0 中以实验性功能加入）。¹¹³¹⁶²

共享线程快照（2026年8月20日）：在所有 Codex 套餐中，macOS 桌面应用均可共享本地 Codex 线程的只读快照。原始线程发生变化时，快照不会同步更新；个人账户链接可由任何获得链接的人打开，工作区账户链接则仅限源工作区成员访问。Codex 会在分享前隐去已知的密钥模式，但 OpenAI 仍建议您审查共享内容，因为其中可能残留敏感信息。可在 ChatGPT 数据控制中的 Shared links 下查看或撤销链接。[^214]

何时使用应用，何时使用 CLI：协调多个工作流或需要可视化 diff 审查时，请使用桌面应用。需要终端组合能力、脚本编写或 CI/CD 集成时，请使用 CLI。

3. IDE Extension（VS Code、Cursor、Windsurf）

Codex IDE extension 可直接集成到编辑器中：

• 默认采用 Agent 模式：读取文件、进行编辑并运行命令
• 内联编辑：在当前文件中提供上下文感知建议
• 共享会话：会话可在 CLI 与 IDE extension 之间同步
• 相同的身份验证方式：使用 ChatGPT 账户或 API 密钥登录

可从 VS Code Marketplace 或 Cursor/Windsurf 扩展商店安装。³

4. Codex Cloud [EXPERIMENTAL]

云端任务在 OpenAI 管理的环境中异步运行：

• 提交后即可离开：将任务加入队列，使其独立于本地计算机运行
• 并行执行：同时运行多个云端任务
• 创建 PR：Codex 根据已完成的工作创建拉取请求
• 应用到本地：使用 codex apply <TASK_ID> 将云端结果拉取到本地仓库

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

也可从 chatgpt.com/codex 访问云端任务。⁴

5. Browser Extension（Chrome、Edge、Brave、Opera、Vivaldi）

Codex 提供适用于 Google Chrome、Microsoft Edge、Brave、Opera 和 Vivaldi 的浏览器扩展，成为继 CLI、桌面应用、IDE extension 和云端之后的第5种界面。该扩展于2026年5月在 Chrome 上线；2026年8月25日的更新日志新增了其余4款浏览器，可在 ChatGPT 桌面应用的 Settings > Computer Use 中进行设置。5款浏览器均支持标签页提及和浏览器控制；Opera 不支持侧边聊天，因此其任务需要从桌面应用启动。该扩展旨在伴随日常浏览使用，而非接管浏览体验：Codex 会在后台跨标签页并行工作，由您决定它可以访问哪些网站。⁹⁰¹²⁷

• 并行标签页执行：Codex 可同时操作多个标签页，不会锁定前台标签页。
• 按网站控制：您可以将允许 Codex 交互的网站加入许可名单；默认不授予任何访问权限。
• 以浏览器为工作台：对于以页面为事实依据的应用和网站工作，该扩展尤为适用，例如管理控制台、内部仪表板、内容管理 UI 和工单系统；但它不能取代 CLI 处理本地仓库。
• 相同的智能核心：浏览器扩展使用与其他界面相同的 GPT-5.x-Codex 智能系统，因此，在 CLI 中生效的 AGENTS.md 或 skills 配置，也会将相同约定带入浏览器驱动的工作。

请从浏览器扩展文档安装；该页面原名为 Codex for Chrome。¹²⁷

配置系统详解

Codex 使用 TOML 进行配置。理解优先级层次至关重要，因为它决定了设置发生冲突时以哪项为准。

优先级（从高到低）

1. 会话级覆盖（最高）：CLI 标志（--model、--sandbox、--ask-for-approval、--search、--enable/--disable、--profile）以及 -c key=value 覆盖
2. 项目配置（.codex/config.toml，从 CWD 向上查找到项目根目录；距离最近的目录优先）
3. 用户配置（$CODEX_HOME/config.toml，默认为 ~/.codex/config.toml）
4. 系统配置（Unix 上的 /etc/codex/config.toml）
5. 内置默认值（最低）

requirements.toml 充当策略约束层，在常规配置合并后限制用户可选择的值。请参阅企业部署。

配置文件位置

专家提示：CODEX_HOME 环境变量会覆盖默认的 ~/.codex 目录。适用于 CI/CD 或多账户配置。

桌面端多文件夹项目（26.715，2026年7月23日）：ChatGPT 桌面应用中的本地项目现在可以跨越多个相关文件夹，其中一个指定为主文件夹（项目菜单 → 编辑项目）。config.toml 的自动发现仅针对主文件夹运行；辅助文件夹仍可用于文件搜索、读取和编辑，但不提供任何配置。位于辅助文件夹中的 .codex/config.toml 只是 Codex 可以读取的文件，并不是它会加载的配置。这属于桌面应用的项目范围界定，并未改变上述优先级规则——CLI 仍会从当前工作目录开始向上查找，以解析项目配置。¹¹³

完整配置参考

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-6.1-sol"                  # Docs' example; unset = bundled default (gpt-6.1-sol since v0.159.1)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-6-sol"             # Optional model for /review command
service_tier = "fast"                  # Preferred service tier for new turns
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # on-request|never (untrusted retired in v0.149.0)

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Tools ─────────────────────────────────────────────
tools.update_plan.enabled = false       # Planning tool opt-in (v0.152.0); exposes update_plan when true

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output (global; per-tool MCP overrides in v0.152.0)
log_dir = ""                            # Custom log directory
sqlite_home = ""                        # Override SQLite-backed resumable state location

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]
mouse_scroll_speed = 1.0                # Mouse-wheel scroll multiplier, a finite positive number (v0.162.0)

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
enable_request_compression = true       # zstd request compression where supported (stable)
fast_mode = true                        # Service-tier selection and Fast-tier commands (stable)
instant_interrupt = true                # New input preempts the model's response; on by default since v0.162.0 (under development)
api_key_model_discovery = true          # Fetch the model catalog when signed in with an OpenAI API key; on by default since v0.161.0 (stable)
goals = true                            # Goal mode; stable and on by default in v0.133.0+
hooks = true                            # Lifecycle hooks (stable)
multi_agent = true                      # Enable multi-agent collaboration tools (stable)
personality = true                      # Personality selection (stable)
plugins = true                          # Plugin system (stable)
plugin_hooks = true                     # Plugin-bundled hooks (stable)
plugin_sharing = true                   # Workspace plugin sharing (stable)
browser_use = true                      # In-app browser automation (stable)
browser_use_external = true             # Browser-extension browser use (stable)
computer_use = true                     # macOS Computer Use (stable, plan/region gated)
in_app_browser = true                   # Shared rendered-page preview (stable)
image_generation = true                 # Image-generation tool (stable)
guardian_approval = true                # Auto-review approval path (stable)
skill_mcp_dependency_install = true     # Prompt/install missing skill MCP deps (stable)
tool_suggest = true                     # Tool/plugin suggestion surface (stable)
workspace_dependencies = true           # Workspace dependency discovery (stable)
memories = true                         # Memories (experimental)
network_proxy = false                   # Sandboxed-command network proxy (experimental); boolean or table, see below
prevent_idle_sleep = true               # Keep machine awake during active turns (experimental)
terminal_resize_reflow = true           # Terminal reflow improvements (experimental)
guardian_conversation_history_tools = false  # Guardian reads earlier user messages (under development, v0.160.0)

# Removed or deprecated feature names still appear in `codex features list`
# for migration diagnostics. Do not set removed flags such as
# `collaboration_modes`, `request_rule`, `codex_git_commit`,
# `apply_patch_freeform`, `search_tool`, or `js_repl` in new configs.

# ─── Guardian Auto-Review (v0.160.0 history keys) ─────
[auto_review]
conversation_history_max_output_tokens = 4000   # Per history-tool response, estimated tokens (default 4,000)
experimental_conversation_history_prompt = ""   # Blank = built-in retrieval instructions

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

features.network_proxy 的类型为 boolean | table。 布尔值形式仅用于启动或停止代理；表形式则承载策略。该代理负责对沙盒命令强制执行权限配置文件中的域名规则：如果将其关闭，[permissions.<name>.network] 中的域名规则将不会执行，命令会直接访问网络。它不会筛选网页搜索、应用、MCP 服务器或其他托管工具。[^216]

[features.network_proxy]
enabled = true
allow_local_binding = false
proxy_url = "http://127.0.0.1:3128"

[features.network_proxy.domains]
"api.github.com" = "allow"
"*.npmjs.org" = "allow"          # subdomains only
"**.example.com" = "deny"        # apex plus subdomains; deny wins on conflicts

requirements.toml 中由管理员管理的 experimental_network 要求可以在不设置 features.network_proxy 的情况下启动代理。[^216]

配置方案

适用于不同工作模式的命名配置预设。自 Codex 0.134.0 起，每个配置方案都有自己的文件——~/.codex/<name>.config.toml，且仅包含顶层键——--profile <name> 会将该文件叠加到 ~/.codex/config.toml 上。系统不再读取 config.toml 中旧版的 [profiles.<name>] 表和顶层 profile = "<name>" 选择器；如果遗留了 [profiles.<name>] 表，--profile <name> 将拒绝启动，直到您将其中的键移入配置方案文件。¹²²

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0
sandbox_mode = "read-only"

# ~/.codex/auto.config.toml
model = "gpt-6.1-sol"
# GPT-6.1 Sol starts at Standard speed; /fast toggles Fast (2.5x credits)
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

配置方案文件位于基础用户配置之上、项目配置和 CLI 配置之下，因此只需包含与基础配置不同的值。¹²²

激活配置方案：

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

专家提示：在配置的顶层设置 profile = "fast"，即可指定默认配置方案。使用 --profile 可针对单次会话进行覆盖。

自定义模型提供商

连接到 Azure、AWS Bedrock、本地模型或代理服务：

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
# v0.140.0+ adds managed Amazon Bedrock API-key authentication, and stores
# CLI and MCP OAuth credentials in encrypted local storage.[^184]
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

env_key 指定保存提供商 API 密钥的环境变量；密钥本身绝不能写入 config.toml。设置了 requires_openai_auth = true 的提供商会在首次运行时显示登录界面，并将凭据存储在 cli_auth_credentials_store 所选择的后端（file、keyring 或 auto）中，不一定存储在 auth.json 中。自 v0.160.0 起，设置了 model_catalog_url 的提供商只会获得该目录中的模型，不会合并任何内置模型；如果目录刷新失败，系统会丢弃缓存条目，而不会继续使用过期数据。¹⁷⁵ 自 v0.162.0 起，自定义 Responses 兼容提供商还可以在 [model_providers.<name>.capabilities] 下声明其支持的功能：external_web_access = false 会阻止该提供商的托管网页搜索访问实时互联网；remote_compaction = "v2" 则选择加入 Responses compaction_trigger 协议。否则，只有 OpenAI 和 Azure Responses 提供商会使用该协议（"unsupported" 会将压缩保留在本地执行）。¹⁸⁰

警告： chat/completions 线路 API（wire_api = "chat"）已不建议用于 OpenAI 托管模型，OpenAI 宣布将于2026年2月移除该功能。³⁴ 本地提供商（Ollama、LM Studio）可能仍接受此格式。对于 OpenAI 端点，请改用 wire_api = "responses"。

使用 --oss 标志调用本地模型：

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

也可以在配置中设置：

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

内联配置覆盖

从命令行覆盖任意配置值：

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

我应该选择哪个模型？

可用模型（2026年9月）

**GPT-5.5（2026年4月23日）**在发布时是OpenAI针对大多数Codex任务的推荐选择，包括复杂编码、计算机操作、知识工作和研究工作流。2026年4月23日面向ChatGPT Plus/Pro/Business/Enterprise/Edu/Go用户在Codex CLI/网页/桌面端推出；4月24日进入OpenAI API。上下文窗口：Codex中为400K，API中为1M——Codex将窗口限制为400K，以平衡各订阅层级的吞吐量和成本；API则提供完整的1M。定价（API）：每百万token输入$5/输出$30（是GPT-5.4费率的2倍；OpenAI表示，计入token效率提升后，实际增幅约为20%）。基准测试：Terminal-Bench 2.0为82.7%（在公开可用模型中达到当时的最高水平）、GDPval为84.9%（涵盖44种职业）、OSWorld-Verified为78.7%、Tau2-bench Telecom为98.0%（未进行提示词调优）。OpenAI在发布前曾内部使用GPT-5.5与Codex重写服务基础设施，使token生成速度提升了20%。⁸³

使用ChatGPT登录时，GPT-5.5将于2026年10月14日从Codex退役——模型文档将退役范围限定为所有套餐中的ChatGPT、ChatGPT Work和Codex（包括消费者、Business、Enterprise和Edu），并明确说明OpenAI API不受影响。¹⁴⁸随着GPT-6发布，替代建议也有所变化：Plus、Pro、Business、Enterprise和Edu用户应在“可用时”选择gpt-6-sol；Free和Go用户则应在桌面应用中选择gpt-6-luna。请替换工作区默认值、已保存的模型设置、托管配置、自定义智能体、计划任务和脚本中的gpt-5.5。¹⁶⁴

使用ChatGPT登录时，GPT-5.4和GPT-5.4 mini已于2026年8月31日从Codex退役。¹¹⁷模型文档目前指定gpt-6-sol和gpt-6-luna作为替代模型（在Enterprise和Edu中，管理员必须先启用Luna）；使用API密钥不受影响。⁶⁴¹⁶⁴确切的模型列表因账户和发布进度而异。请检查本地缓存：~/.codex/models_cache.json。

弃用说明（2026年3月11日）：ChatGPT已不再提供GPT-5.1模型。现有对话会自动改用GPT-5.3 Instant、GPT-5.4 Thinking或GPT-5.4 Pro继续进行。GPT-5.1-Codex-Mini仍可通过API和CLI使用，直至2026年7月23日停止服务。⁷¹⁸⁸

免费层级说明（2026年5月5日）：GPT-5.5 Instant于2026年5月5日开始向ChatGPT免费层级推出。这使GPT-5.5系列的受众从付费套餐进一步扩大，但访问Codex CLI仍需符合条件的Plus/Pro/Business/Enterprise/Edu/Go订阅或API密钥。⁹²

GPT-5.4 mini（2026年3月17日）：GPT-5.4的一款更小、更快的变体，拥有400K上下文，价格为每百万token $0.75/$4.50，仅消耗GPT-5.4配额的30%。非常适合委派给子智能体：由GPT-5.4负责规划和协调，同时让GPT-5.4 mini子智能体并行处理范围更窄的子任务（代码库搜索、文件审查和文档处理）。⁷⁶

Bedrock GPT-5.6（Sol、Terra、Luna）（v0.143.0，2026年7月8日）：Codex为Amazon Bedrock托管的3种GPT-5.6模型变体新增了一等支持，包括对max推理强度级别的支持。对于通过Bedrock提供商访问模型的团队，它们的选择方式与其他自定义提供商模型相同（请参阅“自定义模型提供商”）；max强度层级面向最困难的推理和智能体工作负载。¹⁰⁶ v0.144.6（2026年7月18日）更新了Sol、Terra和Luna的内置说明，并将它们的上下文窗口修正为272,000个token。¹¹¹ v0.145.0（2026年7月21日）新增支持自定义端点和身份验证的实验性Bedrock登录，将GPT-5.6 Sol设为默认Bedrock模型，并把内置GPT-5.4模型选择迁移至对应的Terra和Luna变体。¹¹²

GPT-6-Astra（发布于2026年9月3日；通过v0.153.1至v0.153.4进入Codex）：明确日期的时间线如下：v0.153.1于2026年9月3日预置了仅限API的目录条目；OpenAI同日发布GPT-6-Astra；v0.153.4于9月4日新增选择器条目，并将内置CLI默认模型切换为该模型。公告描述了分阶段发布方案：先面向数量有限的组织（网络安全项目合作伙伴优先），随后“在未来几天内”扩展到ChatGPT Plus、Pro、Business和Enterprise，以及OpenAI API和AWS——这些发布信息来自媒体报道（CNBC、Axios、Forbes、Al Jazeera、9to5Mac）。¹³⁸9月4日的更新取代了上述信息：OpenAI在X上宣布，GPT-6 Astra“现已面向ChatGPT Work和Codex中的所有Pro、Enterprise和Business Premium用户开放”，并且“已在API中上线”；预计Plus和Business将在数日内获得访问权限。同日晚些时候，Codex负责人Tibo Sottiaux补充称：“Astra现已向所有Plus和Business用户推出。”实际授权仍不均衡——9月5日的社区报告显示，部分Plus账户在Codex中仍只能看到GPT-5.6模型——而下文引用的模型文档可用性说明没有变化，因此仍应将其视为有效的第一方声明。¹⁴²第一方文档现已上线：API模型页面将gpt-6-astra列为旗舰模型，称其为“我们能力最强的模型，专为最困难的端到端工作打造”——标准短上下文价格为输入每百万token $10、输出每百万token $50；上下文窗口为1.05M个token，最大输入为922,000个token，最大输出为128K，知识截止日期为2026年4月30日——并记录了长上下文计费层级：输入超过272K个token的提示词，整个请求的输入价格为2倍、输出价格为1.5倍；定价页面列出的价格为输入每百万token $20、输出每百万token $75。其定位高于GPT-5.6 Terra（均衡）和Luna（经济型），Codex文档也将Astra称为推荐的Codex模型，但其可用性“取决于发布进度、您的登录方式和客户端”，符合条件的账户包括Pro、Business（$100）和Enterprise。文档列出的Astra Codex推理阶梯为：Low、Medium、High、Extra High、Max、Ultra——文档的模型页面将Medium标为默认值，但v0.153.4内置目录中的default_reasoning_level设为low，因此实际默认值应视具体界面而定，并在会话中使用/status检查；9月15日重新访问时，该阶梯保持不变，同时新增了各级别的选择器说明（Ultra的原文为：“Maximum reasoning with automatic task delegation”），Max和Ultra层级也得到SDK确认——2026年9月10日发布的Python SDK 0.154.0新增了max和ultra推理强度值（#39662）。^139141146在CLI中，自v0.153.1起可通过API配置Astra（-m gpt-6-astra）；v0.153.3将其加入Amazon Bedrock目录（GPT-5.6 Sol仍是Bedrock默认模型，直至v0.157.0将其改为GPT-6 Sol¹⁶⁷）；自v0.153.4起，它进入模型选择器，并在未明确配置模型时作为内置默认模型——文档未说明最低CLI版本，因此可将这些版本视为实际下限。默认模型的切换属于内置CLI目录的事实，并非适用于所有界面——不过cloud方面的差距此后已经弥合：9月4日和9月7日的访问结果将Astra标记为不支持Codex cloud（GPT-5.6 Sol支持），而9月15日重新访问时，可用性矩阵已将Astra标记为同样支持Codex cloud；页面仍注明“目前无法更改Codex cloud聊天的默认模型。”发布注意事项：授权情况因账户而异；在CLI 0.153.4及更高版本中，尚未纳入发布范围的账户会携带一个自身无法使用的内置默认模型——请在config.toml中固定模型（或传递-m）以确保选择结果稳定；自v0.156.1起，文档自身的示例为model = "gpt-6-sol"。虽然模型页面未列出Fast层级，但Astra的Fast模式计费已有文档说明：Codex速度文档指出，使用ChatGPT登录时，其消耗的积分为Standard的2.5倍（“在可用时”）；API定价页面列出的Fast模式费率恰好是相应Standard费率的2倍（短上下文为每百万token $20/$100，长上下文为$40/$150）。v0.153.2目录字符串中“2倍速度”的描述仍只是目录显示文本——速度页面并未说明Astra的速度倍数。^138139140141 **部分内容于2026年9月23日被取代：**模型文档不再将Astra称为推荐的Codex模型。“推荐模型”部分现以GPT-6 Sol和Luna为首选，仅将Astra用于“最困难的端到端工作”，将Astra标记为不支持Codex cloud，并把Astra的起始推理强度设为Light（low），与内置目录一致。在未配置模型时，Astra仍是内置CLI默认模型。¹⁶⁴ **2026年9月29日被取代：**v0.159.1将GPT-6.1 Sol设为内置默认模型，并把Astra移至选择器第二位；模型文档现推荐使用GPT-6.1 Sol进行复杂编码，同时保留Astra用于最困难的端到端工作；文档中的配置示例现已使用gpt-6.1-sol。¹⁷¹

**Astra下的Power预设（文档于2026年9月6日或更早新增）：**Codex模型文档中关于模型选择器的段落现已将选择器的Power选项映射到GPT-6-Astra推理层级——这是文档首次将Power预设映射到Astra。该段落在¹³⁹所述的9月5日重新访问时尚不存在，9月7日确认已上线。原文：“For eligible Pro, Business ($100), and Enterprise accounts, the Astra rollout updates the Power options to Terra Light, Sol Light, Sol Medium, Astra Light, Astra Medium, and Astra Extra High. Options can differ by plan and rollout stage.”此前的文档句子指出，选择器示意图仍显示GPT-5.6控件。结合上方模型表理解：“Power”过去指采用medium推理强度的GPT-5.6 Sol；在已获授权的账户中，同一预设阶梯现覆盖采用固定推理强度的Terra、Sol和Astra，而具体选项仍取决于套餐和发布阶段。2026年9月15日重新访问时，该段落原文未发生变化。¹³⁹ **2026年9月23日更新：**GPT-6 Sol和Luna发布后，文档列出的6个Power预设为“Luna High、Sol Light（起始预设）、Sol Medium、Astra Light、Astra Medium和Astra Extra High”；文档还指出，部分付费套餐不提供Astra Extra High，并建议Sol从Medium开始、Luna从High开始、Astra从Light（low）开始。¹⁶⁴

**跨上下文实验说明（Astra，文档已发布，须主动选择启用）：**Codex模型文档页面包含标题为“Experimental context management”的部分，原文为：“On supported Codex clients, users signed in with ChatGPT Plus or Pro can opt in to experimental context management. Astra keeps notes across context windows and can search earlier messages and tool results from the same task. This experiment is off by default and isn’t available with Business, Enterprise, or API-key sign-in at launch.”主动选择启用的机制原文为：“To opt in, set features.context_management.experimental_mode = true in your config.toml, then start a new task.”这就是v0.153.0推出的features.context_management.experimental_mode配置界面（请参阅“上下文管理”）——模型文档现将其明确关联至Astra以及Plus和Pro登录，而v0.153.0发布说明中曾列出符合条件的Plus、Pro和Pro Lite会话。v0.154.0进一步收紧了代码端限制：实验资格现由会话启动时活动模型的能力决定（#43147）。2026年9月15日重新访问时，该文档部分原文未发生变化。此功能仍处于实验阶段，且默认关闭；其行为和资格条件可能随时变化。^133139145 **v0.157.0：**内置模型目录不再将GPT-6-Astra或任何其他内置模型标记为支持实验性上下文（#47397），而CLI仅会为带有相应标记的模型启用该实验。因此，使用内置目录时，主动启用设置不会产生效果；为已登录账户提供的目录是否有所不同，文档并未说明。截至2026年9月26日，模型文档仍在介绍此主动启用选项。¹⁶⁷ **2026年9月29日：**模型页面已移除该部分；配置参考将features.context_management.experimental_mode描述为“Experimental context-management setting. The feature is not currently available”，GPT-6.1 Sol也未被标记为支持该功能。¹⁷¹

模型选择流程图

Is this a quick fix, extraction, or other well-defined repeatable task?
├─ Yes → gpt-6-luna (most efficient; docs suggest starting at High)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Hardest end-to-end work across many steps and tools?
   │     │  ├─ Yes → gpt-6-astra (strongest; most expensive)
   │     │  └─ No → gpt-6.1-sol (near-Astra at lower cost; default since v0.159.1)
   └─ GPT-6.1 Sol not yet available on your account? → gpt-6-sol, then gpt-5.6-sol

推理强度

控制模型在响应前进行多少“思考”：

支持的级别取决于模型。minimal仅适用于GPT-5模型。并非所有模型都支持每个级别。

**persistent详情（v0.151.0）：**以persistent强度运行的轮次默认启用当前时间提醒和可中断的clock.sleep工具（会保留显式的features.current_time_reminder设置和托管要求），并提供内置的主动行为及后续操作指导；模型元数据可以通过persistent_instructions覆盖或禁用这些指导。¹²⁸

codex -c model_reasoning_effort="xhigh" "find the race condition"

专家提示：对于同一提示词，xhigh推理消耗的token可能是medium的3至5倍。请仅在真正困难且额外思考物有所值的问题上使用它。

TUI快速推理控件（v0.124.0及更高版本）。⁸⁵在交互式TUI会话中，Alt+,可将推理强度降低一级，Alt+.可将其提高一级——当会话中途遇到难题，需要临时按medium → high → xhigh逐级提高强度，又不想使用/effort或-c时，这一功能非常实用。在会话中途接受模型升级后，推理强度会重置为新模型的默认值，而不会沿用之前的级别。

切换模型

使用/model slash command可在会话中途切换模型，也可通过--model/-m为单次运行设置模型：

codex -m gpt-5.3-codex-spark "pair with me on this component"

Codex 的费用是多少？

另请参阅模型选择了解各项功能，并参阅决策框架根据任务选择合适的模型。

通过 ChatGPT 套餐访问

Codex 的可用性取决于您的 ChatGPT 套餐和组织设置：⁵¹

**2026年4月定价更新：**Business 年付价格从每席位每月 $25 降至 $20。Business 和 Enterprise 工作区现已提供按使用量付费的仅 Codex 席位——不收取固定席位费，按 token 使用量计费。⁷⁹ 定价页面现在按模型公布额度范围（参见上表），不再采用 2026年2月 Desktop App 发布时宣传的 2x 倍数。¹⁶¹⁵⁵

**2026年5月使用额度提升（已于2026年5月31日结束）：**Plus 套餐中的 Codex 在 5 小时窗口内采用 25× 额度（标准提升为 20×），同期 $100/月档位的额度翻倍。⁸⁹

TUI 中的速率限制体验（v0.152.0-v0.153.0）：达到限制后不再无路可走。v0.152.0 会在输入框上方显示可操作的速率限制横幅——包括检查用量、管理额度、重置限制、通知工作区所有者和管理套餐——并根据已认证的账户和用户筛选相关操作；发生限制错误后会刷新用量。当横幅发出相应指示时，Codex 会切换到首个可用的后备模型，同时保持其他线程设置不变。¹³¹ v0.153.0 为 Plus 和 Team 套餐增加了更早的警告：在约 5 小时的使用窗口内，剩余额度不足一半时即会发出警告；其他套餐和不同长度的窗口则继续采用现有的 75%、90% 和 95% 阈值。¹³³

额度成本

Codex 操作会消耗套餐分配的额度：

这些费率适用于 Standard 速度。定价页面表示，GPT-6 发布后，GPT-5.6 Sol、Terra 和 Luna 的费率“保持不变”。实际使用中，“GPT-5.6 每条消息平均消耗 5-30 额度”（8月开放使用时页面显示为 5-40）；对于 GPT-6.1 Sol 以及 GPT-6 Astra、Sol 和 Luna，Fast 模式“在可用时”的成本为 Standard 额度费率的 2.5 倍。捆绑模型目录还会在 TUI 中默认对 GPT-6 Sol 和 Luna（不包括 GPT-6.1 Sol）启用 Fast 档位，除非您设置 service_tier。因此，如果额度消耗速度超出预期，请检查 /fast status。图像生成对内含额度的消耗速度，是同等纯文本交互的 3-5 倍。^155164171

Enterprise 和 Edu 套餐的额度会随合同分配规模调整。请在 TUI 中使用 /status 查看当前用量。

API 计费

通过 API 使用 Codex 时，OpenAI 会按照所选模型的标准 OpenAI API 定价按 token 计费（并计入任何适用的提示缓存折扣）。当前每 100 万个 token 的 API 费率为：GPT-6.1 Sol 输入 $2 / 输出 $10（缓存输入 $0.10），GPT-6 Sol 为 $2 / $10，GPT-6 Luna 为 $0.10 / $0.50，GPT-6 Astra 为 $10 / $50；对于这 4 个模型，当提示的输入 token 超过 272K 时，整个请求的输入费用按 2 倍计算，输出费用按 1.5 倍计算；Fast 模式按 2 倍计费。^139164171 使用 API 密钥登录时，不适用 ChatGPT 额度倍数。请查看官方 API 定价页面了解当前费率。²⁰

成本优化策略

1. 使用配置文件：为日常任务创建使用 gpt-6-luna 且设置 model_reasoning_effort = "low" 的 fast 配置文件
2. 为高强度推理留出空间：仅对真正棘手的问题使用 xhigh，因为它会多消耗 3-5 倍的 token
3. 使用 --ephemeral：在 CI/CD 中跳过会话持久化，以减少开销
4. 精简推理摘要：不需要解释时，将 model_reasoning_summary = "none"
5. 通过 exec 模式批量处理：codex exec 可避免自动化工作流中的 TUI 开销
6. 监控用量：查看 TUI 中的 /status 和组织计费仪表板——自 v0.148.0 起，对于符合条件的工作区，/status、状态行和终端标题会显示线程的估算额度或成本¹¹⁸

实际成本示例

常见任务的代表性 API 成本（基于 2026年年中 gpt-5.3-codex 的定价快照，采用中等推理强度——各模型之间的相对成本比例大致相通）：

成本会因推理强度、缓存和对话长度而异。日常任务可使用 gpt-5.6-luna，显著降低相关支出。缓存输入 token 可享受折扣计费。

隐藏的 token 开销

每次工具调用都会产生可见提示之外的额外 token：

**专家提示：**请通过 TUI 中的 /status 监控实际用量。token 计数包含所有开销，而不仅是可见消息。如果成本出乎意料，请检查已连接的 MCP 服务器数量——每台服务器都会向每次 API 调用添加工具定义。

团队成本管理

团队成本控制策略： - 设置 requirements.toml，在整个组织范围内强制实施模型和推理强度限制 - 在 CI/CD 中使用 gpt-5.6-luna——自动化流水线通常无需最高推理强度 - 基于配置文件编制预算——为 ci、review 和 dev 配置文件定义适当的成本上限 - 通过 OpenTelemetry 监控——Enterprise 部署可以将用量遥测数据导出到现有的可观测性技术栈

决策框架

何时使用各个界面

何时使用各个sandbox模式

何时使用各个推理级别

Plan模式与直接执行

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer模式：Enter与Tab

经验法则：Enter=“停下来，现在听取此信息。”Tab=“完成当前工作后，再执行此任务。”

Desktop App与CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

应选择哪个配置文件？

根据任务选择预配置的配置文件：

配置文件（每个预设对应一个文件，位于~/.codex/中；自0.134.0起，不再读取旧版单文件profile = "default" + [profiles.*]布局¹²²）：

# ~/.codex/fast.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"

# ~/.codex/careful.config.toml
model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

# ~/.codex/pair.config.toml
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

# ~/.codex/ci.config.toml
model = "gpt-6-luna"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

为每个会话切换配置文件：codex --profile careful

Sandbox 与审批系统如何运作？

Codex 采用双层安全模型，将技术上可执行的操作与Codex 何时请求人工审批区分开来。这种方法与 Claude Code 的权限系统有本质区别——Codex 在操作系统内核层面强制执行限制。⁵另请参阅企业部署，了解管理员在整个组织范围内强制实施的 requirements.toml 约束。

v0.148.0 安全加固：现在，无论在 Linux 还是 Windows 上，sandbox 限制均采用故障关闭机制——遭到拒绝或无法读取的路径会被视为已阻止，而不会被默许访问。¹¹⁸

第 1 层：Sandbox（可以执行哪些操作）

Sandbox 使用操作系统原生机制控制文件系统和网络访问：

特定平台的强制执行机制：

• macOS：通过 sandbox-exec 使用 Apple 的 Seatbelt 框架，在运行时编译与模式对应的配置文件，并由内核强制执行。⁶自 v0.121.0 起，macOS sandbox 配置文件可以将特定的 Unix 套接字（例如 docker.sock、编辑器 IPC 套接字）加入允许列表，并且默认不再阻止私有 DNS 解析。⁸²
• Linux：使用 Landlock 限制文件系统访问，并使用 seccomp 过滤系统调用。独立辅助进程（codex-linux-sandbox）可提供纵深防御隔离。⁵Bubblewrap（bwrap）已纳入项目，并作为 Linux 构建的一部分进行编译（自 v0.100.0 起由可选组件升级而来）。⁷v0.117.0 提升了在采用旧版内核配置的老旧发行版上的 sandbox 可靠性。⁷⁵v0.129.0 加固了 Linux 上的 sandbox 启动过程，并将项目内置的 Bubblewrap 升级至 0.11.2，纳入上游安全补丁；v0.130.0 进一步加固了启动流程。⁸⁹⁹¹
• Windows：采用带受限令牌的原生 sandbox（自 v0.100.0 起由实验性功能升级而来）。同时支持 WSL（沿用 Linux 的 Landlock 与 seccomp）。v0.117.0 改进了受限令牌 sandbox，可提供更完善的进程隔离。⁷⁵v0.130.0 允许 sandbox 用户访问桌面运行时二进制缓存，使 Windows sandbox 能够为工作区 sandbox 用户可靠地解析运行时二进制文件。⁹¹

这为何重要：与基于容器的 sandbox（Docker）不同，操作系统级 sandbox 速度更快、更轻量，也更难逃逸。甚至在 Codex 看到系统调用之前，内核就已强制执行相关限制。

安全修复： - **zsh-fork sandbox 绕过漏洞（v0.106.0）：**修复了通过 zsh 派生进程执行 shell 时可能绕过 sandbox 限制的漏洞。⁶⁰如果仍在使用更早版本，请立即升级。 - **输入大小上限（v0.106.0）：**Codex 现在将输入限制在约 100 万个字符以内，以防止因载荷过大而卡死。⁶⁰ - **安全的 devcontainer 配置文件（v0.121.0）：**面向 Docker devcontainer 新增了经过加固的客户配置文件，在容器内使用 Bubblewrap 实施 sandbox。支持 WSL2；明确拒绝 WSL1（Bubblewrap 与 WSL1 的内核兼容层不兼容）。⁸² - Guardian 审查与 hooks（v0.121.0）：Guardian 审查会话期间会禁用 hooks，避免工具调用前后的 hooks 干扰 Guardian 子代理的决策。⁸²如果依赖 hooks 进行日志记录或验证，请注意 Guardian 审查会跳过它们。如需完整审计轨迹，请改用应用服务器的可观测性功能。 - **Linux /dev 文件系统（v0.105.0）：**Linux 上以 sandbox 方式运行的命令现在会获得一个最小化的 /dev 文件系统，从而改善与依赖设备节点的工具之间的兼容性。⁶¹

**ReadOnlyAccess 策略（v0.100.0+）：**一种可配置的策略结构，用于精细控制读取权限。即使处于 workspace-write 模式，也可以用它限制 Codex 能够读取哪些目录：

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

第 2 层：审批策略（何时询问）

审批策略决定 Codex 何时暂停并请求人工确认：

on-failure 仍会出现在一些较早的示例和兼容路径中，但 OpenAI 当前的配置文档已将其标记为弃用。交互式运行建议使用 on-request；对于已经具备外部安全边界的非交互式运行，请使用 never。⁸⁷

自 v0.150.0 起，可以绑定一个键盘快捷键，以便从输入区循环切换权限模式——请通过 /keymap 进行配置。[^218]

独立审批 ID（v0.104.0+）

Codex 现在会为多步骤 shell 执行中的每条命令分配独立的审批 ID。这意味着审批粒度更细——批准序列中的一条命令，不会自动批准同一次 shell 调用中的后续命令。⁴⁹

灵活的审批控制（v0.105.0+）

审批流程现在支持额外的 sandbox 权限和精细化拒绝：⁶¹

• 额外的 sandbox 权限：当命令需要超出当前 sandbox 模式的访问权限时，Codex 可以请求特定的附加权限，而无须切换整个模式
• 精细化拒绝：拒绝单个工具调用时可以附带反馈，让 Codex 调整处理方式，而不是简单地再次尝试同一命令

运行时权限请求（v0.113.0+）

Codex 现在内置了 request_permissions 工具，允许模型在运行时请求附加权限。⁶⁹当模型遇到需要提升访问权限的任务时，可以通过 TUI 审批流程正式请求特定权限（文件系统路径、网络访问等），而不会悄然失败，也无须用户使用不同的标志重新启动。

应用审批模式 writes（v0.144.0+）

应用和连接器新增了一个中间审批级别：writes 应用审批模式允许应用声明的只读操作直接运行而不显示提示，但任何写入操作仍会暂停并等待审批。¹⁰⁷在此之前，应用审批更接近全有或全无；writes 更符合多数运维人员对集成的实际信任模式——查看无需询问，修改必须获批。

自动审查审批：--approve-for-me（v0.147.0+）

新的 --approve-for-me CLI 标志会将审批提示转变为自动审查审批：每个请求不再打断您，而是交由审查流程判定，并代表您批准或拒绝。¹¹⁶它介于“批准一切”（现已移除的 --full-auto 曾鼓励采用的方式）与“一切都要打断”之间——提示仍作为决策节点存在，只是改由审查器作答。该标志会沿用 v0.146.1 针对具备网络安全能力的模型所设置的更安全自动审查默认值。应当像对待任何权限委托一样使用它：适合长时间无人值守、被打断就会停滞的运行；如果会话会接触凭据或生产环境状态，而您希望亲自审查，则不应使用。

提升权限的终端输入审批（v0.151.0；自 v0.158.0 起默认启用）

write_stdin_approval 功能标志在 v0.151.0 推出时默认关闭，自 v0.158.0 起默认启用。向提升权限的统一执行终端发送非空输入之前，该标志会要求重新审批。这类审查会通过 hooks、Guardian、应用服务器和 TUI，以 writeStdin 审批形式进行；终端环境、启动目录和权限提升状态会跨轮次保留，并且在审批通过后、写入任何字节之前，会重新验证进程身份。完整格式化的操作和审批理由不得超过 8,000 字节——过大或遭截断的操作会在请求审批或向终端发送任何内容之前被拒绝。¹²⁸v0.158.0 启用了该标志（#47799），并停止对仅限运行时的授权触发审查，例如插件用于指标收集的授权；但代理额外权限、sandbox 绕过以及启动后的策略变更仍会触发审查（#48073）。**如需关闭：**请在 config.toml 的 [features] 下设置 write_stdin_approval = false。¹⁶⁹

权限配置文件（v0.113.0+，在 v0.128.0 和 v0.133.0 中扩展）

权限配置文件将文件系统和网络 sandbox 策略拆分为可命名、可复用的部分。将 default_permissions 设置为内置配置文件，例如 :read-only、:workspace，或让它指向自定义 [permissions.<name>] 表。⁸⁷v0.133.0 将配置文件提升为托管界面：用于列出 API 的接口会公开可用的配置文件元数据；配置文件之间可以相互继承；托管的 requirements.toml 可以声明权限要求；活动配置文件会在运行时刷新；Windows sandbox 设置现在也会使用解析后的配置文件，而不再使用单独的临时策略。⁹⁸

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

对于敏感文件和 glob 模式，请使用 none，确保即使项目根目录可写，这些内容也无法读取。对于一次性的命令例外，建议优先使用规则，而不是大范围扩展配置文件。⁸⁷

**v0.151.0：**恢复的应用服务器线程会保留其权限配置文件，不再被扁平化为旧式的逐轮 sandbox 覆盖设置——配置文件可在轮次路由和兼容的 /cd 目录变更中持续生效；如果某个 /cd 无法将恢复的配置文件安全地表示为旧式 sandbox 模式，系统会拒绝该操作，而不会悄然削弱限制。[^221]

旧版 --full-auto 指南

较早的指南将 --full-auto 描述为以下设置的便捷别名：

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

在 v0.128.0 中，发行说明将 --full-auto 标记为弃用，并且当前的 CLI 帮助信息已不再为交互式运行列出该选项。请改用上述明确标志或命名权限配置文件。⁸⁶

**v0.147.0 完成了移除工作：codex exec --full-auto 已不复存在。**仍传入该标志的脚本现在会报错，而不会继续运行。迁移方式简单直接——将其替换为 --sandbox workspace-write（如果旧调用依赖 --full-auto 的审批行为，还需添加审批标志或配置文件）。升级前，请审查所有通过 shell 调用 codex exec 的自动化流程：该问题会表现为流水线中断，而不是弃用警告。¹¹⁶

**Sandbox 可靠性（v0.129.0）：**Linux sandbox 启动加固减少了在低速文件系统或使用符号链接的检出目录中出现的竞态问题；Windows sandbox 的可靠性改进解决了长时间运行期间发生的若干边缘崩溃问题；项目内置的 Bubblewrap 也已升级至包含上游安全补丁的 0.11.2。无须更改配置。运行 codex update 即可获取这些更新。⁸⁹

推荐配置

日常开发（安全的默认选项）：

sandbox_mode = "workspace-write"
approval_policy = "on-request"

高级用户（完整访问权限，由人工参与决策）：

sandbox_mode = "danger-full-access"
approval_policy = "on-request"   # `untrusted` retired in v0.149.0

社区文章将这种组合推荐为“最佳平衡点”⁸；在照搬建议之前，应先了解它实际会做什么：当命令需要越过 sandbox 边界或访问网络时，系统才会显示审批提示，而 danger-full-access 会移除这两项边界，因此 on-request 几乎没有需要提升审批的操作。这意味着权限最大化、询问最少化，而不是每条命令都由人工检查；如果需要后者，请保留 workspace-write，让 sandbox 边界触发提示。¹²³

CI/CD 自动化：

sandbox_mode = "workspace-write"
approval_policy = "never"

使用 Guardian 子代理进行智能审批（v0.115.0+）

智能审批可以通过 Guardian 子代理处理审查请求，无须每项操作都由人工批准。Guardian 会话会在多次审批之间持续存在，以便复用提示缓存并避免启动开销。每次审查都会获得干净的历史记录（此前的决策不会泄漏到后续审查中）。⁷³

在 config.toml 中配置审查器：

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

这尤其适用于 CI/CD 工作流：既希望通过推理实现自动审查，又不想直接采用一概而论的 approval_policy = "never"。

**Guardian v2 默认设置反转（v0.151.0）：**Guardian v2 现在默认使用包含图像的计算机操作审查。features.guardianv2.review_scope.computer_use_only 默认为 true——将其设置为 false 可保留范围更广的工具审查——而 features.guardianv2.transcript.include_images 默认为 true——将其设置为 false 可阻止图像进入 Guardian 记录。这两项设置在 v0.150.0 中作为可配置且默认关闭的功能发布；从 v0.151.0 开始，它们默认启用。¹²⁸

Guardian 范围会随审批模式调整（v0.153.0）：现在有两种模式会跳过无法改变结果的 Guardian 工作。在 Full Access 模式下（该模式已将 approvalPolicy: "never" 与不受限制的权限相结合），仅要求确认的 Guardian 和 MCP 请求无须同步审查、采样器预热或后台评分即可获批——待处理、失败或受限的环境不会被视为 Full Access；系统会在每个轮次重新评估当前权限状态，因此现有线程可以安全地进入或退出 Full Access。在用户审批模式（approvals_reviewer = "user"）下，系统会跳过 Guardian 预热和异步评分，并自动接受普通的 node_repl.js 执行确认，而敏感操作检查和用户输入请求会保留原有行为。¹³³这缩小的是 Guardian 的运行时机，并非人工审批层：本指南所述 on-request 下 danger-full-access 的提示行为属于审批策略，是另一套独立机制。v0.152.1 还允许 Guardian 审批审查从模型元数据（auto_review.node_repl_policy）中获取其 Node REPL 策略；如果缺少该字段，则回退到内置策略。¹³²

**Guardian 计算机操作评分遵循模型要求（v0.153.1）：**只有当活动模型在其元数据中设置 node_repl_auto_review_required 时，才会运行仅限计算机操作的 Guardian 评分和快速审批决策；如果切换模型后跳过评分，既有或进行中的评分都会失效——因此切换回受审查模型时，无法重新启用过期的审批决策。这是 v0.153.1 补丁的主要内容，但未列入发行说明正文：#42422（对 38ba8cdc 的拣选提交）只能通过 rust-v0.153.0…rust-v0.153.1 对比加以证实。¹³⁵

Guardian 父线程压缩复用默认启用（v0.156.0）：#46522 将 guardian_reuse_parent_compaction 提升为稳定功能并默认启用，使 Guardian 在重新启动审查会话时能够复用父线程的加密压缩内容。根据该 PR 的测试，当父级历史记录发生变化时，缓存的审查会话仍会失效。**如需恢复此前行为：**请在 config.toml 的 [features] 下设置 guardian_reuse_parent_compaction = false，或运行 codex features disable guardian_reuse_parent_compaction。¹⁶²¹⁶⁴

Guardian 线程上下文默认启用（v0.157.0）：#47275 将 guardianv2.thread_context 提升为稳定功能，并为同步和异步 Guardian 审查启用该功能，使审查使用线程自身的上下文。它独立于 Guardian v2 的 enabled 开关。在 v0.157.0 中，可以在 [features.guardianv2] 下设置 thread_context = false 将其关闭；v0.158.0 移除了该选项。¹⁶⁷

Guardian 线程上下文始终启用（v0.158.0）：#47686 和 #47689 规定 Guardian 会话捕获和子代理历史记录分支无条件使用线程自身的上下文。Codex 会忽略 [features.guardianv2] 下的 thread_context，包括配置文件覆盖和托管要求中的设置，并显示弃用通知，要求从 config.toml 中将其移除。没有替代的关闭开关。¹⁶⁹

**Guardian 可以读取较早的用户消息（v0.160.0，选择启用）：**Guardian 审查的记录可能会遗漏较早的指令、限制或已撤销权限。在 [features] 下设置 guardian_conversation_history_tools = true 并启用应用后，审查器会获得两个工具：user_message.search_messages 和 user_message.read_messages。这两个工具通过父会话自身的应用连接和身份提供服务。每次调用都会重新检查父会话当前的应用与工具策略；如果工具已禁用或需要审批，则采用故障关闭机制。可通过两个 [auto_review] 键进行调整：conversation_history_max_output_tokens 限制每次响应的大小（默认估算为 4,000 个 token；父会话更严格的限制仍然适用），experimental_conversation_history_prompt 则替换内置检索指令（留空时使用默认指令）。第二个选择启用标志 guardian_root_handoff_context 会将工作代理审查时使用的根对话证据，缩小至每次向其移交任务前后的消息以及最新的 3 条消息。这两个标志仍在开发中，默认关闭；配置参考文档尚未将其列出。¹⁷⁵

[features]
guardian_conversation_history_tools = true

[auto_review]
conversation_history_max_output_tokens = 4000

PowerShell 分类器收紧（v0.142.2）：如果 PowerShell 命令包含安全分类器无法检查的可执行 AST 区域，现在将要求审批，而不会逃过自动审批——这填补了 Windows 上经过混淆或动态构建的 PowerShell 绕过分类的缺口。¹⁰⁵

危险命令检测扩展（v0.144.5）：检测现在能够识别更多强制执行 rm 的形式，并且被拒绝的命令会返回更明确的拒绝理由，而不是含糊的拒绝信息——调整审批策略并需要了解命令为何被阻止时，这一点尤为实用。¹¹⁰

启用网络访问

默认情况下，Codex 会在 workspace-write 模式中阻止网络访问。需要时可将其启用：

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

WebSocket 代理支持（v0.104.0+）

对于通过代理转发 WebSocket 流量的企业环境，Codex 现在支持 WS_PROXY 和 WSS_PROXY 环境变量：⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

它们是对现有 HTTPS_PROXY 和 SOCKS5 代理支持（v0.93.0+）的补充。

**v0.146.0 才真正实现了“所有传输层”均受支持。**配置的代理现在会在身份验证、插件下载、MCP 授权、远程执行、WebSocket 连接、HTTP 重定向和 LM Studio 连接中生效——变更日志列出的这 7 条路径此前都会忽略代理。¹¹⁴如果在 v0.146.0 之前通过企业代理运行 Codex，并发现普通模型调用可以正常工作，但登录或插件安装失败，那么很可能正是这一缺口所致。

**macOS 上的系统代理（v0.142.2+）：启用 respect_system_proxy 后，macOS 身份验证客户端会遵循系统代理、PAC 和 WPAD 设置，因此通过配置文件下发代理配置的企业 Mac 无须再为身份验证流量逐个 shell 设置代理环境变量。¹⁰⁵自 v0.143.0 起，该支持扩展至 Windows 和 Responses API 流量：**Codex 会通过 macOS 或 Windows 系统代理路由身份验证和 Responses API 调用，包括 PAC 与 WPAD 自动配置，从而补齐这两种操作系统在严格管控的企业网络中的最后一处缺口。¹⁰⁶

测试 Sandbox

在信任 sandbox 之前，请先验证其行为：

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

如果 sandbox 工作正常，在工作区范围的配置文件下，这两条命令都应因权限被拒绝而失败。如果其中任何一条命令成功执行，则需要检查 sandbox 配置。

AGENTS.md 如何工作？

AGENTS.md 是 Codex 的项目指令系统，也是一项开放标准⁹，现由 Linux Foundation 旗下的 Agentic AI Foundation 管理。Codex、Cursor、Copilot、Amp、Jules（Google）、Gemini CLI、Windsurf、Cline、Aider、Zed、Factory、RooCode 以及超过 60,000 个开源项目均支持该标准。它定义了 Codex 在特定代码仓库或目录中的行为方式。有关与 AGENTS.md 相辅相成的可复用专业能力包，请参阅 Skills。

发现层级

Codex 会在会话开始时遍历目录树，构建指令链：

1. 全局（~/.codex/）：AGENTS.override.md > AGENTS.md
2. 项目（从 git 根目录到当前目录）：在每一级依次检查 AGENTS.override.md > AGENTS.md > 后备文件名
3. 合并：文件按从根目录向下的顺序拼接；路径越近的文件在提示词中出现得越靠后，并会覆盖先前的指导

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

**不受信任的项目会跳过项目 AGENTS.md（v0.150.0）：**上述遍历过程以项目受信任为前提。自 v0.150.0 起，“不受信任的项目不再提供项目级 AGENTS.md 指令，并且托管的拒绝读取规则在权限变更后仍会继续执行” – 在保留用户级 ~/.codex/AGENTS.md 指令的同时，系统会跳过项目范围的发现流程，因此不受信任的检出内容无法在您信任它之前注入操作约定。[^218]

**桌面端多文件夹项目（26.715，2026年7月23日）：**上述遍历过程描述的是 CLI，它会相对于当前工作目录解析所有内容。ChatGPT 桌面应用现在允许一个本地项目横跨多个相关文件夹，但只会以其中一个文件夹为准执行发现：“新聊天、Git 操作以及 AGENTS.md、skills 和 config.toml 的自动发现均使用主文件夹。辅助文件夹仍可用于文件搜索、读取和编辑。”您可以通过项目菜单中的 Edit project 选择主文件夹。¹¹³

这一项设置会同时控制 Codex 五大核心系统中的三个系统——指令、skills 和配置都以主文件夹为准。具体而言：辅助文件夹中的 AGENTS.md 只是 Codex 可以打开的文件，并不是它会加载的操作约定。如果承载规则的代码仓库是第二个添加的文件夹，请将其提升为主文件夹，或在主文件夹的 AGENTS.md 中重新声明这些规则；对于原本希望系统自动发现的代码仓库 skill 文件夹，同样如此。CLI 的目录遍历机制本身没有任何变化——这只是桌面应用的项目范围界定方式。

优秀的 AGENTS.md 应具备哪些特质

根据 Codex 本身的直接指导和社区实践模式¹⁰：

应该： - 明确具体："Use rg --files for discovery" 优于 "search efficiently" - 定义收尾标准：“完成”具体意味着什么？（测试通过、lint 无错误等） - 包含命令：构建、测试、lint、格式化（准确的调用方式） - 按任务组织：编码、审查、发布、事件/调试等章节 - 定义升级处理方式：遇到阻塞或意外状态时应采取什么措施

不应该： - 在缺少执行规则的情况下堆砌整套风格指南 - 使用含糊不清的指令（“谨慎操作”“进行优化”） - 混用相互矛盾的优先级（追求速度 + 全面验证 + 不提供运行时预算） - 编写说明性文档（AGENTS.md 是操作策略，不是 README）

示例：生产环境 AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Agent 会话中的密钥处理

应将 Codex 可见的历史记录视为安全风险面，而不只是关注源代码。Codex 发布说明记录了 shell 快照和环境变量脱敏方面的改进，memory 系统也会扫描写入 memory 的内容以检测密钥，但这些保护措施并不意味着可以放心地在命令输出、会话记录、shell 快照、本地日志或辅助脚本中打印凭据。³⁷⁵⁵⁹⁵

操作规则很简单：不要打印密钥供模型检查；将辅助凭据保存在环境要求的配置中；审计时应区分可执行源代码、文档、生成的缓存、会话记录、shell 快照、日志和有意设置的密钥存储；发现高度疑似密钥的内容时，应对本地历史记录进行脱敏；只有在人工卫生检查流程得到验证后，才应启用预防性 hooks。适合公开分享的是风险面分布和验收标准，而不是私有令牌值、确切路径或检测器内部机制。⁹⁵

覆盖机制

任意目录层级中的 AGENTS.override.md 都会取代该作用域内常规的 AGENTS.md。适用于：

• 发布冻结：“不新增功能，只允许修复”
• 事件处理模式：“所有变更都必须由值班人员审查”
• 临时加固：“本次迭代不更新依赖项”

配置

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

脚手架生成

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

或者验证您的指令链：

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex 在 v0.99.0 和 v0.100.0 中以旧版名称 AfterAgent 和 AfterToolUse 引入 hooks，随后在 v0.114.0 中新增了包含 SessionStart 和 Stop 的实验性 hooks 引擎，⁷⁰并于 v0.124.0（2026年4月23日）将 hooks 正式转为稳定功能。⁸⁵ rust-v0.150.0 搭载的引擎注册了十二个事件（参见 codex-rs/hooks/src/lib.rs 中的 HOOK_EVENT_NAMES）——v0.149.1 中有十一个，v0.150.0 将 Interrupt 添加为第十二个事件[^218]——旧版名称已从可配置界面中移除：AfterToolUse 不再出现在源代码树的任何位置，而 AfterAgent 仅作为旧版 notify 桥接的内部负载名称保留下来。¹²⁴ Hooks 会在智能体循环期间运行脚本或 MCP 工具。来自多个文件的所有匹配 hooks 都会运行，同一事件的多个匹配命令 hooks 会并发启动，而每个非托管 hook 都必须经过审查和信任后才能运行。¹²⁴ v0.148.0 扩展了该引擎：hooks 可以异步运行命令，也可以调用 MCP 工具——在命令处理程序上设置 async = true，即可让其在 Codex 继续运行的同时于后台执行；也可以使用 mcp_tool 处理程序访问智能体所使用的同一组 MCP 服务器。¹¹⁸¹²⁴

可用的 Hook 事件

WebSearch 等托管工具不会经过 hook 路径，某些专用工具路径也可选择绕过；OpenAI 对此的表述是：“一种实用的防护机制，而非完整的强制执行边界。”¹²⁴

Hook 配置

Hooks 分为三个层级——事件、匹配器组以及一个或多个处理程序——可配置在 hooks.json（~/.codex/hooks.json、<repo>/.codex/hooks.json 或插件的 hooks/hooks.json）中，也可内联配置在 config.toml 和 requirements.toml 中。只有项目的 .codex/ 层受到信任时，才会加载项目本地 hooks。¹²⁴ 内联 TOML 格式如下：

# ~/.codex/config.toml or <repo>/.codex/config.toml
[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/session_start.py"
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use_review.py"
async = true
timeout = 120

处理程序字段包括：type（command 或 mcp_tool；prompt 和 agent 处理程序会被解析但跳过）、command、以秒为单位的 timeout（默认为 600；SessionEnd 默认为 1 秒，上限为 3 秒）、statusMessage、additionalContextLimit（在 Codex 将完整文本保存到磁盘并发送预览之前，允许多少 additionalContext 进入模型）、commandWindows（仅限 Windows 的覆盖配置）以及 async。命令以会话的 cwd 作为工作目录运行，因此仓库本地 hooks 应通过 git rev-parse --show-toplevel 解析路径，而不应依赖相对的 .codex/hooks/... 路径。¹²⁴

审查与信任。 Codex 会根据每个非托管 hook 的当前哈希值记录其信任状态；新增或发生更改的 hooks 会被标记为待审查，并在获得信任前跳过。运行 /hooks 可检查 hook 来源、进行审查、授予信任或禁用单个 hook；如果启动时有 hooks 需要审查，Codex 会输出一条指向 /hooks 的警告。来自系统、MDM、云端或 requirements.toml 的托管 hooks 根据策略受到信任，且无法在用户 hook 浏览器中禁用。--dangerously-bypass-hook-trust 可在单次调用中运行已启用的 hooks，而不持久保存信任状态，适用于已在其他位置审核 hook 来源的自动化流程。¹²⁴

SessionStart hook 的 stdout 会进入模型上下文，因此非常适合在会话开始时注入动态信息（日期、分支名称、环境变量）。

复现 Claude Code Hook 模式

对于已经实现的事件，Codex 使用与 Claude Code 相同的事件名称，因此大多数 hook 配置只需将 JSON 移至 hooks.json，再通过 /hooks 授予信任即可完成迁移：

专家提示： 新的 hook 事件仍会随版本发布——v0.150.0 添加了 Interrupt 事件（[^218]）——因此请查看 codex-rs/hooks/src/lib.rs 中的 HOOK_EVENT_NAMES 以及 Codex 更新日志，以获取当前事件列表。

TUI 内置 hook 浏览器（v0.129.0）： 在 TUI 中运行 /hooks，即可发现可用的 hooks、查看当前处于活动状态的 hooks，并在无需编辑 config.toml 的情况下切换单个 hook。此功能非常适合排查插件捆绑 hook 的异常行为，或在专注编辑期间临时禁用 PostToolUse 代码检查工具。⁸⁹

什么是 MCP（Model Context Protocol）？[EXPERIMENTAL]

MCP 通过连接外部工具和服务来扩展 Codex 的能力。codex mcp 命令组目前标记为实验性，命令和配置格式可能在各版本之间发生变化。Codex 支持两种传输类型：STDIO（本地进程）和 Streamable HTTP（远程服务器）。¹¹

v0.121.0 MCP 变更： 工具现在注册时带有命名空间，因此列表中的工具名称显示为 <server>:<tool> 而非裸名称——请更新任何依据非限定工具名称进行 grep 的脚本或提示词。新增的 supports_parallel_tool_calls 标志会贯通传递给所含的 MCPs，让声明支持的服务器能够并行执行。沙箱状态元数据现在通过 MCP 工具元数据传递，服务器因此可以据此调整行为（例如，在 read-only 沙箱下运行时发出警告）。自定义的 codex/sandbox-state 请求已移除——请改用元数据路径。MCP Apps 推出的第三阶段在此落地，带来工具调用支持；对于使用延迟调用模式的服务器，现已支持扁平化的延迟工具调用。⁸²

v0.142.2 MCP 变更（2026年6月25日）： MCP 工具现在在受支持时默认使用工具搜索——Codex 不再预先加载每个工具定义，而是按需发现工具，在工具繁多的配置中改善了发现体验，同时保持与较旧模型和提供方的兼容。远程 stdio MCP 服务器现在也接受以远程平台路径格式书写的绝对工作目录（例如来自 macOS 客户端的 Windows 风格路径，反之亦然）。¹⁰⁵

v0.147.0 MCP 变更（2026年8月7日）： Codex 新增了对 MCP 2026-07-28 协议修订版的可选启用支持——分页发现（庞大的工具目录分页流式传入，而非一次性返回超大列表）、多轮请求（服务器可在一个逻辑请求内进行多步交互），以及非阻塞式服务器启动，缓存的 MCP 工具会在服务器启动完成前就暴露出来，因此慢启动的服务器不再拖住会话启动。该支持需要主动启用，所以使用旧修订版的服务器可照常工作，无需改动。¹¹⁶

v0.151.0 MCP 变更（2026年8月29日）： 可选的 MCP 服务器获得了可配置的启动宽限期——mcp_optional_startup_grace_ms（默认 1,000 毫秒）控制工具目录捕获等待可选服务器的时长，设为 0 则禁用共享宽限期，可选服务器随即回退到各自配置的 startup_timeout_sec，更新后的值在运行时和 MCP 配置刷新期间生效。扩展还可以在 MCP 工具结果抵达模型之前检查或替换它：ToolLifecycleContributor::on_mcp_tool_result 会在 MCP 完成事件发布之前、以及结果为模型准备就绪之前运行，成功和错误结果一视同仁，通过 Code Mode 时同样如此。[^221]

v0.152.0 MCP 变更（2026年9月1日）： 三项增量变更。openai/elicitation 表单请求落地：当客户端声明对象值形式的 form 能力时，Codex 会通告表单支持，处理 openai/elicitation/create 请求，并将其元数据和不透明 schema 以 openaiForm 形式经由 app server 转发（保留 x-openai-* 注解）；旧有的 openai/form 处理保持独立，TUI 会自动拒绝其无法渲染的表单请求。按工具设定输出上限：MCP 服务器 tools 配置下的每个条目都接受一个正值 output_token_limit（例如 [mcp_servers.context7.tools.search] 配合 output_token_limit = 2000）；当插件策略与用户策略重叠时，以最严格的上限为准，且有效预算会记入对话历史，因此工具输出、post-tool hook 响应和恢复的会话都在同一上限处截断——这与全局的 tool_output_token_limit 是增量关系。包风格的服务器名称：MCP 服务器名称现在可以包含 :、@、/ 和 .（因此 npm:@modelcontextprotocol/server-sequential.thinking 是合法名称），并在 mcp add/get/list/remove、运行时工具命名空间和 OAuth 凭据查找中一致保留，生成的 config.toml 恢复提示中会为非裸名称加上引号。¹³¹

配置 MCP 服务器

STDIO 服务器（本地进程）：

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

HTTP 服务器（远程）：

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

CLI 管理

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

会话内：/mcp 显示活动的服务器和可用工具。/mcp verbose（v0.123.0+）⁸⁴ 返回完整的服务器诊断信息、资源和资源模板——当服务器加载失败或工具没有出现在预期位置时很有用。普通的 /mcp 则保持快速。自 v0.144.0 起，MCP 工具可以交互式请求身份验证，无需实验性选项开关——会话中途需要认证的服务器会通过正常流程弹出提示，而不是一直失败直到您预先用 codex mcp login 完成认证。¹⁰⁷

插件 MCP 加载（v0.123.0+）同时接受标准的 mcpServers schema 和 .mcp.json 中的顶层服务器映射，因此按任一约定编写的插件都能顺利加载。⁸⁴

MCP 用户验证（v0.155.0，受支持的 Mac）： 受支持 Mac 上的本地 TUI 会话可以用 Touch ID 验证 MCP 请求，并由 Secure Enclave 签名（#43624、#43712、#43715）。验证身份仅限于其注册时所在的工作区（#43524），且验证会原生延续到 MCP 工具的后续调用中（#44346）。该特性最早出现在 v2.68 的推广检查清单中，随 alpha.7 集群从 0.154.0 中撤下，最终在 0.155.0 发布。¹⁴⁹

将 Codex 作为 MCP 服务器运行

已移除（v0.154.0，2026年9月9日）。 自稳定版 0.154.0 起，codex mcp-server 命令和独立的 codex-mcp-server 二进制文件均已移除（#42993），2026年8月24日宣布的弃用就此完成。官方更新日志（2026年9月5日）写道：”codex mcp-server 命令和独立的 codex-mcp-server 二进制文件已在 2026年8月24日弃用之后被移除。升级 Codex 前，请更新会启动上述任一命令的集成。”集成方应转向 app-server 协议，即 VS Code 扩展和桌面应用背后的接口（身份验证、对话历史、审批、流式代理事件）——移除条目本身将其标注为实验性且”不支持用于生产工作负载”——或者，从 Claude Code 出发，使用 面向 Claude Code 的 Codex 插件：”从 Claude Code 使用 Codex 来审查代码或委派任务。”将 Codex 连接到外部 MCP 服务器（codex mcp ...、/mcp）不受影响。^125145146

在 CLI 0.153.4 及更早版本上该命令依然存在（自 2026年8月24日起弃用；自 v0.149.0 起会向 stderr 打印 warning: `codex mcp-server` is deprecated and will be removed in a future release. 然后照常启动，PR #39657），因此若某个集成无法立即迁移，锁定 npm install -g @openai/codex@0.153.4 便是权宜之计：^12125141145

codex mcp-server                        # REMOVED in 0.154.0; works only on 0.153.x and earlier (deprecated, warns)

在 0.153.x 及更早版本上，该服务器暴露两个工具： 1. codex()：以提示词、沙箱、模型和审批参数启动新会话 2. codex-reply()：用 threadId 和提示词继续已有会话

配合 Agents SDK（Python）使用——仅限 CLI 0.153.4 或更早版本：

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "@openai/codex@0.153.4", "mcp-server"]},  # pin: removed in 0.154.0
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

值得关注的 MCP 服务器

实用模式

模式 1：上下文感知开发 —— 将 Context7 与您的框架文档搭配使用，让 Codex 始终掌握最新的 API 参考：

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

模式 2：输出上限 —— MCP 工具响应默认在约 25K 字符处截断。对于返回大量数据的工具（数据库查询、日志抓取），不妨用 enabled_tools 限定到特定工具，让响应保持聚焦。

模式 2a：多模态工具输出（v0.107.0） —— 自定义工具现在可以在文本之外返回多模态输出（图像、富内容）。这让产出可视化成果的工具——截图、示意图、图表渲染——能够直接把它们传给模型进行分析。⁶²

模式 3：企业级 MCP 治理 —— 通过 requirements.toml 锁定开发者可以使用哪些 MCP 服务器：

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

任何与 requirements.toml 中身份不匹配的服务器都会在启动时被阻止。完整的策略配置请参阅 企业部署。

Code Mode [实验性]

Code Mode（v0.114.0）通过将代理的作用范围限制在以代码为中心的操作中，提供隔离性更强的编码工作流。⁷⁰启用后，代理将专注于读取、编写和测试代码，不会与更广泛的系统交互。

从v0.139.0开始，Code Mode可以直接调用独立网页搜索，包括从嵌套的JavaScript工具调用中发起搜索，并接收纯文本结果。因此，Code Mode工作流无需离开沙盒化编码上下文，即可获取实时信息。¹⁵⁸v0.146.0将独立网页搜索扩展到兼容的自定义模型提供商，此功能不再局限于OpenAI托管的模型。¹¹⁴

v0.146.0允许app-server连接到远程Code Mode主机，因此Code Mode运行时不再必须与客户端位于同一台计算机上——最初通过WebSocket实现。¹¹⁴v0.151.0移除了WebSocket传输方式（#40692）：app server的--code-mode-host连接仅接受http://和https:// gRPC端点，而独立Code Mode主机仅支持stdio和gRPC监听器——在rust-v0.151.0标签中，其监听器文档原文为“Transport endpoint: stdio, stdio://, or grpc://IP:PORT.”。WebSocket仅作为可选端点保留，用于流式传输原始OTLP跟踪批次，而不再作为会话传输方式。¹²⁸

此功能尚处于实验阶段。请查阅发行说明以获取更新。

JavaScript REPL运行时[已移除]

Codex v0.100.0添加了实验性JavaScript REPL运行时（js_repl），v0.106.0又通过/experimental界面推广了该功能。⁶⁰这项说明现已成为历史信息。在v0.128.0中，发行版变更日志包含“Remove js_repl feature”，当前功能列表也将js_repl和js_repl_tools_only标记为已移除。⁸⁶

请勿在新配置中添加features.js_repl = true。需要可重复执行的逻辑时，请使用shell命令、已提交到代码库的脚本、MCP工具，或带有scripts/目录的Codex skill。

什么是skills？

skills是可复用且面向特定任务的能力包，Codex会按需加载。它们遵循开放的agent skills标准。¹³

Skill结构

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

发现位置

Codex将用户安装的skills存储在$CODEX_HOME/skills中（默认：~/.codex/skills），其中包括位于.system/下的内置系统skills。Codex支持通过符号链接关联的skill文件夹。

创建Skill

SKILL.md格式：

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

元数据（agents/openai.yaml）：

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

调用Skills

• 显式调用：通过/skills菜单或在提示词中提及$skill-name
• 隐式调用：Codex根据任务描述自动检测匹配的skills（前提是allow_implicit_invocation: true）
• 创建工具：使用$skill-creator以交互方式构建新skill
• 安装工具：使用$skill-installer install <name>安装社区skills
• 执行器提供（v0.146.0）：Codex会发现执行器提供的skills并读取其关联资源，包括您显式选择的skills¹¹⁴

上下文预算会截断skill目录。v0.146.0可在上下文紧张时保留更多可用skills，并会在必须截断目录时发出警告。¹¹⁴在此之前，较大的skill库可能会被悄然裁减，导致您原以为处于作用范围内的skill根本没有出现。如果依赖大量skills的隐式调用，请留意此警告。

启用/禁用

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills与Slash Commands对比

调试Skills

如果某个skill未激活：

1. 检查发现情况：TUI中的/skills应列出该skill
2. 验证路径：确保skill文件夹位于可识别的位置（~/.codex/skills/、项目根目录或/etc/codex/skills/）
3. 检查enabled：config.toml中设置了enabled = false的skills不会加载
4. 检查隐式激活：如果依赖自动检测，请确保agents/openai.yaml中设置了allow_implicit_invocation: true
5. 使用关键词：在提示词中加入skill的description术语，以提高隐式匹配效果

生产环境示例：部署Skill

以下是一个完整的多文件skill，展示了引用资料与脚本如何协同工作：

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md：

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

调用方式：$deploy to staging或$deploy production with canary rollout

Plugins

Plugins 将 skills、MCP 条目、hooks 和应用连接器整合为单个可安装包（v0.110.0+）。⁶⁵ 自 v0.117.0 起，Plugins 成为一等公民：产品范围的 Plugins 会在启动时自动同步，/plugins 则提供 TUI 内浏览器，用于发现和管理 Plugins。⁷⁵ v0.128.0 扩展了 Plugin 工作流，新增市场安装、远程包缓存、远程卸载 API、Plugin 随附的 hooks、hook 启用状态以及外部代理配置导入。⁸⁶ v0.129.0（2026年5月7日）新增了 Plugin 工作区共享（无需重新发布，即可将一组 Plugins 推送给团队成员）、共享访问控制（按接收者启用或禁用、撤销访问权限）、来源筛选（限制工作区从哪些市场拉取内容），以及可直接从 /plugins 浏览器调用的市场操作，无需使用 CLI。⁸⁹ **v0.133.0（2026年5月21日）**让 Plugin 发现结果更易于审查：列表输出可识别市场，已安装版本清晰可见，市场根目录会列出，并且远程 Plugin 集合也能直接呈现，无需猜测结果来自哪个注册表。⁹⁸ **v0.130.0（2026年5月8日）**提高了 Plugin 打包的透明度，也让共享工作流更可控：⁹¹

• Plugin 详情中显示随附的 hooks。 /plugins 详情视图现在会列出 Plugin 随附的每个生命周期 hook（SessionStart、UserPromptSubmit、Stop 等）。安装 Plugin 前，便可确切了解它会在会话中注册哪些 hooks，避免仅因信任其工具，却意外遭遇 hook 带来的副作用。
• shareContext 中的 Plugin 共享元数据。 从工作区共享 Plugin 时，共享链接的有效载荷现在会公开链接元数据（创建者、范围、时效性），以便接收会话显示来源，并决定是否接受。
• 共享设置中的可发现性控制。 共享设置提供可发现性开关，团队可将 Plugins 发布到特定工作区或接收者列表，而不必让整个组织都能搜索到它们。

v0.143.0（2026年7月8日）默认启用远程 Plugins。 现在无需选择加入标志即可启用远程 Plugins，/plugins 目录增加了信息更丰富的条目（除 git 和本地来源外，还包括 npm 市场来源），每个条目同时显示远程版本和本地已安装版本，版本偏差一目了然。¹⁰⁶ 对于统一采用一组共享 Plugins 的团队，默认启用远程 Plugins 省去了过去阻碍推广的逐台设备启用步骤。

Plugin 来源

自 v0.147.0 起，一次 Plugin 搜索即可覆盖本地、个人、工作区和远程目录——搜索的是所需能力，而不必关心它恰好位于哪个目录。结合可移植 Agent Plugin 包，在一种环境中构建的 Plugin 可以顺利安装到另一种环境中，不再受限于其创建时所在的设备或工作区。¹¹⁶

Plugin 发现

Codex 会在会话开始时告知模型已启用哪些 Plugins（v0.111.0），从而改善对已安装 MCP、应用和 skills 的发现能力。⁶⁵ 模型可根据任务上下文，在会话期间推荐相关 Plugins。v0.117.0 会在启动时同步产品范围的 Plugins，确保无需手动干预即可使用最新的 Plugin 目录。⁷⁵ 自 v0.142.0 起，/plugins 菜单将远程 Plugins 分为 OpenAI 精选、工作区和与我共享几个部分，符合条件的对话轮次还可直接推荐并安装相关 Plugins。¹⁰⁴ 自 v0.151.0 起，plugin/list 和 plugin/installed 会为每个请求的 cwd 加载最终生效的 Plugin 配置——本地市场按请求顺序组合，已安装和已启用状态跨存储库合并；无效的项目配置则通过 marketplaceLoadErrors 报告，同时保留有效的本地目录和全局启用的远程目录。[^221]

@plugin 提及（v0.112.0+）

在聊天中使用 @plugin-name 可直接引用任何已安装的 Plugin。⁶⁸ 提及 Plugin 后，其上下文（功能、工具、配置）会自动纳入模型的上下文窗口，无需另行说明该 Plugin 的用途。

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

此功能适用于任何已安装的 Plugin，包括自定义 skills、MCP 服务器和应用连接器。

Plugin 市场（v0.113.0+）

Plugin 市场现在提供更丰富的发现功能，包括元数据、分类和评分。⁶⁹ 安装时的身份验证检查会确认，需要 API 密钥或 OAuth 的 Plugins 已具备有效凭据。卸载端点则可完整移除 Plugins 及其关联配置。

添加第三方市场（v0.121.0+）

当前 OpenAI Codex 文档将市场来源管理统一归入 codex plugin marketplace。这使 OpenAI 第一方市场之外的第三方 Plugin 分发正式化，并支持 GitHub 存储库简写、HTTP(S) Git URL、SSH URL 和本地市场根目录；可使用 --ref 固定 Git 引用，而 --sparse PATH 仅可对基于 Git 的市场存储库重复使用。⁹³

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add git@example.com:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

添加后，该市场中的 Plugins 会与默认 Plugins 一同显示在 /plugins 浏览器中。App-server 调用方（IDE/桌面集成）也有对应的端点，可通过编程方式注册市场。⁸²

安全注意事项：第三方市场会使用您的 Codex 权限运行任意 Plugin 代码。添加前请严格审查来源，首次运行时建议采用沙盒执行。

Agent Plugins：跨供应商标准（v0.146.0–v0.147.0）

“Agent Plugins”不只是 Codex 的功能名称，它还是一项开放且与供应商无关的打包标准，于2026年8月6日以 Agent Plugins 1.0.0 的形式发布。其官方网站将其概括为“用于扩展 AI 代理的可复用组件的可移植包格式”。¹⁵⁴ Plugin 是一个目录，其中必须包含 plugin.json 清单（采用封闭式 schema，顶层仅允许以下10个字段：$schema、name、version、description、author、homepage、repository、license、keywords、extensions；对于每个未知字段，“客户端必须报告并忽略”）。它还可包含可选的 skills/ 文件夹（每个直接子目录如包含 SKILL.md，即代表一项 skill）、用于声明 stdio、Streamable HTTP 或旧版 HTTP+SSE 服务器的可选 mcp.json，以及采用反向域名命名的可选客户端命名空间目录，其他客户端“必须忽略”这些目录。其规范范围是打包：该规范“定义了规范化的 Agent Plugins Specification v1.0.0，用于将扩展 AI 代理的可复用组件打包为可分发 Plugins”——Agent Skills 和 MCP 在其下仍各自遵循独立规范。¹⁵⁴

治理模式才是关键。Vercel 发起了这项提案，并与 Amazon、Anysphere（Cursor）、GitHub、Microsoft 和 OpenAI 共同制定了 1.0 规范；规范存储库的维护者来自 Amazon、Cursor、Microsoft、OpenAI 和 Vercel，Google 也在发布当天宣布加入核心维护者行列。¹⁵⁴ 已公布的首发客户端包括 ChatGPT、Codex、Cursor、GitHub Copilot、Kiro 和 VS Code。一个显而易见的缺席者是：创建底层 Agent Skills 格式和 MCP 本身的 Anthropic 并不在维护者之列——Claude Code 继续采用自己的 Plugin 格式，而 Codex 则通过 Claude Code 市场来源（v0.146.0）和 /import 从自身一侧弥合这一差距。¹⁵⁴

就 Codex 而言：v0.146.0 新增 Agent Plugins 清单、工作区 Plugin 发布以及另外两个 Plugin 市场——Amazon Bedrock 和 Claude Code¹¹⁴；v0.147.0 则通过可移植 Agent Plugins 安装，以及横跨本地、个人、工作区和远程目录的搜索能力，完成了整个闭环。¹¹⁶ 对团队来说，工作区发布是更具实际操作价值的一环：可将 Plugins 发布到自己的工作区，无需搭建公开市场，也不必要求每位开发者手动添加 Git 来源。

发行说明公布了 Codex 提供的相关功能界面，但未公开其配置键或 CLI 语法。此处仅记录该能力已经上线以及标准所规定的内容，并非说明如何在 Codex 中操作。在 OpenAI 文档正式涵盖之前，请将清单编写工作流及任何 codex plugin publish 调用视为尚未验证。

管理 Plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace
codex plugin list                        # List plugins; includes remote catalog entries (v0.153.0)
codex plugin list --json                 # JSON adds source, version, install + auth policy (v0.153.0)

v0.153.0 将 Plugin CLI 的能力从市场管理扩展到针对远程市场的 Plugin 级操作：codex plugin list 会包含远程目录条目（在 JSON 输出中显示其来源、版本、安装策略和身份验证策略），并且可通过现有 Plugin CLI 添加或移除远程 Plugins。远程目录按范围和集合缓存——优先采用仍然有效的缓存结果；如果添加请求未在缓存中找到 Plugin，则会重新获取一次；当未筛选的远程列表获取失败时，本地精选目录仍会保留（若明确选择了某个远程市场，错误仍会显示）。¹³³

在 TUI 中，可使用 /plugins（v0.117.0+）以交互方式浏览、安装和移除单个 Plugins，无需离开当前会话。⁷⁵

专家提示：Plugins 将过去需要分别配置 MCP、安装 skill 和设置应用连接器的工作整合到一起。单个 Plugin 可同时打包这三者，让团队成员更快上手，配置也更易于移植。

Plan 模式与协作

Plan 模式允许 Codex 在执行更改前设计实施方案。自 v0.94.0 起，此模式默认启用。¹⁴ 有关“Plan 模式与直接执行”的决策树，请参阅决策框架。

Plan 模式与 update_plan 工具（v0.152.0）：二者并非一回事，且只有一个默认启用。Plan 模式是本节所述的协作模式，即 Codex 在执行前提出方案；自 v0.94.0 起默认启用，至今未变。update_plan则是模型可调用的规划工具，用于在单次交互中维护结构化计划。它在 v0.152.0 中作为选择启用功能发布：tools.update_plan.enabled 默认为 false；禁用期间，Codex 还会从模型、协作模式、多智能体、上下文压缩、预热和目标延续提示中移除内置的 update_plan 指引（即使自定义基础指令、模型目录指令、协作策略和用户目标文本提及规划，也会予以保留）。如需启用，请在 config.toml 中明确设置 tools.update_plan.enabled = true。¹³¹

进入 Plan 模式

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

在 Plan 模式下，Codex： - 读取文件并分析代码库 - 提出实施计划 - 在您批准之前不会进行更改 - 在专用 TUI 视图中流式显示计划

Steer 模式

Steer 模式自 v0.98.0 起默认启用，允许您在 Codex 正在工作时注入新指令，而不必中断当前任务。¹⁴

有两种注入方式：

实际示例：

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Steer 模式在 TUI 中始终处于活动状态。如果希望等 Codex 完成后再给出指令，只需在当前轮次结束后正常输入即可，无需切换到特殊模式。

TUI 增强功能（v0.105.0–v0.106.0）

**语法高亮（v0.105.0）：**TUI 现在可直接对围栏代码块和差异内容进行语法高亮。使用 /theme 选择配色方案。⁶¹

新增 TUI 命令（v0.105.0+）：⁶¹

语音转录（v0.105.0，实验性）：按空格键可通过语音转录口述提示。此功能尚处于实验阶段，可能需要麦克风权限。⁶¹ 自 v0.107.0 起，实时语音会话支持选择麦克风和扬声器设备，可指定具体的音频输入/输出硬件。⁶² 在 v0.140.0 中移除，于 v0.145.0 中恢复：实验性的 /realtime 语音控制及其音频依赖项在 v0.140.0 中从 TUI 移除（空格键语音转录不受影响）。¹⁰² v0.145.0 以全新形式恢复语音功能：支持常见本地音频格式的音频输入和音频工具输出，以及流式实时 V3 对话。¹¹² **v0.155.0 和 v0.156.0：实时语音对话。**v0.155.0（2026年9月17日）将 /voice 作为实验性的选择启用功能加入：在受支持的构建版本中通过 /experimental 启用后，可进行带流式文字记录和麦克风控制的实时对话（#43581、#43651、#44331）；同时支持配置静音快捷键（#43690），并在 macOS 软件包中提供已签名的语音资源（#43983）。v0.156.0（2026年9月22日）将其转为稳定功能并默认启用（#44921），文档变更日志也在同日宣布：“语音对话现已默认启用，并提供 F8 切换键、/voice settings 选择器，以及适用于 Linux 和 Windows 的内置音频运行时。”如需关闭，请在 config.toml 的 [features] 下设置 realtime_conversation = false。CLI 斜杠命令参考资料仍未列出 /voice，而文档中的语音功能页面介绍的是桌面应用中的 ChatGPT Voice，二者属于不同的功能界面。¹⁴⁹¹⁶²

其他改进： - 长链接即使跨越多行 TUI 文本换行显示，现在仍可点击（v0.105.0）⁶¹ - 本地文件链接采用了更完善的呈现格式（v0.106.0）⁶⁰ - TUI Markdown 通过 OSC 8 元数据保持网页链接可点击；空间不足的表格会回退为清晰易读的键值记录，且不会丢失链接目标（v0.136.0）¹⁶¹ - 在受支持的终端中，Markdown 链接显示为可点击标签；其他终端则保留可见 URL（v0.150.0）[^218] - 修复了子智能体的 Ctrl+C 处理，使其能够正确终止子进程（v0.106.0）⁶⁰

记忆系统

Codex 提供持久化记忆系统（v0.100.0+），可跨会话存储事实、偏好和项目背景信息。²⁴

记忆命令

记忆存储在 ~/.codex/memory/ 下的 Markdown 文件中。Codex 会在会话开始时加载这些记忆，并利用它们指导后续所有会话中的行为。

适合存储的内容

记忆最适合用于持久偏好和项目事实：

• 项目约定：“此项目使用制表符而非空格”，或“API 响应始终包含 meta 字段”
• 工具偏好：“使用 pnpm 而非 npm”，或“使用 pytest -x --tb=short 运行测试”
• 架构决策：“身份验证模块位于 src/core/auth/，而非 src/middleware/”
• 工作流偏好：“向我显示差异之前，始终先运行代码检查工具”

流水线中的记忆

运行 codex exec 时，记忆会自动加载。这意味着 CI/CD 流水线和脚本也能获得与交互式会话相同的背景信息，无需在每次调用时重复指令。

记忆功能改进（v0.101.0–v0.107.0）

• 敏感信息清理：写入磁盘前，会自动扫描记忆中的敏感信息
• CWD 感知：记忆文件现在包含工作目录背景信息，便于检索项目特定的记忆
• 排除开发者消息：开发者/系统消息不会纳入第1阶段的记忆输入，使记忆专注于用户交互，从而提升质量
• 基于差异的遗忘（v0.106.0）：记忆现在采用基于差异的遗忘机制移除过时事实，让记忆存储长期保持精简且切合需要⁶⁰
• 使用感知选择（v0.106.0）：记忆检索现在能够感知使用情况，优先选取频繁访问及近期相关的记忆⁶⁰
• 可配置记忆（v0.107.0）：记忆功能现在可全面配置。使用 codex debug clear-memories 可重置所有已存储记忆，从头开始；在无关项目之间切换背景或记忆状态已经偏移时，此功能尤为实用⁶²
• 第2阶段模型升级（v0.121.0）：第2阶段的记忆整合模型现已升级为 gpt-5.4（取代此前的默认模型）。第2阶段流水线会在会话之间运行，将第1阶段的文字记录提炼为持久事实；此次模型变更在令牌成本不变的情况下提高了记忆检索质量。⁸²
• TUI 记忆菜单（v0.121.0）：新增会话内界面，可查看记忆模式、删除单条记忆以及执行重置。重置记忆现在会保留以往的执行记录，而非使其失效；因此，重置操作会清除未来可检索的记忆，但不会破坏会话回放。⁸²

记忆与 AGENTS.md

提示：对于需要永久保留的事实，请使用 /m_update。对于会话特定的背景信息，直接在对话中告知 Codex 即可。对于团队共享的背景信息，请使用 AGENTS.md。

会话管理

Codex 将会话持久化存储在 ~/.codex/sessions/ 下，支持在 CLI 和桌面端之间恢复、分叉会话以及开展多线程工作流。

v0.146.0 让线程可通过名称定位。 /new 和 /clear 现在可以接受会话名称；重要线程可以置顶；开启支线对话时，也不必再关闭当前对话才能切换到另一个对话。¹¹⁴ 实际效果是，长期运行的项目不再是一串需要您根据日期辨认的时间戳。v0.147.0 新增对话分区：对话可以整理到持久化且支持手动排序的分区中；浏览长篇记录时会增量加载，而非一次性加载全部内容。¹¹⁶ v0.148.0 新增 /export 和命令行分叉功能：/export 可将完整对话写入 Markdown（复制到剪贴板或保存为新文件）；codex exec fork 可通过非交互方式分叉会话；恢复选择器还支持归档和还原会话。¹¹⁸ v0.149.0 新增 codex queue——从命令行向现有本地或远程会话发送消息——并修复了恢复或分叉线程后无法还原其当前权限配置文件的问题。¹²⁰ v0.150.0 新增自动标题：未命名的终端任务会自动获得描述性标题，/rename 也会根据对话内容建议一个可编辑的标题。[^218] v0.151.0 新增 /recap：可按需获取对话近期进展与后续步骤的简短摘要；对于符合条件、处于空闲且未聚焦状态的对话，Codex 也会自动生成同样的回顾并添加到对话记录中。此类请求受到严格限制并彼此隔离，且仅在自动生成失败时重试。¹²⁸ v0.153.0 让自动生成部分成为可选功能：tui.auto_recap = false 会取消已安排的自动回顾检查并丢弃待处理的自动结果，但手动执行 /recap 仍可正常使用。¹³³

**codex agents（v0.149.0）**是用于管理计算机上所有活跃代理会话的交互式控制面板：可以在一个界面中搜索、启动、打开、重命名和停止任务，并支持配置快捷键。在会话中，/agents 用于在所有活跃代理会话之间切换，/subagents 则用于在当前会话的子代理之间切换。¹²⁰[^215] v0.150.0 让任务可从对话中直接引用：可使用 @ 提及其他 Codex 任务，也可以要求代理通过终端读取、创建任务或向任务发送消息。[^218]

恢复

从上次中断的位置继续：

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

TUI 内的 /resume slash command 会打开同一个支持搜索的交互式选择器。

分页线程历史记录（v0.145.0 引入，v0.151.0 正式启用）： 分页线程历史记录为会话管理带来了高效恢复、跨历史记录搜索、持久化线程名称、子代理支持和记忆功能——历史记录会逐页加载，而不是一次性全部加载。这对于包含数百个会话的长期工作目录尤为重要。该功能在 v0.145.0 中作为实验性功能引入；v0.151.0 将这些 APIs 移出实验阶段（thread/turns/list、thread/items/list 和 thread/revert 不再需要实验性的 API 功能），并且仅当持久线程的存储支持 thread/turns/list 和 thread/items/list，且 thread/start 未指定 historyMode 时，才会将分页模式设为解析后的默认值。临时线程以及由不支持这些 APIs 的存储提供支持的线程仍默认采用旧版模式；显式选择仍保持原有行为；在 rust-v0.151.0 标签中，协议层的 ThreadHistoryMode 枚举仍默认设为 Legacy（protocol.rs:755-758）——这只是支持相应功能的持久线程所采用的解析后默认值，并非全面切换。¹¹²¹²⁸

分叉

分支出一个对话以探索其他方案，同时保留当前进度：

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

分叉会创建彼此独立的线程，并共享截至分叉点的相同历史记录。从 v0.146.0 起，分叉历史记录采用分页方式加载，并且可以创建为临时分叉——临时分叉不会出现在Thread Listing中，从而避免一次性实验干扰您实际浏览的线程列表。¹¹⁴ 一个分叉中的更改不会影响另一个分叉。此功能适合比较不同方案（例如，“分叉后尝试用 Redis 取代 Memcached”），或安全地探索风险较高的更改。

将线程分叉为子代理（v0.107.0）： 现在可以将线程分叉为独立的子代理，让一个对话派生出多个能够自主执行的并行工作流。此功能扩展了现有的分叉模型——分叉线程不再只是对话分支，而是会成为拥有独立执行上下文的子代理。⁶² 从 v0.117.0 起，子代理采用基于路径的地址（例如 /root/agent_a），并通过结构化的代理间消息进行通信，使多代理协调更清晰，也更便于调试。⁷⁵

加密的代理间消息（v0.138.0+）： Multi-agent v2 现在会加密父代理在生成子代理或向其发送消息时所传递的任务文本。spawn_agent、send_message 和 followup_task 的消息参数被标记为加密参数：当父模型发出工具调用时，Responses API 会加密载荷；本地运行的 Codex 只传递密文（InterAgentCommunication.encrypted_content，明文内容为空）；随后由 API 在服务器端将消息交给接收模型时解密。¹⁰⁸ 这会带来3项实际影响：

• 本地会话日志不再包含委派指令的明文。 您可以看到父代理生成了子代理以及子代理返回的结果，却无法看到发送给它的确切指令。如果从会话历史记录中审计或调试多代理运行过程，这部分记录已经无法获取；截至2026年7月中旬，追踪此问题的公开回归问题尚未关联任何修复方案。¹⁰⁹ 扩展生命周期事件（子代理启动与停止、工具执行、轮次元数据——v0.133.0+）以及app-server可观测性，是目前重现执行过程的其余途径。⁹⁸
• 自定义提供商的模型可能失效。 如果模型端点未配置为支持加密工具调用，它会拒绝包含加密 spawn_agent 模式的请求并返回400错误（"declares encrypted parameters but is not configured for encrypted tool use"）。如果使用自定义提供商时，多代理委派因该错误而失败，原因在于这项加密变更，而非您的配置。¹⁰⁹
• Codex 生成的通知仍可正常阅读。 子代理完成通知由 Codex 自身生成，因此仍以明文形式存在，并且现在会渲染为有类型的 agent_message 项，而非序列化的 JSON 信封。¹⁰⁸

OpenAI 尚未公布此项变更背后的威胁模型；相关 PR 仅描述了密文流转过程，并未说明其防护目标。

Multi-agent v2 已趋于稳定（v0.145.0，需主动启用）： Multi-agent v2 体验最初在 v0.137.0 中推出，并于 v0.138.0 中加入加密委派功能；如今已稳定为一项可主动启用的功能。v0.145.0 新增了可配置的子代理模型、每个子代理独立的推理级别、可配置并发数、恢复的多代理角色，以及改进后的代理导航。如果您在 v0.137/v0.138 的调整期暂缓采用 v2，那么此版本标志着配置方式已经趋于稳定——子代理的模型和推理选项现在由配置控制，不再由运行时固定。¹¹²

线程列表

查看和管理活跃会话：

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

在桌面应用中，线程显示在侧边栏内，并提供完整历史记录和差异预览。

会话生命周期

会话会在 CLI 与桌面应用之间同步——可以在一端开始，然后在另一端继续。

非交互模式（codex exec）

codex exec以非交互方式运行Codex，适用于脚本、CI/CD和自动化场景。¹⁵

基本用法

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write -c approval_policy=on-request "fix the CI failure"   # exec has no -a flag; set the policy via -c or config
codex exec --json "triage open bugs" -o result.txt

默认情况下，codex exec将进度和事件写入stderr，并将代理的最终消息写入stdout。这一设计使其能够与标准Unix管道灵活组合。

会话归档（v0.136.0）

可以归档会话，使恢复和分叉列表保持简洁，同时又不删除历史记录。您可以在TUI中使用/archive归档，也可以从shell执行：¹⁶¹

codex archive <session-id>     # archive a session
codex unarchive <session-id>   # restore it

归档的会话在取消归档前无法执行恢复或分叉操作。这项保护措施可避免意外继续原本打算停用的会话。同一版本还带来了以下改进：codex app-server --stdio能够以stdio模式启动app-server，供编辑器和宿主集成使用；/diff现在会阻止执行仓库提供的Git辅助程序，以提高命令安全性。在Windows上，管理员还可通过新增的Alpha预配路径运行codex sandbox setup --elevated。¹⁶¹

JSON Lines输出

使用--json后，stdout将变为JSONL事件流：

codex exec --json "fix the tests" | jq

事件类型：thread.started、turn.started/completed/failed、item.started/completed、error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

结构化输出

使用JSON Schema强制限定响应结构：

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message会将最终消息写入文件。

会话恢复与审查

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

关键标志

CI身份验证

codex exec支持使用CODEX_API_KEY在自动化环境中进行非交互式身份验证。

codex exec启动横幅（v0.130.0）。 codex exec启动横幅不再显示旧版“research preview”字样。如果您的CI会抓取启动输出，现在的横幅文本更加精简；结构化--json事件保持不变。⁹¹

codex remote-control（v0.130.0及更高版本）

codex remote-control是一个顶级命令，用于启动由其他进程驱动的无头app-server，例如IDE扩展、自定义编排器或远程控制平面。它取代了许多集成方手动拼接的多标志codex app-server调用，为第三方工具提供一个稳定且统一的入口，使其能够接入桌面端和IDE界面底层所使用的同一套app-server运行时。⁹¹ v0.133.0改进了该命令的运行方式：它可以像前台命令一样运行、等待服务就绪并报告机器状态，同时仍为长期运行的控制器部署提供明确的守护进程式start / stop命令。⁹⁸ v0.143.0新增了codex remote-control pair，可从正在运行的守护进程生成手动配对码，让控制器无需自动发现握手即可连接。当控制进程与守护进程位于不同主机或网段时，这项功能尤其有用。¹⁰⁶

# Start a headless, remotely controllable app-server
codex remote-control

# Generate a manual pairing code for an out-of-band controller (v0.143.0+)
codex remote-control pair

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

构建需要枚举大量线程历史记录、同时又不希望一次性将每个轮次全部加载到内存的UI时，请将codex remote-control与下文介绍的app-server分页API配合使用。

App-Server线程分页（v0.130.0及更高版本）

app-server客户端现在可以通过3种不同的轮次项目视图，对大型线程进行分页：⁹¹

将分页功能与v0.121.0引入的ThreadStore接口结合使用，可以高效遍历长期运行的线程。这对于远程控制部署尤为重要，因为编排器与部署文件可能位于不同机器上。⁸² v0.143.0扩展了控制器的检查能力： app-server客户端现在可以枚举可用环境、列出某个线程的后代线程，并从特定轮次分叉历史记录。这些是UI从早期节点创建运行分支而无需向前重放所需的基础能力。¹⁰⁶ v0.151.0将分页线程历史记录API从实验阶段提升为正式功能；对于具有支持存储的持久线程，当thread/start省略historyMode时，默认使用分页历史记录（临时线程和不支持此功能的存储仍沿用旧版模式）；对于分页线程，完整历史记录加载已弃用（#40676）。¹²⁸

App-Server实时配置刷新（v0.130.0及更高版本）

正在运行的app-server线程现在无需重启即可应用config.toml的更改。编辑并保存配置后，运行中的线程会在下一轮次采用新值。这是与codex remote-control相配套的错误修复：长期运行的无头服务器可以就地重新配置，无需先将其关闭。⁹¹

实时轮次级设置（v0.151.0）： 正在运行的轮次现在可以在执行过程中更改设置。实验性的turn/settings/update app-server方法可为某个特定实时轮次的后续步骤更新model、effort、summary和serviceTier，而不会影响未来轮次；它还会报告更新是已应用、被拒绝，还是目标已丢失。在发布更新后的设置快照前，系统会重新验证托管约束，并保留该轮次获准的审批和Guardian安全属性。turn/start现在也接受serviceTierForTurn，允许单个新轮次覆盖服务层级，而不更改线程保存的层级（"default"表示标准速度；省略或设为null时继承线程层级）。¹²⁸

加密远程执行器（v0.141.0）

自v0.141.0（稳定版，2026年6月18日）起，远程执行器通过经过身份验证的端到端加密Noise中继通道建立连接。控制平面和执行器不再需要信任两者之间的中继。当编排器跨越网络边界驱动app-server时，这一点至关重要。同一版本还确保跨平台远程执行会保留执行器原生的工作目录和shell，因此，当一个操作系统上的控制器驱动另一个操作系统上的执行器时，其路径或shell语义不会再被暗中改写。TLS现在还接受P-521证书签名，以兼容企业代理。¹⁰³

Codex Cloud 与后台任务[EXPERIMENTAL]

**GitLab 支持（测试版，2026年8月19日）：**Codex Cloud 现已支持在所有 ChatGPT 套餐中连接 GitLab 项目——您可以关联项目、创建环境、从议题和合并请求启动任务，以及请求审查；Self-Managed GitLab 需要19.0或更高版本。¹¹⁹

状态：Codex Cloud 是一项实验性功能。其界面、定价和可用性可能发生变化。云环境由 OpenAI 管理，您无法控制底层基础设施。

Codex Cloud 在 OpenAI 管理的环境中异步运行任务。⁴ 从 CLI v0.150.0 开始，还可以通过终端对话操作任务：使用@提及其他 Codex 任务，并要求代理读取、创建任务或向任务发送消息。[^218] 如需将 Codex 集成到 CI 流水线，另请参阅GitHub Action 与 CI/CD。

**云任务凭据安全性增强（v0.152.0）：**云任务请求可以携带已保存的 ChatGPT 凭据，因此现在会在加载身份验证信息之前限制其目标地址——系统会验证CODEX_CLOUD_TASKS_BASE_URL是否属于使用443端口且受信任的 ChatGPT HTTPS 来源（拒绝包含用户信息、查询参数或片段的 URL），同时禁用云任务后端和环境发现客户端的重定向，确保凭据绝不会被转发至重定向目标。¹³¹

工作原理

1. 提交任务（通过 chatgpt.com/codex、Slack 集成或 CLI）
2. Codex 将您的代码仓库克隆到隔离的云沙箱中
3. 代理独立开展工作：读取代码、运行测试并进行更改
4. 完成后，Codex 会创建 PR 或提供差异供您审查
5. 使用codex apply <TASK_ID>在本地应用结果

云环境中的互联网访问

代理的互联网访问权限默认关闭，并按环境进行配置：

• 关闭：代理无法访问互联网（默认）
• 开启：可选择配置域名允许列表和 HTTP 方法限制

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

即使代理的互联网访问权限已关闭，设置脚本仍可访问互联网以安装依赖项。

Slack 集成

在 Slack 频道或话题中提及@Codex，即可启动云任务。

前提条件： 1. 符合条件的 ChatGPT 套餐（Plus、Pro、Business、Enterprise 或 Edu） 2. 已连接的 GitHub 账户 3. 至少配置了一个云环境 4. 已为您的工作区安装 Slack 应用

Codex 会回复任务链接，并在任务完成后发布结果。

Cloud CLI

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

Codex Desktop App

Codex Desktop App（macOS和Windows）提供专为多项目管理优化的图形界面。¹⁶ Windows版本于2026年3月4日发布，原生支持PowerShell和Windows沙箱。⁶⁶

安装

codex app                      # Auto-downloads and installs on first run

或直接下载：Codex.dmg（macOS）| 可从Microsoft Store获取（Windows）

主要功能

Appshots、浏览器评论与Computer Use

5月21日的应用更新强化了桌面应用的上下文能力，使其不再只是线程管理器。当Codex必须先了解另一个Mac应用的状态才能执行操作时，请使用Appshots：Codex会捕获最前端窗口，以及该应用所提供的屏幕内外可见文本，并将附件存储在本地会话历史记录中。⁹⁹

对于Web和前端工作，如果页面无须身份验证，请优先使用应用内浏览器：它为您和Codex提供共享的渲染预览，支持点击、截屏、下载资源等浏览器操作，以及只读检查JavaScript；还可在页面区域添加评论，供Codex在下一轮处理中落实。⁹⁹ 对于已登录的网站，请继续使用浏览器扩展（支持Chrome、Edge、Brave、Opera或Vivaldi；Opera不提供侧边聊天）。网站工具（WebMCP，2026年8月25日）：在桌面应用的内置浏览器中，ChatGPT Work和Codex可以使用网站提供的工具与页面交互；请在最新版本的桌面应用中使用GPT-5.6 Sol或GPT-5.6 Terra，因为GPT-5.6 Luna以及Enterprise或Edu工作区不支持网站工具。¹²⁷

仅当结构化集成或浏览器预览无法验证任务时，才使用Computer Use。它可以检查和操作获准的Mac应用，但涉及文件编辑和shell命令时，仍须遵循Codex的审批及沙箱规则。锁定使用的范围也十分有限：Mac锁定后，仅在可信且活跃的Computer Use轮次中，Codex才能暂时访问获准的应用，同时设有重新锁定保护和本地输入检测机制。⁹⁹

线程模式

每个线程都会以3种模式之一运行，创建线程时即可选择：

Worktree隔离机制：

启动Worktree线程时，桌面应用会： 1. 在临时目录中创建新的git worktree（git worktree add） 2. 从当前HEAD检出一个新分支 3. 在worktree内运行代理——所有文件更改均相互隔离 4. 完成后显示差异审查——由您选择要合并回去的更改

这意味着多个Worktree线程可以在同一仓库中同时运行而不会发生冲突。每个线程都有自己的分支和工作目录。

**Worktree设置与线程所有权（v0.151.0）：**托管worktree的行为由专用设置解析器根据现有[desktop]配置确定——worktree根目录默认为$CODEX_HOME/worktrees，自动清理默认启用，并保留15个worktree；配置的根目录、清理标志和保留数量均会在使用前经过验证。每个托管的链接worktree还可在其Git元数据中包含带版本的codex-thread.json所有权记录，将其绑定到某个线程：写入采用原子操作且不会覆盖现有内容（重复绑定具有幂等性，所有权冲突会被拒绝）；在修改所有权元数据之前，主检出、嵌套检出和非托管检出都会被拒绝。¹²⁸

**托管worktree在v0.154.0中进入CLI（实验性）：**启动时使用--worktree或在TUI中使用/worktree，即可为新会话或分叉会话创建隔离检出；codex exec支持在自动化中使用托管worktree；TUI会话命令和worktree浏览器则可用于列出、浏览和恢复worktree会话（#42196、#42366、#42652、#43069、#43120、#43286）。**v0.155.0新增了相关管理功能，但worktree仍未默认启用：**代理概览中可以隐藏、归档和删除worktree会话，也会显示所有权详情；删除干净的托管worktree时，系统会要求确认（#43942、#44424、#44433）。默认启用变更（#44870）已于9月11日合并，但未包含在稳定版0.155.0中；这一点已通过rust-v0.155.0标签进行祖先关系检查。¹⁴⁵¹⁴⁹

托管worktree从v0.156.0起默认启用：#44870将worktrees提升为稳定功能、默认启用，并将其从/experimental中移除。一同发布的功能还包括：worktree会话可以连接到现有本地守护进程，无须自行启动守护进程（#46498）；还可直接从代理概览创建worktree会话（#45276），代理概览同时新增状态筛选标签页（#46839）。如果您的脚本或配置基于“除非明确请求，否则worktree处于关闭状态”这一假设编写，那么0.156.0正是改变其行为的版本。**如需选择退出：**请在config.toml的[features]下设置worktrees = false（单次运行可使用：--disable worktrees）。**较旧的本地守护进程：**如果创建worktree或执行/cd时出现“The local Codex service cannot check background terminals”并被阻止，请运行codex app-server daemon update，然后重启Codex。¹⁶²¹⁶⁴

**供模型使用的worktree工具（v0.162.0）：**在已启用该功能且受信任的本地项目中，模型本身可通过新工具创建和列出托管worktree（#50148）；新对话和分叉提示词也会说明worktree选项（#50416）。¹⁸⁰

自动化

自动化任务在应用本地运行，因此应用必须保持运行，并且项目须位于可用的本地磁盘中：

• 在Git仓库中，自动化任务使用专用的后台worktree（与工作目录隔离）
• 在非Git项目中，任务直接在项目目录中运行
• 自动化任务使用您的默认沙箱设置

设置自动化任务： 1. 在桌面应用中打开项目 2. 单击侧边栏中的Automations标签页 3. 定义触发器（计划、webhook或手动触发） 4. 编写提示词并选择执行模式（local或worktree） 5. 设置自动化任务运行时的推理级别（App v26.312）⁷² 6. 自动化任务按计划运行，并将结果加入队列以供审查

用例示例： - 问题分流：自动对新问题进行分类和优先级排序 - CI监控：监视构建失败并提出修复建议 - 警报响应：通过诊断分析响应监控警报 - 依赖项更新：检查并应用安全补丁

结果会显示在审查队列中，等待人工审批。

Windows支持

Codex Desktop App于2026年3月4日登陆Windows（App v26.304），原生支持PowerShell和Windows沙箱，并且无须WSL即可完整使用skills、自动化和worktrees等全部功能。⁶⁶

GitHub Action 与 CI/CD

官方 GitHub Action 可将 Codex 集成到 CI/CD 流水线中。¹⁸

基本用法

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

配置选项

输出：final-message，即供后续步骤/作业使用的最终 Codex 响应文本。

安全策略

访问控制

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

默认情况下，只有具备写入权限的协作者才能触发 Codex 工作流。

Codex SDK

TypeScript SDK 可将 Codex 的 Agent 能力嵌入自定义应用程序。¹⁹

安装

npm install @openai/codex-sdk

基本用法

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

高级 SDK 功能

• runStreamed(...)：用于获取中间更新的异步事件流
• Python SDK 身份验证（v0.132.0+）：API 密钥登录、ChatGPT 浏览器/设备代码流程、账户检查和退出登录均已成为一等 SDK 路径。⁹⁷
• 纯文本轮次便捷功能（v0.132.0+）：Python 轮次 API 接受纯字符串，并返回更丰富的 TurnResult 元数据，其中包含收集到的项目、耗时和用量。⁹⁷
• outputSchema：强制最终输出符合 JSON 结构
• 多模态输入：传入文本和本地图片（{ type: "local_image", path: "..." }）
• 图片工作流（v0.117.0）：view_image 返回 URL，生成的图片可以重新打开，恢复会话后图片历史记录仍会保留⁷⁵
• 多环境 view_image（v0.130.0）：对于跨多个环境的会话（v0.124.0 引入每轮环境和工作目录选择，v0.125.0 又通过粘性环境加以完善），view_image 现在会通过所选环境解析文件路径，而非通过编排器的本地文件系统解析。从远程环境附加的图片会相对于该环境的工作目录获取，而不是相对于运行 SDK 的主机获取。⁹¹

线程与客户端配置

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.5" },
});

会话持久存储在 ~/.codex/sessions 下。

运行时：Node.js 18+。

性能优化

上下文管理

上下文窗口因模型而异。当前 GPT-5.6 系列（Sol、Terra、Luna）的窗口为 272K；上一代旗舰模型 GPT-5.5 在 Codex 中提供 400K（在 API 中为 1M）；GPT-5.4 / GPT-5.4-mini（将于 2026年8月31日退出 Codex）分别提供 1M / 400K；旧版 GPT-5.3-Codex 系列则采用 272K 输入 + 128K 输出（总预算 400K）。这些窗口的填充速度都比预想更快，因此应主动管理：

1. 定期使用 /compact：汇总对话历史记录以释放 token
2. 提供本地文档：高质量的 AGENTS.md 和本地文档可减少探索开销（探索会消耗上下文）
3. 使用 @ 附加特定文件：直接引用文件，而不是让 Codex 自行查找
4. 保持提示词聚焦：与开放式探索相比，限定范围并明确指定文件的提示词消耗的上下文更少

实验性上下文管理（v0.153.0，默认禁用）： features.context_management.experimental_mode 会为使用 Codex 后端且符合条件的 ChatGPT Plus、Pro 和 Pro Lite 会话启用协同式上下文栈——包括 token 预算上下文、历史记录注释和 new_context 工具。使用 API 密钥的会话、自定义提供商、非 Codex 端点以及临时结构化线程均不在适用范围内。此标志仍明确处于开发阶段：应将其视为上下文处理发展方向的预览，而不应据此构建工作流。¹³³ v0.154.0 新增了能力门控：会话启动时，会根据当前模型的能力确定是否符合条件（#43147）——Codex 模型文档也在同一处按名称将 Astra 与 Plus 和 Pro 登录关联起来（请参阅“我应该选择哪个模型？”下的跨上下文说明）。¹³⁹¹⁴⁵ 截至 v0.157.0，捆绑目录中没有任何模型被标记为支持此功能（#47397），因此使用该目录时，此设置不会产生任何效果。¹⁶⁷ v0.159.1 新增的 GPT-6.1 Sol 同样未被标记，配置参考现在也将此键描述为“当前不可用”。¹⁷¹

Token 效率

速度优化

1. gpt-5.3-codex-spark：适用于交互式结对协作的低延迟变体
2. --profile fast：预先配置的 gpt-5.6-luna，采用低推理强度
3. 并行执行工具：Codex 会并发运行相互独立的读取/检查，因此请合理组织提示词以充分利用此功能
4. 结果导向的循环：提出“实现、测试、修复，全部通过后停止”，而不是逐步给出指令

如何调试问题？

常见问题和解决方案

错误消息参考