Codex CLI：权威技术参考

摘要：Codex 是一个多界面编码代理：它会读取您的代码库，在操作系统级沙箱中运行命令、修补文件，并将任务委派给云端。掌握五大系统——config.toml、沙箱/审批模型、AGENTS.md、MCP 和 skills——它就会成为效率倍增器。推荐默认使用 GPT-5.6 Sol（“Power”设置，中等推理）；上一代旗舰 GPT-5.5 在 Codex 中提供 400K 上下文，在 API 中提供 1M 上下文。⁸³¹¹⁷ 刚接触？可直接跳转至安装和快速开始。想跟踪版本发布？最新稳定版是v0.147.0（2026年8月7日）——近期版本脉络请参阅发布亮点，每次更新请查看变更日志。¹¹⁶

Codex 以多界面编码代理的形式运行，而不是一个只会编写代码的聊天机器人。CLI 会读取您的代码库，在沙箱中执行命令、修补文件，通过 MCP 连接外部服务，并将长时间运行的任务委派给云端。它在本地运行，却具备全局视野；同一套智能会根据您的工作方式驱动 5 个不同界面，其中包括新的 Chrome 扩展程序，让您能在浏览器中运行 Codex，而无需由它接管浏览器。⁹⁰

随意使用 Codex 与高效使用 Codex 的差别，归根结底在于五个核心系统。掌握它们，Codex 就会成为效率倍增器：

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

我花了数月时间，在生产代码库、CI/CD 流水线和团队工作流中，将 Codex 与 Claude Code 并行使用。本指南将这些经验提炼为一份完整参考资料——这是我刚开始时最希望拥有的内容。每项功能均包含实际语法、真实配置示例，以及即使是经验丰富的用户也容易踩中的边界情况。

核心要点

• 五种界面，同一个大脑：CLI、桌面应用、IDE 扩展、云任务和全新的 Chrome 扩展都共享同一套 GPT-5.x-Codex 智能能力，因此请根据工作流选择合适的界面。⁹⁰
• 操作系统级沙箱：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 在它们之间切换。
• 上下文管理至关重要：GPT-5.6 系列（Sol、Terra、Luna）采用 272K 上下文窗口；上一代旗舰 GPT-5.5 在 Codex 中提供 400K，在 API 中提供 1M。使用 /compact、聚焦的提示词和 @file 引用，主动管理 token 预算。⁸³¹¹²

如何使用本指南

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

文末的快速参考卡提供了所有主要命令的便于浏览的摘要。

发布亮点：近期有哪些变化

按版本梳理的叙述，适合希望跟踪 Codex 发布节奏的读者。初次接触？请先跳过本节，在完成快速开始后再回来——其中没有任何内容是高效使用所必需的。

GPT-5.6 Sol 是 Codex 推荐的默认选择——默认采用中等推理强度的“Power”设置，可向更智能或更快速调节；GPT-5.5（2026年4月23日：Codex 中为 400K 上下文，API 中为 1M，每 MTok 为 $5/$30，Terminal-Bench 2.0 SOTA 达到 82.7%）是上一代旗舰。⁸³¹¹⁷ 自 CLI v0.147.0 起（稳定版，2026年8月7日），codex exec --full-auto 已被移除（自 v0.128 起弃用）——仍传入该参数的脚本现在会报错；请将其替换为 --sandbox workspace-write，并搭配审批标志或配置文件。v0.147.0 还发布了 --approve-for-me（由自动审查流程裁定审批提示）、可移植的 Agent Plugins（可搜索本地、个人、工作区和远程目录）、选择启用的 MCP 2026-07-28 协议（分页发现、多轮请求、非阻塞式服务器启动），以及用于整理长转录记录的会话分区。¹¹⁶ v0.146.0（稳定版，7月29日）使已配置代理覆盖所有传输层，添加了 Agent Plugins 清单以及 Amazon Bedrock 和 Claude Code 市场、支持线程置顶的会话命名，以及执行器提供的 skills；v0.146.1（8月5日）强化了具备网络安全能力模型的自动审查默认设置。¹¹⁴¹¹⁵ 自 CLI v0.145.0 起（稳定版，2026年7月21日），/import 除 Claude Code 外也支持从 Cursor 迁移——包括设置、MCP 服务器、插件、会话、命令和项目范围的记忆；语音功能以流式实时 V3 会话形式回归，支持音频输入和常见本地格式的音频工具输出；选择启用的多代理 v2 体验已稳定化，支持配置子代理模型、推理级别和并发数；实验性的分页线程历史记录带来高效恢复、搜索、持久化名称、子代理支持和记忆；发布了支持自定义端点和身份验证的实验性 Amazon Bedrock 登录（GPT-5.6 Sol 为默认 Bedrock 模型）；捆绑的 GPT-5.4 模型选择迁移至 GPT-5.6 Terra 和 Luna 变体；v0.144.6（7月18日）将 GPT-5.6 Sol/Terra/Luna 的上下文窗口更正为 272,000 token。¹¹¹¹¹² 自 CLI v0.140.0 起（稳定版，2026年6月15日），/usage 显示每日/每周/累计账户 token 活动，可通过 codex delete / /delete 永久删除会话（带确认保护措施），/import 可选择性地从 Claude Code 迁移设置、项目配置和最近聊天记录，输入 @ 默认会打开文件、插件和 skills 的统一提及菜单；托管式 Amazon Bedrock API-key 身份验证与针对 CLI 和 MCP OAuth 凭据的加密本地存储一同发布；实验性的 /realtime 语音控制已从 TUI 移除（语音后来在 v0.145.0 中以流式实时 V3 形式回归）。¹⁰²¹¹² 自 CLI v0.139.0 起（稳定版，2026年6月9日），代码模式可直接调用独立网页搜索（包括从嵌套的 JavaScript 工具调用中调用）并接收纯文本结果，工具/连接器输入 schema 现在会保留 oneOf/allOf 构造，以更好地兼容大型 schema 和 MCP；codex doctor 增加了编辑器和分页器环境详情（在 JSON 中脱敏敏感值）；插件市场可通过 codex plugin marketplace list --json 展示来源，并提供更快的缓存目录列出功能。¹²² v0.138.0（6月8日）新增 /app，可在 macOS 和 Windows 上将 CLI 会话移交给桌面应用；向模型公开本地图像路径；使推理强度选择更加灵活；并为插件自动化提供结构化 JSON 输出；它还开始在多代理 v2 中加密父代理到子代理的任务文本，因此委派指令不再以明文形式出现在本地会话日志中（参见多代理）。¹²³¹⁰⁸ v0.137.0（6月4日）发布了多代理 v2（每个线程保留运行时、更简洁的后续操作和元数据默认设置、hide_spawn_agent_metadata 默认值为 true）、F13–F24 TUI 按键绑定，以及具备每轮目录解析功能的 v1 skills 扩展。¹²⁴ 自 CLI v0.135.0 起（稳定版，2026年5月28日），codex doctor 报告更丰富的环境、Git、终端、app-server 和线程清单；当 TUI 通过远程连接时，/status 会显示远程连接详情和服务器版本；vim 模式获得了文本对象编辑、改进的单词/行尾行为，以及可配置的中断轮次；/permissions 现已识别具名权限配置文件并显示自定义配置文件；打包的 Codex 构建可在支持的 macOS 系统中发现并使用捆绑的修补版 zsh 帮助程序；Python SDK 为线程和轮次 API 提供了友好的 Sandbox 预设。¹²⁶ v0.134.0（2026年5月26日）引入了跨本地会话历史记录的搜索，支持不区分大小写的内容匹配和结果预览；使 --profile 成为 CLI、TUI 权限和沙箱流程中的主要配置文件选择器（旧版配置文件配置将被拒绝，并提供迁移指引）；通过每服务器环境定位和针对流式 HTTP 服务器的 OAuth 选项改进了 MCP 设置；通过保留本地 $ref/$defs 并压缩超大 schema，提高了连接器工具 schema 的可靠性；允许只读 MCP 工具在声明 readOnlyHint 时并发运行；并添加了更丰富的扩展和 hook 上下文，包括扩展工具的会话历史记录。¹⁰¹ v0.133.0（2026年5月21日）默认启用目标功能，并提供专用存储和进度跟踪；codex remote-control 增加前台就绪/状态以及守护进程式启动/停止；权限配置文件新增列表 API、继承、托管 requirements.toml、运行时刷新，以及更强的 Windows 沙箱集成；插件发现会显示已安装版本、市场根目录和远程集合；扩展可观察子代理启动/停止、工具执行、轮次元数据，以及异步审批/轮次处理。5月21日的 Codex 应用更新新增了前台 Mac 窗口的 Appshots、覆盖应用/IDE/CLI 的正式版 Goal mode、应用内浏览器标注改进，以及面向符合条件 Mac 用户、可选择启用的受锁定 Computer Use。⁹⁹¹⁰⁰ v0.132.0（2026年5月20日）新增 Python SDK 一等身份验证、更简洁的纯文本轮次 API、更丰富的 TurnResult、codex exec resume --output-schema、更快的 TUI 启动、由身份验证支持的远程执行器注册，以及 app-server 轮次中的图像保真度保留。请使用显式沙箱/审批标志或权限配置文件——旧版 --full-auto 已自 v0.147.0 起移除；js_repl 仍处于移除状态。^{86878991969798116}

稳定性说明：标记为 [EXPERIMENTAL] 或 under development 的功能可能会在各版本之间发生变化。自 v0.133.0（2026年5月21日）起，目标功能默认开启，权限配置文件成为一等托管界面，插件发现更加可检查，remote-control 也更容易作为前台或守护进程化 app-server 命令运行。Codex Cloud 和代码模式仍处于实验性或开发中状态；而核心 CLI、沙箱、AGENTS.md、config.toml、Skills、hooks、多代理工具、插件、Browser、Computer Use 和 Appshots 则根据平台和套餐，属于稳定或已有文档说明的面向用户界面。v0.132.0 完善了 Python SDK 身份验证和结构化恢复自动化；v0.131.0 新增 codex doctor、统一的 @ 提及搜索、市场 CLI 命令、感知版本的插件共享、支持运行时启用/禁用的守护进程管理 remote-control、由注册表支持的环境，以及额外的 Windows 沙箱加固。⁹⁶⁹⁷⁹⁸ 旧版 --full-auto 已在 v0.147.0 中移除（自 v0.128 起弃用），js_repl 仍处于移除状态。^8687116

Codex 的工作原理：心智模型

在深入了解各项功能之前，先理解 Codex 的架构如何塑造您与它的每一次交互。该系统由共享的智能层支撑，并通过五个界面运行：

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                       │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐   │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │   │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │   │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘   │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
│  ┌──────────┐                                           │
│  │  Chrome  │  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 (untrusted → 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-5.x 模型系列为一切提供支持。截至2026年8月，gpt-5.6-sol 是推荐的默认选择——即“Power”设置和中等推理强度——同时还有适用于日常任务的 Terra 和快速、经济的 Luna；gpt-5.5 是上一代旗舰模型（在 Codex 中拥有400K上下文，在API中拥有1M上下文），而gpt-5.4将于2026年8月31日从 Codex 中退役。⁸³¹¹⁷它能够读取文件、编写补丁、执行 shell 命令，并针对您的代码库进行推理。当上下文空间耗尽时，Codex 会压缩对话以释放空间。此层会消耗 token。

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

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

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

关键洞见：大多数用户只使用一个界面。高级用户会使用全部五个：Cloud 用于长时间运行的任务，CLI用于确定性的仓库操作，IDE 扩展用于紧密的编码循环，桌面应用用于规划和协调，Chrome 用于已登录的浏览器工作流。

目录

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 桌面应用
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作为后备来源。¹¹⁴ 如果您的网络允许列表为 Codex 的安装和更新放行了GitHub，也请添加 OpenAI 发布主机——后备机制意味着允许列表未命中时会悄然降级，而非明显失败。

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

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

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

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

当某个发布版本导致问题时，固定版本才是正确做法。Codex 采用快速稳定发布线，因此安装精确版本是最快的回滚方式——提交问题、固定版本，然后继续工作即可。请使用codex --version确认回滚生效，因为PATH中被遮蔽的第二个安装会继续悄然提供旧二进制文件（codex doctor会在Environment下准确标记此问题）。

卸载软件包不会删除您的状态。身份验证、配置和会话历史位于~/.codex/。重新安装时请保留该目录，以保留登录状态和历史记录；仅在确实需要完全重置时才删除它——rm -rf ~/.codex也会丢弃config.toml、auth.json以及所有已存储的会话。

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

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

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

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

二进制文件下载

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

系统要求

• macOS：Apple Silicon 或 Intel（通过 Seatbelt 提供完整沙盒支持）
• Linux：x86_64 或 arm64（通过 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 Key：通过CODEX_API_KEY环境变量或codex login --with-api-key设置。部分功能（云线程）可能不可用。

专家提示：可通过config.toml中的cli_auth_credentials_store配置凭据存储。选项包括：file（默认）、keyring（操作系统密钥链）或auto（可用时使用密钥链，否则回退到文件）。

Amazon Bedrock 登录（v0.145.0，实验性）：模型访问通过 Amazon Bedrock 进行的团队，可使用支持自定义端点和身份验证的实验性登录路径；此外，还支持现有的托管API-key 身份验证（v0.140.0+）及 AWS 凭据链（请参阅“自定义模型提供商”）。GPT-5.6 Sol 是默认的 Bedrock 模型。¹¹²

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

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

在 5 分钟内从零开始高效工作。

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

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

2. 进入项目目录：

cd ~/my-project                  # Any git repo works

3. 启动 Codex：

codex

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

4. 提出问题：

> What does this project do? Summarize the architecture.

Codex 会读取关键文件并解释代码库。此类问题不会做出任何更改——只有在您要求修改时，Codex 才会修补文件；沙盒和审批策略决定其何时必须先征求您的同意。

5. 进行修改：

> Add input validation to the login endpoint

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

6. 使用 slash command：

> /plan Refactor the database layer to use connection pooling

Codex 会创建计划，但不会执行。审核计划后，再批准开始执行。

7. 检查您的工作：

> /diff

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

下一步：

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

核心交互界面

Codex提供5种由同一智能能力支持的不同界面。每种界面都针对不同的工作流模式进行了优化。

1. 交互式CLI（终端UI）

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

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

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

关键TUI快捷键：

状态行变更（v0.121.0）：状态行中原有的上下文窗口仪表已替换为上下文百分比指示器，用于显示上下文窗口的占用程度。如果您有解析状态行的脚本或 hooks，请检查此格式变更。⁸²当有新版本可用时，Codex也会显示CLI更新公告。

TUI中可用的 slash commands：

工作流选择器重新设计（v0.129.0）：通过重新设计的选择器，现在更容易访问恢复和分叉功能；新的原始回滚缓冲区模式让您能滚动浏览未渲染的记录文本，以便逐字复制命令或模型输出。适合在排查较长的调试会话，或将输出通过管道传递给其他工具时使用。⁸⁹

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

2. Codex Desktop App（macOS + Windows）

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

桌面应用新增了CLI不具备的能力：

• 多任务处理：可同时在不同项目中运行多个并行 agents
• Git worktree隔离：每个线程都在仓库的隔离副本中工作
• 内联 diff 审查：无需离开应用即可暂存、还原和提交更改
• 集成终端：每个线程都有用于运行命令的终端
• 对话分叉：分支对话以探索备选方案
• 浮动弹出窗口：将对话分离为可移动的独立窗口
• 自动化：安排定期任务（issue分类、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自身的空格键语音转录则是独立的实验性功能。¹¹³

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

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

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

• 默认 Agent mode：读取文件、进行编辑、运行命令
• 内联编辑：在活动文件中提供上下文感知建议
• 共享会话：会话在CLI和IDE extension之间同步
• 相同认证方式：使用ChatGPT账户或API key登录

可从VS Code Marketplace或Cursor/Windsurf extension stores安装。³

4. Codex Cloud[EXPERIMENTAL]

Cloud tasks在OpenAI托管环境中异步运行：

• 一劳永逸：将独立于本地计算机运行的任务加入队列
• 并行执行：同时运行多个cloud tasks
• PR创建：Codex根据已完成的工作创建pull requests
• 本地应用：使用codex apply <TASK_ID>将cloud结果拉取到本地仓库

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

也可通过chatgpt.com/codex访问Cloud tasks。⁴

5. Chrome版Codex[NEW]

Codex以Chrome浏览器扩展形式提供，在CLI、桌面应用、IDE extension和cloud之外增加了第5种界面。该扩展旨在与您的日常浏览并行运行，而不是接管浏览过程：Codex会在后台跨标签页并行工作，您始终可以控制它可操作哪些网站。⁹⁰

• 并行标签页执行：Codex可同时操作多个标签页，而不会锁定前台标签页。
• 按网站控制：您可将Codex可交互的网站加入允许列表；默认没有访问权限。
• 浏览器作为工作台：该扩展最适合页面是事实来源的应用和网站工作——管理控制台、内部仪表板、内容管理UI、工单系统——并非用于替代本地仓库中的CLI。
• 同一个大脑：Chrome版Codex运行与其他界面相同的GPT-5.x-Codex智能能力，因此在CLI中有效的AGENTS.md或skills配置，会将相同约定带入浏览器驱动的工作中。

请从Codex Chrome extension docs安装。⁹⁰

配置系统详解

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 或多账户设置。

Desktop 多文件夹项目（26.715，2026年7月23日）：ChatGPT desktop app 中的本地项目现在可跨越多个相关文件夹，并可将其中一个指定为主文件夹（项目菜单 → Edit project）。config.toml 的自动发现仅针对主文件夹运行；次要文件夹仍可用于搜索、读取和编辑文件，但不会提供配置。位于次要文件夹中的 .codex/config.toml 是 Codex 可以读取的文件，而不是它会加载的配置。这是 desktop app 的项目作用域规则，并非对上述优先级规则的改动——CLI 仍会从当前工作目录向上遍历以解析项目配置。¹¹³

完整配置参考

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.6-sol"                  # Recommended default (the "Power" setting)
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-5.5"               # 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"          # untrusted|on-request|never

[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)

# ─── 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
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             # Chrome 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 networking proxy (experimental)
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

配置档案

适用于不同工作模式的命名配置预设：

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

激活配置档案：

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"

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

使用 --oss 标志运行本地模型：

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

或在配置中设置：

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

内联配置覆盖

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

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

应选择哪种模型？

可用模型（2026年8月）

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

GPT-5.4 和 GPT-5.4 mini 将于2026年8月31日从 Codex 退役。¹¹⁷ 在此之前，GPT-5.4 仍可在各 Codex 端面中选择。⁶⁴ 具体模型列表因账户和分批发布情况而异。请检查本地缓存：~/.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 tokens。¹¹¹ v0.145.0（2026年7月21日）新增了带有自定义端点和身份验证支持的实验性 Bedrock 登录，将 GPT-5.6 Sol 设为默认 Bedrock 模型，并将捆绑的 GPT-5.4 模型选择迁移至对应的 Terra 和 Luna 变体。¹¹²

模型选择流程图

Is this a quick fix or simple question?
├─ Yes → gpt-5.6-luna (fastest, most affordable)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.6-luna (the bundled subagent pick since v0.145.0)
   │     │  └─ No
   │     │     ├─ Everyday coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.6-terra (everyday model, 272K context)
   │     │     │  └─ No → gpt-5.6-sol (flagship — the default "Power" setting)
   └─ Still unsure? → gpt-5.6-sol

推理强度

控制模型在响应前“思考”的程度：

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

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

专家提示：对于相同提示，xhigh 推理的 token 用量可能是 medium 的 3-5 倍。请将其留给确实困难、额外思考能够带来回报的问题。

TUI 快捷推理控制（v0.124.0+）。⁸⁵ 在交互式 TUI 会话中，Alt+, 将推理强度降低一级，Alt+. 将其提高一级——当会话进行中遇到困难问题，需要临时按 medium → high → xhigh 逐级提升时，无需使用 /effort 或 -c。如果您在会话中接受模型升级，推理强度会重置为新模型的默认值，而不会沿用之前的级别。

切换模型

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

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

Codex 的费用是多少？

另请参阅模型选择了解能力差异，以及决策框架以便针对每项任务选择合适的模型。

通过 ChatGPT 套餐访问

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

2026年4月价格更新：Business 年付价格从$25降至$20/席位/月。Business 和 Enterprise 工作区现可使用按量付费的仅 Codex 席位——无固定席位费用，按 token 消耗计费。⁷⁹ 定价页面现在按模型发布限制区间（见上表），不再沿用2026年2月 Desktop App 发布时的促销性2x倍数。¹⁶¹¹⁹

2026年5月用量限制提升（已于2026年5月31日到期）：Plus 套餐中的 Codex 采用25×的5小时限制（相比标准的20×提升），且$100/月档位在同一窗口内翻倍。⁸⁹

积分成本

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

实际使用中，“GPT-5.6 每条消息平均消耗5-40积分”；在支持的模型上，快速模式以更高的速率消耗积分；图像生成消耗包含额度的速度比可比的纯文本轮次快3-5倍。¹¹⁹

Enterprise 和 Edu 套餐会根据合同额度调整积分。请在 TUI 中查看 /status 以了解当前用量。

API 计费

通过 API 使用 Codex 时，OpenAI 会根据所选模型的标准 OpenAI API 定价按 token 计费（加上任何适用的提示词缓存折扣）。请查看官方 API 定价页面了解当前费率。²⁰

成本优化策略

1. 使用配置文件：为日常任务创建使用 gpt-5.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，并查看组织计费仪表板

真实场景成本示例

常见任务具有代表性的 API 成本（2026年中期 gpt-5.3-codex 定价快照，中等推理强度——相对规模可迁移至各模型）：

成本会因推理强度、缓存和对话长度而异。日常任务使用 gpt-5.6-luna，可大幅降低日常任务支出。缓存的输入 token 按折扣价计费。

隐藏的 token 开销

每次工具调用都会在可见提示词之外增加 token：

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

团队成本管理

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

决策框架

何时使用各个界面

何时使用各个 Sandbox 模式

何时使用各个推理级别

Plan 模式与直接执行

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

Steer 模式：Enter 与 Tab

经验法则：Enter =“停止，现在听这个。”Tab =“完成后，也做这件事。”

Desktop App 与 CLI

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

选择哪个配置文件？

将您的任务与预配置的配置文件相匹配：

config.toml 设置：

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

按会话切换配置文件：codex --profile careful

Sandbox 与审批系统如何运作？

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

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

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

特定平台的强制实施机制：

• macOS：通过 sandbox-exec 使用 Apple 的 Seatbelt 框架，在运行时编译特定于模式的配置文件，并由内核强制实施⁶。自 v0.121.0 起，macOS sandbox 配置文件可以将特定 Unix sockets（例如 docker.sock、编辑器 IPC sockets）加入允许列表，且默认不再阻止私有 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 devcontainers 新增了强化的客户配置文件，并使用 Bubblewrap 在容器内实现 sandbox。支持 WSL2；明确拒绝 WSL1（Bubblewrap 与 WSL1 的内核兼容层不兼容）。⁸² - Guardian 审查与 hooks（v0.121.0）：在 Guardian 审查会话期间会禁用 hooks，防止工具调用前后的 hooks 干扰 Guardian 子代理的决策。⁸² 如果依赖 hooks 进行日志记录或验证，请注意，Guardian 审查会跳过它们。如需完整的审计跟踪，请改用 app-server 可观测性。 - 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。⁸⁷

独立审批 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.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。对于一次性的命令例外，建议使用规则，避免大范围扩展配置文件权限。⁸⁷

旧版 --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 = "untrusted"

社区普遍认为这种组合是“最佳平衡点”：既提供最大能力，又要求每条命令都经过审批。⁸

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

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 相辅相成的可复用专业能力包，请参阅技能。

发现层级

会话启动时，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

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

这一项设置会同时控制 Codex 的5个核心系统中的3个——指令、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 中引入了 hooks（AfterAgent），并在 v0.100.0 中加入 AfterToolUse；随后又在 v0.114.0 中加入了包含 SessionStart 和 Stop 事件的实验性 hooks 引擎。⁷⁰ 自 v0.124.0（2026年4月23日）起，hooks 已进入稳定状态。⁸⁵ 现在可直接在 config.toml 和 requirements.toml 中配置 hooks，无须再使用单独的 hook 脚本文件；除 apply_patch 和长时间运行的 Bash 会话外，它们还可观察 MCP 工具。该系统现已覆盖会话生命周期和工具级自动化，补齐了与 Claude Code hook 模型之间的差距。

可用的 Hook 事件

Hook 配置

Hooks 在 .codex/config.toml 中配置：

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

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

复现 Claude Code Hook 模式

如果正在从 Claude Code 迁移，可以通过以下方式实现类似的自动化：

专家提示：自 v0.124.0（2026年4月23日）起，hooks 引擎已进入稳定状态。新 hook 事件仍会随版本发布——请查看 Codex 更新日志。

TUI 内置 hook 浏览器（v0.129.0）：在 TUI 中运行 /hooks，可查看有哪些 hooks、哪些当前处于活动状态，还能在不编辑 config.toml 的情况下切换单个 hook。此功能适合用于排查插件捆绑的 hook 行为异常，或在专注编辑期间临时禁用 AfterToolUse linter。⁸⁹

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

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

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

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工具即可暴露，因此缓慢的服务器不再阻塞会话启动。该支持为选择性启用，因此使用旧修订版的服务器仍可照常工作。¹¹⁶

配置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+）同时接受.mcp.json中的标准mcpServers架构和顶层服务器映射，因此按照任一约定编写的插件都能顺利加载。⁸⁴

将Codex作为MCP服务器运行

Codex可以将自身作为MCP服务器公开，用于多智能体编排：¹²

codex mcp-server                        # Start as MCP server (stdio transport)

该服务器公开两个工具： 1. codex()：使用提示词、沙盒、模型和审批参数启动新会话 2. codex-reply()：使用threadId和提示词继续现有会话

与Agents SDK（Python）配合使用：

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

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    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中身份不匹配的服务器都会在启动时被阻止。完整的策略配置请参阅企业部署。

代码模式[EXPERIMENTAL]

代码模式（v0.114.0）通过将智能体范围限制为以代码为中心的操作，提供更隔离的编码工作流。⁷⁰启用后，智能体会专注于读取、编写和测试代码，而不会进行更广泛的系统交互。

从v0.139.0起，代码模式可直接调用独立网页搜索——包括从嵌套的JavaScript工具调用中调用——并接收纯文本结果，因此代码模式流程无需离开沙盒化的编码上下文即可获取实时信息。¹²²v0.146.0将独立网页搜索扩展至兼容的自定义模型提供商，因此该能力不再仅限于由OpenAI托管的模型。¹¹⁴

v0.146.0允许app-server通过WebSocket连接到远程代码模式主机，因此代码模式运行时不再必须与客户端位于同一台机器上。¹¹⁴

此功能为实验性功能。请查看发行说明以获取更新。

JavaScript REPL运行时[REMOVED]

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

插件

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

• 插件详情中显示捆绑 hooks。 /plugins 详情视图现在会列出插件捆绑的每个生命周期 hook（SessionStart、UserPromptSubmit、Stop 等）。安装插件前，您可以准确了解它将针对当前会话注册哪些 hooks——不再因仅信任插件工具而遭遇意料之外的 hook 副作用。
• shareContext 中的插件共享元数据。 从工作区共享插件时，共享链接负载现在会公开链接元数据（创建者、范围、新鲜度），以便接收会话显示来源并决定是否接受。
• 共享设置中的可发现性控制。 共享设置提供可发现性开关，团队可将插件发布到特定工作区或接收者列表，而无需让其在整个组织内普遍可列出。

v0.143.0（2026年7月8日）默认启用远程插件。 远程插件现在无需选择性启用标志即可使用，/plugins 目录新增更丰富的行信息（npm marketplace 来源与 git 和本地来源并列），每个条目同时显示远程版本和本地已安装版本，因此版本差异一目了然。¹⁰⁶ 对于正在统一采用共享插件集的团队，默认远程插件省去了过去阻碍推广的逐台机器启用步骤。

插件来源

自 v0.147.0 起，插件搜索可通过一次查询覆盖本地、个人、工作区和远程目录——您搜索的是能力，而非恰好存放该能力的目录。结合可移植的 Agent Plugin 软件包，在一个环境中构建的插件可顺利安装到另一个环境，而不会绑定于其创作所在的机器或工作区。¹¹⁶

插件发现

Codex 会在会话开始时向模型告知已启用的插件（v0.111.0），从而改善对已安装 MCPs、应用和 skills 的发现。⁶⁵ 模型可以根据任务上下文，在会话期间建议相关插件。v0.117.0 中，产品范围内的插件会在启动时同步，确保无需人工干预即可获得最新插件目录。⁷⁵ 自 v0.142.0 起，/plugins 菜单会将远程插件整理到 OpenAI Curated、Workspace 和 Shared with me 分区中，符合条件的对话轮次还可内联推荐并安装相关插件。¹⁰⁴

@plugin 提及（v0.112.0+）

可在聊天中通过 @plugin-name 直接引用任意已安装插件。⁶⁸ 提及某个插件时，其上下文（功能、工具、配置）会自动纳入模型的上下文窗口——无需描述该插件的用途。

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

这适用于任何已安装插件，包括自定义 skills、MCP servers 和应用连接器。

插件 Marketplace（v0.113.0+）

插件 marketplace 现已提供更丰富的发现能力，包括元数据、类别和评分。⁶⁹ 安装时的身份验证检查会在安装前确认需要 API keys 或 OAuth 的插件是否具备有效凭据。卸载端点可干净地移除插件及其关联配置。

添加第三方 Marketplace（v0.121.0+）

当前 OpenAI Codex 文档将 marketplace 来源管理置于 codex plugin marketplace 下。这使第三方插件分发超越 OpenAI 的第一方 marketplace，并支持 GitHub repo 简写、HTTP(S) Git URL、SSH URL 和本地 marketplace 根目录；使用 --ref 固定 Git ref，且仅对以 Git 为后端的 marketplace repo 重复使用 --sparse PATH。⁹³

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

添加后，marketplace 中的插件会与默认插件一起显示在 /plugins 浏览器中。应用服务器调用方（IDE/桌面集成）也有对应端点，可通过编程方式注册 marketplace。⁸²

安全注意事项：第三方 marketplace 会以您的 Codex 权限运行任意插件代码。添加前请审查来源，并优先在首次运行时采用沙盒执行。

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

“Agent Plugins”不只是 Codex 的功能名称——它还是一项开放、供应商中立的打包标准，于2026年8月6日以 Agent Plugins 1.0.0 发布；其官方网站将其概括为“用于扩展 AI agents 的可复用组件的可移植软件包格式”。¹¹⁸ 一个插件是一个目录，包含必需的 plugin.json manifest（这是一个封闭 schema，恰好允许十个顶级字段——$schema、name、version、description、author、homepage、repository、license、keywords、extensions——其中规定“Clients MUST report and ignore each unknown field”），可选的 skills/ 文件夹（每个包含 SKILL.md 的直接子目录即为一个 skill），可选的 mcp.json（声明 stdio、Streamable HTTP 或旧版 HTTP+SSE servers），以及可选的反向域名客户端命名空间目录，其他客户端“MUST ignore”。其规范性范围是打包：该规范“defines the canonical Agent Plugins Specification v1.0.0 for packaging reusable components that extend AI agents into distributable 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。有一项明显缺席：Anthropic，它创建了底层 Agent Skills 格式和 MCP 本身，却不在维护者之列——Claude Code 保留自己的插件格式，Codex 则通过 Claude Code marketplace 来源（v0.146.0）和 /import 从自身一侧弥合这一差距。¹¹⁸

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

发布说明宣布了 Codex 相关功能，但未公布其配置键或 CLI 语法。此条目记录的是该能力已上线以及该标准的规定，而非如何通过 Codex 操作它——在 OpenAI 文档覆盖之前，应将 manifest 编写工作流以及任何 codex plugin publish 调用视为未经验证。

管理插件

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

在 TUI 中，使用 /plugins（v0.117.0+）可在不离开当前会话的情况下，以交互方式浏览、安装和移除单个插件。⁷⁵

专家提示：插件整合了过去需要分别进行的 MCP 配置、skill 安装和应用连接器设置。单个插件可同时捆绑这三者——从而加快团队入职，并提高配置的可移植性。

Plan Mode 与协作

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

进入 Plan Mode

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

在 Plan Mode 中，Codex 会： - 读取文件并分析代码库 - 提出实施计划 - 在您批准前不会进行更改 - 在专用 TUI 视图中实时输出计划

Steer Mode

自 v0.98.0 起，Steer Mode 默认启用。它允许您在 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 中回归： v0.140.0 从 TUI 中移除了实验性的 /realtime 语音控件及其音频依赖项（空格键语音转写不受影响）。¹⁰² v0.145.0 以全新形式恢复了语音功能：支持常见本地音频格式的音频输入和音频工具输出，并支持流式实时 V3 对话。¹¹²

其他改进： - 长链接即使跨 TUI 行换行，仍可点击（v0.105.0）⁶¹ - 改进了本地文件链接的呈现格式（v0.106.0）⁶⁰ - TUI markdown 通过 OSC 8 元数据保持网页链接可点击；空间不足的表格会改用易读的键／值记录展示，同时保留链接目标（v0.136.0）¹²⁵ - 修复了 sub-agents 的 Ctrl+C 处理，可正确终止子进程（v0.106.0）⁶⁰

Memory System

Codex 提供持久化 Memory System（v0.100.0+），可跨会话存储事实、偏好和项目上下文。²⁴

Memory 命令

Memory 存储在 ~/.codex/memory/ 下的 markdown 文件中。Codex 会在会话开始时加载这些文件，并在今后的所有会话中据此调整行为。

适合存储的内容

Memory 最适合保存长期有效的偏好和项目事实：

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

流水线中的 Memory

运行 codex exec 时，Memory 会自动加载。这意味着 CI/CD 流水线和脚本可以获得与交互式会话相同的上下文，无需在每次调用时重复指令。

Memory 优化（v0.101.0–v0.107.0）

• 密钥清理：Memory 写入磁盘前会自动扫描其中的密钥
• CWD 感知：Memory 文件现在包含工作目录上下文，以便按项目准确回忆
• 排除开发者消息：阶段 1 的 Memory 输入会排除开发者／系统消息，将重点放在用户交互上，从而提高 Memory 质量
• 基于差异的遗忘（v0.106.0）：Memory 现在通过基于差异的遗忘机制移除过时事实，使 Memory 存储长期保持精简且相关⁶⁰
• 基于使用情况的选择（v0.106.0）：Memory 检索现在会考虑使用情况，优先选取频繁访问和近期相关的 Memory⁶⁰
• 可配置的 Memory（v0.107.0）：Memory 现已支持全面配置。使用 codex debug clear-memories 可重置所有已存储的 Memory、恢复初始状态；在互不相关的项目间切换上下文或 Memory 状态逐渐偏离时，这一功能尤其有用⁶²
• 阶段 2 模型升级（v0.121.0）：阶段 2 的 Memory 整合模型现已升级为 gpt-5.4（此前使用默认模型）。阶段 2 流水线在会话之间运行，将阶段 1 的记录提炼为持久事实；此次模型升级在 token 成本不变的情况下提升了回忆质量。⁸²
• TUI Memory 菜单（v0.121.0）：新增会话内 UI，可设置 Memory 模式、逐条删除 Memory 以及执行重置。Memory 重置现在会保留历史运行记录而非使其失效，因此重置操作只会清除后续可回忆的内容，不会破坏会话回放。⁸²

Memory 与 AGENTS.md

提示：使用 /m_update 保存需要无限期保留的事实。对于仅在当前会话中有效的上下文，直接在对话中告知 Codex 即可。对于团队共享的上下文，请使用 AGENTS.md。

会话管理

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

v0.146.0 让线程可以按名称寻址。 /new 和 /clear 现可接受会话名称；重要线程可以置顶；侧边对话保持打开，无需关闭一个对话才能进入另一个。¹¹⁴ 实际效果是，长期项目不再是一串只能通过日期辨认的时间戳。v0.147.0 新增对话分区：对话会组织到持久化、可手动排序的分区中；长转录记录将渐进式浏览，而非一次性全部加载。¹¹⁶

恢复

从上次中断处继续：

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 斜杠命令会打开同一个支持搜索的交互式选择器。

分页线程历史记录（v0.145.0）[EXPERIMENTAL]： 实验性的分页线程历史记录为会话管理带来高效恢复、跨历史记录搜索、持久化线程名称、子代理支持和记忆功能——历史记录按页加载，而非一次性全部加载；对于拥有数百个会话的长期工作目录，这一点尤为重要。该功能仍处于实验阶段：不同版本之间的界面可能会发生变化。¹¹²

分叉

分支出一段对话来探索替代方案，同时保留当前进展：

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

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

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

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

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

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

多代理 v2 已稳定（v0.145.0，可选启用）： 在 v0.137.0 首次推出、并于 v0.138.0 获得加密委派能力的多代理 v2 体验，如今已稳定为一项可选启用功能。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 --ask-for-approval on-request "fix the CI failure"
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接口配合使用，可以高效浏览长期运行的线程。这对远程控制部署尤为重要，因为编排器与rollout文件可能位于不同计算机上。⁸² v0.143.0扩大了控制器的检查范围：app-server客户端现在可以枚举可用环境、列出线程的后代线程，并从特定轮次分叉历史记录。这些基础能力使UI能够从较早的节点创建运行分支，而无需向前重放。¹⁰⁶

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

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

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

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

Codex Cloud与后台任务[EXPERIMENTAL]

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

Codex Cloud在OpenAI管理的环境中异步运行任务。⁴ 如需将Codex集成到CI管道中，另请参阅GitHub Action与CI/CD。

工作原理

1. 提交任务（通过chatgpt.com/codex、Slack集成或CLI）
2. Codex将您的仓库克隆到隔离的云沙箱中
3. 代理独立工作：读取代码、运行测试并进行更改
4. 完成后，Codex创建PR或提供diff供您审查
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会回复任务链接，并在任务完成后发布结果。

云端CLI

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

Codex Desktop App

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

安装

codex app                      # Auto-downloads and installs on first run

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

主要功能

Appshots、浏览器评论和 Computer Use

5月21日的应用更新让 Desktop App 成为更强大的上下文载体，而不再只是线程管理器。当 Codex 必须先了解另一个 Mac 应用的状态才能执行操作时，请使用 Appshots：Codex 会捕获最前方的窗口、应用提供的可见及屏幕外文本，并将附件存储在本地会话历史记录中。⁹⁹

对于 Web 和前端工作，如果页面无需身份验证，请优先使用应用内浏览器：它为您和 Codex 提供共享的渲染预览，支持点击、截屏、下载资源等浏览器操作以及通过 JavaScript 进行只读检查，还允许您在页面区域添加评论，供 Codex 在下一轮处理中解决。⁹⁹ 对于需要登录的网站，请继续使用 Chrome 扩展。

仅当结构化集成或浏览器预览无法验证任务时，才使用 Computer Use。它可以检查并操作获准的 Mac 应用，但对于文件编辑和 shell 命令，仍须遵循 Codex 的审批及沙箱规则。锁定状态下的使用范围依然严格受限：Mac 锁定后，在处于活动状态且受信任的 Computer Use 轮次中，Codex 可以临时访问获准的应用，同时配有重新锁定保护机制和本地输入检测。⁹⁹

线程模式

每个线程均以以下3种模式之一运行，您需要在创建线程时进行选择：

Worktree 隔离机制：

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

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

自动化

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

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

设置自动化任务： 1. 在 Desktop App 中打开一个项目 2. 单击侧边栏中的自动化选项卡 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的代理能力嵌入自定义应用程序中。¹⁹

安装

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. 保持提示聚焦：带有确切文件范围的提示比开放式探索消耗更少上下文

Token效率

速度优化

1. gpt-5.3-codex-spark：用于交互式结对的低延迟变体
2. --profile fast：预配置低推理的gpt-5.6-luna
3. 并行工具执行：Codex会并发运行独立的读取/检查，因此请组织提示以支持这一点
4. 以结果为导向的循环：要求“实现、测试、修复，绿灯后停止”，而非提供逐步指令

如何调试问题？

常见问题与解决方案

错误消息参考

codex doctor 有什么作用？

在提交 bug 或调试损坏的安装之前，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、终端、app-server 和线程清单报告；在 v0.139.0 中加入了编辑器和分页器详情（JSON 中的敏感值会被脱敏）。^96126122

请优先使用，而非最后使用。 大多数“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
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

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

干净重装

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

会保留 ~/.codex/（身份验证、配置、会话）。如需固定到特定版本、在错误发布后降级，或彻底清除状态，请参阅 更新、降级或卸载 Codex CLI。

调试模式

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 web 使用该功能。

工作原理：Codex Security 会分析代码仓库以构建项目专属的威胁模型，识别按真实世界影响分类的漏洞，并在沙盒环境中对发现结果进行压力测试以验证其有效性。该 agent 会呈现置信度更高且附带修复方案的发现结果，从而减少无关紧要 bug 带来的噪声。

性能：在研究预览期间，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 = ["untrusted", "on-request", "never"]

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

与用于设置偏好的用户级 config.toml 不同，requirements.toml 是硬性约束层，用于限制用户可选择的值，且用户无法覆盖。管理员要求规则只能提示或禁止（绝不会静默允许）。

macOS MDM 配置

通过 MDM 使用 com.openai.codex 偏好设置域进行分发。²¹ Codex 支持标准 macOS MDM 载荷（Jamf Pro、Fleet、Kandji 等）。将 TOML 编码为不换行的 base64：

优先级（从高到低）：

1. macOS 受管偏好设置（MDM）
2. 云端获取的要求（ChatGPT Business / Enterprise）
3. /etc/codex/requirements.toml（本地文件系统）

云端要求仅填充尚未设置的要求字段，因此优先级更高的受管层始终优先。云端要求采用尽力而为的方式；如果获取失败或超时，Codex 会在不使用云端层的情况下继续运行。

OpenTelemetry 集成

Codex 支持将标准 OTel 环境变量中的 OpenTelemetry 跟踪上下文传播至 OpenAI API 调用。请在启动 Codex 前设置标准环境变量：

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• 支持标准 OTEL_* 环境变量（端点、服务名称、资源属性）
• 跟踪上下文会通过 Codex 传播至 API 调用，实现端到端可观测性
• 使用资源属性按团队、环境或项目标记跟踪
• 启用提示词/工具日志记录时，请留意隐私要求——跟踪中可能包含代码片段
• 可配置的 OpenTelemetry 跟踪元数据（v0.130.0+）。 除标准 OTEL_RESOURCE_ATTRIBUTES 封装外，codex-otel crate 现提供可配置的跟踪元数据，使管理员无需在每次调用时从头重建 OTEL_RESOURCE_ATTRIBUTES，即可使用组织特定维度（成本中心、项目 ID、工单引用）标记跟踪。将其与同一版本发布的更丰富审查/反馈分析功能结合使用，可在 CLI、app-server 和远程控制会话之间统一进行调试与分诊。⁹¹

企业访问

• ChatGPT Business / Enterprise / Edu：由组织管理员控制访问权限，并自动应用云端获取的要求。支持通过身份提供商（Okta、Entra ID 等）使用 SAML/OIDC 实现 SSO
• API：标准 API 身份验证、计费以及组织/项目控制。OpenAI 发布 SOC 2 Type II 和 SOC 3 报告；Enterprise 层级提供 HIPAA BAA
• Codex SDK：嵌入内部工具和工作流
• 大规模策略强制执行：使用通过 MDM 分发的 requirements_toml_base64，或文件系统级 /etc/codex/requirements.toml

数据处理与合规性： - 根据 OpenAI 的 Business/Enterprise/API 条款，API 输入/输出不会用于训练 - 就数据驻留而言，OpenAI API 流量默认通过位于美国的基础设施路由；如有欧盟数据驻留要求，请咨询 OpenAI 的 Enterprise 销售团队 - 会话记录存储在本地；只有 API 调用会离开设备 - ChatGPT Enterprise 支持包括 SOC 2、GDPR 和 CCPA 在内的合规框架

推广策略

建议组织采用分阶段推广：

1. 试点（第 1-2 周）：向 3-5 名资深工程师部署，并通过 requirements.toml 强制使用 untrusted sandbox 模式和 cached 网页搜索。收集有关 AGENTS.md 模式和 MCP server 需求的反馈。
2. 团队扩展（第 3-4 周）：向整个团队推广。通过 MDM 或仓库分发团队标准 config.toml。为受信任仓库启用 workspace-write sandbox。
3. CI 集成（第 5-6 周）：将 codex-action 添加到 CI/CD 流水线，用于自动化 PR 审查和测试生成。使用 --ephemeral 保持成本可预测。
4. 全组织推广（第 2 个月起）：通过 MDM 部署，并使用 requirements.toml 强制使用获批准的 MCP server、sandbox 策略和模型允许列表。

审计模式

跟踪 Codex 使用情况并强制执行合规要求：

• OpenTelemetry 跟踪：按团队监控 API 调用量、token 使用量和延迟
• 会话持久化：审计 ~/.codex/sessions/ 以进行合规审查（在敏感场景中使用 --ephemeral 禁用）
• MCP 身份强制执行：requirements.toml 会记录被阻止的 server 尝试——审查是否存在未经授权的工具使用
• Git 审计轨迹：所有 Codex 文件更改均通过标准 git 完成——通过分支历史和 PR 差异进行审查

最佳实践与反模式

提示模式

1. 约束驱动的提示：先明确边界。“不要更改 API 合约。仅重构内部实现。”
2. 结构化复现步骤：编号步骤比模糊描述更容易产出高质量的 bug 修复
3. 验证请求：以“运行 lint 加上最小的相关测试套件。报告命令和结果。”结尾
4. 文件引用：使用 @filename 将特定文件附加到上下文
5. 结果驱动的循环：“实现、运行测试、修复失败项，只有全部测试通过才停止。”Codex 会持续迭代直至完成

测试理念

社区逐渐形成了以测试驱动 AI 协作的共识：²²

• 提前定义测试，将其作为完成信号
• 让 Codex 持续迭代，直到测试通过（红→绿→重构）
• 采用 Tiger Style 编程模式
• 请求补丁时提供准确的文件文本。Codex 使用严格匹配，而非基于模糊 AST 的补丁方式

上下文管理最佳实践

• 提供高质量的本地文档，而非依赖网络搜索
• 维护包含目录和进度文件的结构化 Markdown（“渐进式披露”）
• 统一受跟踪文件的行尾格式（LF 与 CRLF），避免补丁失败
• 保持 AGENTS.md 简洁，因为过长的指令会被挤出上下文

Git 工作流

• 在不熟悉的仓库中运行 Codex 前，始终先创建新分支
• 使用基于补丁的工作流（git diff / git apply），而不是直接编辑
• 像审查代码审查 PR 一样审查 Codex 的建议
• 提交前使用 /diff 验证变更

社区 skills 和提示

feiskyer/codex-settings 仓库提供由社区维护的配置：²³

可复用提示（位于 ~/.codex/prompts/）： - deep-reflector：从开发会话中提炼经验 - github-issue-fixer [issue-number]：系统化分析 bug 并创建 PR - github-pr-reviewer [pr-number]：代码审查工作流 - ui-engineer [requirements]：生产级前端开发

社区 skills： - claude-skill：通过权限模式将任务移交给 Claude Code - autonomous-skill：通过进度跟踪实现多会话任务自动化 - deep-research：并行编排子任务 - kiro-skill：需求→设计→任务→执行流水线

反模式

这些常见错误会浪费 token、降低结果质量，或造成令人沮丧的工作流。

成本反模式

上下文反模式

工作流反模式

提示反模式

工作流配方

适用于常见开发场景的端到端模式。

配方 1：新项目设置

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

审查生成的 AGENTS.md，编辑以符合您的约定，然后：

> Run the health endpoint test and confirm it passes

配方 2：日常开发流程

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

使用 /diff 审查，然后提交。

配方 3：使用计划模式进行复杂重构

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

审查计划。批准或引导：

[Tab] Also add a migration script using Alembic

Codex 执行后，进行验证：

> Run the full test suite and report results
> /diff

配方 4：使用 codex exec 进行 PR 审查

codex exec --model gpt-5.6-luna \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

配方 5：使用 Cloud Tasks 调试 [EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

稍后检查进度：

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

完成后在本地应用修复：

codex apply <TASK_ID>

迁移指南

从 Claude Code

需要了解的关键差异：

• 沙盒处于 OS 层级：Codex 使用 Seatbelt/Landlock，而非容器。限制在内核层面运行，位于应用层之下。
• Hooks 正在扩展：Codex 现支持 5 个 hook 事件：SessionStart、Stop 和 UserPromptSubmit（v0.114.0–v0.116.0，实验性功能），以及 AfterAgent（v0.99.0）和 AfterToolUse（v0.100.0）。该系统涵盖会话生命周期、提示拦截和工具级自动化，但 Claude Code 的 12+ 个生命周期事件仍提供更广泛的覆盖范围。对于尚未覆盖的自动化模式，请使用 AGENTS.md 指令或 skills。
• 子代理 v2（v0.117.0）：子代理现在使用基于路径的地址（例如 /root/agent_a），并提供结构化的代理间消息传递和代理列表功能。⁷⁵ 这扩展了现有机制（最多 6 个并发，已在 v0.91.0 从 12 个减少）。多代理角色仍可通过配置自定义（v0.104.0+）。⁴⁷ v0.105.0 新增了 spawn_agents_on_csv，可跨行扇出并跟踪进度和 ETA。⁶¹ Codex 仍缺少 Claude Code 用于用户定向委派的显式 Task 工具 UX——请使用云任务或 SDK 编排实现委派模式。
• AGENTS.md 跨工具通用：您的 AGENTS.md 可在 Cursor、Copilot、Amp、Jules、Gemini CLI 以及 60,000+ 个开源项目中使用。CLAUDE.md 仅适用于 Claude。
• Profiles 取代手动切换：无需每次运行时更改标志，可在 config.toml 中定义 profiles。

从 GitHub Copilot

您将获得： - OS 级沙盒（Seatbelt/Landlock——内核强制执行，而非基于容器） - 通过 codex apply 委派云任务 - 用于切换工作流的配置 profiles - 具备 worktree 隔离的桌面应用

从 Cursor

快速参考卡

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                 ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "task" Sandboxed auto   ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers               ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Aug 2026)                                            ║
║  gpt-5.6-sol           Recommended default ("Power", 272K)    ║
║  gpt-5.6-terra         Everyday model (272K)                  ║
║  gpt-5.6-luna          Fast + affordable (272K)               ║
║  gpt-5.5               Previous-gen flagship (400K in Codex)  ║
║  gpt-5.4 / -mini       Retire from Codex Aug 31, 2026         ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

更新日志