沙盒

沙箱是一道边界，让 Codex 能够自主行动，而无需授予其对您计算机的无限制访问权限。当 Codex 在 Codex 应用, IDE 扩展, or CLI，这些命令将在受限环境中运行，而不是默认以完整访问权限运行。

中运行本地命令时，该环境决定了 Codex 能独立完成的操作，例如可以修改哪些文件，以及命令是否能使用网络。当任务在这些边界内进行时，Codex 可以无需暂停等待确认而继续执行。当需要超出这些边界时，Codex 会回退到审批流程。

沙箱的作用

沙箱适用于生成的命令，而不仅限于 Codex 内置的文件操作。如果 Codex 运行类似以下工具： git、软件包管理器或测试运行器，这些命令将继承相同的沙盒边界。

Codex 在每个操作系统上使用平台原生机制来实施沙箱。具体实现在 macOS、Linux、WSL2 和原生 Windows 上有所不同，但核心理念在各平台保持一致：为代理提供一个受限的工作空间，使常规任务能在明确的限制内自主运行。

为何重要

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

它还为代理工作提供了更清晰的信任模型。您不仅仅是信任代理的意图，更是信任代理在强制限制内运行。这使得您可以更放心地让 Codex 独立工作，同时仍能知道它何时会停下来寻求帮助。

入门

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

前提条件

On macOS，沙盒开箱即用，采用了内置的 Seatbelt 框架。

On Windows，Codex 使用原生 Windows 沙盒 在 PowerShell 中运行时，以及 Linux 沙箱实现在 WSL2 中运行时。

On Linux 和 WSL2安装 bubblewrap 首先通过您的包管理器

sudo apt install bubblewrap

sudo dnf install bubblewrap

Codex 会使用它在路径上找到的第一个 bwrap 可执行文件，如果 PATH. If no bwrap 可执行文件可用，Codex 会回退到内置的辅助程序，但该辅助程序需要支持非特权用户命名空间创建。安装提供 bwrap 的发行版软件包可以保持此设置的可靠性。

当 bwrap 缺失或辅助程序无法创建所需的用户命名空间时，Codex 会在启动时显示警告。在限制此 AppArmor 设置的发行版上，建议加载 bwrap AppArmor 配置文件，以便 bwrap 可以继续工作，而无需全局禁用该限制。

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

sudo systemctl reload apparmor.service

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

控制方式

大多数人首先会使用产品中的权限控制功能。

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

In the CLI, use /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: 符合条件的审批提示将发送给审查代理（参见 自动审查).

完全访问权限意味着将 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" for automatic approval review.

如果你需要 Codex 在多个目录中工作，可写根目录 (writable roots) 允许你扩展其可修改的位置，而无需完全移除沙盒。如果你需要更宽或更窄的信任边界，请调整默认的沙盒模式和审批策略，而不是依赖一次性的例外设置。

当工作流需要特定例外时，请使用 规则。规则允许你允许、提示或禁止沙盒外的命令前缀，这通常比广泛扩大访问权限更合适。有关应用中审批和沙盒行为的高层概述，请参见 Codex 应用功能,以及 IDE 专属设置的入口点,请参阅 Codex IDE 扩展设置.

自动审查（如果可用）不会更改沙盒边界。它是针对该边界上的审批请求（例如沙盒升级、被阻止的网络访问或仍需审批的带副作用的工具调用）的一种可能的 approvals_reviewer 方案。沙盒内已允许的操作无需额外审查即可运行。有关审查者的生命周期、触发器类型、拒绝语义和配置详情，请参阅 自动审查.

平台详情请参见特定平台的文档。有关原生 Windows 的设置、行为和故障排除，请参阅 Windows。有关管理员要求以及组织级别对沙箱和审批的约束,请参阅 智能体审批与安全.