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系列模型仍保留在模型选择器中，而GPT-5.5于2026年10月14日停止向通过ChatGPT登录的Codex用户提供服务。^146171178初次接触？直接前往安装和快速入门。关注版本动态？最新稳定版为v0.164.0（2026年10月23日）：提供10个用于保存可复用提示词的/presets槽位，支持内联/model和/permissions参数、全屏对话记录中的图片预览、企业管理的MCP登录，并默认启用Bedrock设置向导；版本亮点首先概述当前状态（哪些功能默认启用，哪些仍处于实验阶段），随后逐版介绍，更新日志则列出本指南的每次更新。^116178182183

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

随手使用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使用bubblewrap + 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在Codex中提供400K上下文窗口，直至2026年10月14日退役。使用/compact、聚焦明确的提示词和@file引用，主动管理令牌预算。^83112178

如何使用本指南

这是一份超过3,300行的参考指南——请从符合您经验水平的部分开始：

末尾的快速参考卡汇总了所有主要命令，便于快速查阅。

版本更新要点：近期变化

按版本记录更新内容，从新到旧排列，供关注Codex发布进展的读者查阅。初次使用？请直接跳到快速入门；无需了解以下内容即可开始使用。验证详情（版本对比、提交列表、文档核查）见脚注。

当前状态

截至2026年10月23日的Codex CLI

• 稳定版：v0.164.0（10月23日，npm latest），基于0.164.0-alpha.11加上1次发布提交构建（alpha.12包含稳定版中没有的9次提交），比v0.163.0多330次提交：新增10个带编号的/presets槽位，用于保存可复用的提示词和slash commands；支持直接使用/model [model] --reasoning <level> --speed <tier>和/permissions <profile-id>；在Kitty或Sixel终端的全屏会话记录中显示图像预览；为MCP连接提供企业托管授权；为受支持的远程Bash命令提供凭据掩蔽（由credential_masking标志控制）；默认启用Amazon Bedrock设置向导。此前的v0.163.0（10月15日）新增了可搜索的/config面板、前导键，并默认启用Daybreak。
• Alpha版：npm alpha为0.165.0-alpha.1（10月23日，稳定版发布数小时后）。在该标签版本中，reasoning_effort_override已标记为稳定并启用，新加入的guardianv3、guardian_recorded_items和tui_multi_backend均处于关闭状态。0.164系列从alpha.1（10月16日）持续到alpha.12（10月22日），同期还发布了计划外构建0.163.0-alpha.11.1和11.2（10月21日至22日），以及0.164.0-alpha.11.1（10月23日）。
• 自v0.159.1起的默认模型：GPT-6.1 Sol取代GPT-6-Astra，Amazon Bedrock上也同步调整。如需继续使用其他模型，请在config.toml中设置model。v0.164.0内置的模型目录与v0.162.1和v0.163.0的目录逐字节相同，列出的模型也与v0.159.1一致。
• 自v0.164.0起默认启用：Amazon Bedrock设置向导（bedrock_setup_wizard，稳定；在[features]下设置bedrock_setup_wizard = false可关闭）、增量工具更新（incremental_tools，稳定），以及MCP OAuth刷新协调（mcp_oauth_refresh_coordination，稳定）。托管worktrees和实时对话现已永久启用：对应标志已标记为移除，功能仍保持开启。
• 自v0.163.0起默认启用：Daybreak（cli_daybreak，现已稳定；在[features]下设置cli_daybreak = false可隐藏相关控件）和代码模式中断（code_mode_interrupt，稳定），因此后续输入也会停止正在运行的Code Mode单元；使用API密钥的会话默认启用Cyber访问计划（api_key_cyber_access_programs）。已移除：shell_zsh_fork和unified_exec_zsh_fork，这两个标志会被忽略，并显示迁移提示。
• 自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）、Guardian历史记录检索（guardian_conversation_history_tools，v0.160.0），以及v0.164.0发布时默认关闭的开发中标志（沿自v0.163.0：async_compaction、credential_masking、output_token_replay、retain_client_tool_outputs、subagent_default_context_limits、code_mode_host_grpc、code_mode_tool_description_first、guardian_trust_orchestrator_connectors；v0.164.0新增：app_server_websocket_compression、executor_capability_discovery_v2、mcp_tool_list_changed、multi_env_copy_file、runtime_agent_instances、subagent_thread_environments、wake_on_agent_messages）。实验性上下文管理目前不可用。
• 模型：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.164.0，然后运行codex --version。^{176178186187188189192193194195}

v0.164.0（2026年10月23日）

0.164系列基于自身的alpha版本发布稳定版。v0.164.0于10月23日发布（UTC时间04:48；npm latest于UTC时间04:52更新），基于0.164.0-alpha.11加上1次发布提交构建；alpha.12（10月22日）比这一发布基点多9次提交，计划外构建0.164.0-alpha.11.1（10月23日，UTC时间01:58）则在alpha.11基础上增加了4次提交。与v0.163.0相比，共有330次提交。3个标志改为默认启用，并标记为稳定：bedrock_setup_wizard（Amazon Bedrock设置向导，检测到凭据时，会将API密钥输入与其他AWS登录方式归为一组）、incremental_tools和mcp_oauth_refresh_coordination。worktrees和realtime_conversation标志已标记为移除，对应功能保持开启，因此托管worktrees和实时对话不再支持开关控制；stable_environment_tools和transcript_v2也已移除。新增7个开发中标志，默认均关闭。内置模型目录与v0.162.1发布时使用的blob相同。¹⁹⁴¹⁹⁵

TUI新增功能。/presets提供10个带编号的槽位和键盘菜单，用于保存可复用的提示词和slash commands；可根据输入框中的文本，或当前模型、推理强度和速度创建预设，预设会持久保存在当前生效的用户配置的tui.presets中（#54380、#54381）。/model [model] --reasoning <level> --speed <tier>可将模型、推理和速度设置应用于当前会话，而不改变已保存的默认值，标志值支持用空格或=分隔；省略模型时，设置会应用于当前模型，仅输入/model仍会打开选择器（#54378）。/permissions <profile-id>可直接选择内置或自定义权限配置，例如/permissions :read-only，并支持:ask-for-approval和:approve-for-me两个别名（#54383）。在支持Kitty或Sixel图形协议的终端上，全屏会话记录会以尺寸受限的缩略图预览已查看和生成的图像；远程工作区、不受支持的终端和超大图像仍保留纯文本条目（#54216）。¹⁹⁴

连接与凭据。直接配置的MCP服务器可通过存储在密钥环中、作用域限定于账户的企业授权，或专门的登录流程进行身份验证，也支持需要客户端密钥的OAuth客户端；企业托管授权扩展通过2026-07-28协议协商，账户所有者变更或企业登录替代该授权时，原授权会被撤销（#55334、#55859、#56001）。凭据掩蔽现已支持部分远程Bash命令和zsh快照会话，包括来自自定义提供商的凭据：命令看到的是占位符，执行器本地代理会为匹配的目标注入真实凭据；无法使用掩蔽时，会发出警告并回退到不掩蔽凭据的执行方式；在该标签版本中，credential_masking标志仍默认关闭（#54309、#54432、#56049）。¹⁹⁴¹⁹⁵

修复与维护。压缩失败后，不再在对话历史中留下不完整的摘要；后台压缩失败时会回退处理，不再触发panic（#53932、#55581）。恢复会话时，能够找到压缩后的历史记录，并恢复已保存的线程设置，而不是用全局默认值替换（#54008、#55923）。在Windows上，HTTPS和WebSocket连接会使用已登录用户的Negotiate或NTLM凭据响应代理身份验证质询（#55994、#56000）。在多个子命令层级传入-c或--config时，会保留所有覆盖项（#56022）；排队中的提示词会等待尚未完成的权限选择确定后再执行（#55682）；沙箱会检查macOS上大小写变体的元数据路径，以及用于定位可执行文件、可被替换的符号链接（#54273、#55384）。磁盘占用有所降低：清理未使用的安装版本（保留当前和上一次选用的守护进程版本）、废弃的市场检出目录，并限制守护进程日志大小（#53827、#55149、#55689、#55690、#55856）；内嵌的JavaScript运行时为优化后的Array.sort增加了安全检查（#54519）。¹⁹⁴ 建议操作：升级。除非您在Bedrock上进行初始设置，否则不会察觉默认行为有任何变化。Bedrock设置向导现在会自动运行（在[features]下设置bedrock_setup_wizard = false可将其关闭）；如果之前在[features]下设置了worktrees或realtime_conversation，这些键现在会被忽略。¹⁹⁴¹⁹⁵

v0.163.0（2026年10月15日）

0.163系列从独立分支发布稳定版。 v0.163.0于10月15日发布（UTC时间21:30；npm的latest于UTC时间21:37更新），基于0.163.0-alpha.10.2加上1次发布提交构建。该版本是在alpha.10基础上单独构建的版本；主线上的alpha.11（10月14日）包含23次稳定版中没有的提交，再次沿用了0.158的发布模式。与v0.162.1相比，共有232次提交。2个功能标志默认开启，并均被标记为稳定：cli_daybreak（Daybreak控制功能、/daybreak开关，以及为符合条件的OpenAI账户自动路由至Cyber访问计划；当服务器提供访问权限时，codex exec可使用OpenAI API密钥选择该功能）和code_mode_interrupt（中断轮次时，也会停止正在运行的Code Mode单元及其嵌套工具调用）。已处于稳定状态的api_key_cyber_access_programs也默认开启。instant_interrupt保持开启，仍处于开发中。¹⁹²¹⁹³

TUI新增功能。 /config可打开支持搜索的偏好设置面板，按外观、通知、输入、会话和文本选择分为多个选项卡；支持即时生效的更改会立即应用，需要重启的更改会在面板中注明，编辑结果会保存至选定的本地配置文件（#52990、#53429）。/keymap可配置前缀键：tui.keymap.global.leader默认为ctrl-x，leader c等按键绑定以前缀键开头，快捷键提示会持续显示，直到您选择或取消，语音静音快捷键则从Ctrl+X改为F9（#52273）。/daemon可重启托管后台服务器，重启前会提示可能中断的工作，重启后会重新连接（#53173）。Codex会并行运行相互独立的只读工具，包括skills、记忆和对话历史查询，插件和智能体列表查询，当前时间、剩余上下文和get_goal查询（#52245）。在Codex响应期间发送的后续消息会立即引导其调整方向（#51812、#51835）。¹⁹²

修复与平台更新。 恢复已保存的线程时，会还原其权限和网络批准状态，同时遵循显式覆盖设置和托管策略（#53150、#53419、#53424）。网络代理会在DNS查询前检查权限，拒绝重复的Host标头，并阻止凭据别名绕过检查hooks（#51650、#52661、#53506）。切换线程后，/side会返回已有的侧边对话，待处理提示的回答也会发回提出该提示的线程（#52184、#53436）。在Windows上，Ctrl+V和Shift+Insert既可粘贴文本，也可粘贴图片；在WSL上，重复粘贴会复用剪贴板读取器，复制尝试超时后会结束，不再卡住（#53224、#52967、#53453）。即使子进程保持输出管道打开，本地命令也能及时结束；远程命令会保留延迟到达的输出，供最后一次轮询获取；codex exec也不再于无关命令执行后重复显示文件差异（#52652、#53331、#53622、#53444）。¹⁹²

已移除打过补丁的zsh。 Codex使用标准shell执行器，不再捆绑打过补丁的zsh；codex-execve-wrapper和shell-escalation crate也一并移除。shell_zsh_fork和unified_exec_zsh_fork会被忽略，并显示迁移提示；托管要求中若仍指定这些配置项，则会显示警告（#52160、#52213）。Linux和macOS软件包移除了随附二进制文件中的符号信息，因此体积更小（#52178）。Linux沙箱crate的命名和README现在明确说明了沙箱一直采用的机制：通过bubblewrap隔离文件系统和命名空间，通过seccomp过滤系统调用，并将Landlock实现保留为旧版代码；实际执行机制没有变化（#52610）。随附的OpenAI Docs指南涵盖了向GPT-6系列的迁移（#51768）。¹⁹²¹⁹³

建议操作：升级。如果config.toml或requirements.toml中包含shell_zsh_fork或unified_exec_zsh_fork，请将其移除；如果之前手动开启了Daybreak，现在无需再设置该标志；如果之前使用Ctrl+X将/voice静音，现在请改用F9。¹⁹²

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中以可选功能推出，允许新输入抢占模型响应，或让长时间运行的code-mode调用交出控制权。从本版本起，该功能对所有用户默认开启（PR #51812，于10月7日合并），但仍标记为开发中。在[features]下设置instant_interrupt = false可恢复旧行为，即输入的内容会等待响应结束后再处理。

TUI新增功能：启用worktrees功能后，可使用工具从受信任的本地项目创建和列出托管Git worktrees，让模型能够自行打开worktree（#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模式提供该档位；此标签随附的目录未列出此类档位。Code mode新增用于流式传递promise结果的JavaScript辅助函数，以及可选的按相关性排序的工具搜索（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 条目。自 v0.163.0 起，该功能默认启用，并标记为稳定。¹⁹³

修复：获批的文件系统权限提升可授予更广泛的写入权限，同时保留读取限制和网络限制；后台任务会保留其发起回合的权限。显式指定的启动权限在终端重新连接后仍然有效。以提升权限运行的 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 维护分支保持同步：纳入包含 GPT-6.1 Sol 的内置目录和 Amazon Bedrock 目录，以及 v0.159.3 的账户安全提醒。若无此补丁，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 个半小时后发布。它不更改任何默认设置、配置键或模型，新的启动辅助程序在 macOS 和 Linux 上的行为也与之前相同。

建议操作：在 Windows 上，如果 Codex 工作时出现控制台窗口闪现，请升级，尤其是在已安装后台服务器的情况下。¹⁸⁰

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（需手动启用，仍在开发中）：新输入会中断模型响应，或让长时间运行的code-mode调用交还控制权。在[features]下设置instant_interrupt = true即可试用。自v0.162.0起默认开启。
• 警告查看器关闭时会清除已查看的警告；按k可保留某条警告，以便稍后处理。
• 在决定是否实施计划时，可以滚动查看对话记录。
• Mermaid渲染支持更多流程图连线、标签和节点组。
• 切换任务时，空白会话会保留草稿；线程也可在首轮交互前归档。
• /status采用无边框显示，较长的值会自动换行。
• App-server客户端可从指定条目开始分页读取线程历史。

沙箱变更：已获批准的命令仍受显式文件系统拒绝规则约束；可写根目录下的.aws目录默认受保护（显式规则仍可覆盖此行为）；启用网络的macOS沙箱允许执行TLS信任评估；需要代理的执行环境现在也会获得代理。内置的plugin-creatorskill已移除。

建议操作：如果沙箱任务需要向.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连接的Bearer令牌、生成图像的透明背景，以及/ps中的多行命令预览。修复内容涵盖Windows沙箱故障（常规Windows 10路径、已存储凭据遭拒、大型权限策略）、存在嵌套可写根目录时的Linux沙箱启动、跨可写根目录的Git元数据保护、补丁审批中的macOS路径别名，以及Guardian审查在您中途发送消息时改为重试而非中止。

建议操作：如果自动化流程会向权限提升后的命令发送按键输入，请预期会出现审批提示，或关闭此功能；同时从配置中移除thread_context。¹⁷⁶

v0.157.1（2026年9月26日）

这是一个Windows补丁版本，包含从主分支回移的4项修复。Codex启动code-mode宿主或本地stdio MCP服务器时，不再弹出控制台窗口。即使Windows将进程留在外层作业对象中，后台服务器也能启动；脱离启动器运行的后台服务器不再持续占用启动器的输出管道，避免启动器退出后，调用它的命令仍一直等待。GitHub发布说明和更新日志条目仅表示“无法确定”主要更新；以上列表来自该版本的提交记录。

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

v0.157.0（2026年9月25日）

此版本又调整了3项默认行为。

• 全屏对话记录默认开启。v0.156.0通过/tui提供的全屏界面，现在成为会话启动时的默认界面，即使配置中没有[tui]部分也如此。要保留终端回滚缓冲区，请在/tui中选择Scrollback，或在[tui]下设置fullscreen_transcript = false；--no-alt-screen和tui.alternate_screen = "never"仍具有更高优先级。按住Shift单击现在可扩展对话记录中的选区。
• 符合条件的交互式启动会自动启动后台服务器，该选项也已从/experimental中移出。使用--no-daemon、--oss、--profile或大多数-c覆盖参数启动时，不会使用后台服务器。如果正在运行的服务器设置与会话不匹配，Codex会提供3个选项：不使用后台服务器继续运行、按所需设置重启服务器，或取消（默认选项）。要关闭自动启动，请在[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会话可连接到现有的本地守护进程，也可从智能体概览中创建。
• Guardian默认复用父线程的压缩结果： Guardian重启审查会话时，可以复用父线程的加密压缩结果。

各项功能的关闭方法见slash commands表中的/voice和/worktree条目，以及Guardian章节。

其他新增内容包括：可通过/tui选择的可选全屏TUI，支持对话记录搜索、鼠标选择与复制、右键复制、可点击链接和警告查看器；/theme选择器中的6款内置主题；/usage分析仪表板；在终端中渲染Mermaid图表和TeX数学公式，两者均有独立开关；/daemon菜单和--no-daemon标志；新建TUI线程默认关闭推理摘要。安全修复堵住了Windows入站流量、特权套接字和只读文件句柄方面的沙盒漏洞，codex doctor也不再在错误信息中回显配置值。错误修复确保轮次失败或中断后保留流式输出的回答，修复了tmux和SSH中的剪贴板转发，恢复会话时还原Plan模式，并使登录过程能够通过系统代理恢复。¹⁶⁹

v0.155.1（2026年9月18日）

这是仅包含1项修复的热修复版本。在0.155.0中，如果配置未设置model_reasoning_summary，新建的本地TUI线程会请求detailed摘要，不支持推理摘要的提供商会直接拒绝该请求。0.155.1将回退值恢复为none，因此未设置此键时不会请求摘要。显式设置的auto、concise和detailed始终有效，此后也保持不变。同一项单行改动也已合入main，并随0.156.0发布。

建议操作：如果0.155.0中的新TUI会话在连接非OpenAI提供商或自托管提供商时失败，请升级。如果需要摘要，请显式设置此键（参阅配置参考）。¹⁵⁸

v0.155.0（2026年9月17日）

语音以需要主动启用的实验性功能形式进入稳定版TUI：在支持的构建版本中，通过/experimental启用后，/voice可开启实时对话，提供流式转写和麦克风控制，并支持可配置的静音快捷键；macOS安装包还包含经过签名的语音资源。5天后，v0.156.0将其默认开启。托管worktrees在此版本中仍默认关闭。

0.155.0还包含以下内容：

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

安全修复堵住了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守护进程，以及托管守护进程更新。
• 远程权限配置文件，可从应用服务器发现，并在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起，Astra出现在选择器中。文档未注明最低CLI版本，因此请将上述版本视为最低要求。如果您的账户无权使用内置默认设置选中的模型，请在config.toml中显式设置model，不要依赖默认值。^145146147148

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用户发出速率限制警告：当约5小时窗口内的剩余额度不足一半时发出警告；其他套餐仍保留75/90/95%的阈值。
• Guardian的适用范围随审批模式调整： Full Access会跳过仅需确认操作的Guardian审查，User审批模式则跳过后台评分和预热。
• features.context_management.experimental_mode（默认关闭）为Codex后端上符合条件的Plus、Pro和Pro Lite会话启用基于token预算的上下文、历史备注和new_context工具。
• tui.disable_paste_burst取代了顶层键，后者仍可作为回退设置使用。

修复：TUI会话在app-server连接断开后可重新连接，并完整保留草稿；Guardian审查历史在压缩、重启和分支后仍会保留；已记住的MCP审批仅适用于所选账户。¹⁴⁰

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

update_plan改为需主动启用：tools.update_plan.enabled默认为false。关闭时，模型、协作模式、多智能体、上下文压缩、预热和目标延续提示中均不再包含内置的update_plan指导（请参阅计划模式与协作）。其他新增功能包括：Vim支持使用/和?搜索，以及n/N跳转，可与操作符组合使用，新草稿默认进入插入模式；提供操作指引的速率限制横幅；凭据刷新进度显示，包括Amazon Bedrock重新认证；包命名风格的MCP服务器名称（允许使用:、@、/和.）；MCP openai/elicitation表单请求；按工具设置的MCP output_token_limit；云端任务凭据仅限用于可信来源；可配置的thread/shellCommand超时；以及通过模型元数据默认启用的token预算机制。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；完整变更集请参阅版本比较。¹³⁴¹³⁵

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预算。¹³²¹³³

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）。

同期价格调整：OpenAI自8月21日起将GPT-5.6 Sol价格下调超过20%，为期3个月（至少持续至2026年11月21日）。Codex中Sol每100万输入、缓存输入和输出token的额度消耗分别从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新增通过/export导出Markdown、codex exec fork、在/status中显示预估额度或费用、将Amazon Bedrock Runtime作为内置提供商、异步hooks和可调用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日）：/import除支持从Claude Code导入外，还支持从Cursor导入；语音功能以流式实时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，Goal模式正式发布，并提供需主动启用的锁定式Computer Use。^{96979899100101196}

旧版--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起默认启用，仍标记为开发中）、Daybreak和代码模式中断（cli_daybreak、code_mode_interrupt；自v0.163.0起稳定并启用），以及Bedrock设置向导、增量工具更新和MCP OAuth刷新协调（自v0.164.0起稳定并启用）。自v0.164.0起，托管worktrees和实时对话成为永久启用的功能：其功能标志已标记为移除，但功能保持开启。Browser、Computer Use和Appshots是已有文档说明的用户功能，是否可用取决于平台和套餐。实验性或开发中的功能包括：Codex Cloud、代码模式及代码模式工具搜索、Memory v2、本地智能体留言板、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）、shell_zsh_fork和unified_exec_zsh_fork标志及打过补丁的zsh本身（v0.163.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。^176179181185近期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。0.163版本线于10月15日正式发布稳定版：v0.163.0基于计划外构建0.163.0-alpha.10.2发布（在其基础上增加一次发布提交），而alpha.11比该基线领先23次提交。0.164版本线于10月16日以alpha.1和alpha.2开启，10月17日推进至0.164.0-alpha.3，10月22日推进至alpha.12；同期还发布了计划外构建0.163.0-alpha.11.1和11.2（10月21日至22日），以及0.164.0-alpha.11.1（10月23日）。0.164版本线于10月23日发布稳定版v0.164.0，基于alpha.11加上一次发布提交构建（alpha.12比该基线领先9次提交），同一天，alpha更新为指向0.165.0-alpha.1。^{189190191193195}

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 / bubblewrap / 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 中退役。^{83117146148149171178} 它会读取文件、编写补丁、执行 shell 命令，并对您的代码库进行推理。当上下文接近容量上限时，Codex 会压缩对话以腾出空间。此层会消耗 token。

安全层：Codex 运行的每条命令都会经过操作系统级沙箱。在 macOS 上，Apple 的 Seatbelt 框架会实施内核级限制。在 Linux 上，bubblewrap 会隔离文件系统和命名空间，seccomp 则会过滤系统调用；较旧的 Landlock 实现将作为旧版方案保留。沙箱在内核层运行，而非容器内部。随后，审批策略会决定何时请求人工确认。

扩展层：MCP 用于连接外部服务（GitHub、Figma、Sentry）。skills 将可复用的工作流封装起来，供 Codex 按需加载。Apps 用于连接 ChatGPT 连接器。网页搜索则从互联网引入实时上下文。

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

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

目录

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 与协作
17. 记忆系统
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？

Codex从v0.128.0起提供自更新命令；其他操作均通过最初安装它的 包管理器完成。⁸⁶ 从v0.146.0起，发布产物、渠道元数据和安装程序别名均由OpenAI托管的发布基础设施提供，GitHub作为备用来源。¹¹⁴ 如果您的网络已将GitHub加入允许列表，以便安装和更新Codex，也请添加OpenAI的发布主机——有备用来源时，允许列表的遗漏可能只会触发静默回退，而不会报出明显错误。

# Check what you are running
codex --version                          # -> codex-cli 0.164.0
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会在 Environment下明确指出这一问题）。

卸载软件包不会删除您的状态数据。 身份验证信息、配置和会话历史记录 存储在~/.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（通过bubblewrap + 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

两种身份验证方式：

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（优先使用keyring，不可用时回退到文件存储）。

Amazon Bedrock登录（v0.145.0，实验性）： 对于通过Amazon Bedrock访问模型的团队，除了现有的托管API密钥身份验证（v0.140.0+）和AWS凭据链（参见“自定义模型提供商”）外，还提供了一种实验性登录方式，支持自定义端点和身份验证。GPT-5.6 Sol是默认的Bedrock模型。¹¹² v0.150.0修复了Amazon Bedrock模型的对话压缩和多智能体兼容性问题。¹³² v0.151.0在符合条件的TUI登录流程中新增了受功能开关控制的Amazon Bedrock选项：初始设置流程会发现现有的AWS配置档案和环境凭据，支持手动设置配置档案、访问密钥、环境变量及Bedrock API密钥，收集AWS区域信息，在输入时遮蔽机密信息，并在更换提供商时重启内嵌服务器。¹³⁵ v0.152.0新增凭据刷新进度显示：模型提供商刷新过期凭据时，TUI和codex exec会显示进度，其中也包括Amazon Bedrock会话的重新身份验证。此功能由稳定的modelProvider/authRecoveryStarted和modelProvider/authRecoveryCompleted app-server通知支持，通知中包含线程、轮次、提供商和面向用户的消息。¹³⁸

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.164.0

快速入门：您的首次会话

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 commands：

> /plan Refactor the database layer to use connection pooling

Codex会制定计划，但不会执行。请先审阅计划，再批准开始执行。

7. 检查工作成果：

> /diff

查看Codex在当前会话中所做的所有修改。

后续步骤： - 在AGENTS.md中设置项目指令（参见AGENTS.md如何工作？） - 根据您的工作流程配置配置档案（参见配置档案） - 尝试使用codex exec实现非交互式自动化（参见非交互模式）

核心交互界面

Codex提供5种不同的界面，均由相同的智能能力驱动。每种界面都针对不同的工作流进行了优化。

1. 交互式CLI（终端界面）

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

终端界面是一个全屏应用，包含：

• 输入区：输入提示词，通过@附加文件，使用!前缀运行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所不具备的功能：

• 多任务处理：在不同项目中同时运行多个并行智能体
• Git worktree隔离：每个线程都在仓库的独立副本中工作
• 内联差异审查：无需离开应用，即可暂存、还原和提交更改
• 集成终端：每个线程都有用于运行命令的终端
• 对话分叉：为对话创建分支，探索不同方案
• 浮动弹出窗口：将对话分离为可自由移动的窗口
• 自动化：安排定期任务（问题分类、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上，开启屏幕上下文后，会将最前方窗口的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数据控制的“共享链接”中查看或撤销链接。¹²⁸

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

3. IDE扩展（VS Code、Cursor、Windsurf）

Codex IDE扩展直接集成到编辑器中：

• 默认采用智能体模式：读取文件、进行编辑、运行命令
• 内联编辑：在当前文件中提供结合上下文的建议
• 共享会话：会话在CLI和IDE扩展之间同步
• 相同的身份验证方式：使用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. 浏览器扩展（Chrome、Edge、Brave、Opera、Vivaldi）

Codex提供适用于Google Chrome、Microsoft Edge、Brave、Opera和Vivaldi的浏览器扩展，在CLI、桌面应用、IDE扩展和云端之外，新增了第5种界面。该扩展于2026年5月率先支持Chrome；2026年8月25日的更新日志新增了另外4款浏览器的支持，可从ChatGPT桌面应用的设置 > Computer Use进行配置。5款浏览器均支持标签页提及和浏览器控制；Opera不支持侧边聊天，因此需从桌面应用启动其任务。该扩展旨在伴随您的日常浏览协同工作：Codex在后台跨标签页并行处理任务，而您始终掌控它可以访问哪些网站。⁹⁰¹²⁷

• 标签页并行执行：Codex可同时操作多个标签页，不会锁定前台标签页。
• 逐站点控制：您通过允许列表指定Codex可交互的网站；默认无权访问任何网站。
• 以浏览器为工作台：该扩展最适合以页面为准的应用和网站工作，例如管理控制台、内部仪表板、内容管理界面和工单系统；它并不替代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 服务器或其他托管工具。¹³⁰

[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 的情况下启动代理。¹³⁰

配置方案

适用于不同工作模式的命名配置预设。自 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）。^146148153在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的速度倍数。^145146147148 部分内容于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日重新访问时，该文档部分原文未发生变化。此功能仍处于实验阶段，且默认关闭；其行为和资格条件可能随时变化。^140146152 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 倍。^162171178

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 倍计费。^146171178 使用 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 sockets（例如 docker.sock、编辑器 IPC sockets）加入允许列表，而且默认不再阻止私有 DNS 解析。⁸²
• Linux：使用 bubblewrap（bwrap）隔离文件系统和命名空间，并使用 seccomp 过滤系统调用；这些机制通过独立的辅助进程（codex-linux-sandbox）运行。Landlock 实现作为旧版方案保留；v0.163.0 重命名了该 crate 中以 Landlock 命名的命令类型和系统调用模块，但未改变强制执行机制。⁵¹⁹³ Codex 优先使用 PATH 中位于工作目录之外的第一个 bwrap，找不到时则回退到捆绑的 codex-resources/bwrap（自 v0.100.0 起内置）。⁷ 如果缺少 bwrap 或无法创建用户命名空间，启动时会显示警告。v0.117.0 提高了在采用旧版内核配置的较老发行版上的 sandbox 可靠性。⁷⁵ v0.129.0 加固了 Linux 上的 sandbox 启动流程，并将内置 Bubblewrap 升级至 0.11.2，以包含上游安全补丁；v0.130.0 进一步加强了启动安全性。⁸⁹⁹¹
• Windows：使用受限令牌的原生 sandbox（在 v0.100.0 中由实验性功能转为正式功能）。同时支持 WSL（沿用 Linux 的 bubblewrap + seccomp）。v0.117.0 改进了受限令牌 sandbox，以实现更完善的进程隔离。⁷⁵ v0.130.0 允许 sandbox 用户访问桌面运行时二进制缓存，使 Windows sandbox 能够为工作区 sandbox 用户可靠地解析运行时二进制文件。⁹¹

为何这很重要：与基于容器的 sandbox（Docker）不同，操作系统级 sandbox 更快、更轻量，也更难逃逸。内核会在 Codex 看到系统调用之前强制实施限制。

安全修复： - zsh-fork sandbox 绕过漏洞（v0.106.0）：修复了通过 zsh fork 执行 shell 时可能绕过 sandbox 限制的漏洞。⁶⁰ 如果您使用的是更早版本，请立即升级。 - 输入大小上限（v0.106.0）：Codex 现在将输入限制在约 100 万个字符以内，防止超大负载导致程序挂起。⁶⁰ - 安全的 devcontainer 配置文件（v0.121.0）：面向 Docker devcontainers 新增了经过加固的客户配置文件，在容器内使用 Bubblewrap 实现 sandbox。支持 WSL2；明确拒绝 WSL1（Bubblewrap 与 WSL1 的内核兼容层不兼容）。⁸² - Guardian 审查 + hooks（v0.121.0）：在 Guardian 审查会话期间会禁用 hooks，防止工具调用前后的 hooks 干扰 Guardian subagent 的决策。⁸² 如果依赖 hooks 进行日志记录或验证，请注意 Guardian 审查会跳过这些 hooks；若需要完整的审计轨迹，请改用应用服务器的可观测性功能。 - 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 进行配置。¹³²

独立的审批 ID（v0.104.0+）

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

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

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

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

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

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

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

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

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

新的 --approve-for-me CLI flag 会将审批提示转变为自动审查的审批：每个请求不再打断您，而是由一次审查流程代为裁定批准或拒绝。¹¹⁶ 这种方式介于“全部批准”（已移除的 --full-auto 曾鼓励采用这种做法）与“所有操作均打断询问”之间——提示依然作为决策节点存在，但由审查程序作答。它会沿用 v0.146.1 针对具备网络安全能力模型所提供的更安全自动审查默认设置。应将其视为任何其他形式的授权委托：适合长时间无人值守、任何中断都会导致停滞的运行；不适合涉及凭据或生产状态、需要由您亲自审查的会话。

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

write_stdin_approval 功能标志在 v0.151.0 推出时默认关闭，自 v0.158.0 起默认启用。向已提升权限的 unified-exec 终端发送非空输入前，它要求重新审批。这些审查会通过 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 将配置文件提升为受管理的配置界面：列出 APIs 时会公开可用配置文件的元数据；配置文件可以彼此继承；受管理的 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 模式，系统会拒绝该操作，而不会静默削弱限制。¹³⁴

旧版 --full-auto 指南

旧版指南将 --full-auto 描述为以下配置的便捷别名：

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

v0.128.0 的发行说明将 --full-auto 标记为弃用，当前 CLI 帮助也不再针对交互式运行列出该选项。请改用上述明确的 flags 或具名权限配置文件。⁸⁶

v0.147.0 完成了移除工作：codex exec --full-auto 已不复存在。仍传入该 flag 的脚本现在会直接报错，而不会继续运行。迁移过程并不复杂——将其替换为 --sandbox workspace-write；如果旧调用依赖 --full-auto 的审批行为，还需添加审批 flag 或配置文件。升级前请审查所有通过 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 Subagent 进行智能审批（v0.115.0+）

智能审批可以将审查请求交由 guardian subagent 处理，不必让每项操作都等待人工审批。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 的运行时机，不会改变人工审批层：本指南所述 danger-full-access 配合 on-request 时的提示行为属于审批策略，是一套独立机制。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 的 cherry-pick）只能通过 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 会话捕获和 subagent 历史记录 fork 必须无条件使用线程自有上下文。Codex 会忽略 [features.guardianv2] 下的 thread_context，包括配置文件覆盖和受管理的要求，并显示弃用通知，要求从 config.toml 中删除该设置。没有替代的关闭开关。¹⁷⁶

Guardian 可以读取更早的用户消息（v0.160.0，可选启用）：Guardian 审查的记录可能会遗漏更早的指令、限制或已撤销的权限。在启用 Apps 的情况下，如果在 [features] 下设置 guardian_conversation_history_tools = true，审查程序将获得 user_message.search_messages 和 user_message.read_messages 两个工具；它们通过父会话自身的 Apps 连接和身份提供服务。每次调用都会重新检查父会话当前的应用和工具策略；如果工具已禁用或需要审批，则以关闭方式失败。可通过两个 [auto_review] 键进行调整：conversation_history_max_output_tokens 用于限制每次响应的大小（默认估算为 4,000 个 token；父会话更严格的限制仍然适用）；experimental_conversation_history_prompt 用于替换内置检索指令（留空则使用默认值）。另一个可选标志 guardian_root_handoff_context 会将 worker agent 审查所用的根对话证据缩小到每次向其交接前后的消息，再加上最新的 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 指令的同时，系统会跳过项目范围的发现流程，因此不受信任的检出内容无法在您信任它之前注入操作约定。¹³²

桌面端多文件夹项目（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 添加为第十二个事件¹³²——旧版名称已从可配置界面中移除：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 事件（¹³²）——因此请查看 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 时同样如此。¹³⁴

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）不受影响。^125152153

在 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 便是权宜之计：^12125148152

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 报告，同时保留有效的本地目录和全局启用的远程目录。¹³⁴

@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）¹³² - 修复了子智能体的 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 也会根据对话内容建议一个可编辑的标题。¹³² v0.151.0 新增 /recap：可按需获取对话近期进展与后续步骤的简短摘要；对于符合条件、处于空闲且未聚焦状态的对话，Codex 也会自动生成同样的回顾并添加到对话记录中。此类请求受到严格限制并彼此隔离，且仅在自动生成失败时重试。¹³⁵ v0.153.0 让自动生成部分成为可选功能：tui.auto_recap = false 会取消已安排的自动回顾检查并丢弃待处理的自动结果，但手动执行 /recap 仍可正常使用。¹⁴⁰

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

恢复

从上次中断的位置继续：

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 任务，并要求代理读取、创建任务或向任务发送消息。¹³² 如需将 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");