Codex 沙箱内部
Codex 如何在你的机器上运行受限命令。
Michael Bolin,技术团队成员
分享在 OpenAI,我们采取纵深防御方法来保护智能体。虽然我们在训练和对齐方面的投入是这项工作的基石,但我们也在智能体运行框架 Codex 中实现了额外功能来提供补充保护。由于 Codex 最常用(也最具潜在风险)的行为之一是在你的计算机上执行命令,我们构建了 Codex 沙箱,让 Codex 能够在你现有的环境中,在你可控的文件系统和网络限制范围内工作。
沙箱通过限制程序在运行期间可以访问的资源,来实现上述目标。例如,对于照片整理任务,你可以配置 Codex 沙箱,允许命令读取和修改 ~/Pictures 目录下的文件,同时阻止网络访问以防止上传。对于代码审查,你可以允许访问在线文档,但将源文件设为只读。用户通过权限配置文件来配置 Codex 沙箱,这些文件定义了 Codex 会话的文件系统和网络限制。
在本文中,我们将从 Codex 沙箱默认设置背后的权衡开始,然后解释沙箱的设计以及框架如何使用它来执行命令。我们将展示最终用户和企业如何根据需求定制其权限,以及开发者如何在自己的工具中复用该沙箱。最后,我们将探讨这些限制如何在 macOS、Linux 和 Windows 上强制执行。
选择沙箱边界
在 Codex 中,我们的理念是设定保守的默认沙箱参数,同时仍能支持有意义的工作。例如,当以 Git 仓库作为工作区根目录时,内置的 :workspace 权限配置文件:
允许在工作区内写入,同时将 `.git` 和 `.codex` 等目录设为只读。这样 Codex 编辑源码时无需为每处修改请求许可,又防止直接改动 `.codex/config.toml` 或 `.git/hooks` 下的 Git hooks。 允许大范围读取文件系统,但仍受用户现有系统权限约束。编译器、运行时和构建工具依赖仓库之外的 SDK、库和配置,如果把读取范围限制在工作区内,很多常规工作流都会中断。代价是机器上其他位置的敏感文件(比如包含 API key 的配置文件)也可能被读取。 禁用网络访问。这既阻止了向外部服务直接上传数据(包括试图外传命令能读到的内容),也阻断了下载依赖等合法操作——后者需要额外授权。 这些限制能防止一大类恶意行为,但危害依然可能发生。比如 agent 可以向本地安装的包(如 `node_modules/prettier`)注入恶意代码。由于 `node_modules` 通常被 Git 忽略,这种改动不会出现在 `git status` 中。如果用户的编辑器在保存时运行该份 Prettier,那么保存一个文件就可能在 Codex 沙箱之外执行恶意代码。这正是我们采取纵深防御的原因:沙箱限制命令能访问什么,而训练和对齐则确保模型按照用户意图使用这些权限。 关于如何定制沙箱权限、以及如何在企业环境中将其与其他防护措施结合,请参阅 Codex 安全手册(在新窗口打开)。 设计沙箱 虚拟机和容器(在新窗口打开)是两种常见的沙箱机制,但 Codex 采用了不同的方案。它不是把计算迁移到隔离的独立环境中,而是利用各平台自身的沙箱设施,对运行在用户现有环境中的命令施加约束。对于许多开发者而言,笔记本电脑就像一套量身定做的开发环境,可以随时随性调整。要在 Docker 容器里复刻这套环境颇费周折,且部分工作流仍依赖宿主机器上的工具。
举个例子,在 Mac 上用 Codex 开发 iOS 应用时,若选择通过 Docker 对 Codex 进行沙盒隔离,Codex 将无法调用由原生 Mac 可执行文件组成的 iOS 构建工具链,也无法启动 iPhone 模拟器来运行代码。基于 Docker 的工作流固然可以将构建和模拟器操作委托给 Mac 宿主机,但这些操作会发生在容器沙盒之外,需要单独施加限制。因此,我们在各操作系统上深度投入沙盒机制,以便 Codex 能在最适合当前任务的环境中运行,从而保持流程简单。
该框架通过一套跨 macOS、Windows 和 Linux 的统一 API,暴露了这些操作系统专属的沙盒机制。此 API 接受一个命令和一份权限配置。如果权限配置允许有限的网络访问,调用者必须提供一个网络代理来强制执行这些限制:
Python
1# 这是实际 API 的简化版本。2def spawn_command_under_sandbox(3 program_and_args: list[str],4 cwd: Path,5 env: dict[str, str],6 permission_profile: PermissionProfile,7 network_proxy: NetworkProxy | None,8) -> Child:
该函数在沙盒中启动进程,并返回一个 Child 句柄,框架可借此等待进程结束。每个子进程都会继承父进程的沙盒约束,因此这些限制适用于该命令引发的整个进程树,即使某些后代进程的存活时间超过了原始进程,限制依然有效。
下图展示了这些组件如何协同工作,从配置阶段到运行受沙盒保护的命令。下文将逐一解释每个阶段。
框架如何利用沙盒
正如 Unrolling the Codex Agent Loop 一文所述,Codex harness 负责执行模型生成的工具调用。在编码任务中,最常用的工具是 shell 工具,它的运行方式类似用户在 Bash 这类交互式 shell 中手动执行命令。下面我们以一次性的 exec_commandshell 工具为例,说明 harness 如何借助沙箱实现所需的保护。
下面是不加沙箱时,Codex harness 处理 exec_command 工具调用的简化版本:
Python
(代码保留原样)要对命令进行沙箱化,harness 会把对 subprocess.Popen() 的调用替换为 spawn_command_under_sandbox(),并传入权限配置文件,必要时还会传入网络代理:
Python
1
# 执行 exec_command 工具调用,同时强制应用沙箱约束。
2
3
def
perform_exec_command_with_sandboxing
(
4
tool_call: ExecCommandToolCall,
5
permission_profile: PermissionProfile,
6
network_proxy: NetworkProxy |
None
,
7
):
8
# ...按前述示例构建 program_and_args...
9
child = spawn_command_under_sandbox(
10
program_and_args=program_and_args,
11
cwd=Path(tool_call.workdir
or
"."
).absolute(),
12
env=os.environ.copy(),
13
permission_profile=permission_profile,
14
network_proxy=network_proxy,
15
)
16
output, exit_code = collect_output(child, timeout_ms=tool_call.timeout_ms)
17
return
{
"output"
: output,
"exit_code"
: exit_code}
exec_command 工具允许模型为单条命令请求不同的权限,但由 harness 决定是否批准该请求:
Python
1
class
ExecCommandToolCall
:
2
# ...命令相关字段...
3
4
# 单命令级别的沙箱权限覆盖。默认值为 "use_default"。
5
sandbox_permissions:
Literal
[
6
"use_default"
,
7
"with_additional_permissions"
,
8
"require_escalated"
,
9
] =
"use_default"
10
11
# 面向用户的审批提示;仅适用于 "require_escalated"。
12
justification:
str
|
None
=
None
13
14
# 扩展网络或文件系统访问权限;仅适用于 "with_additional_permissions"。
15
# AdditionalPermissions 支持细粒度选项。
16
additional_permissions: AdditionalPermissions |
None
=
None
当指定 use_default 时,harness 将使用当前回合的默认沙箱配置。with_additional_permissions 请求在沙箱内扩展访问权限,而 require_escalated 则请求在沙箱外执行。harness 会先根据用户偏好评估该请求,然后再执行命令。(例如,Codex 可能会直接提示用户,也可能将请求路由至 自动审查(在新窗口打开)。)如果获得授权,Codex 将把合适的 permission_profile 和 network_proxy 连同原始 ExecCommandToolCall 中的命令参数一起传递给 perform_exec_command_with_sandboxing()。
shell 工具是 spawn_command_under_sandbox() 的主要使用方,harness 在读取和修改本地文件等操作中也复用了同一套沙箱基础设施。这种复用不止于 harness:codex sandbox 命令让你能在自己的工具中集成沙箱化的命令执行,后文会详细介绍。接下来我们看看权限配置是如何定义的。
配置沙箱
命名权限配置让你可以重
