codex-core 深度解析：Codex CLI 业务逻辑核心、跨平台沙箱依赖与 Wine-exec 测试体系

本文基于仓库内 codex-rs/core/README.md 展开，系统讲解 codex-core crate 在 Codex 中的定位、Wine-exec 集成测试的运行方式与五个 skip 宏的适用场景，并逐平台剖析其对 sandbox-exec、codex-linux-sandbox（arg0 机制）、bubblewrap/Landlock 及 Windows 沙箱后端的运行依赖。读完后，你能够理解 Codex 跨平台沙箱策略的落地路径，知道何时该用哪个测试跳过宏，以及 Linux/WSL 环境下沙箱的降级与回退逻辑。

codex-core 是什么

codex-core 是整个 Codex 的业务逻辑层：它实现了 Codex 的核心行为（会话、工具执行、沙箱策略的生成与消费、补丁应用等），设计目标是"被各种用 Rust 编写的 Codex UI 复用"。在当前仓库中，UI 侧如 codex-rs/cli、codex-rs/tui、codex-rs/app-server 等都建立在这个核心 crate 之上。

README 还明确了 codex-core 的一个隐含前提：它假定某些辅助二进制能力存在于运行环境中（例如沙箱执行器、apply_patch 虚拟 CLI）。后文的"依赖支持矩阵"就是这个前提的逐平台细化。

Wine-exec 集成测试

在 x86-64 Linux 上，可以通过 Bazel 对共享测试套件跑一遍"Windows 执行服务器"环境：

bazel test //codex-rs/core:core-all-wine-exec-test

这套机制的意图是：让同一份共享测试在不同执行后端上复用——Local 执行目标是宿主操作系统，Docker 目标是 Linux，Wine 执行目标是 Windows。因此，写跨执行环境的测试时，应根据测试的依赖选择正确的跳过宏：

宏	适用场景
skip_if_target_windows!	测试依赖"Windows 目标行为"之外的假设，即 Windows target 下需跳过
skip_if_host_windows!	测试受"Windows 宿主"限制，在 Windows 主机上无法执行
skip_if_remote!	测试只应在本地执行（local-only 行为）
skip_if_no_remote_env!	测试只应在远程环境执行（remote-only 行为）
skip_if_wine_exec!	测试存在 Wine 专属 runner 的已知债务，需在 Wine-exec 环境下跳过

这些宏在测试公共库 codex-rs/core/tests/common/lib.rs 中统一定义（#[macro_export] 导出，供下游测试 crate 展开），全部建立在内核宏 skip_if_test_condition! 之上：满足条件时向 stderr 打印 Skipping test in <环境>: <原因> 后直接 return（或返回调用方指定的值）。例如：

• skip_if_wine_exec! 判断 is_wine_exec_test_environment()，命中即打印 Skipping test in the Wine-exec test environment: ...；
• skip_if_target_windows! 判断 test_target_os() == TestTargetOs::Windows；
• skip_if_host_windows! 则使用编译期 cfg!(target_os = "windows") 判断，打印 Skipping test because it cannot execute on Windows.。

此外还有一个与沙箱测试配套的 codex_linux_sandbox_exe_or_skip!：仅在 Linux 目标平台下查找 codex-linux-sandbox 可执行文件，找不到时跳过测试并在 stderr 说明原因。

在构建侧，codex-rs/core/BUILD.bazel 中存在 run_tests_with_wine_exec = True 配置项，用于把测试套件挂到 Wine 执行路径上。

运行依赖支持矩阵

README 的 Dependencies 一节给出了 codex-core 对各平台辅助工具的假设，这是部署/打包 Codex 时需要核对的清单。

macOS

• 假定 /usr/bin/sandbox-exec 存在（macOS 自带的 Seatbelt 命令行工具）。
• 使用 workspace-write 沙箱策略时，Seatbelt profile 允许在配置的 writable roots 下写入，但将 .git（目录或指向别处的指针文件）、gitdir: 解析后的实际目标目录、以及 .codex 保持为只读——这保证了即使工作区可写，版本元数据与 Codex 自身状态目录也不会被会话误改。
• 网络访问与文件系统读写根由 SandboxPolicy 统一控制：Seatbelt 只负责"消费已解析的策略并强制执行"。
• Seatbelt 策略中还保留了 user-preference-read（传统默认偏好读取权限），这是 cfprefs 支持的 macOS 行为所必需的遗留访问。

对应实现位于 codex-rs/sandboxing crate：seatbelt.rs 生成策略，随附的 seatbelt_base_policy.sbpl 与 seatbelt_network_policy.sbpl 分别是基础策略与网络策略的 Seatbelt 模板。

Linux

Linux 的假设分两条线：

1. arg0 机制。 包含 codex-core 的二进制在 arg0 为 codex-linux-sandbox 时，应执行等价的 codex sandbox 行为，细节见 codex-rs/arg0 crate。从源码看，codex-rs/arg0/src/lib.rs 的 arg0_dispatch() 正是这个分发点：进程启动时读取 argv[0]，若可执行文件名等于 CODEX_LINUX_SANDBOX_ARG0，直接转入 codex_linux_sandbox::run_main()；若 argv[0] 是 apply_patch（或拼写错误的 applypatch），则转入补丁应用入口。也就是说，同一个 Codex 二进制通过 argv[0]/argv[1] 伪装成多种辅助 CLI，这就是 README 反复提到的"virtual CLI"。

2. Landlock 与 bubblewrap 的自动路由。 旧的 SandboxPolicy / sandbox_mode 配置在 Linux 上仍然受支持，路由规则是：

• 当拆分式文件系统策略（split filesystem policy）在 cwd 解析后与旧模型沙箱等价时，继续走传统 Landlock 路径；
• 当策略需要 FileSystemSandboxPolicy 的直接执行——例如在更宽的可写根下出现只读或被拒绝（denied）的 carveout——则自动路由到 bubblewrap；
• 旧 Landlock 路径仅在拆分式策略能"无损往返"旧 SandboxPolicy 模型（语义不变）时使用。README 特别举了一个易错的叠加案例：/repo = write、/repo/a = none、/repo/a/b = write——更具体的可写子目录必须在被拒绝的父目录下"重新打开"，这类语义在往返后保持不变，因此仍可留在 Landlock 路径。

3. bubblewrap 的查找与回退链。 Linux 沙箱助手遵循以下优先级（对应 codex-rs/linux-sandbox crate，其中 launcher.rs 负责启动、bundled_bwrap.rs 负责定位捆绑副本）：

1. 优先使用 PATH 上（且不在当前工作目录内）找到的第一个 bwrap；
2. 若系统 bwrap 版本过旧、不支持 --argv0，则继续使用系统 bubblewrap，但内部 re-exec 切换到"不带 --argv0 的兼容路径"；
3. 若完全没有 bwrap，回退到随 Codex 一起分发的捆绑二进制 codex-resources/bwrap，同时 Codex 通过正常的通知路径发出启动警告（而不是从沙箱助手进程直接打印）；
4. 若 bubblewrap 无法创建 user namespace，Codex 同样会发出启动警告。

4. WSL 的边界。 WSL2 走正常的 Linux bubblewrap 路径；WSL1 因无法创建所需的 user namespace，不支持 bubblewrap 沙箱——Codex 会在调用 bwrap 之前直接拒绝会进入该路径的沙箱 shell 命令（fail fast，而非让 bwrap 本身报错）。

Windows

Windows 同样保持对旧 SandboxPolicy / sandbox_mode 的支持，但有两点语义差异：

• 旧的 read-only 与 workspace-write 策略隐含整个文件系统的读权限；若要精确限定可读根，必须改用拆分式文件系统策略；
• 新的 [permissions] / 拆分式策略仅在其能被所选 Windows 后端直接执行、或能无损往返旧 SandboxPolicy 模型时受支持。若策略需要"显式不可读 carveout（none）"或"只读 carveout 之下重新打开的可写后代"这类无法等价的语义，Codex 会fail closed（直接失败）而不是降级为更弱的执行。

两个后端各自的能力：

• elevated 沙箱支持：旧 ReadOnly/WorkspaceWrite 行为；需要精确可读根、精确可写根、或可写根下额外只读 carveout 的拆分式策略；以及后端管理的系统读根（如 C:\Windows、C:\Program Files、C:\Program Files (x86)、C:\ProgramData），当拆分式策略请求平台默认时自动补入，以保证基本执行能力。
• unelevated restricted-token 后端支持：旧的 full-read Windows 模型（对应旧 ReadOnly 与 WorkspaceWrite）；以及一个较窄的拆分式子集——可读根为全读、可写根与旧 WorkspaceWrite 根集合一致、但额外增加了这些可写根之下只读 carveout 的策略。

相关实现在 codex-rs/windows-sandbox-rs crate（含 48 个源文件与 codex-windows-sandbox-setup.manifest）。

全平台：apply_patch 虚拟 CLI

所有平台共享的最后一条假设：包含 codex-core 的二进制在 arg1 为 --codex-run-as-apply-patch 时，应模拟虚拟的 apply_patch CLI（细节同样见 codex-rs/arg0）。回到 arg0/src/lib.rs 的源码可以看到对应的分发分支：argv1 == CODEX_CORE_APPLY_PATCH_ARG1 时读取补丁参数并在当前工作目录下执行应用逻辑。这一机制让核心工具调用（打补丁）能以"看起来像外部 CLI"的方式被 shell 命令直接调用，而不需要启动独立进程树。

小结：如何把 codex-core 放进你的执行环境

• 核对平台假设：macOS 需 sandbox-exec；Linux 依赖 arg0 分发到 codex-linux-sandbox 与可用的 bwrap（系统版或捆绑版均可）；Windows 注意 elevated / restricted-token 后端对拆分式策略的支持边界，无法等价表达的策略会 fail closed。
• WSL1 用户：不要依赖 bubblewrap 沙箱，Codex 会在进入 bwrap 路径前拒绝命令；WSL2 则按正常 Linux 路径运行。
• 写跨环境测试：按"target / host / local / remote / wine"五类依赖选择对应 skip 宏，全部定义在 codex-rs/core/tests/common/lib.rs，可直接在下游测试 crate 中展开复用；共享套件的 Wine 回归用 bazel test //codex-rs/core:core-all-wine-exec-test（x86-64 Linux）驱动。
• 理解"虚拟 CLI"：argv[0]/argv[1] 分发（codex-linux-sandbox、apply_patch、--codex-run-as-apply-patch 等）是 codex-core 与其外围沙箱/工具生态耦合的关键接口，改动产物打包方式时应重点覆盖 codex-rs/arg0 的分发逻辑。