Codex CLI：权威技术参考指南

要点速览：Codex 是一款覆盖多种使用界面的编码代理：它能够读取代码库、在操作系统级沙箱中运行命令、修补文件，并将任务委派到云端。掌握五大系统——config.toml、沙箱与审批模型、AGENTS.md、MCP 和 skills——即可让它成为效率倍增器。模型选择：OpenAI 的模型文档目前建议日常及复杂编码使用 GPT-6 Sol（gpt-6-sol，自 v0.156.1 起进入 CLI 选择器），最棘手的端到端工作使用 GPT-6-Astra（未指定模型时，它仍是 CLI 的内置默认模型），而目标明确的大批量任务则使用 GPT-6 Luna。模型可用性取决于订阅计划、工作区设置和发布进度；在此期间，GPT-5.6 系列模型仍可使用。通过 ChatGPT 登录 Codex 时，GPT-5.5 将于 2026年10月14日退役。¹⁴⁶¹⁷¹ 初次接触？请直接前往安装和快速入门。想要跟踪版本发布？最新稳定版为 v0.157.1（2026年9月26日）；版本亮点首先概述当前状态（哪些功能默认启用，哪些仍处于实验阶段），随后逐一介绍各个版本；更新日志则列出了本指南的每一次更新。¹¹⁶¹⁷⁴

Codex 是一款覆盖多种使用界面的编码代理，而不是只会编写代码的聊天机器人。CLI 能够读取代码库、在沙箱中执行命令、修补文件、通过 MCP 连接外部服务，并将长时间运行的任务委派到云端。它在本地运行，却能统筹全局；同一套智能能力可根据您的工作方式服务于五种不同界面，其中包括浏览器扩展。该扩展支持 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 使用 Landlock + seccomp），而非在容器内部实施。
• AGENTS.md 可跨工具使用：项目指令可用于 Codex、Cursor、Copilot、Amp、Jules、Gemini CLI、Windsurf、Cline、Aider、Zed 以及超过 60,000 个开源项目。一次编写，随处使用。
• 配置档案可减少上下文切换开销：定义具名配置预设（fast、careful、auto），并使用 --profile 在它们之间切换。
• 上下文管理至关重要：Codex 内置模型目录为 GPT-6 Astra、Sol、Luna 及 GPT-5.6 系列提供 272K 上下文窗口（API 中列出的 GPT-6 Sol 和 Luna 为 1.05M）；在 GPT-5.5 于 2026年10月14日从 Codex 退役前，其上下文窗口为 400K。请使用 /compact、聚焦明确的提示词和 @file 引用，主动管理令牌预算。⁸³¹¹²

本指南使用方法

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

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

发布亮点：近期更新

以下按版本逐一记录，最新版本在前，供关注 Codex 发布进度的读者查阅。如果您刚接触 Codex，可直接跳到快速入门；以下内容并非高效使用 Codex 的必读信息。验证详情（版本比较、提交列表和文档检查）见脚注。

当前状态

截至2026年9月26日的 Codex CLI

• 稳定版：v0.157.1，于9月26日发布（npm latest）；这是基于v0.157.0（9月25日）的 Windows 补丁版本。
• Alpha 版：npm alpha 为0.159.0-alpha.4。0.158系列未发布稳定版。
• 自v0.157.0起默认启用：全屏会话记录、后台服务器自动启动和 Guardian 线程上下文。如需关闭其中某项，请在[tui]下设置fullscreen_transcript = false，在[features]下设置daemon_auto_start = false（或使用--no-daemon启动），或在[features.guardianv2]下设置thread_context = false。
• 自v0.156.0起默认启用：/voice、托管 worktrees，以及 Guardian 父级压缩复用（对应的[features]键为realtime_conversation、worktrees、guardian_reuse_parent_compaction）。
• 仍需主动启用或仍处于实验阶段：实验性上下文管理、Codex Cloud 和代码模式。
• 模型：GPT-6 Sol（gpt-6-sol）适用于日常及复杂编码；GPT-6-Astra 适用于最困难的端到端工作（未设置模型时，它仍是CLI内置的默认模型）；GPT-6 Luna 适用于高吞吐量任务。通过 ChatGPT 登录使用 Codex 时，GPT-5.5 将于2026年10月14日下线。
• 固定版本：运行npm install -g @openai/codex@0.157.1，然后使用codex --version确认版本。¹⁷⁴¹⁷⁵

v0.157.1（2026年9月26日）

这是一个 Windows 补丁版本，包含从主分支回移的4项修复。Codex 启动代码模式主机或本地 stdio MCP服务器时不再打开控制台窗口。当 Windows 将进程置于外层作业对象中时，后台服务器现在也能启动；分离运行的后台服务器也不再持续占用启动器的输出管道，从而避免启动器退出后调用命令仍一直等待。GitHub发布说明和变更日志仅称亮点“无法确定”；以上列表根据该版本的提交记录整理而成。

建议操作：如果您在 Windows 上运行 Codex，请升级。上述4项修复仅针对 Windows。¹⁷⁴

v0.157.0（2026年9月25日）

此版本又将3项功能改为默认启用。

• 全屏会话记录默认启用。v0.156.0通过/tui提供的全屏 UI 现已成为会话启动时的默认界面，即使配置中没有[tui]部分也是如此。如需保留终端回滚缓冲区，请在/tui中选择 Scrollback，或在[tui]下设置fullscreen_transcript = false；--no-alt-screen和tui.alternate_screen = "never"仍具有更高优先级。现在按住 Shift 单击可扩展会话记录中的选区。
• 后台服务器自动启动，适用于符合条件的交互式启动，并且该选项已移出/experimental。使用--no-daemon、--oss、--profile或大多数-c覆盖项启动时，不会使用后台服务器。如果正在运行的服务器设置与会话不匹配，Codex 会提供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日）

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

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

v0.155.0（2026年9月17日）

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

0.155.0还包括：

• MCP用户验证：在受支持的 Mac 上，本地 TUI 会话可通过 Touch ID 验证MCP请求，由 Secure Enclave 签名；同时支持工作区范围的身份限制，并可在MCP工具后续流程中进行原生验证。
• 已移除 Windows 的/sandbox-add-read-dir slash command。
• Worktree 管理：可在智能体概览中隐藏、归档和删除 worktree 会话，查看所有权详情，并在删除干净的托管 worktree 前进行确认。
• 实时推理摘要会流式显示在 TUI 状态行中，已完成的工作附带完成时间戳。
• 守护进程：支持配置更新计划，新增codex app-server daemon update命令，并可在守护进程重启后恢复线程。
• Amazon Bedrock AWS 凭据命令，以及与稳定版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起，它会出现在选择器中。由于文档未规定最低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 会话启用令牌预算上下文、历史记录备注和new_context工具。
• tui.disable_paste_burst取代顶层键；后者仍可作为回退设置使用。

修复内容：应用服务器连接中断后，TUI 会话可在保留草稿的情况下重新连接；Guardian 审查历史记录会在压缩、重启和派生后继续保留；记住的MCP审批仅适用于所选账户。¹⁴⁰

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

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

v0.151.0（2026年8月29日）

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

修复内容包括：防止/cd削弱沙箱限制，以及防止权限变化后过期的 Guardian 分类继续授权操作。发布正文仅列出最后几个 PR；完整变更集请参阅版本比较。¹³⁴¹³⁵

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会将保留的图像计入远程压缩的令牌预算。¹³²¹³³

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日）；Sol 每100万个输入、缓存和输出令牌的 Codex 积分费率从125/12.5/750降至100/10/500。^120121126

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

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

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

• v0.146.0和v0.146.1（7月29日、8月5日）：配置的代理覆盖所有传输方式；Agent Plugins 清单以及 Amazon Bedrock 和Claude Code市场；支持固定线程的会话命名；执行器提供的 skills；针对具备网络安全能力的模型增强自动审查默认设置。¹¹⁴¹¹⁵
• v0.145.0（7月21日）：除Claude Code外，还可从 Cursor 使用/import导入；语音以流式实时 V3 对话的形式回归；可选启用的多智能体 v2 体验趋于稳定；实验性分页线程历史记录和 Amazon Bedrock 登录；内置 GPT-5.4 选择迁移至 GPT-5.6 Terra 和 Luna。v0.144.6将 GPT-5.6 上下文窗口设置为272,000个令牌。¹¹¹¹¹²
• 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。^{96979899100101176}

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

稳定性说明：稳定且有文档支持的功能包括：核心CLI和 TUI、沙箱和审批策略、config.toml、AGENTS.md、skills、hooks、插件、多智能体工具、目标、权限配置文件、/voice和托管 worktrees（自v0.156.0起默认启用），以及全屏会话记录和后台服务器自动启动（自v0.157.0起默认启用）。Browser、Computer Use 和 Appshots 是有文档支持的面向用户功能，其可用性取决于平台和套餐。仍处于实验或开发阶段的功能包括：Codex Cloud、代码模式、实验性上下文管理、Memory v2、本地智能体留言板，以及本指南中标记为[EXPERIMENTAL]或列于/experimental下的任何功能；这些功能可能随版本变化。已移除：--full-auto（v0.147.0）、untrusted审批策略（v0.149.0）、codex mcp-server（v0.154.0）和js_repl。

Alpha 渠道：Alpha 构建每天发布数次，Alpha 版本线的发布正文均为占位内容，并且经常出现从较旧基础版本分出的带外构建（最近的包括：0.155.0-alpha.16.4、0.157.0-alpha.11.1、0.158.0-alpha.15.1和0.158.0-alpha.2.1）。npm alpha标签至少有两次指向其中之一，导致@alpha安装的构建版本比latest更旧。0.158版本线从0.158.0-alpha.2（9月23日）延续至alpha.15（9月25日），但未发布稳定版；9月25日，alpha标签转移到0.159版本线，目前为0.159.0-alpha.4。如果您跟踪 Alpha 版本，请检查npm view @openai/codex dist-tags，并安装确切版本，而非@alpha。¹⁷²¹⁷⁵近期 Alpha 版本线如何演变为稳定版的按日期历史记录见¹⁷³。

Codex 的工作原理：心智模型

在深入了解各项功能之前，请先理解 Codex 的架构如何影响您使用它的方方面面。该系统由共享智能层提供支持，并通过五个界面运行：

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

核心层：GPT 模型系列为一切功能提供支持。截至2026年9月23日，当前一代为 GPT-6：gpt-6-sol 适用于日常及复杂编码，gpt-6-astra 适用于最具挑战性的端到端工作（未配置模型时，它也是内置的 CLI 默认模型），而 gpt-6-luna 则适用于目标明确的大批量任务。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 中退役。^{83117146148149171} 它可以读取文件、写入补丁、执行 shell 命令，并对代码库进行推理。当上下文占满时，Codex 会压缩对话以释放空间。此层会消耗 token。

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

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

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

关键洞察：大多数用户只使用一个界面。高级用户会同时使用全部五个界面：通过 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？

自 v0.128.0 起，Codex 提供了自更新命令；其他操作均通过最初安装它的 包管理器完成。⁸⁶ 自 v0.146.0 起，发布产物、渠道元数据和安装程序别名均由 OpenAI 托管的发布基础设施提供，并以 GitHub 作为后备。¹¹⁴ 如果您的网络允许列表已放行 GitHub，以便安装和更新 Codex，也请加入 OpenAI 发布主机——后备机制意味着允许列表遗漏时，系统会悄然降级，而不会直接报错失败。

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

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

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

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

当某个版本导致环境出现问题时，锁定版本才是明智之举。 Codex 采用快速迭代的稳定版本线，因此 安装指定版本是最快的回滚方式——提交问题、锁定版本，然后继续工作。 请使用 codex --version 验证回滚是否生效，因为 PATH 中被遮蔽的另一份安装 可能仍会悄然提供旧版二进制文件（codex doctor 会在 环境部分明确指出此问题）。

卸载软件包不会删除您的状态数据。 身份验证信息、配置和会话历史记录 存储在 ~/.codex/ 中。保留该目录，可在重新安装后继续使用登录信息和历史记录； 只有确实需要彻底重置时才应删除它——rm -rf ~/.codex 还会清除 config.toml、 auth.json 以及所有已存储的会话。

直接安装脚本（v0.106.0+）

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

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

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

下载二进制文件

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

系统要求

• macOS：Apple Silicon 或 Intel（通过 Seatbelt 提供完整沙箱支持）
• Linux：x86_64 或 arm64（通过 Landlock + seccomp 提供沙箱）
• Windows：使用受限令牌的原生沙箱（在 v0.100.0 中从实验性功能升级）。同时支持 WSL²

身份验证

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

有两种身份验证方式：

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

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

Amazon Bedrock 登录（v0.145.0，实验性）： 对于通过 Amazon Bedrock 获取模型访问权限的团队，Codex 提供了实验性登录方式，支持自定义端点和身份验证；此外仍可使用现有的托管 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 应用服务器通知提供支持，通知中包含线程、轮次、提供商以及面向用户的消息。¹³⁸

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

快速入门：您的第一个会话

只需 5 分钟，即可从零开始高效使用。

1. 安装并完成身份验证：

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

2. 进入项目目录：

cd ~/my-project                  # Any git repo works

3. 启动 Codex：

codex

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

4. 提出问题：

> What does this project do? Summarize the architecture.

Codex 会读取关键文件并解释代码库。此类问题不会产生任何更改——只有在您要求修改时，Codex 才会修补文件；沙箱和审批策略则决定它何时必须先征求许可。

5. 进行更改：

> Add input validation to the login endpoint

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

6. 使用 slash command：

> /plan Refactor the database layer to use connection pooling

Codex 会创建计划，但不会执行。审阅计划后，批准即可开始执行。

7. 检查工作成果：

> /diff

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

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

核心交互界面

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

1. 交互式 CLI（终端 UI）

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

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

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

主要 TUI 快捷键：

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

TUI 中可用的 Slash commands：

工作流选择器重新设计（v0.129.0）：经过重新设计的选择器让恢复和分叉操作更易访问；新增的原始回滚模式则允许滚动浏览未经渲染的转录文本，方便逐字复制命令或模型输出。在排查长时间调试会话或将输出传送至其他工具时尤为实用。⁸⁹

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

2. Codex Desktop App（macOS + Windows）

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

桌面应用增加了 CLI 不具备的功能：

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

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

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

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

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

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

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

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

4. Codex Cloud [实验性]

云端任务在 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种界面。Chrome 版扩展于2026年5月推出；2026年8月25日的更新日志增加了其他4款浏览器，可从 ChatGPT 桌面应用的 Settings > Computer Use 中完成设置。5款浏览器均支持标签页提及和浏览器控制；Opera 不支持侧边聊天，因此需要从桌面应用启动相关任务。该扩展旨在与日常浏览相辅相成，而非接管整个浏览过程：Codex 会在后台跨标签页并行工作，您始终可以控制它能够访问哪些网站。⁹⁰¹²⁷

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

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

配置系统深度解析

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

优先级（从高到低）

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

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

配置文件位置

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

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

完整配置参考

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-6-sol"                    # Docs' example default; unset = bundled default (gpt-6-astra)
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"]

# ─── 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)
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)

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

# ─── 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 servers 或其他托管工具。¹³⁰

[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-sol"
# GPT-6 Sol/Luna start on the Fast tier (2.5x credits) unless service_tier is set; check /fast status
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"

警告：用于 OpenAI 托管模型的 chat/completions 传输API（wire_api = "chat"）已被弃用，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 任务的推荐选择，包括复杂编码、计算机操作、知识工作和研究工作流。4月23日起，ChatGPT Plus / Pro / Business / Enterprise / Edu / Go 用户可在 Codex CLI / web / desktop 中使用；4月24日起可通过 OpenAI API 使用。上下文窗口：Codex 中为 400K，API 中为 1M——Codex 将窗口限制为 400K，以平衡不同订阅层级的吞吐量与成本；API 则开放完整的 1M。定价（API）：每 MTok 输入 $5、输出 $30（是 GPT-5.4 费率的 2 倍；OpenAI 表示，考虑令牌效率提升后，实际增幅约为 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 重写服务基础设施，使令牌生成速度提升了 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日）：GPT-5.1 模型已不再通过 ChatGPT 提供。现有对话会自动改用 GPT-5.3 Instant、GPT-5.4 Thinking 或 GPT-5.4 Pro 继续进行。GPT-5.1-Codex-Mini 在2026年7月23日停用前，仍可通过 API 和 CLI 使用。⁷¹⁸⁸

免费层级说明（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 上下文，每 MTok 费率为 $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 个令牌。¹¹¹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 列为旗舰模型，并称其为“我们能力最强的模型，专为最困难的端到端工作构建”——标准短上下文费率为每 MTok 输入 $10、输出 $50，上下文窗口为 1.05M 个令牌，最大输入 922,000 个令牌，最大输出 128K，知识截止日期为2026年4月30日——同时记录了长上下文计费层级：输入提示超过 272K 个令牌时，整个请求的输入费用按 2 倍、输出费用按 1.5 倍计算，即定价页面所列的每 MTok 输入 $20、输出 $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 确认——Python SDK 0.154.0 版本（2026年9月10日）增加了 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 倍（短上下文每 MTok 输入 $20、输出 $100，长上下文输入 $40、输出 $150）。v0.153.2 目录字符串中的“2x speed”部分仍只是目录显示文本——速度页面并未说明 Astra 的速度倍数。^145146147148部分内容已于2026年9月23日被取代：模型文档不再将 Astra 称为推荐的 Codex 模型。其“Recommended models”部分现以 GPT-6 Sol 和 Luna 为首选，仅将 Astra 用于“最困难的端到端工作”，并将 Astra 标记为不适用于 Codex cloud，同时将 Astra 的起始推理强度设为 Light（low），与内置目录一致。在未配置模型时，Astra 仍是内置 CLI 默认模型。¹⁷¹

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日重新访问时，该文档章节的原文保持不变。此功能仍处于实验阶段，且默认关闭；其行为和使用资格可能发生变化。^140146152v0.157.0：内置模型目录不再将 GPT-6-Astra 或任何其他内置模型标记为支持实验性上下文（#47397），并且 CLI 只会为带有此标记的模型启用该实验。因此，使用内置目录时，选择启用不会产生效果；文档并未说明向已登录账户提供的目录是否有所不同。截至2026年9月26日，模型文档仍在介绍这一选择启用方式。¹⁷⁴

模型选择流程图

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; bundled default when no model is set)
   │     │  └─ No → gpt-6-sol (everyday and complex coding; start at Medium)
   └─ GPT-6 not yet available on your account? → 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 推理消耗的令牌可能是 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 采用 25× 的5小时限额（标准提升为 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 Astra、Sol 和 Luna 的 Fast 模式成本为 Standard 点数费率的2.5倍。捆绑模型目录还会在 TUI 中将 Fast 设为 GPT-6 Sol 和 Luna 的默认档位，除非您设置 service_tier。因此，如果点数消耗速度超出预期，请检查 /fast status。与类似的纯文本交互相比，图像生成消耗内含限额的速度快3-5倍。¹⁶²¹⁷¹

Enterprise 和 Edu 套餐的点数随合同配额调整。请在 TUI 中使用 /status 查看当前用量。

API 计费

通过 API 使用 Codex 时，OpenAI 会按照所选模型的标准 OpenAI API 定价按 token 计费（另加任何适用的提示缓存折扣）。当前每100万 token 的 API 费率为：GPT-6 Sol 输入 $2 / 输出 $10，GPT-6 Luna 输入 $0.10 / 输出 $0.50，GPT-6 Astra 输入 $10 / 输出 $50；对于这3种模型，当提示输入超过272K token 时，整个请求的输入费用按2倍计算，输出费用按1.5倍计算；Fast 模式费用按2倍计算。¹⁴⁶¹⁷¹ 使用 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 进行监控——企业部署可以将使用遥测数据导出到现有的可观测性技术栈

决策框架

各界面的适用场景

各 sandbox 模式的适用场景

各推理级别的适用场景

Plan Mode 与直接执行

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

应选择哪个 Profile？

根据任务选择预配置的 Profile：

Profile 文件（每个预设对应一个文件，存放在 ~/.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"

按会话切换 Profile：codex --profile careful

Sandbox 与审批系统如何运作？

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

v0.148.0 安全加固：现在，无论在 Linux 还是 Windows 上，sandbox 限制都会以安全方式失败——被拒绝或无法读取的路径将被视为已阻止，而不会被悄然放行。¹¹⁸

第 1 层：Sandbox（允许执行哪些操作）

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

各平台的强制实施机制：

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

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

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

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

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

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

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

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

从 v0.150.0 开始，可以绑定键盘快捷键，从编辑器中循环切换权限模式——请通过 /keymap 进行配置。¹³²

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

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

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

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

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

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

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

App 审批模式 writes（v0.144.0+）

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

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

新的 --approve-for-me CLI 标志会将审批提示转变为自动审查的审批：每项请求不会中断您的操作，而是由审查流程代您判断并批准或拒绝。¹¹⁶这种方式介于“全部批准”（现已移除的 --full-auto 曾鼓励采用这种策略）和“所有操作均中断询问”之间——提示仍然是决策点，只是由审查器代为回答。建议将其与 v0.146.1 中针对具备网络安全能力的模型所采用的更安全自动审查默认设置配合使用；此标志会继承这些默认设置。请将其视为任何其他形式的授权委托：适合长时间无人值守且一旦中断就会停滞的运行；不适合涉及凭据或生产状态、需要由您亲自审查的会话。

提升权限的终端输入审批（v0.151.0）

write_stdin_approval 功能标志默认禁用。启用后，在向已提升权限的 unified-exec 终端发送非空输入之前，必须重新获得审批。这类审查会通过 hooks、Guardian、应用服务器和 TUI，以 writeStdin 审批的形式进行路由；终端环境、启动目录和权限提升状态会跨轮次保留，并且在获得审批后、写入任何字节之前，会重新验证进程身份。完整格式化后的操作和审批原因不得超过 8,000 字节——内容过大或被截断的操作会在请求审批或向终端发送任何内容之前被拒绝。¹³⁵

权限配置文件（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 帮助中已不再列出用于交互式运行的该选项。请改用上述显式标志或具名权限配置文件。⁸⁶

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

Sandbox 可靠性（v0.129.0）：Linux sandbox 启动加固减少了慢速文件系统或符号链接检出环境中的竞态问题；Windows sandbox 的可靠性改进解决了长时间运行过程中的若干边缘崩溃问题；随附的 Bubblewrap 也已升级至 0.11.2，纳入上游安全补丁。无需更改配置。运行 codex update 即可获取这些改进。⁸⁹

推荐配置

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

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

高级用户（完全访问权限，保留人工参与）：

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

社区文章将这种搭配推荐为“最佳平衡点”⁸；在照搬建议前，请先理解它实际意味着什么：当命令需要越过 sandbox 边界或访问网络时，才会触发审批提示；而 danger-full-access 会移除这两道边界，因此 on-request 几乎没有任何需要上报审批的操作。这代表的是以最少询问换取最大能力，而不是每条命令都由人工检查的最大能力。如果您需要后者，请保留 workspace-write，让 sandbox 边界负责触发提示。¹²³

CI/CD 自动化：

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

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

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

在 config.toml 中配置审查器：

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

这对于 CI/CD 工作流尤其有用：既能通过推理实现自动审查，又不必笼统地设置 approval_policy = "never"。

Guardian v2 默认值调整（v0.151.0）：Guardian v2 现在默认使用带图像的计算机操作审查。features.guardianv2.review_scope.computer_use_only 默认为 true——将其设为 false 可保留更广泛的工具审查范围；features.guardianv2.transcript.include_images 默认为 true——将其设为 false 可避免在 Guardian 记录中包含图像。这两项功能在 v0.150.0 中作为可配置且默认关闭的界面推出；从 v0.151.0 开始，默认值改为开启。¹³⁵

Guardian 范围会跟随审批模式（v0.153.0）：现在有两种模式会跳过无法改变结果的 Guardian 工作。在 Full Access 模式下（该模式已将 approvalPolicy: "never" 与无限制权限相结合），仅用于确认的 Guardian 和 MCP 请求无需同步审查、采样器预热或后台评分即可获批——待处理、失败或受限的环境不会被视为 Full Access，并且每一轮都会重新评估活动权限状态，因此现有线程可以安全地进入或退出 Full Access。在用户审批模式（approvals_reviewer = "user"）下，系统会跳过 Guardian 预热和异步评分，并自动接受常规的 node_repl.js 执行确认；敏感操作检查和用户输入请求则保持原有行为。¹⁴⁰这只会缩小 Guardian 的运行时机，不会改变人工审批层：本指南中关于 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 的拣选提交）只能通过 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 开关，同时会保留显式配置和配置文件覆盖设置。如需将其关闭：请在 config.toml 的 [features.guardianv2] 下设置 thread_context = false。¹⁷⁴

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 Mode 与协作

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

Plan mode 与 update_plan 工具（v0.152.0）：二者并不相同，并且只有一个默认启用。Plan mode——即本节介绍的协作模式，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 Mode

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

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

Steer Mode

Steer mode 自 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 mode 在 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+），可跨会话存储事实、偏好和项目上下文。²⁴

记忆命令

记忆以 Markdown 文件形式存储在 ~/.codex/memory/ 下。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桌面应用（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。¹⁶⁹¹⁷¹

自动化

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

• 在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沙箱，并提供完整的功能对等性，包括skills、自动化和worktrees，无需安装WSL。⁶⁶

GitHub Action 与 CI/CD

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

基本用法

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

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

配置选项

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

安全策略

访问控制

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

默认设置：只有拥有写入权限的协作者才能触发 Codex 工作流。

Codex SDK

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

安装

npm install @openai/codex-sdk

基本用法

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

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

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

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

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

高级 SDK 功能

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

线程和客户端配置

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

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

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

运行时：Node.js 18+。

性能优化

上下文管理

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

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

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

Token 效率

速度优化

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

如何调试问题？

常见问题及解决方案

错误消息参考

codex doctor有什么作用？

在提交错误报告或调试损坏的安装之前，应首先运行codex doctor这一命令。 它会将本地运行时、配置、身份验证、终端、网络和状态汇总到一份报告中， 项目自身的问题模板也会要求您粘贴该命令的输出。¹⁶³

codex doctor                           # Full human-readable report (the default)
codex doctor --summary                 # Compact view
codex doctor --json                    # Redacted structured JSON, for bug reports
codex doctor --all                     # Expand truncated lists
codex doctor --no-color                # Strip ANSI color

报告按固定章节组织，便于快速查看所需内容：¹⁶³

每项检查都带有状态标记——✓正常、✗失败、⚠警告、○空闲——以及一行摘要。 --json通过稳定标识符标记每项检查，因此除了人工查看外， 还可用于CI或支持脚本。¹⁶³

此命令在多个版本中逐步完善：它最初随v0.131.0发布，在v0.135.0中增加了环境、Git、 终端、应用服务器和线程清单报告，并在v0.139.0中加入了编辑器和分页器 详情（JSON中的敏感值会被隐去）。^96176165

应当最先使用，而非最后才用。大多数“Codex坏了”的报告最终都能归结为doctor 已明确指出的问题：过期的身份验证模式、解析失败的config.toml，或另一项安装 遮蔽了PATH中的版本。

诊断工具

codex doctor                           # Full local diagnostic (start here)
codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

会话内TUI诊断：

/status                                # Token/session overview
/debug-config                          # Show config layers and requirement sources
/compact                               # Summarize history to reclaim context

注意：codex --verbose不是有效的顶层标志。请使用上述调试子命令和TUI诊断功能。

全新重装

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

此操作会保留~/.codex/（身份验证、配置、会话）。如需锁定到特定版本、在有问题的版本发布后降级， 或彻底清除状态，请参阅 更新、降级或卸载。

调试模式

codex debug app-server send-message-v2  # Test app-server client

报告问题

/feedback                              # Send logs to Codex maintainers (in TUI)

也可以在github.com/openai/codex/issues提交问题。¹

Codex Security【预览】

Codex Security于2026年3月6日进入研究预览阶段，将具备上下文感知能力的应用安全审查引入Codex技术栈。⁷⁷ ChatGPT Pro、Enterprise、Business和Edu客户可通过Codex网页版使用。

工作原理：Codex Security通过分析代码仓库来构建项目专属的威胁模型，根据现实影响识别漏洞，并在沙箱环境中对发现结果进行压力测试和验证。该代理会提供置信度更高的发现结果及修复方案，减少无关紧要的错误所产生的噪声。

性能表现：研究预览期间，Codex Security扫描了120万个提交，识别出10,561个高严重性漏洞。其精确率持续提升——噪声减少84%，严重性高估减少90%以上，误报率降低一半。该系统已在OpenSSH、GnuTLS和Chromium中发现真实漏洞，其中14个已获分配CVE编号。⁷⁷

注意：Codex Security不同于CLI内置的沙箱安全模型。沙箱保护您的计算机免受Codex影响；Codex Security则保护您的代码库免受漏洞威胁。

企业部署

管理员控制（requirements.toml）

管理员可通过 requirements.toml 强制执行企业策略。该配置文件由管理员实施，用于约束用户无法覆盖的安全敏感设置：²¹

v0.146.0 新增了企业计划识别功能，并允许管理员控制应用内更新。¹¹⁴ 对于受管设备群而言，这决定了是由开发人员在发现新版本时自行更新 CLI，还是由管理员决定版本的部署时间。发行说明公布了此控制功能，但未公开其 requirements.toml 键——在 OpenAI 发布相关文档之前，应将确切的设置名称视为尚未验证。

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["on-request", "never"]   # `untrusted` retired in v0.149.0

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"