OpenAI

2026年11月18日

工程

深入了解 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 钩子。

  • 允许广泛读取文件系统,但仍受用户现有操作系统权限的约束。编译器、运行时和构建工具依赖代码仓库之外的 SDK、库和配置。如果只能读取工作空间内的内容,许多常规工作流将无法正常运行。代价是,机器上其他位置的敏感文件也可能仍可读取,例如包含 API 密钥的配置文件。

  • 禁用网络访问。这会阻止系统直接向外部服务上传内容,包括试图外泄该命令可读取的数据。它也会阻止系统下载依赖项等正常操作,这些操作需要额外的访问权限。

这些限制可以阻止一大类不良行为,但有害操作仍有可能发生。例如,智能体可能会向本地安装的软件包(如 node_modules/prettier)注入恶意代码。这种修改可能不会出现在 git status 中,因为 Git 通常会忽略 node_modules。如果用户的编辑器在保存时运行 Prettier 副本,那么仅仅保存文件,就可能在 Codex 沙箱之外执行恶意代码。这正是我们采用纵深防御策略的原因:沙箱限制命令可以访问的资源,而训练和对齐则帮助模型按照用户的意图使用这些访问权限。

如需了解如何在企业环境中调整沙箱权限,并将其与其他保护措施结合使用,请参阅 Codex 安全实用指南⁠(在新窗口中打开)。

沙箱设计

虚拟机和容器⁠(在新窗口中打开)是两种常见的沙箱实现机制,但 Codex 沙箱采用了不同的方式。Codex 不会将计算任务移到独立环境中来实现隔离,而是利用各平台的沙箱机制,约束在用户现有环境中运行的命令。

对许多开发者而言,笔记本电脑就是按自己需求打造的开发环境,可以随时调整。在 Docker 容器中复现这一环境需要花费精力,而且有些工作流仍然依赖主机上运行的工具。

例如,考虑在 Mac 上使用 Codex 开发 iOS 应用的场景。如果你决定将 Codex 放进 Docker 中运行,以此实现沙箱隔离,那么 Codex 既无法运行由 Mac 原生可执行程序组成的 iOS 构建工具链,也无法启动 iPhone 模拟器来运行代码。基于 Docker 的工作流可以将构建和模拟器操作交给 Mac 主机,但这些操作会在容器沙箱之外执行,因此需要单独施加限制。对 Codex 而言,我们更倾向于化繁为简 — 重点投入各操作系统层面的沙箱机制,让 Codex 能在最适合当前任务的环境中运行。

执行框架通过一套跨 macOS、Windows 和 Linux 的通用 API,提供这些操作系统专属的沙箱机制。该 API 接收一条命令和一个权限配置集。如果权限配置集允许有限的网络访问,调用方必须提供网络代理来实施这些限制:

Python

1
# This is a simplified version of the actual API.
2
def 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 句柄,执行框架可以用它等待进程结束。每个子进程都会继承父进程的沙箱约束,因此,这些限制会作用于由该命令启动的整个进程树,即使后代进程在原始进程退出后仍继续运行,也不例外。

下图展示了从配置到在沙箱中运行命令的全过程,以及各部分如何协同运作。后续章节将逐一说明各个阶段。

流程图:配置和托管要求共同定义会话的权限配置集;Codex 执行框架在 macOS、Linux 或 Windows 上,根据各平台专属的沙箱限制启动命令。子进程继承这些限制,可选的网络代理则负责实施域名规则。

执行框架如何利用沙箱

如《解析 Codex 智能体循环》所述,Codex 执行框架负责执行模型生成的工具调用。对于编程任务,最常用的是 shell 工具,它运行命令的方式与用户在 Bash 等交互式 shell 中的操作大致相同。我们将在本文中以单次执行的 ⁠(在新窗口中打开)exec_command⁠(在新窗口中打开) shell 工具⁠(在新窗口中打开)为例,说明执行框架如何利用沙箱实现所需的保护。

以下简化版本展示了
不使用沙箱时,Codex 执行框架如何处理 exec_command 工具调用:

Python

1
# Illustrative implementation of the exec_command tool call.
2

3
class ExecCommandToolCall:
4
cmd: str
5
workdir: str | None = None
6
shell: str | None = None
7
login: bool = True
8
timeout_ms: int = 10_000
9

10

11
def perform_exec_command(tool_call: ExecCommandToolCall):
12
program_and_args = [
13
tool_call.shell or os.environ.get("SHELL") or "/bin/sh",
14
"-lc" if tool_call.login else "-c",
15
tool_call.cmd,
16
]
17
child = subprocess.Popen(
18
program_and_args,
19
# workdir defaults to the turn's cwd, assumed here to be the process cwd.
20
cwd=Path(tool_call.workdir or ".").absolute(),
21
stdout=subprocess.PIPE,
22
stderr=subprocess.STDOUT,
23
)
24
output, exit_code = collect_output(child, timeout_ms=tool_call.timeout_ms)
25
return {"output": output, "exit_code": exit_code}

要让命令在沙箱中运行,执行框架会将对 subprocess.Popen() 的调用替换为 spawn_command_under_sandbox()。执行框架会提供权限配置集,并在需要时提供网络代理:

Python

1
# Honoring the exec_command tool call while enforcing sandbox constraints.
2

3
def perform_exec_command_with_sandboxing(
4
tool_call: ExecCommandToolCall,
5
permission_profile: PermissionProfile,
6
network_proxy: NetworkProxy | None,
7
):
8
# ...build program_and_args as in the previous example...
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 工具还允许模型为单条命令请求不同的权限,但是否批准由执行框架决定:

Python

1
class ExecCommandToolCall:
2
# ...command-related fields...
3

4
# Per-command sandbox override. Defaults to "use_default".
5
sandbox_permissions: Literal[
6
"use_default",
7
"with_additional_permissions",
8
"require_escalated",
9
] = "use_default"
10

11
# User-facing approval question; only for "require_escalated".
12
justification: str | None = None
13

14
# Expand network or filesystem access; only for "with_additional_permissions".
15
# AdditionalPermissions supports fine-grained options.
16
additional_permissions: AdditionalPermissions | None = None

指定 use_default 时,执行框架会使用当前轮次的默认沙箱配置。with_additional_permissions 请求扩大沙箱内的访问权限,而 require_escalated 请求在沙箱外执行。执行框架会在执行命令前,根据用户偏好评估该请求。(例如,Codex 可能直接提示用户,也可能将请求路由至自动审核⁠(在新窗口中打开)。)如果执行获得授权,Codex 会将相应的 permission_profile 和 network_proxy,连同原始 ExecCommandToolCall 中的命令参数,一起传给 perform_exec_command_with_sandboxing()。

shell 工具是 spawn_command_under_sandbox() 的主要调用方,执行框架也会复用其沙箱基础设施,进行读取和修改本地文件等操作。这种复用并不限于执行框架:codex sandbox 命令让你能够将沙箱命令执行能力集成到自己的工具中,后文将介绍这一点。接下来,我们将介绍如何定义权限配置集。

配置沙箱

为权限配置集命名后,你就可以跨项目复用同一套文件系统和网络限制。你可以在 config.toml 的 [permissions] 下定义自己的配置集。例如,以下配置定义了一个名为“dev”的配置集,它扩展⁠(在新窗口中打开)了内置的 :workspace 配置集:

TOML

1
# Use the dev profile by default.
2
default_permissions = "dev"
3

4
[permissions.dev]
5
# This is displayed when /permissions is run in the Codex CLI.
6
description = "Development with extra read-only protections."
7

8
# A profile can be derived from an existing profile.
9
# Profiles starting with ":" are provided by Codex.
10
extends = ":workspace"
11

12
[permissions.dev.filesystem]
13
"~/build-cache" = "write"
14

15
[permissions.dev.filesystem.":workspace_roots"]
16
".devcontainer" = "read"
17
".vscode" = "read"
18
"**/*.env" = "deny"
19
"secrets" = "deny"

dev 配置集增加了对 ~/build-cache 的写入权限,并对工作空间内的文件施加了额外限制。文件系统条目可以授予只读权限 (read)、授予读写权限 (write),或完全禁止访问 (deny)。

通过 :workspace_roots 表,你可以为相对于项目工作空间根目录的路径定义规则。默认情况下,Codex CLI 将其工作目录作为唯一的工作空间根目录,而 ChatGPT 桌面应用则使用项目的源代码文件夹。Codex 会将每条规则应用于所有根目录,因此 dev 中的 .vscode 条目会将每个根目录下的 .vscode 目录设为只读。

除自身规则外,dev 还会从 :workspace 继承以下保护措施:

TOML

1
[permissions.":workspace".filesystem.":workspace_roots"]
2
".agents" = "read"
3
".aws" = "read"
4
".codex" = "read"
5
".git" = "read"

网络权限

在 Codex 中配置沙箱网络时,大致有三种选择:

  • 禁用所有网络访问(:workspace 配置集的默认设置)

  • 启用完整的直接网络访问(:danger-full-access 配置集的默认设置)

  • 仅允许通过代理访问网络,由代理根据权限配置集决定放行哪些请求


要让
dev 直接访问网络,请在 config.toml 的顶层设置 permissions.dev.network.enabled = true。在网络代理被禁用时,这会授予完整的网络访问权限。

要将 dev 的访问范围限制为一组域名,请启用网络代理并配置其域名规则:

TOML

1
[permissions.dev.network]
2
enabled = true
3

4
[permissions.dev.network.domains]
5
"*.openai.com" = "allow"
6
# Allow requests to local services by hostname or by IPv4/IPv6 loopback address.
7
"localhost" = "allow"
8
"127.0.0.1" = "allow"
9
"::1" = "allow"
10
"evil.example" = "deny"
11

12
[features]
13
# If neither local config nor managed requirements enable the proxy,
14
# this profile allows direct network access; domain rules are not enforced.
15
network_proxy = true

域名规则支持精确名称和通配符模式,显式拒绝规则优先于允许规则。对其他域名的请求需要获得批准,否则会被阻止,详见下文的网络代理部分。

分层配置与强制限制

个人用户可以配置适用于所有项目的默认设置,并针对某个受信任的项目覆盖这些设置。企业管理员也可能希望为用户配置默认设置,并限制用户可以更改哪些设置。Codex 通过分层配置和托管要求同时支持这两种需求。

如配置优先级⁠(在新窗口中打开)所述,Codex 会合并多个 config.toml 文件中的设置。表会递归合并,值发生冲突时,以优先级较高的来源为准。数组则会被整体替换。

这就是权限配置集使用表来表示文件系统路径和网络域名的原因。团队可以在其配置中添加或覆盖个别条目,同时自动继承组织基础配置中所有其他条目的更改:

TOML

1
[permissions.dev.filesystem.":workspace_roots"]
2
".idea" = "read"
3

4
[permissions.dev.network.domains]
5
"example.com" = "allow"

管理员还可以通过 requirements.toml 提供托管要求⁠(在新窗口中打开),限制用户的配置选择。这些要求可以来自多个来源,包括系统文件和云端提供的策略。一种常见用法是指定 allowed_permission_profiles,限制企业用户可选的权限配置集范围。例如,管理员可以指定以下云端要求:

TOML

1
default_permissions = ":read-only"
2

3
[allowed_permission_profiles]
4
":read-only" = true
5
":danger-full-access" = false

云端要求的优先级高于系统要求文件 /etc/codex/requirements.toml,因此该文件中的条目无法覆盖上文显式设置的 ":danger-full-access" = false。不指定 :workspace,就可以由其他要求层来提供该条目。最终合并后的表中,条目为 false 或没有对应条目的配置集均不可用。

这种分离方式让组织能够强制实施限制,同时允许用户在限制范围内调整配置。生成的权限配置集既可以供执行框架使用,也可以直接应用于命令,接下来我们将介绍这一点。

使用 codex sandbox 命令

Codex CLI 提供了 sandbox 命令,方便你在 Codex 配置中定义的权限配置集下运行任意命令。它通常用于测试配置集,确保沙箱能够阻止预期拦截的行为。

例如,以下命令试图配置 VS Code,让它在保存时运行恶意的自动格式化程序。假设 .vscode 已存在,上文定义的 dev 配置集应会阻止这次写入,因为该目录是只读的(codex sandbox 默认将 cwd 视为工作空间根目录):

Bash

1
codex sandbox --permission-profile dev -- \
2
bash -c 'cat > .vscode/settings.json' <<'JSON'
3
{
4
"prettier.prettierPath": "./node_modules/evil-prettier",
5
"[typescript]": {
6
"editor.defaultFormatter": "esbenp.prettier-vscode",
7
"editor.formatOnSave": true
8
}
9
}
10
JSON

实际在 macOS 上运行时,该命令确实会失败,并显示:

Plain text

1
bash: .vscode/settings.json: Operation not permitted

借助 codex sandbox 命令,你可以独立于智能体会话使用 Codex 的沙箱机制。你可以使用同一套配置语言和各平台专属的强制实施机制,约束由你自己的工具启动的命令。

示例:将 MCP 服务器置于沙箱中

对于在 config.toml 中配置的 stdio MCP 服务器,Codex 执行框架不会尝试将用于启动服务器的命令放入沙箱。Codex 无法准确推断该服务器需要哪些文件或网络服务,因此,应用默认沙箱配置集可能会使原本有效的配置无法正常运行。

例如,要将 @modelcontextprotocol/server-memory⁠(在新窗口中打开) MCP 服务器配置为供 Codex 使用,标准方式如下:

TOML

1
[mcp_servers.memory]
2
command = "npx"
3
args = [
4
"-y",
5
"@modelcontextprotocol/server-memory@1.0.0"
6
]
7

8
[mcp_servers.memory.env]
9
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"

由于这条 npx 命令未在沙箱中运行,它可以使用与运行 Codex 的用户相同的权限写入文件和发起网络请求,这样的权限过于宽泛。为收紧权限,我们可以定义一个名为“memory-mcp”的权限配置集,然后使用 codex sandbox --permission-profile memory-mcp 包装原来的 npx 命令,限制服务器可写入的位置,并阻止其访问网络:

TOML

1
[permissions.memory-mcp.filesystem]
2
# Allow broad reads for Node.js/npm dependencies and configuration.
3
":root" = "read"
4
"~/.npm" = "write"
5
"~/mcp-data" = "write"
6

7
[permissions.memory-mcp.network]
8
enabled = false
9

10
[mcp_servers.memory]
11
command = "codex"
12
args = [
13
"sandbox",
14
"--permission-profile",
15
"memory-mcp",
16
"--",
17
"npx",
18
"--offline",
19
"@modelcontextprotocol/server-memory@1.0.0"
20
]
21

22
[mcp_servers.memory.env]
23
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"

启动服务器之前,先创建其数据目录,并将锁定版本的软件包存入 npm 缓存。这样,npx --offline 就能在禁用网络访问的配置集下启动服务器:

Bash

1
# The sandbox can write to this folder, but it cannot create it.
2
mkdir -p ~/mcp-data
3

4
# Installing the MCP server requires network access.
5
npx -y --package=@modelcontextprotocol/server-memory@1.0.0 -c true

软件包缓存完成后,Codex 无须访问网络即可启动记忆服务器,且只能向 npm 缓存和服务器的数据目录写入。

Codex 沙箱的实现

沙箱实现会将权限配置集转化为由操作系统强制实施的限制。网络代理的核心请求处理和策略逻辑由三大操作系统共用,而代理的设置及其与沙箱的集成方式则因操作系统而异。我们将先介绍共享代理,再分别介绍 macOS、Linux 和 Windows 上的实现。

网络代理

为实施权限配置集中的网络限制,执行框架会启动网络代理,并配置沙箱:允许连接该代理,同时阻止直接连接外部主机。代理会根据配置集中的域名规则检查每个请求,以决定是否转发。

在 Codex 代码仓库中,网络代理由 codex-network-proxy⁠(在新窗口中打开) crate 实现。执行框架将其作为库使用,但它也可以构建为独立的 CLI⁠(在新窗口中打开)。启用后,codex-network-proxy 默认会同时启动 HTTP 代理和 SOCKS5 代理。这些代理地址会通过环境变量传递给沙箱启动的进程。除了注入 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY 等标准环境变量,还会注入一些常见的应用程序专用环境变量⁠(在新窗口中打开),例如 PIP_PROXY。当然,并非所有程序都会遵循这些环境变量。如果程序尝试直接连接外部主机,操作系统的沙箱限制会将其阻止,详见下文各平台的相关章节。

网络代理负责实施权限配置集中定义的网络限制。例如,前文展示的 dev 配置集允许向 *.openai.com 发起请求,并明确拒绝向 evil.example 发起请求。当请求的目标域名既不匹配允许规则,也不匹配拒绝规则时,代理可以暂停该请求,并将其交给执行框架审批。与 shell 命令示例一样,Codex 可能直接询问用户,也可能将请求路由至自动审核⁠(在新窗口中打开)。收到决定后,代理要么允许请求继续,要么拒绝请求并返回错误响应。

这里的顺序很重要,因为即使是 DNS 查询,也可能泄露编码在主机名中的信息。因此,代理只有在确定请求已获授权或批准后,才会解析所请求的主机名。请注意,范围宽泛的通配符规则或对 DNS 服务的访问权限,仍可能成为数据经 DNS 外泄的通道。

macOS

在 macOS 上,Codex 使用 Seatbelt⁠(在新窗口中打开),这是苹果由内核强制执行的沙箱机制。Seatbelt 策略使用沙箱配置语言 (SBPL) 编写,这是一种基于 Scheme、用于表达沙箱限制的语言。Codex 通过 macOS 的 /usr/bin/sandbox-exec 命令调用 Seatbelt。与 codex sandbox 一样,它先接收描述沙箱的选项,然后再接收要运行的命令:

Bash

1
sandbox-exec -p PROFILE [-Dkey=value]* -- PROG ARGS...

PROFILE 是一个 SBPL 字符串,其中的条目用于配置沙箱。例如,根据沙箱策略,以下 SBPL 片段会允许读写 /dev/null 和 /dev/zero:

Scheme

1
(allow file-read* file-test-existence file-write-data
2
(literal "/dev/null")
3
(literal "/dev/zero"))

在调用沙箱时启用网络代理,会将以下规则注入配置集,使连接仅限于相应的本地端口:

Scheme

1
; local HTTP proxy launched by Codex
2
(allow network-outbound (remote ip "localhost:3128"))
3

4
; local SOCKS proxy launched by Codex
5
(allow network-outbound (remote ip "localhost:8081"))


Codex 的基础配置集以
(deny default) 开头,因此,除非明确允许,否则出站连接仍会被阻止。

最后,SBPL 还可以使用 (param) 包含占位符:

Scheme

1
; Pass -DWRITABLE_ROOT_0=/path/to/dir to specify a folder that cannot be removed.
2
(deny file-write-unlink
3
(require-all
4
(literal (param "WRITABLE_ROOT_0"))
5
(vnode-type DIRECTORY)))

这些占位符由传给 sandbox-exec 的 -Dkey=value 选项填充。

为实现自身的沙箱 API,Codex 从基础策略⁠(在新窗口中打开)出发,构建传给 ⁠(在新窗口中打开)sandbox-exec 的参数列表,再根据 permission_profile 和其他上下文进行调整,生成完整的 Seatbelt 配置集。生成的配置集及配套的 -D 参数用于配置由 Seatbelt 强制实施的限制,而网络代理则负责实施额外的网络规则。完整的参数列表构建好后,调用 sandbox-exec 就很简单了。

生成正确的 SBPL 并不容易,因为苹果没有为第三方提供该语言的文档。事实上,man sandbox-exec 中写明了 The sandbox-exec command is DEPRECATED(sandbox-exec 命令已弃用);通过 man 3 sandbox_init 查阅文档的 sandbox_init() 库函数也已弃用。尽管有弃用警告,macOS 仍在 /usr/share/sandbox 中附带 Seatbelt 配置集,Google Chrome 和 Chromium⁠(在新窗口中打开) 等第三方软件也仍然依赖 Seatbelt。因此,在可预见的未来,我们计划继续使用 Seatbelt。

Linux

为了在 Linux 上创建沙箱,Codex 结合使用 bubblewrap⁠(在新窗口中打开) (bwrap) 和 seccomp-bpf⁠(在新窗口中打开):前者是用于构建隔离环境的命令行工具,后者是用于过滤系统调用的 Linux 内核机制。一个名为“codex-linux-sandbox”的内部辅助程序负责协调设置过程。与 macOS 上的 sandbox-exec 一样,它接收沙箱配置,然后接收要运行的命令:

Bash

1
codex-linux-sandbox SANDBOX_ARGS... -- PROG ARGS...

需要文件系统隔离或代理路由时,codex-linux-sandbox 会调用 bwrap 来创建初始沙箱环境。随后,bwrap 会在其中启动 codex-linux-sandbox --apply-seccomp-then-exec。第二次调用会使用 seccomp-bpf,在运行用户命令之前施加额外限制。

为构建初始沙箱环境,Codex 使用 bubblewrap 在独立的挂载命名空间中创建文件系统视图,使其符合权限配置集中的文件系统规则。由于这是沙箱实现的基础,Codex 自带一份 bwrap,以备用户尚未安装;不过,如果在 PATH 中找到了兼容版本,它会优先使用已安装的 ⁠(在新窗口中打开)bwrap⁠(在新窗口中打开)。实践中,某些 Linux 发行版默认禁止访问用户命名空间⁠(在新窗口中打开),但会为系统自带的 bwrap 设置例外情况。

与 sandbox-exec 类似,bwrap 接收沙箱配置,然后接收要在沙箱内运行的命令。bwrap 不使用 SBPL 等自定义配置语言,而是通过各个命令行标志进行配置。Codex 使用以下选项创建文件系统视图:

  • --bind:指定可写的文件或目录

  • --ro-bind:指定只读的文件或目录

  • --perms 000 --tmpfs DIR --remount-ro DIR:拒绝访问 DIR

  • --perms 000 --ro-bind-data FD FILE:拒绝访问 FILE(其中 FD 是指向 /dev/null 的已打开文件描述符)

为通过这些选项应用拒绝访问的 glob 模式,Codex 会在每次启动命令之前,将模式展开为具体路径。新增的匹配路径不会自动加入该命令的沙箱限制。

Codex 还会指定 --unshare-ipc 和 --unshare-pid 等选项,防止沙箱访问主机上的其他资源,因此 bubblewrap 的作用不只是控制文件可见性。

使用 bubblewrap 时,只要网络被禁用,或连接必须通过网络代理,Codex 就会传入 --unshare-net,为沙箱创建新的网络命名空间。随后,我们使用 seccomp-bpf,对命令可用的网络系统调用和套接字族施加额外限制。


具体来说,我们使用
seccompiler crate⁠(在新窗口中打开),根据所需的过滤器动态编译 BPF 程序⁠(在新窗口中打开),并将其应用到沙箱内的启动器进程,使整个进程树都继承这些约束。因此,bwrap 不会直接运行用户命令,而是运行 codex-linux-sandbox 启动器,先传入启动器自身的配置参数,再附上用户命令:

Bash

1
bwrap BWRAP_ARGS... -- \
2
codex-linux-sandbox --apply-seccomp-then-exec CODEX_LINUX_SANDBOX_ARGS... -- \
3
PROG ARGS...

为了在不提升权限的情况下应用 seccomp 过滤器,启动器会设置 Linux 的 no_new_privs 标志⁠(在新窗口中打开)。子进程会继承这一标志,因此无法在执行其他程序(如 setuid 可执行程序)时获得额外权限。

seccomp 过滤器取决于网络配置。当网络访问被禁用时,我们会阻止多种与网络相关的系统调用,例如 connect(2) 和 bind(2)。不过,在沙箱中启用网络代理时,我们会允许 IP 套接字,以便访问 codex-linux-sandbox 创建的 TCP 监听器;但默认禁止创建独立的 Unix 域套接字,因为它们可能导致意外访问主机资源。

连接网络代理

当沙箱配置需要使用网络代理时,Codex 执行框架会创建一个代理实例,供同一 Codex 对话线程内的多次 codex-linux-sandbox 调用复用。每个沙箱都需要设法从其隔离的网络命名空间中访问这个共享代理。Codex 在该命名空间内提供回环 TCP 监听器,并安排沙箱外的一个进程接受该监听器上的连接,将其转发至代理。

下图以一个代理端点为例展示这套机制,最后一张图展示了经过该端点的一条连接。在启动 bubblewrap 之前,codex-linux-sandbox 会创建一对 Unix 套接字作为控制通道,并派生子进程。子进程运行 run_host_bridge(),等待通过该通道接收监听器的文件描述符:

示意图:Codex 执行框架启动 codex-linux-sandbox,后者派生一个中继进程,两者通过 Unix 套接字控制通道连接。

在此示例中,父进程使用 exec,将自身的程序映像替换为 bwrap。这会建立沙箱,并在其中启动 codex-linux-sandbox --apply-seccomp-then-exec,同时传入控制通道的文件描述符 (FD):

示意图:bwrap 创建沙箱网络命名空间,并在其中启动 codex-linux-sandbox,通过 Unix 套接字控制通道连接沙箱外的中继进程。

在沙箱的网络命名空间内,第二次调用的 codex-linux-sandbox 会创建回环 TCP 监听器,并通过套接字传递其文件描述符。监听器仍与沙箱的网络命名空间关联,因此留在沙箱外的子进程可以接受沙箱内程序的连接,同时在主机的网络命名空间中建立上游连接。传递完成后,两个进程都会关闭各自的控制通道描述符,沙箱内的进程还会关闭其监听器副本。

TCP 监听器就绪后,沙箱内的进程会设置 HTTP_PROXY⁠(在新窗口中打开) 及相关环境变量的值,使其指向该监听器。随后,它会先应用 seccomp,再派生进程并执行用户命令:

示意图:沙箱内的程序连接到回环 TCP 监听器,沙箱外的 codex-linux-sandbox 中继进程将流量转发至 Codex 网络代理。

沙箱外的进程会保持监听器开启。每接受一个连接,它都会与配置的代理建立连接,并双向转发数据。

这套额外的机制为命令提供了专属的网络命名空间,其中包含独立的回环接口。在 macOS 上,Seatbelt 允许命令直接连接到主机回环接口上的指定端口。在 Linux 上,命令则连接到其隔离命名空间内的监听器,再由沙箱外的进程将这些连接转发至配置的代理。通过传递描述符,可以在不向命令暴露主机网络命名空间的情况下建立这种连接。

Windows

今年早些时候,我们实现了 Windows 沙箱,并撰文介绍了我们在 Windows 上构建沙箱的实践。此后,微软发布了一个名为“MXC”的库,以及 Windows 操作系统中的进程隔离新功能。我们目前正在用基于 MXC 库的沙箱替换现有沙箱。

什么是 MXC?

MXC(Microsoft eXecution Container,微软执行容器)是微软推出的沙箱代码执行系统⁠(在新窗口中打开),支持 Windows、Linux 和 macOS 上的多种隔离后端。Codex 在兼容的 Windows 设备上支持基于 MXC 的沙箱,使用原生进程隔离机制,对用户现有环境中运行的命令施加限制。

我们正转向 MXC,以提升安全性和易用性,同时解决现有 Windows 沙箱的几个局限:

  • 设置沙箱需要提升权限或管理员权限

  • ACL 检查和设置操作开销大、速度慢

  • 主机上会持久保留沙箱设置状态,包括

    • ACL

    • 防火墙规则

    • 沙箱用户

    • 控制平面文件

MXC 提供了 JSON 配置模式⁠(在新窗口中打开)。Codex 使用 MXC SDK⁠(在新窗口中打开) 按照该模式构建执行请求,其中包含命令、工作目录、环境和权限。这些权限涵盖文件系统和网络访问权限,以及桌面、剪贴板等 Windows 资源。

将策略转换为 MXC 调用

Codex 对多个控制项使用固定设置,以兼顾兼容性和安全性。它允许读取注册表,并保留 PowerShell 启动时所需的 Win32k 和桌面访问权限。剪贴板访问、输入注入以及桌面和系统设置控制项均被禁用。最后,还会禁止 MXC 回退到修改主机文件系统权限的方式。

Codex 会将权限配置集中的文件系统和网络规则转换为 MXC 配置。以之前的 dev 配置集为例,并假设:

  • C:\、D:\ 和 Z:\ 是这台机器上仅有的本地驱动器。

  • 工作空间根目录和工作目录均为 C:\work\demo。

  • 用户主目录为 D:\Users\dev,因此 ~/build-cache 会解析为 D:\Users\dev\build-cache。

  • 拒绝访问的 glob 模式仅匹配 C:\work\demo\config\dev.env 和 C:\work\demo\config\prod.env。

相应的 MXC 设置将包括:

JSON

1
{
2
...
3
"filesystem": {
4
"readwritePaths": [
5
"C:\\work\\demo",
6
"D:\\Users\\dev\\build-cache",
7
...
8
],
9
"readonlyPaths": [
10
"C:\\",
11
"D:\\",
12
"Z:\\",
13
"C:\\work\\demo\\.agents",
14
"C:\\work\\demo\\.aws",
15
"C:\\work\\demo\\.codex",
16
"C:\\work\\demo\\.devcontainer",
17
"C:\\work\\demo\\.git",
18
"C:\\work\\demo\\.vscode",
19
...
20
],
21
"deniedPaths": [
22
"C:\\work\\demo\\config\\dev.env",
23
"C:\\work\\demo\\config\\prod.env",
24
"C:\\work\\demo\\secrets"
25
]
26
},
27
"network": {
28
"egress": {
29
"default": "deny",
30
"allow": [{
31
"to": [
32
{"cidr": "127.0.0.0/8"},
33
{"cidr": "::1/128"}
34
]
35
}]
36
},
37
"ingress": {
38
"default": "deny",
39
"hostLoopback": "allow"
40
}
41
},
42
...
43
}

驱动器根目录访问

MXC 的文件系统策略默认拒绝访问。因此,Codex 会为本地驱动器根目录添加只读授权,以提供该配置集所允许的广泛读取权限。这些授权会递归生效,但仍受用户现有操作系统 (OS) 权限的约束。

有一点需要注意:驱动器根目录的可写授权不会递归生效,因此 Codex 会将授权范围扩展到驱动器下现有的直接子项。

授权冲突

更具体路径的授权会覆盖上层路径的授权,因此,即使 C:\ 是只读的,其下的 C:\work\demo 仍可设为可写,而 C:\work\demo\.git 则保持只读。

当不同的路径写法或符号链接/目录联接别名指向同一路径时,MXC 会采用更严格的权限:拒绝访问优先于只读,只读优先于读写。

拒绝访问的 glob 模式

MXC 只接受具体的拒绝访问路径,因此 Codex 会在启动前,将拒绝访问的 glob 模式展开为匹配的文件和目录。命令运行期间,新增的匹配路径不会自动加入限制。

网络访问

*.openai.com 等域名规则由前文介绍的共享 Codex 网络代理负责实施。Codex 在沙箱外运行该代理,并通过前文提到的同一组标准 *_PROXY 环境变量,将代理地址传递给命令。MXC 会阻止直接对外连接,但允许连接主机回环接口,包括访问代理。其他本地服务仍然可以访问。

在 macOS、Linux 和 Windows 上,执行框架都使用同一套沙箱 API,在权限配置集的约束下启动命令。各平台专属的实现负责完成应用这些限制所需的设置。

基于 Codex 沙箱构建工具

编写和执行代码,让智能体能够以灵活的方式解决软件开发之外的问题。Codex 沙箱让智能体能够在用户现有的环境中运用这项能力,同时明确限制其文件系统和网络访问。沙箱是执行框架中可复用的基础组件,而 codex sandbox 命令让你自己构建的工具也能使用它。

随着智能体承担更多任务,我们希望让沙箱能切实应用于更多工具和环境。这意味着我们要简化权限配置,并在操作系统提供更完善的保护机制时,及时加以利用。我们的目标是拓展智能体的能力,同时始终让人们掌控它们可以访问的资源。

作者

OpenAI

致谢

特别感谢 David Wiesen、Charlie Weems、Viyat Bhalodia 和 Fotis Chantzis 对本文的贡献。