AI 编码代理在本地开发环境执行命令时，本质上是在用户权限上下文中运行外部生成的代码。这种 "自动执行不可信代码" 的场景对安全边界提出了严苛要求 —— 既要保证代理能够完成代码编辑、测试运行等开发任务，又必须防止其越界访问敏感文件或外泄数据。OpenAI Codex CLI 通过分层沙箱架构解决了这一矛盾，本文将深入剖析其安全模型的设计思路与工程实现。
三层权限模型：从只读到完全访问
Codex CLI 定义了三种沙箱模式，通过 --sandbox 参数显式控制：
read-only 模式仅允许全局文件读取，禁止任何写入操作。该模式适用于代码审查、架构分析等只读场景，可最大程度降低意外修改风险。命令示例：codex --sandbox read-only "分析项目依赖结构"。
workspace-write 模式是默认配置，允许在当前工作目录及其子目录进行读写，同时保持对其他路径的只读访问。这一设计平衡了安全性与实用性 —— 代理可以修改项目代码、生成测试文件，但无法触碰用户主目录中的配置文件或系统敏感路径。
danger-full-access 模式完全禁用沙箱，授予代理完整的文件系统和网络访问权限。该模式仅应在隔离环境或明确可控的场景下使用，例如需要安装系统级依赖的初始化任务。
三种模式的关系体现了 "最小权限原则" 的渐进式应用：日常开发使用 workspace-write，敏感审查降级到 read-only，特殊任务按需提升到 danger-full-access。
跨平台隔离机制的技术选型
Codex 并未采用单一的跨平台抽象层，而是针对各操作系统原生安全能力进行了深度适配：
Linux 平台采用 Landlock（内核 5.13+）结合 seccomp 的双重防护。Landlock 在系统调用层面实施基于路径的访问控制，无需特权即可限制进程的文件读写范围；seccomp 则通过系统调用过滤阻断危险操作（如特权提升）和网络套接字创建。对于需要更强隔离的场景，Codex 还支持 Bubblewrap 实验特性，利用 Linux 命名空间实现 PID、网络、挂载点的完全隔离，并通过 Unix 域套接字代理受控网络流量。
macOS 平台使用 Apple 原生的 **Seatbelt（App Sandbox）** 机制。Codex 根据当前沙箱模式动态生成 .sbpl 配置文件，通过 sandbox-exec 应用沙箱策略。这种设计允许灵活调整可写路径、网络访问等权限，同时与 macOS 安全框架深度集成。
Windows 平台面临最大挑战 —— 系统未提供开箱即用的等效沙箱能力。OpenAI 工程团队经过多轮迭代，最终采用受限令牌（Restricted Token）+ 专用用户账户 + 防火墙规则的混合方案，下文将详细展开。
Windows 沙箱的工程实现细节
Windows 沙箱的设计经历了两个主要阶段。早期 "未提升沙箱" 原型使用合成 SID（Security Identifier）与写入受限令牌实现文件隔离，但网络保护仅依赖环境变量（如 HTTPS_PROXY=http://127.0.0.1:9），容易被绕过。
当前 "提升沙箱" 方案在 setup 阶段需要管理员权限，但提供了更可靠的隔离：
合成 SID 与写入受限令牌。Codex 创建名为 sandbox-write 的合成 SID，将其写入 ACL 授予工作目录的写权限，同时显式拒绝该 SID 对 .git/、.codex/、.agents/ 等保护路径的访问。运行时，子进程以写入受限令牌启动，该令牌的受限 SID 列表包含 Everyone、当前登录会话 SID 和 sandbox-write 合成 SID。Windows 在执行写入操作时会进行双重检查：常规用户权限检查通过后，还需验证受限 SID 列表中的至少一个 SID 具有相应权限。
专用用户账户与防火墙规则。为精确控制网络访问，Codex 在 setup 阶段创建两个本地用户账户：CodexSandboxOffline（网络受限）和 CodexSandboxOnline（网络允许）。防火墙规则针对 CodexSandboxOffline 用户阻止所有出站连接。运行时命令以对应用户身份启动，通过 LogonUserW 获取令牌，再经 CreateRestrictedToken 生成受限令牌，最终由 codex-command-runner.exe 以 CreateProcessAsUserW 启动子进程。
读取权限的异步修复。由于沙箱用户并非真实用户，默认无法读取其他用户的配置文件（如 C:\Users\<real-user>）。Codex 在 setup 阶段异步为沙箱用户授予常用系统目录（Windows、Program Files、用户主目录等）的读取 ACL，避免阻塞用户交互。
网络访问控制与保护路径
网络访问与文件沙箱正交配置，通过 sandbox_policy.network_access 控制：
enabled：允许出站网络连接restricted：禁止网络访问（Linux Bubblewrap 通过--unshare-net隔离网络命名空间）
保护路径机制确保关键数据不会被意外修改。无论沙箱模式如何，.git/（Git 仓库元数据）、.codex/（Codex 配置与数据）、.agents/（代理数据）始终只读。此外，用户可在 config.toml 中自定义保护路径：
[sandbox_policy]
mode = "workspace-write"
network_access = "restricted"
protected_paths = [".env", "secrets/"]
writable_roots = ["/tmp/codex-scratch"]
可落地的配置参数与最佳实践
基于上述机制，建议按以下策略配置 Codex 沙箱：
日常开发：使用默认 workspace-write 模式，网络访问按需开启。通过 --add-dir 扩展可写范围时，优先使用绝对路径并遵循最小必要原则。
敏感代码审查：切换至 read-only 模式，完全杜绝写入风险。若需网络获取文档，可临时启用网络访问。
CI/CD 集成：在自动化流程中显式设置 --sandbox workspace-write 并禁用交互式升级提示，通过 config.toml 预定义所有可写路径。
故障排查：Linux 平台可通过 RUST_LOG=debug codex "test command" 查看沙箱诊断信息；macOS 使用 log show --predicate 'eventMessage contains "Sandbox"' --last 1h 检查 Seatbelt 拒绝记录。
安全升级策略：当代理请求越权操作时，Codex 的审批系统支持四级策略 ——never（自动批准）、on-request（按需提示）、unless-trusted（策略覆盖时自动批准）、on-failure（失败后提示）。建议生产环境使用 unless-trusted 并维护明确的信任策略文件。
Codex CLI 的沙箱设计展示了 AI 代理本地安全的核心矛盾：完全隔离会削弱实用性，完全开放则带来不可接受的风险。通过分层权限模型、平台原生隔离机制以及精细的访问控制策略，Codex 在两者之间找到了工程上的平衡点。对于需要在本地运行 AI 编码工具的团队，理解这些安全边界的设计原理，是构建可信开发环境的第一步。
参考来源
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。