项目概述

Codex 是 OpenAI 提供的本地编码代理（coding agent），既可以在终端以 CLI 形式运行，也提供桌面应用与云端 Web 体验。其核心业务逻辑由 codex-rs/core 实现，被多种 Rust 写的 Codex UI 共用，文档位置见 codex-rs/README.md。

顶层仓库（README.md）把 Codex 拆分成几条独立交付路径：

• Codex CLI：终端命令行入口，跨 Mac / Linux / Windows 安装。
• Codex 桌面应用：通过 codex app 启动，或在 chatgpt.com/codex 获取。
• Codex Web：云端代理，定位与本地 CLI 不同。
• IDE 集成：VS Code、Cursor、Windsurf 等编辑器插件入口位于 developers.openai.com/codex/ide。

仓库根的 package.json 是一个 monorepo 维护工具包，承载 prettier 格式化与钩子（hooks）schema 生成等脚本，并不直接发布运行时（package.json）。

安装方式

脚本一键安装

官方 README 提供了两条原生安装脚本：

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

两条脚本会拉取并放置 codex 可执行文件，简化了跨平台的初始化步骤（资料来源：README.md）。

包管理器安装

除了脚本，也可以通过 npm 安装 Node.js 版的 CLI：

npm install -g @openai/codex

对应包元数据见 codex-cli/package.json，它声明 "bin": { "codex": "bin/codex.js" }，仅打包入口脚本与最小必要文件（codex-cli/package.json）。

从源码构建

仓库内的 scripts/codex_package/README.md 描述了基于 cargo build 的打包器：默认 cargo profile 为 dev-small，以便本地快速迭代；发布作业应显式传入 --cargo-profile release 与 --target，并通过 --entrypoint-bin、--bwrap-bin、--codex-command-runner-bin、--codex-windows-sandbox-setup-bin 等参数复用已经签名好的产物，避免重复构建。该 builder 通过 --variant 选择入口变体（scripts/codex_package/README.md）。

包变体与运行时

scripts/build_codex_package.py 在 --variant 中显式支持 codex 与 codex-app-server 两种入口：

codex-rs/protocol 定义了内部（CLI ↔ TUI）与外部（codex app-server）通信所使用的类型，强调“最小依赖 + 避免业务逻辑外泄”（codex-rs/protocol/README.md）。codex-rs/tools 则承载模型可见工具的 host 端模型、发现、适配与执行契约，作为从 core/src/tools 拆出的共享支持 crate（codex-rs/tools/README.md）。

TypeScript SDK

sdk/typescript 包 @openai/codex-sdk 通过 spawn @openai/codex CLI 与之交换 JSONL 事件，对 Node.js 18+ 提供 runStreamed() 异步事件流与结构化输出。包元数据见 sdk/typescript/package.json（sdk/typescript/README.md）。

Python SDK

sdk/python 包 openai-codex（Beta）暴露 Codex() 上下文管理器，复用现有 Codex 鉴权并支持浏览器登录、设备码登录与 API Key 登录。sdk/python-runtime 描述了发布期间按平台暂存的运行时 wheel，确保 SDK 能锁定精确的 CLI 版本而不需要在仓库内提交二进制（sdk/python/README.md；sdk/python-runtime/README.md）。

平台支持与沙箱

flowchart LR
  A[Codex CLI / App] --> B[codex-core 业务逻辑]
  B --> C{平台判断}
  C -->|macOS| D[sandbox-exec + Seatbelt]
  C -->|Linux| E[bubblewrap / Landlock]
  C -->|Windows| F[codex-command-runner / windows-sandbox-setup]
  D --> G[受保护的文件系统/网络访问]
  E --> G
  F --> G

• macOS：依赖 /usr/bin/sandbox-exec，通过 Seatbelt profile 实施 SandboxPolicy，并保留 .git 与 .codex 的只读权限（codex-rs/core/README.md）。
• Linux：依赖 codex-arg0 机制，当 arg0 为 codex-linux-sandbox 时调用 codex-linux-sandbox 等价行为。默认文件系统沙箱为 bubblewrap，仅当 split 策略与旧模型语义一致时才走 Landlock 兼容路径；缺失 bwrap 时回落到随包分发的 codex-resources/bwrap，并在启动时告警。WSL2 走标准 Linux bubblewrap，WSL1 因无法创建 user namespace 而拒绝沙箱化 shell 命令（codex-rs/linux-sandbox/README.md）。
• Windows：包内携带 codex-command-runner.exe 与 codex-windows-sandbox-setup.exe 作为资源二进制（scripts/codex_package/README.md）。

配置层与扩展点

codex-rs/config/src/loader 是配置层加载的规范位置，公开 load_config_layers_state、ConfigLayerStack、merge_toml_values 等接口，用于合并用户配置、CLI/会话覆盖、云托管配置与 MDM 配置，并在每键上记录来源与版本指纹（codex-rs/config/src/loader/README.md）。codex-rs/codex-api 在通用传输之上封装 Responses / Compact / Memory summarize 端点，是 codex-core 之下唯一的 wire-level 层（codex-rs/codex-api/README.md）。

社区关注点

仓库尚未原生覆盖但社区呼声较高的方向包括：桌面应用的远程开发（#10450）、Linux 桌面端可用性（#11023）、事件钩子系统（#2109）、从手机远程控制本地 CLI（#9224）以及 Plan Mode（#2101）。在选择 CLI vs. App Server vs. SDK 时，若需要扩展宿主行为或自动化工作流，可优先评估 SDK 与配置层加载接口。

See Also

• Protocol Types
• Sandbox & Platform Support
• Configuration Layers
• Codex API Wire Layer
• TypeScript SDK
• Python SDK

概述

OpenAI Codex 是一个多语言、多形态的代码代理项目：既提供本地 CLI 体验，也提供桌面应用、IDE 集成以及云端 Codex Web。仓库顶层以 Rust 为主实现核心业务逻辑（codex-rs 工作区），同时通过 npm 包 @openai/codex 分发 Node.js 形态的 CLI，并以独立的 TypeScript / Python SDK 暴露编程接口供外部应用嵌入（README.md、codex-rs/README.md）。这种"一个核心，多种外包装"的形态决定了 Cargo 工作区必须以严格的依赖分层隔离协议、传输、业务核心与沙箱执行等关注点。

Cargo 工作区结构

工作区与入口二进制

codex-rs 是一个 Cargo 工作区，其 [workspace.package].version 字段被包构建器读取并写入 codex-package.json（scripts/codex_package/README.md）。工作区暴露多种二进制入口，并通过包构建器的 --variant 标志切换，目前支持 codex 与 codex-app-server 两种入口，分别对应交互式 CLI 与面向外部应用的服务器形态。

核心 crate 及其边界

工作区内的 crate 按依赖方向自下而上组织：

• 协议层 codex-protocol：定义 CLI 内核与 TUI 之间、以及 CLI 内核与 codex app-server 之间的"内部类型"和"外部类型"。该 crate 要求最小依赖并避免承载业务逻辑，必要时通过 Ext 风格 trait 在其他 crate 中扩展能力（codex-rs/protocol/README.md）。

• 传输层 codex-api：基于通用传输 codex-client 构建的 Responses / Compact 客户端，拥有 provider 配置、鉴权头注入、重试与流式空闲设置，并把 SSE 流解析为 ResponseEvent/ResponseStream。它是 codex-core 的线缆层，高层只负责鉴权刷新与业务逻辑（codex-rs/codex-api/README.md）。

• 业务核心 codex-core：承载 Codex 真正的业务逻辑，被各 Rust UI 复用。它对运行环境做出强假设——macOS 需要 /usr/bin/sandbox-exec，Linux 通过 arg0 为 codex-linux-sandbox 的方式触发 codex sandbox（codex-rs/core/README.md）。

• 共享工具 codex-tools：承担 host 侧的工具模型与适配（聚合的 ToolSpec/ConfiguredToolSpec、MCP/动态工具适配、code-mode 兼容垫片等），正处于从 core/src/tools 中逐步剥离的迁移过程中，明确不提前迁入 Session / TurnContext / 审批流（codex-rs/tools/README.md）。

• 沙箱与执行：codex-linux-sandbox 负责 Linux 上 bwrap 与 Landlock 沙箱回退路径，并在 bwrap 缺失或无法创建 user namespace 时回退到包内 codex-resources/bwrap（codex-rs/linux-sandbox/README.md）；codex-exec-server 是基于 codex-utils-pty 的 JSON-RPC 子进程控制服务器，对外复用 codex-app-server-protocol 信封（codex-rs/exec-server/README.md）。

• 配置加载 codex-config：在 loader 子模块中统一管理用户配置、CLI 覆盖、云管理配置、managed 配置与 MDM 偏好，并产出 per-key 来源元数据与 per-layer 版本指纹，供乐观并发 / 冲突检测使用（codex-rs/config/src/loader/README.md）。

平台分支与依赖矩阵

业务核心对宿主机工具有强假设，形成明确的支持矩阵。macOS 通过 Seatbelt（sandbox-exec）保护 .git 与 .codex 只读并允许配置的可写根；Linux 优先 PATH 上位于工作目录之外的 bwrap，缺失或过旧时回退到包内 codex-resources/bwrap（codex-rs/linux-sandbox/README.md）。SandboxPolicy 与 sandbox_mode 的旧式配置仍在 Linux 上保留，分卷文件系统策略等价于旧模型时走 Landlock，否则路由到 bubblewrap（codex-rs/core/README.md）。

架构视图

flowchart TD
    subgraph "外部形态 (Front-ends)"
        CLI["@openai/codex (Node)"]
        DESKTOP["Codex Desktop App"]
        IDE["VS Code / Cursor / Windsurf"]
        SDKTS["@openai/codex-sdk"]
        SDKPY["codex Python SDK"]
    end

    subgraph "Rust 工作区 codex-rs"
        BIN["CLI / app-server 二进制"]
        APPSERVER["codex-app-server"]
        CORE["codex-core"]
        PROTOCOL["codex-protocol"]
        API["codex-api"]
        CONFIG["codex-config"]
        TOOLS["codex-tools"]
        SBX["codex-linux-sandbox / Seatbelt"]
        EXEC["codex-exec-server"]
        GIT["codex-git-utils"]
    end

    OPENAI["OpenAI Responses / Compact API"]

    CLI --> BIN
    DESKTOP --> APPSERVER
    IDE --> APPSERVER
    SDKTS --> BIN
    SDKPY --> BIN
    BIN --> CORE
    APPSERVER --> CORE
    APPSERVER --> PROTOCOL
    CORE --> PROTOCOL
    CORE --> API
    CORE --> CONFIG
    CORE --> TOOLS
    CORE --> SBX
    CORE --> GIT
    EXEC --> APPSERVER
    API --> OPENAI

打包与多语言分发

scripts/codex_package 中的包构建器产出标准化的 Codex 包目录，其中包含 codex-package.json、可执行入口以及平台相关资源（Linux 的 bwrap、Windows 的 codex-command-runner.exe 与 codex-windows-sandbox-setup.exe、ripgrep 等），.tar.gz、.tar.zst、.zip 等归档格式都是该目录的序列化（scripts/codex_package/README.md）。省略 --target 时使用宿主平台默认发布目标（Linux 默认 musl）；本地 glibc 构建需显式传入 GNU Linux 目标。开发循环使用 dev-small profile 加速构建，发布流水线应传入 --cargo-profile release 并配合 --entrypoint-bin、--bwrap-bin 等预构建参数，避免重新打包时再次编译。

仓库顶层 package.json 标注为 codex-monorepo 私有包，统一托管仓库级维护工具（如 prettier 与 write_hooks_schema）（package.json）。Node.js 端通过 @openai/codex 暴露 codex CLI（bin/codex.js），适用于 Node ≥16（codex-cli/package.json）；TypeScript SDK @openai/codex-sdk 通过 codex startThread() 启动线程，并以 runStreamed() 返回异步事件生成器（sdk/typescript/README.md）。

这种"CLI 为后端，SDK 为前端"的边界使社区中讨论度较高的诉求——远程开发（#10450）、Linux 桌面应用（#11023）、从移动端远控桌面 CLI（#9224）、事件钩子（#2109）以及计划模式（#2101）——都可以在不改动 codex-core 业务逻辑的前提下，通过工作区中已有的 app-server、exec-server 与协议层增量扩展。

See Also

• Configuration Loading
• Tools Subsystem
• Sandbox and Execution
• Protocol Types

概述

codex-app-server-protocol 是 Codex CLI 与外部客户端（包括桌面应用、远程控制服务、SDK 等）通信的核心协议层。它定义了基于 JSON-RPC 的消息信封以及"外部类型"（external types），用于驱动 Codex 会话、线程（thread）、回合（turn）等高层语义。codex-protocol 的 README 明确指出，"external types" 用于与 codex app-server 通信，而"internal types" 仅在 codex-core 与 codex-tui 之间流转（资料来源：codex-rs/protocol/README.md）。这一分层使得 app-server 既可被本机进程调用，也可作为远程入口供其他客户端接入。

协议以模块化的 crate 形式组织：根 lib.rs 提供通用接口与共享消息类型，protocol/mod.rs 暴露版本化子模块 v1 和 v2，客户端可通过 protocol_version 协商选择兼容的协议版本。

协议分层与版本管理

模块结构

codex-app-server-protocol 的模块划分遵循"先根模块，再版本子模块"的组织方式：

该结构允许客户端在连接初始化阶段选择协议版本，并在不破坏兼容性的前提下演进协议。资料来源：codex-rs/app-server-protocol/src/lib.rs、codex-rs/app-server-protocol/src/protocol/mod.rs。

v1 与 v2 的演进

v1 与 v2 并存表明协议处于迭代中：v2 引入了更细粒度的对象模型，例如把 thread 与 turn 拆分为独立模块，对应官方 SDK 中 "Thread" 与 "Turn" 的概念（参见 sdk/typescript/README.md）。v1 则保留旧有消息类型以便向后兼容。

JSON-RPC 消息信封

协议所有消息都遵循统一的 JSON-RPC 信封结构。codex-exec-server 的中继层和传输测试都直接引用了下列类型：

• JSONRPCMessage：消息枚举，分发到请求、响应或通知分支（资料来源：codex-rs/exec-server/src/relay.rs）。
• JSONRPCRequest：客户端发出的请求，包含 method 与 params。
• JSONRPCResponse：服务器对请求的应答，包含 result 或 error。
• JSONRPCNotification：服务器主动推送的事件，不期望应答。
• RequestId：请求标识，用于将响应与请求配对。

这些类型由 codex-app-server-protocol 导出，被 codex-exec-server、codex 主二进制以及 SDK 共同消费。下图展示了消息流的典型走向：

sequenceDiagram
    participant Client as 客户端/SDK
    participant Server as codex app-server
    participant Core as codex-core

    Client->>Server: JSONRPCRequest (thread/start)
    Server->>Core: 内部 Session 调用
    Core-->>Server: 事件流
    Server-->>Client: JSONRPCNotification (item.completed 等)
    Server-->>Client: JSONRPCResponse (turn.completed)

传输与运行环境

WebSocket 与 stdio

codex-exec-server 的 README 描述了 app-server 协议在传输层的两种形态（资料来源：codex-rs/exec-server/README.md）：

• 本地 WebSocket：默认监听 ws://IP:PORT，便于同机进程通过 WebSocket 客户端接入。
• stdio：通过 codex exec-server 的 stdio:// 端点交换 JSON-RPC 帧，适合嵌入式调用与单元测试。parse_listen_url("stdio://") 与 parse_listen_url("stdio") 在 transport_tests.rs 中均有覆盖测试（资料来源：codex-rs/exec-server/src/server/transport_tests.rs）。

远程注册与认证

codex-exec-server 还支持 --remote URL --environment-id ID 模式：本地执行服务器先向环境注册中心（environment registry）发起注册请求，再连接服务提供的会合（rendezvous）WebSocket。注册请求支持三种认证路径：

1. codex login 生成的 ChatGPT 登录状态。
2. CODEX_API_KEY 作为 Bearer Token。
3. CODEX_ACCESS_TOKEN 中的 Agent Identity JWT（容器化调用方），通过 --use-agent-identity-auth 启用，服务会注册 Agent 任务并发送派生的 AgentAssertion 头。

中继（Relay）帧协议

远程模式下，WebSocket 之上叠加了一层二进制中继帧协议，由 codex-exec-server/src/relay.rs 定义。帧类型包括 Data、Ack、Resume、Reset 与 Heartbeat，用于多路复用、可靠投递与会话恢复。RELAY_MESSAGE_FRAME_VERSION 字段标识帧格式版本，便于将来演进（资料来源：codex-rs/exec-server/src/relay.rs）。

与社区关注的关联

社区中有多个高互动议题直接依赖 app-server 协议作为基础设施：

• 桌面应用远程开发（#10450，177 评论）：用户期望 Codex Desktop App 能接入远程机器，这需要 app-server 提供稳定的远程注册与中继能力。
• 远程控制 CLI（#9224，56 评论）：从手机 ChatGPT App 控制桌面 CLI，需要双向 JSON-RPC 通知流以及可靠的中继帧协议。
• Linux 桌面应用（#11023，103 评论）：平台扩展同样依赖跨进程 JSON-RPC 与 WebSocket 传输。

这些场景的共同基础正是 codex-app-server-protocol 的版本化消息模型与传输层抽象。

See Also

• Codex SDK (TypeScript)
• Exec Server 与 PTY 子进程管理
• Rollout Trace 与事件回放
• Protocol Types 概览

远程控制与桌面集成

概述

Codex 提供本地 CLI 与桌面应用两种形态：CLI 通过 codex 二进制执行任务，桌面体验则可通过 codex app 子命令或 chatgpt.com/codex?app-landing-page=true 入口获得。两种形态共享同一套 codex-core 业务逻辑与 codex-protocol 协议层，而远端控制能力主要由 codex-exec-server 承担。社区对此方向表达了强烈关注——Issue #10450（"Remote Development in Codex Desktop App"，177 条评论）呼吁桌面端支持远端开发；#9224（"Codex Remote Control"，56 条评论）则希望用手机通过 ChatGPT 应用反向控制桌面上的 codex CLI。

资料来源：README.md:1-20、codex-rs/core/README.md:1-10

`codex-exec-server` 远程模式

codex-exec-server 是 Codex 远端控制链路的入口组件：它是一个小型 JSON-RPC 服务器，负责派生并控制子进程（基于 codex-utils-pty），对外暴露 codex exec-server CLI、ExecServerClient Rust 客户端，以及共享的请求/响应类型。CLI 启动时支持的连接形态如下：

进入远端模式后，服务器先在 environment registry 中注册本地执行环境，再以该环境身份重连至 rendezvous 端点。默认使用 Codex ChatGPT 登录态；若远端注册要求鉴权，需先执行 codex login。

资料来源：codex-rs/exec-server/README.md:1-40

传输与协议层

codex-exec-server 在 wire 层使用共享的 codex-app-server-protocol 消息信封（message envelope）。codex-protocol crate 同时承载 CLI 与 TUI 之间的内部类型、以及与 codex app-server 之间的外部类型，并被刻意约束为"最小依赖、不放业务逻辑"，以便各前端共用。exec-server 中的 relay 模块维护可控的 WebSocket 句柄 ControlledWebSocketHandle：通过 set_write_blocked / set_write_ready 与 write_blocked_waker / write_waker 协作，能够在写缓冲区满时挂起发送任务，并在对端可写时唤醒，避免远端模式下因背压造成消息丢失或延迟。

资料来源：codex-rs/protocol/README.md:1-8、codex-rs/exec-server/src/relay.rs:1-60、codex-rs/exec-server/src/lib.rs:1-35

认证选项

codex-exec-server 的远端注册支持三条认证路径，便于在不同部署场景下复用：

``sh CODEX_API_KEY="$OPENAI_API_KEY" \ codex exec-server \ --remote ... \ --environment-id "$ENVIRONMENT_ID" ``

• ChatGPT 登录态：默认路径，首次使用前需运行 codex login。
• Agent Identity JWT：通过环境变量 CODEX_ACCESS_TOKEN 注入；启用方式为 CLI 参数 --use-agent-identity-auth。Codex 会以 Agent 身份注册任务，并在注册请求中携带派生的 AgentAssertion 请求头。
• API Key：通过环境变量 CODEX_API_KEY 注入，Codex 在注册请求中以 bearer token 形式发送。例如：

资料来源：codex-rs/exec-server/README.md:25-45

桌面应用集成与社区诉求

桌面应用通过 codex app 或 Codex App 页面启动，复用 codex-core 中的业务逻辑和 codex-protocol 中的消息类型，因此新增的远端开发与跨设备控制能力（对应社区 Issue #10450、#11023、#9224）自然落点都在 codex-exec-server 的远程模式与 codex-app-server-protocol 之上。exec-server 的模块划分（environment、environment_provider、remote、remote_file_system、remote_process、relay、server 等）已为注册、重连以及远端文件系统/进程接入预留了独立边界，可作为后续桌面端"远端开发"与"手机反向控制"扩展的支点。

资料来源：codex-rs/exec-server/src/lib.rs:1-40、README.md:1-20

另请参阅

• Codex CLI 总览
• codex-core 业务逻辑
• codex-protocol 消息信封
• codex-linux-sandbox 沙箱策略
• codex-tools 工具模型

概览

Codex 的 Event Hooks System 是一个独立的 Rust crate（codex-rs/hooks），用于让用户在 Codex 的关键生命周期事件前后注入自定义脚本或命令，从而实现外部流程与代理行为的自动化衔接。该特性直接回应了社区长期关注的功能请求：issue #2109 中，用户期望能够通过模式匹配（pattern matching）的方式定义 hooks，在 Codex 执行特定行为之前或之后触发外部脚本或命令。

在仓库层面，hooks 与其他子 crate 平级，独立编译；monorepo 通过 package.json 中的 write-hooks-schema 脚本调用 codex-hooks 二进制来生成 schema fixture。资料来源：codex-rs/hooks/src/lib.rs

核心架构

codex-hooks crate 的内部按职责划分为三个层次：

这种分层使得类型定义、声明语法与运行时引擎解耦：声明层面向用户配置，调度层负责把事件分发到匹配规则，执行层负责与外部进程对接。资料来源：codex-rs/hooks/src/types.rs codex-rs/hooks/src/declarations.rs codex-rs/hooks/src/engine/mod.rs

工作流程

当 Codex 代理在某个关键节点触发事件时，事件首先进入 engine 的 dispatcher，由其根据用户声明的 pattern 进行匹配；命中的 hook 被送入 command_runner，并行或串行地启动外部脚本。下图展示了从事件触发到外部命令执行的完整数据流。

flowchart LR
    A[Codex 核心事件<br/>session start / tool call / turn end] --> B[engine/mod.rs<br/>接收事件]
    B --> C[dispatcher.rs<br/>pattern 匹配]
    C --> D{匹配命中?}
    D -- 是 --> E[command_runner.rs<br/>启动外部命令]
    D -- 否 --> F[记录未命中]
    E --> G[外部脚本/命令执行]
    G --> H[收集 stdout/stderr<br/>与退出码]
    H --> I[回写结果到 Codex 事件流]

匹配规则与命令定义都来自 declarations.rs，使得用户在不动核心代码的前提下扩展行为。资料来源：codex-rs/hooks/src/engine/dispatcher.rs codex-rs/hooks/src/engine/command_runner.rs

配置与声明

用户通过声明文件（通常位于 .codex/hooks 或等价位置）描述 hook 规则。declarations.rs 提供的数据结构大致包括：

• 事件类型枚举：覆盖 session、turn、tool、subagent 等生命周期节点；
• 匹配模式：支持基于事件字段（如工具名、命令前缀、路径）的模式匹配；
• 命令规范：声明要运行的脚本路径、参数与环境变量；
• 执行控制：例如 before/after 触发、阻塞/非阻塞、同步/异步。

这种声明式设计降低了与 Codex 内核的耦合，与 issue #2109 提出的 "pattern matching + before/after trigger" 诉求保持一致。资料来源：codex-rs/hooks/src/declarations.rs

与其它模块的关系

hooks 子系统刻意保持轻量与独立：

• 不依赖 codex-rs/core 的编排逻辑，避免引入循环依赖；
• 通过标准化的 types 与外部 crate（如 codex-protocol）对接；
• 与 codex-rs/tools 类似，遵循 "最小职责、清晰边界" 的拆分原则（详见该 crate 的 README 关于 vision 与 non-goals 的描述）。资料来源：codex-rs/hooks/src/lib.rs codex-rs/tools/README.md

常见使用模式与失败模式

典型用法包括：

1. 前置校验：在 tool.call 之前运行 lint、format 或安全扫描；
2. 审计记录：在 turn.end 后将结果写入外部日志系统；
3. 通知联动：在 subagent.spawn 之后触发 IM/邮件通知。

需要注意的失败模式：

• 命令执行超时：若用户脚本未设超时，可能阻塞事件流；
• 非零退出码：command_runner 需要明确语义（忽略/告警/中止）；
• 模式过宽：过于宽松的 pattern 会导致 hook 频繁触发，影响性能；
• 沙箱冲突：hooks 的命令执行需要与 Codex 现有 SandboxPolicy 协同，否则可能被 macOS Seatbelt 或 Linux Landlock/bubblewrap 拦截。资料来源：codex-rs/hooks/src/engine/command_runner.rs codex-rs/core/README.md

相关社区讨论

• #2109 Event Hooks：原始 feature request，明确提出基于 pattern matching 的 before/after 触发机制；
• #2101 Plan Mode：用户希望在执行前先规划，hooks 可作为实现该工作流的一种外部手段；
• 最新发布 0.139.0 在工具与连接器 schema、codex doctor 等方面持续打磨（见仓库发布说明）。

See Also

• Codex CLI README
• codex-core 文档
• codex-tools 拆分与愿景
• codex-protocol 类型说明
• Rollout Trace 与事件总线

社区中长期呼声最高的特性之一就是"先规划、再执行"的工作流（#2101），用户希望代理在动手修改代码之前能够产出可审阅、可编辑的计划；Multi-Agent v2 则回应了用户对复杂任务派发、子代理隔离与上下文回收的需求。

Plan Mode（规划模式）

用途与定位

Plan Mode 让 Codex 在只读约束下进行调研、产出方案，并在用户显式批准后才进入修改阶段。这避免了"代理一上来就改文件"带来的不可控变更。

实现位置

• 工具处理器实现：codex-rs/core/src/tools/handlers/plan.rs
• 工具规格定义：codex-rs/core/src/tools/handlers/plan_spec.rs
• 模板原文：codex-rs/collaboration-mode-templates/templates/plan.md

在 plan_spec.rs 中，Plan Mode 被声明为一种特殊的模型可见工具；当模型调用它时，plan.rs 会触发一段"只读调研 + 方案撰写"的工作流，并将产出作为可审阅的计划条目交给用户。

关键行为

1. 在进入 Plan Mode 时，文件系统沙盒通常处于 read-only 或 workspace-write 之外的受限状态，以阻止未授权的写入。
2. 模型可调用其他只读工具（如搜索、读取文件、查询文档）来收集上下文。
3. 用户通过 UI 或 CLI 在计划上确认/编辑后，才会切换到执行阶段。
4. 计划本身会作为 ConversationItem 出现在会话上下文中，便于后续审计。

资料来源：codex-rs/core/src/tools/handlers/plan.rs; codex-rs/core/src/tools/handlers/plan_spec.rs; codex-rs/collaboration-mode-templates/templates/plan.md。

Collaboration Modes（协作模式）

模板化的协作契约

协作模式是一组预定义的协作模板，把"模型应扮演什么角色、可以使用哪些工具、遵循哪些约束"打包成可复用的配置。模板由 codex-rs/collaboration-mode-templates/src/lib.rs 加载，目录中的 Markdown 文件提供原始内容：

• plan.md —— 仅规划、不执行的协作契约
• execute.md —— 直接执行修改的协作契约
• default.md —— 通用默认协作契约

资料来源：codex-rs/collaboration-mode-templates/src/lib.rs; codex-rs/collaboration-mode-templates/templates/execute.md; codex-rs/collaboration-mode-templates/templates/default.md。

与 Plan Mode 的关系

Plan Mode 可以视为协作模式模板的一个特化应用：plan.md 模板在加载后会被注入到 codex-core 的会话上下文中，约束模型只输出计划条目而不调用修改工具。execute.md 则相反，明确允许文件写入与命令执行。

与协议层的关系

模板加载后的字符串会作为 instructions 或 system 字段进入 ResponsesApiRequest，由 codex-rs/codex-api/README.md 中描述的 Responses 客户端负责序列化；模板本身不依赖 codex-core 的运行时状态，因此可以在 codex-tui、codex-app-server、SDK 等多个入口复用。资料来源：codex-rs/protocol/README.md; codex-rs/codex-api/README.md。

Multi-Agent v2（多智能体工作流）

概览

Multi-Agent v2 让 Codex 在一个根会话（root thread）内派生多个子线程（child thread），通过专门的工具在父子之间传递任务、结果与控制信号。根回溯包（root rollout bundle）会把所有父线程、子线程以及它们之间的边（edge）合并到同一个 state.json 中，便于完整回放。

核心工具与边

spawn_agent / followup_task / send_message 是根线程的工具调用入口，它们向子线程注入任务或消息；close_agent 用于显式终止目标子线程。每一次注入与返回都会在归约（reducer）阶段产生一条 InteractionEdge，对应关系如下：

flowchart LR
    RootTool["根线程 ToolCall<br/>spawn_agent / followup_task / send_message"]
    ChildInput["子线程 ConversationItem<br/>被注入的任务/消息"]
    ChildThread["子线程 AgentThread"]
    ChildResult["子线程助手 ConversationItem<br/>结果消息"]
    RootNotice["根线程 ConversationItem<br/>子代理通知"]
    CloseTool["根线程 ToolCall<br/>close_agent"]
    TargetThread["目标 AgentThread"]

    RootTool -- "spawn/task edge" --> ChildInput
    ChildInput --> ChildThread
    ChildThread --> ChildResult
    ChildResult -- "agent_result edge" --> RootNotice
    CloseTool -- "close_agent edge" --> TargetThread

资料来源：codex-rs/rollout-trace/README.md。

归约（Reducer）不变式

归约阶段严格保持原始证据的可追溯性：原始事件按 seq 顺序重放；payload 文件必须可读；不同语义对象（ConversationItem、ToolCall、CodeCell、TerminalOperation、InteractionEdge）彼此独立。这种区分使得模型既能引用精确的原始 payload，又能保持模型可见的转录简洁——例如嵌套 JavaScript 工具调用在 JSON 运行时边界有完整输入输出，但模型可见的转录仅包含外层 exec 自定义工具调用。

资料来源：codex-rs/rollout-trace/README.md。

与工具生态的协同

codex-tools crate 负责把模型可见的工具集、MCP 适配、code-mode 兼容性垫片等"主机侧"逻辑从 codex-core 中拆出来。Multi-Agent v2 在派生子线程时会复用这部分规划与发现逻辑，而不会重复实现。资料来源：codex-rs/tools/README.md。

组合使用与典型场景

下表总结了三种核心模式在用户工作流中的位置：

典型链路：用户提出需求 → 进入 Plan Mode 输出方案 → 用户编辑并批准 → 切到 Execute Mode 执行；如任务过大，可在 Execute 阶段通过 spawn_agent 派生子代理并行处理，再由 close_agent 收回控制权。TypeScript SDK 与 Python SDK 的调用方可以使用相同的 Thread.run() / thread.run() 入口，在外部触发这一链路，资料来源：sdk/typescript/README.md; sdk/python/examples/README.md。

需要"事件钩子"的用户可以参考 #2109，未来若事件钩子落地，可在 Plan Mode 结束、子代理返回等边界挂接自定义脚本。

See Also

• Codex CLI 总览：README.md
• 协议与类型定义：codex-rs/protocol/README.md
• API 客户端与传输：codex-rs/codex-api/README.md
• 回溯跟踪与多代理归约：codex-rs/rollout-trace/README.md
• 共享工具支持 crate：codex-rs/tools/README.md
• TypeScript SDK 快速上手：sdk/typescript/README.md
• 规划模式社区讨论：#2101
• 事件钩子社区讨论：#2109

MCP、Plugins、Marketplaces 与 Skills

本页说明 Codex 在 MCP（Model Context Protocol）、插件（plugins）、市场（marketplaces）与技能（skills）四个相关领域的代码组织与职责划分，重点覆盖传输层、工具适配、插件边界以及多层配置装载机制。

概览：扩展能力的分层结构

Codex 把"扩展能力"拆分为多个职责清晰的 Rust crate：codex-rs/codex-mcp 是面向 Codex 自身的 MCP 服务端实现，codex-rs/rmcp-client 作为通用 MCP 客户端封装与第三方 MCP 服务器通信；codex-rs/core-plugins 作为独立插件核心 crate 存在；codex-rs/tools 是面向宿主（host）的工具适配共享层；codex-rs/config/src/loader 则承担多层配置装载，是市场与技能加载的底层机制。

MCP 工具规范的统一适配

codex-rs/tools/README.md 把"MCP 与 dynamic-tool 适配到 Responses API 形态"列为该 crate 的明确职责，并强调它拥有聚合宿主模型 ToolSpec、ConfiguredToolSpec、LoadableToolSpec、ResponsesApiNamespace 与 ResponsesApiNamespaceTool。该 crate 同时承担 schema sanitization、code-mode augmentation 与 image-detail 归一化等宿主侧适配工作。资料来源：codex-rs/tools/README.md:30-50

codex-rs/codex-api/README.md 进一步描述了 Responses API 的请求结构：ResponsesApiRequest 包含 model、instructions、input、tools、parallel_tool_calls 以及 reasoning/text 控制字段；ResponsesOptions 携带 conversation_id、session_source、extra_headers、compression、turn_state 等传输层选项。MCP 工具在被 codex-core 使用之前，必须被转换为这种形态。资料来源：codex-rs/codex-api/README.md:10-25

发布说明 0.139.0 指出，工具与连接器的输入 schema 现在保留 oneOf 和 allOf，并且大型 schema 在压缩时保留更浅结构，从而提升与更复杂 MCP 工具的兼容性。这意味着 schema sanitization 不再是简单字符串替换，而是保留组合类型语义。

插件核心与扩展边界

codex-rs/core-plugins/src/lib.rs 是独立插件核心 crate。codex-rs/tools/README.md 中的迁移规划明确指出：扩展拥有的可执行工具创作应保留在 codex-extension-api；宿主侧的规划/适配帮助只有在不再需要与 codex-core 耦合时，才迁入 codex-tools。这意味着当前 codex-tools 与 codex-core 之间存在严格边界——Session、TurnContext、审批流与运行时执行逻辑不得被过早搬入共享层。资料来源：codex-rs/tools/README.md:60-85

配置层与市场加载机制

codex-rs/config/src/loader/README.md 描述了 Codex 的配置装载机制。load_config_layers_state 把用户配置、CLI/会话覆盖、云端托管配置、托管 TOML 与 MDM 偏好等层叠合成一个 ConfigLayerStack。ConfigLayerStack::effective_config() 输出合并后的 TOML，origins() 返回每个键的来源元数据，layers_high_to_low() 返回高到低优先级列表；每一层都有一个稳定版本指纹（version 字段），用于乐观并发与冲突检测。资料来源：codex-rs/config/src/loader/README.md:15-40

市场（marketplace）层在模型上对应一个独立的 ConfigLayer，技能（skills）则是该层中可被用户启用的条目——它们共享同一套发现与合并机制，因此 UI 可以通过 origins() 直接呈现"当前技能来自哪一层"。

数据流

flowchart LR
  A[MCP Server / Plugin] -->|JSON-RPC| B[rmcp-client]
  B -->|ToolSpec| C[codex-tools 适配层]
  C -->|ResponsesApiRequest.tools| D[codex-core]
  D -->|调用结果| B

常见失败模式

• 复杂 MCP schema 被压平：升级前会丢失 oneOf/allOf 语义，0.139.0 起保留组合类型，但仍需避免过深嵌套以免触发压缩回退。
• 配置层覆盖不可见：用户配置与 MDM 层同名时托管层胜出；UI 应基于 origins() 明确标注来源，否则用户难以察觉覆盖。
• 扩展过早耦合核心：把 Session/TurnContext 直接放入共享层会破坏边界，codex-rs/tools/README.md 已明确此为非目标。
• 传输层误用：codex-rs/exec-server/README.md 显示，子进程控制与 MCP 共用 codex-app-server-protocol 消息信封，混用会导致请求路由错配。资料来源：codex-rs/exec-server/README.md:40-60

社区关注的相关请求

社区中呼声较高的扩展相关诉求（如 issue #2109 "Event Hooks"、#2101 "Plan Mode"）也属于"在不改写核心的前提下扩展能力"的范畴，未来可能以插件或技能的形式承载。当前 codex-core-plugins 与 codex-tools 的分层正是为这类扩展点准备的基础设施。

See Also

• codex-rs/core/README.md — Codex 核心业务逻辑
• codex-rs/protocol/README.md — 内外部协议类型
• codex-rs/exec-server/README.md — JSON-RPC 子进程服务器
• codex-rs/codex-api/README.md — Responses API 类型化客户端
• sdk/typescript/README.md — TypeScript SDK 中的工具调用

概述

Codex CLI 是一个运行在本地计算机上的编码代理，它需要在「可配置、可控、可审计」三者之间取得平衡。本页聚焦支撑这三点的四个核心子系统：配置加载（codex-config）、权限模型（permissions / approvals）、平台沙箱执行（Seatbelt 与 bubblewrap），以及驱动整个会话的核心引擎（codex-core）。

业务逻辑集中在 codex-core crate 中，按设计它的目标是供多个 Codex UI（TUI、app-server、CLI 等）共用。配置与协议则被刻意拆分为独立 crate，以便不同入口能够共享同一套契约。

flowchart TB
    UI[TUI / app-server / CLI]
    UI -->|JSONL / JSON-RPC| Core[codex-core<br/>Session & TurnContext]
    Core -->|读取| CfgLoader[config/loader<br/>多层 TOML 合并]
    CfgLoader -->|effective_config| Core
    Core -->|查询| Perms[Permissions / Approvals]
    Core -->|下发| Sandbox[SandboxPolicy]
    Sandbox --> MacOS[/usr/bin/sandbox-exec<br/>Seatbelt/]
    Sandbox --> Linux[bwrap / codex-linux-sandbox]
    Sandbox --> Win[codex-windows-sandbox-setup]
    Perms --> Core

配置加载与分层合并

codex-config loader 是 Codex 配置层加载与描述的规范入口。它将多种来源的 TOML 配置（用户配置、CLI/会话覆盖、云托管配置、MDM 托管偏好等）按优先级合并成一个 effective_config，并同时输出每个 key 的来源元数据与每个层的稳定指纹用于乐观并发控制。

公开接口包括 load_config_layers_state、ConfigLayerStack、ConfigLayerEntry、ConfigLoadOptions、LoaderOverrides 与 merge_toml_values 等。资料来源：codex-rs/config/src/lib.rs:1-120；codex-rs/config/src/loader/README.md:1-40。

合并模型遵循「上层覆盖下层」的规则。从低到高大致为：用户配置 → CLI/会话覆盖 → 云托管配置 → MDM 托管偏好。在 Linux 上仍保留对 SandboxPolicy / sandbox_mode 这种遗留配置的支持；当分割文件系统策略与遗留模型语义一致时会走 Landlock，否则自动切换到 bubblewrap。资料来源：codex-rs/core/README.md:1-60；codex-rs/linux-sandbox/README.md:1-50。

权限模型与审批流

权限模型将「默认拒绝」与「用户显式批准」结合：模型产生的工具调用必须经过审批流（approval flow）才能进入执行器。审批决策会同时写入 Permissions 状态，并可被持久化为 permissions.toml，以便后续会话复用。

配置入口方面，config_toml.rs 负责常规配置项的反序列化；permissions_toml.rs 则专门承载权限规则文件，确保权限子系统与通用配置解耦。资料来源：codex-rs/config/src/config_toml.rs:1-200；codex-rs/config/src/permissions_toml.rs:1-200。

这一边界使得 codex-core 的高层编排（Session / TurnContext / approval flow / runtime execution）不会过早被迁移到 codex-tools 中去，保持了治理边界的稳定性。资料来源：codex-rs/tools/README.md:1-60。

平台沙箱：Seatbelt、bubblewrap 与 Windows 辅助

沙箱策略由 SandboxPolicy 与 FileSystemSandboxPolicy 共同描述，并在不同平台落到不同实现：

在 macOS 上，workspace-write 策略允许在配置的可写根目录下写入，但会把 .git 目录或指针文件、解析后的 gitdir: 目标以及 .codex 目录保持只读。资料来源：codex-rs/core/src/sandbox/mod.rs:1-160；codex-rs/core/README.md:1-60。

在 Linux 上，Codex 优先使用 PATH 中位于当前工作目录之外的 bwrap；如果 bwrap 过旧不支持 --argv0，会回退到无 --argv0 的兼容路径；如果缺失，则使用随 Codex 一起打包的 codex-resources/bwrap 辅助程序，并产生启动警告。WSL2 走标准 Linux bubblewrap 路径，而 WSL1 因无法创建用户命名空间被拒绝进入沙箱 shell 命令。资料来源：codex-rs/linux-sandbox/src/lib.rs:1-160；codex-rs/linux-sandbox/README.md:1-60。

核心会话引擎（`codex-core`）

codex-core 是 Codex 的业务逻辑核心：它承载 Session、TurnContext、审批流以及运行时执行，被 CLI、TUI 与 app-server 共同复用。该 crate 在外部依赖上对环境有强假设，例如 macOS 上依赖 /usr/bin/sandbox-exec，Linux 上依赖 arg0 为 codex-linux-sandbox 的二进制来转发到沙箱辅助。

协议层则被刻意独立到 codex-protocol：它只承载「类型」，既包含 codex-core ↔ codex-tui 的内部类型，也包含 codex-app-server 使用的外部类型。该 crate 应保持最小依赖，并避免将业务逻辑沉淀其中。资料来源：codex-rs/protocol/README.md:1-30；codex-rs/core/README.md:1-60。

会话的生命周期可以概括为：UI 通过 JSONL 或 JSON-RPC 发送指令 → Session 构造 TurnContext → 根据 Permissions 走审批流 → 由 SandboxPolicy 选择平台执行器（Seatbelt / bwrap / Windows setup）→ 收集工具输出并回传 UI。整个过程既受 codex-config 的有效配置约束，也受 codex-protocol 的强类型契约约束，从而实现「跨入口一致、可审计、可恢复」的设计目标。

参见

• Codex CLI 顶层介绍：codex-rs/README.md
• 配置层合并细节：codex-rs/config/src/loader/README.md
• Linux 沙箱实现：codex-rs/linux-sandbox/README.md
• 协议类型定义：codex-rs/protocol/README.md
• 工具系统边界与迁移规划：codex-rs/tools/README.md

Pitfall Log / 踩坑日志

项目：openai/codex

摘要：发现 10 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：Take approve or not for full access。

1. 配置坑 · 来源证据：Take approve or not for full access

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Take approve or not for full access
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/codex/issues/27134 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

2. 配置坑 · 来源证据：Unethical business practice

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Unethical business practice
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/openai/codex/issues/27384 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Codex CLI plugin sync writes bundled plugin marketplace into active workspace

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI plugin sync writes bundled plugin marketplace into active workspace
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/codex/issues/27416 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:965415649 | https://github.com/openai/codex | host_targets=chatgpt, cursor, codex

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:965415649 | https://github.com/openai/codex | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:965415649 | https://github.com/openai/codex | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:965415649 | https://github.com/openai/codex | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:965415649 | https://github.com/openai/codex | no_demo; severity=medium

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:965415649 | https://github.com/openai/codex | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:965415649 | https://github.com/openai/codex | release_recency=unknown