跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/concepts/sandboxing

沙盒

Codex 如何在 Codex app、IDE 和 CLI 中使用沙箱

沙箱是一个边界，它让 Codex 能够自主行动，同时又不会给予它对你机器的无限制访问权限。当 Codex 在 Codex app、IDE 扩展或 CLI 中运行本地命令时，这些命令会在受约束的环境中运行，而不是默认以完全访问权限运行。

该环境定义了 Codex 可以自行执行的操作，例如它可以修改哪些文件，以及命令是否可以使用网络。当任务保持在这些边界之内时，Codex 可以继续执行而无需停下来确认。当它需要超出这些边界时，Codex 会回退到审批流程。

沙箱和审批是两种不同但协同工作的控制机制。沙箱定义技术边界。审批策略决定 Codex 何时必须停下来，并在跨越这些边界之前发出询问。

沙箱的作用​

沙箱适用于生成的命令，而不仅仅是 Codex 的内置文件操作。如果 Codex 运行诸如 git、包管理器或测试运行器之类的工具，这些命令会继承相同的沙箱边界。

Codex 在每个操作系统上都使用平台原生的强制执行机制。具体实现因 macOS、Linux、WSL2 和原生 Windows 而异，但各个使用场景中的理念是相同的：给 agent 一个有边界的工作空间，使常规任务能够在明确限制内自主运行。

为什么这很重要​

沙箱减少了审批疲劳。Codex 不必让你确认每一个低风险命令，而是可以在你已批准的边界内读取文件、进行编辑并运行常规项目命令。

它还为 agent 式工作提供了更清晰的信任模型。你信任的不仅是 agent 的意图；你还信任 agent 运行在受强制执行的限制之内。这让你更容易让 Codex 独立工作，同时仍然知道它何时会停下来并请求帮助。

入门​

当你使用默认权限模式时，Codex 会自动应用沙箱。

前置条件​

在 macOS 上，沙箱开箱即用，使用内置的 Seatbelt 框架。

在 Windows 上，当你在 PowerShell 中运行时，Codex 使用原生的 Windows 沙箱；当你在 WSL2 中运行时，则使用 Linux 沙箱实现。

在 Linux 和 WSL2 上，请先使用你的包管理器安装 bubblewrap：

Ubuntu Debian​

sudo apt install bubblewrap

Fedora​

sudo dnf install bubblewrap

Codex 会使用它在 PATH 上找到的第一个 bwrap 可执行文件。如果没有可用的 bwrap 可执行文件，Codex 会回退到一个捆绑的 helper，但该 helper 需要支持创建非特权用户命名空间。安装发行版中提供 bwrap 的软件包可以让此设置保持可靠。

当缺少 bwrap，或者 helper 无法创建所需的用户命名空间时，Codex 会显示启动警告。在那些对此 AppArmor 设置进行限制的发行版上，建议优先加载 bwrap 的 AppArmor 配置文件，这样 bwrap 就能继续工作，而无需在全局范围禁用该限制。

Ubuntu AppArmor 说明： 在 Ubuntu 25.04 上，从 Ubuntu 的软件包仓库安装 bubblewrap 应该无需额外的 AppArmor 设置即可工作。bwrap-userns-restrict 配置文件包含在 apparmor 软件包中，路径为 /etc/apparmor.d/bwrap-userns-restrict。

在 Ubuntu 24.04 上，即使安装了 bubblewrap，Codex 仍可能警告它无法创建所需的用户命名空间。请复制并加载额外的配置文件：

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

apparmor_parser -r 会在无需重启的情况下将该配置文件加载到内核中。你也可以重新加载所有 AppArmor 配置文件：

sudo systemctl reload apparmor.service

如果该配置文件不可用，或无法解决问题，你可以使用以下命令禁用 AppArmor 对非特权用户命名空间的限制：

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

如何控制​

大多数人会从产品中的权限控制开始。

在 Codex app 和 IDE 中，你可以从 composer 或聊天输入框下方的权限选择器中选择一种模式。该选择器允许你使用 Codex 的默认权限、切换到完全访问，或使用你的自定义配置。

在 CLI 中，使用 /permissions 在会话期间切换模式。

配置默认值​

如果你希望 Codex 每次启动时都具有相同的行为，请使用自定义配置。Codex 会将这些默认值存储在其本地设置文件 config.toml 中。配置基础 解释了其工作方式，而配置参考 记录了 sandbox_mode、approval_policy、approvals_reviewer 和 sandbox_workspace_write.writable_roots 的确切键。使用这些设置来决定 Codex 默认获得多少自主性、它可以写入哪些目录、何时应暂停以等待审批，以及谁来审核符合条件的审批请求。

从高层来看，常见的沙箱模式有：

  • read-only：Codex 可以检查文件，但不能编辑文件，也不能在未经审批的情况下运行命令。
  • workspace-write：Codex 可以读取文件、在工作区内编辑，并在该边界内运行常规本地命令。这是本地工作的默认低摩擦模式。
  • danger-full-access：Codex 在没有沙箱限制的情况下运行。这会移除文件系统和网络边界，只有当你希望 Codex 以完全访问权限行动时才应使用。

常见的审批策略有：

  • untrusted：对于不在其受信任集合中的命令，Codex 会先询问再运行。
  • on-request：Codex 默认在沙箱内工作，并在需要超出该边界时发出询问。
  • never：Codex 不会因审批提示而停止。

当审批是交互式的时，你还可以通过 approvals_reviewer 选择由谁来审核：

  • user：审批提示会展示给用户。这是默认值。
  • auto_review：符合条件的审批提示会发送给 reviewer agent（参见 Auto-review）。

完全访问意味着将 sandbox_mode = "danger-full-access" 与 approval_policy = "never" 一起使用。相比之下，风险较低的本地自动化预设是将 sandbox_mode = "workspace-write" 与 approval_policy = "on-request" 一起使用，或者使用对应的 CLI 标志 --sandbox workspace-write --ask-for-approval on-request。然后你可以保留 approvals_reviewer = "user" 以进行手动审批，或者设置 approvals_reviewer = "auto_review" 以启用自动审批审核。

如果你需要 Codex 跨多个目录工作，可写根目录可以让你扩展它可修改的位置，而无需完全移除沙箱。如果你需要更宽或更窄的信任边界，请调整默认沙箱模式和审批策略，而不是依赖一次性的例外。

当某个工作流需要特定例外时，请使用 rules。Rules 允许你对沙箱外的命令前缀进行允许、提示或禁止，这通常比广泛扩展访问权限更适合。若要查看 app 中审批和沙箱行为的更高层概览，请参见 Codex app features；若要查看 IDE 专用设置入口，请参见 Codex IDE extension settings。

自动审核（如果可用）不会改变沙箱边界。它只是该边界上审批请求的一种 approvals_reviewer，例如沙箱升级、被阻止的网络访问或仍需审批的有副作用工具调用。沙箱内已允许的操作会在无需额外审核的情况下运行。有关 reviewer 生命周期、触发类型、拒绝语义和配置细节，请参见 Auto-review。

平台细节位于各平台专属文档中。有关原生 Windows 的设置、行为和故障排查，请参见 Windows。有关沙箱和审批的管理员要求以及组织级约束，请参见 Agent approvals & security。