如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

沙盒

了解沙盒在 ChatGPT 和 Codex 各客户端中的工作方式

沙盒限制智能体对您计算机的访问范围,让它可以在这个范围内自主行动。在 ChatGPT 桌面应用、Codex CLI 或 IDE 扩展程序中进行本地聊天时,聊天中执行的命令默认在受限环境中运行,只能使用该环境授予的权限。

这个环境规定了智能体可以自行执行哪些操作,例如可以修改哪些文件,以及命令能否访问网络。只要任务在这个范围内,智能体就可以继续执行,无需停下来等待确认。如果需要超出这个范围,就会进入审批流程。

沙盒和审批是两种相互配合的控制机制。沙盒设定技术边界,审批策略决定智能体何时必须在越过边界前暂停并请求审批。

沙盒的作用

沙盒既限制内置文件操作,也限制智能体启动的命令。如果智能体运行 git、包管理器或测试运行器等工具,相应命令也受同样的沙盒限制。

Codex 使用各操作系统的原生机制来强制执行沙盒限制。macOS、Linux、WSL2 和原生 Windows 上的实现方式各不相同,但各客户端遵循同一原则:为智能体划定明确的工作范围,让它可以在范围内自主完成常规任务。

为什么需要沙盒

沙盒可以减少反复审批的负担。在您已批准的范围内,智能体可以读取和编辑文件、运行常规项目命令,无需请您逐一确认低风险命令。

沙盒也让您更清楚地了解将任务交给智能体的信任基础。除了信任智能体的意图,您还可以依靠系统强制执行的限制。这样,您既可以放心让智能体独立工作,也知道它何时会停下来请求帮助。

开始使用

默认权限模式会自动启用沙盒。

前提条件

在 macOS 上,沙盒使用系统内置的 Seatbelt 框架,无需额外设置。

在 Windows 上,如果您在 PowerShell 中运行 Codex,它会使用原生的 Windows 沙盒。如果您在 WSL2 中运行 Codex,它会使用 Linux 沙盒。

在 Linux 和 WSL2 上,请先使用包管理器安装 bubblewrap:

Choose an option
sudo apt install bubblewrap

Codex 会使用它找到的第一个 bwrap 可执行文件,搜索顺序由 PATH 决定。如果找不到可用的 bwrap 可执行文件,Codex 会改用自带的辅助程序,但该程序要求系统允许非特权用户创建用户命名空间。为确保这套配置可靠运行,请安装发行版提供的包含 bwrap 的软件包。

如果缺少 bwrap,或辅助程序无法创建所需的用户命名空间,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

通过工作云端访问本地计算机

如果任务通过工作云端访问本地计算机,对话由 OpenAI 云端协调。每个步骤受到哪些沙盒限制,取决于它在哪里运行:

  • 云端执行:工作云端容器使用现有的工作云端策略。桌面浏览器的站点规则不会自动应用于云端浏览器。
  • 本地执行:在已连接的计算机上运行的步骤受本地执行环境支持的要求约束。

启用托管策略后,受支持的全局策略会应用于可访问本地计算机的工作模式与 dot 共用的云端编排器。工作云端容器和 dot 云端计算机分别使用各自的执行配置,并受各自的执行要求约束。请分别测试本地执行和云端执行,确认每个环境中有哪些控制措施生效。一个环境的策略不会授予对另一个环境的访问权限。

同一策略内,各项设置的优先级从高到低依次为:针对特定操作系统的环境覆盖设置 → 适用于所有操作系统的环境覆盖设置 → 全局设置。即使低优先级策略更具体,仍以高优先级策略为准。对于本地执行,MDM 和旧版受管设备要求优先于智能体安全设置,后者又优先于设备的系统要求文件。

请参阅托管配置,了解各字段的合并规则和运行时限制,并在工作模式的本地安全设置和工作模式的云端安全设置中查看实际生效的文件和网络访问限制。

权限的工作方式

使用当前客户端的权限控件,可以更改 Codex 处理本地操作的方式。

审批决定 Codex 何时需要在执行操作前暂停,沙盒则决定命令可以访问哪些文件和网络资源。如果审批提供多个授权范围,例如仅批准一次或在本次会话中有效,请选择足以让任务继续执行的最小范围。默认将访问范围限定在当前项目内。对于互不相关的代码仓库,请分别使用独立的项目或工作树,避免将访问范围扩大到其他代码仓库。

在 ChatGPT 桌面应用中,请使用编辑器下方的权限控件。根据您的配置,菜单中可能会显示请求审批、代我审批(适用于符合条件的审批请求)、完全访问权限,以及已命名或自定义的权限配置。

选择一种模式,试用文档中的示例。您的 ChatGPT 或 Codex 权限不会因此改变。

如何审批 ChatGPT 的操作?了解更多

Approve for me

Approve for me keeps the same workspace-write sandbox as Ask for approval, but eligible approval requests are routed through automatic review instead of showing a prompt for manual approval. More details about automatic review.

Sandbox
workspace-write
Approvals policy
on-request
Reviewer
auto_review

配置默认设置

要让 Codex 每次启动时都采用相同的行为,请在 config.toml 中设置默认值。配置基础介绍了配置的工作方式,配置参考详细说明了 sandbox_mode、approval_policy、approvals_reviewer 和 sandbox_workspace_write.writable_roots 这些配置键。通过这些设置,您可以指定智能体默认可以自行执行哪些操作、可以写入哪些目录、何时需要暂停并请求审批,以及由谁审查符合条件的审批请求。

常见的沙盒模式如下:

  • read-only:智能体可以查看文件,但必须获得批准才能编辑文件或运行命令。
  • workspace-write:智能体可以读取文件,在工作空间内编辑文件,并在该范围内运行常规本地命令。这是本地工作的默认模式,可以减少操作中断。
  • danger-full-access:智能体在没有沙盒限制的情况下运行。此模式会移除文件系统和网络访问限制,仅当您希望智能体以完全访问权限执行操作时才应使用。

常见的审批策略如下:

  • on-request:智能体默认在沙盒内工作,需要超出沙盒范围时会请求审批。
  • never:智能体不会暂停并请求审批。

Codex 和 ChatGPT 工作不再支持选择 untrusted 作为审批策略。如果现有配置使用该值,请参阅从已停用的 untrusted 审批策略迁移。

使用交互式审批时,您还可以通过 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" 以自动审查审批请求。

如果您需要智能体在多个目录中工作,可以指定可写根目录,扩大它可以修改文件的范围,同时保留沙盒限制。如果需要扩大或缩小信任边界,请调整默认沙盒模式和审批策略,避免依赖一次性例外。

如果工作流需要特定例外,请使用规则。规则可按命令前缀指定哪些命令允许在沙盒外运行、哪些需要请求审批、哪些禁止运行。这通常比大范围扩大访问权限更合适。有关如何在 IDE 中找到相关设置,请参阅 Codex IDE 扩展程序设置。

启用自动审查不会改变沙盒边界。如果自动审查可用,您可以通过 approvals_reviewer 选择由它审查触及该边界的审批请求。这类请求包括请求放宽沙盒限制、访问被阻止的网络资源,或执行会产生副作用且仍需审批的工具调用。沙盒内已获准的操作可以直接执行,无需额外审查。有关审查智能体的生命周期、触发类型、请求被拒绝的含义及配置详情,请参阅自动审查。

各平台的具体说明见相应的平台文档。有关原生 Windows 环境的设置、运行行为和故障排查,请参阅 Windows。有关管理员要求,以及组织对沙盒和审批施加的限制,请参阅智能体审批与安全。