OpenAI ↗ · 2026-11-18 16:00 · UTC+8
Inside the Codex sandbox
媒体报道 OpenAI 原文语言:英文
OpenAI 介绍了其智能体 Harness 工具 Codex 的沙盒设计,该沙盒允许用户在可控的文件系统和网络限制下在本地环境中运行命令。文章探讨了沙盒默认配置的权衡、跨 macOS、Linux 和 Windows 的多平台支持以及安全控制措施。
全文
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 中,因为 node_modules 通常被 Git 忽略。如果用户的编辑器在保存时运行该版本的 Prettier,那么只需保存文件即可在 Codex 沙盒之外执行恶意代码。这就是我们采用纵深防御方法的原因:沙盒限制了命令可以访问的内容,而训练和 alignment(对齐)则帮助模型根据用户的意图使用该访问权限。
有关在企业环境中定制沙盒权限并将其与其他保护措施相结合的指导,请参阅 Codex 安全指南(在新窗口中打开)。
设计沙盒
虚拟机和容器(在新窗口中打开)是用于沙盒化的两种常见机制,但我们在 Codex 沙盒中采取了不同的方法。Codex 没有将计算转移到单独的环境中以提供隔离,而是利用每个平台的沙盒设施来约束在用户现有环境中运行的命令。
对于许多开发者来说,他们的笔记本电脑充当了定制的开发环境,他们可以随时对其进行更改。在 Docker 容器中复制该环境可能需要一定的工作量,并且某些工作流仍然依赖于在宿主机上运行的工具。
例如,考虑使用 Codex 在 Mac 上开发 iOS 应用。如果你决定通过在 Docker 中运行 Codex 来对其进行沙盒隔离,那么 Codex 将无法运行由原生 Mac 可执行文件组成的 iOS 构建工具链,也无法启动 iPhone 模拟器来运行代码。基于 Docker 的工作流可以将构建和模拟器操作委托给 Mac 宿主机,但这些操作将在容器的沙盒之外执行,并且需要它们自己的限制。对于 Codex,我们更倾向于通过大力投资于特定于操作系统的沙盒来保持简单,以便 Codex 能够在最适合当前任务的环境中运行。
该测试工具(harness)通过跨 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 代理循环》(Unrolling the Codex Agent Loop)中所解释的那样,Codex 测试工具负责执行模型生成的工具调用。对于编码任务,最常用的工具是 shell 工具,它运行命令的方式与用户在交互式 shell(例如 Bash)中运行命令的方式非常相似。在这里,我们将研究单次(opens in a new window)exec_command(opens in a new window)shell 工具(opens in a new window),以说明测试工具如何利用沙盒来实现所需的保护。
这是在没有沙盒的情况下,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
# 用户面向的批准问题;仅用于 "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 命令允许你将沙盒化的命令执行融入你自己的工具中。接下来,我们将探讨如何定义权限配置文件。
配置沙盒
命名的权限配置文件允许你在多个项目之间复用相同的文件系统和网络限制。你可以在 config.toml 中的 [permissions] 下定义自己的配置文件。例如,以下定义了一个名为 dev 的配置文件,它扩展了(在新窗口中打开)内置的 :workspace 配置文件:
TOML
1
# 默认使用 dev 配置文件。
2
default_permissions = "dev"
3
4
[permissions.dev]
5
# 当在 Codex CLI 中运行 /permissions 时会显示此内容。
6
description = "具有额外只读保护的开发环境。"
7
8
# 配置文件可以派生自现有的配置文件。
9
# 以 ":" 开头的配置文件由 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
# 允许通过主机名或 IPv4/IPv6 环回地址访问本地服务。
7
"localhost" = "allow"
8
"127.0.0.1" = "allow"
9
"::1" = "allow"
10
"evil.example" = "deny"
11
12
[features]
13
# 如果本地配置和托管需求均未启用代理,
# 则此配置文件允许直接网络访问;域名规则将不被强制执行。
14
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 或在最终合并表中缺省的配置文件将不可用。
这种分离使组织能够在用户在这些限制内定制其配置的同时强制实施限制。所产生的权限配置文件可以由测试框架(harness)使用,或者直接应用于命令,正如我们接下来将看到的。
使用 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 的沙箱机制能够独立于代理会话(agent session)使用。您可以使用相同的配置语言和特定于平台的强制实施来限制您自己的工具启动的命令。
示例:对 MCP 服务器进行沙箱隔离
对于在 config.toml 中配置的 stdio MCP 服务器,Codex 测试框架不会尝试对用于启动服务器的命令进行沙箱隔离。Codex 无法可靠地推断该服务器需要哪些文件或网络服务,因此应用默认的沙箱配置文件可能会破坏原本有效的配置。
例如,为 Codex 配置 @modelcontextprotocol/server-memory MCP 服务器的标准方法如下:
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 cache。这允许 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 使用 Apple 的内核强制沙盒机制 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
; Codex 启动的本地 HTTP 代理
2
(allow network-outbound (remote ip "localhost:3128"))
3
4
; Codex 启动的本地 SOCKS 代理
5
(allow network-outbound (remote ip "localhost:8081"))
Codex 的基本配置文件以 (deny default) 开头,因此除非明确允许,否则出站连接将保持阻止状态。
最后,SBPL 可以包含使用 (param) 的占位符:
Scheme
1
; 传递 -DWRITABLE_ROOT_0=/path/to/dir 以指定无法删除的文件夹。
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 具有挑战性,因为 Apple 没有记录供第三方使用的语言。事实上,man sandbox-exec 指出 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 在单独的挂载命名空间中创建一个文件系统视图,该视图反映了权限文件的文件系统规则。由于这是沙盒实现的基础,如果用户没有安装自己的 bwrap,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 的打开文件描述符)
为了使用这些选项应用拒绝通配符,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 套接字对用作控制通道并进行 fork。子进程运行 run_host_bridge() 并等待通过该通道接收监听器的文件描述符:
在此示例中,父进程使用 exec 将其程序镜像替换为 bwrap. 这会设置沙箱并在其中启动 codex-linux-sandbox --apply-seccomp-then-exec,同时传递控制通道的 FD:
在沙箱的网络命名空间内部,第二次调用 codex-linux-sandbox 会创建一个回环 TCP 监听器并通过套接字传递其文件描述符。该监听器保持与沙箱网络命名空间的关联,允许留在沙箱外部的子进程接受来自沙箱化程序的连接,同时在主机的网络命名空间中打开其上游连接。交接完成后,两个进程都关闭其控制通道描述符,沙箱内部的进程关闭其监听器副本。
一旦 TCP 监听器准备就绪,沙箱内部的进程就会为 HTTP_PROXY(在新窗口中打开)及相关环境变量设置适当的值,以指向该监听器。然后,它在 fork 并执行用户的命令之前应用 seccomp:
沙箱外部的进程保持监听器打开。对于每个接受的连接,它都会打开一个到配置代理的连接并在两个方向上中继数据。
这些额外的机制赋予了命令自身的网络命名空间,包括一个单独的回路接口。在 macOS 上,Seatbelt 允许命令直接连接到主机回路接口上的指定端口。而在 Linux 上,命令则会连接到其隔离命名空间内部的一个监听器,沙盒外部的进程会将这些连接转发给配置好的代理。描述符传递使得这种连接成为可能,同时又不会将主机的网络命名空间暴露给该命令。
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 的配置。使用先前的开发配置文件,并假设:
C:\、D:\ 和 Z:\ 是机器仅有的本地驱动器。
工作区根目录和工作目录是 C:\work\demo。
用户的家目录是 D:\Users\dev,因此 ~/build-cache 解析为 D:\Users\dev\build-cache。
拒绝通配符仅匹配 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 为本地驱动器根目录添加了只读授权,以提供此配置文件所允许的广泛读取权限。这些授权会递归应用,前提是受用户现有的操作系统权限限制。
一个细节:可写驱动器根目录授权不会递归应用,因此 Codex 会将其扩展以包含驱动器现有的直接子级。
冲突授权
更具体的路径会覆盖祖先授权,因此 C:\work\demo 在只读的 C:\ 下可以具有可写性,而 C:\work\demo\.git 仍然保持只读。
当不同的路径拼写或符号链接/连接别名指向同一路径时,MXC 会应用更严格的权限:拒绝优先于只读,只读优先于读写。
拒绝通配符
MXC 只接受具体的拒绝路径,因此 Codex 在启动前会将拒绝通配符展开为匹配的文件和目录。运行期间匹配该通配符的新路径不会自动添加。
网络访问
如 *.openai.com 之类的域规则由前文描述的共享 Codex 网络代理强制执行。Codex 在沙箱外运行该代理,并通过前面提到的标准 *_PROXY 环境变量将其地址传递给命令。MXC 阻止直接的外部连接,同时允许主机回环连接,包括对代理的访问。其他本地服务仍可访问。
在 macOS、Linux 和 Windows 上,工具使用相同的沙箱 API 在权限配置文件下启动命令。平台特定的实现处理应用这些限制所需的设置。
基于 Codex 沙箱
编写和执行代码为代理提供了一种灵活的方式来解决超出软件开发的问题。Codex 沙箱让它们能够在用户现有环境中使用该能力,并对文件系统和网络访问设定明确限制。这是工具链中可复用的原语,codex sandbox 命令使其可供自行构建的工具使用。
随着代理承担更多任务,我们希望让沙箱对更多工具和环境更实用。这意味着让权限配置更简便,并利用更好的操作系统保护机制(当它们可用时)。我们的目标是扩展代理的能力,同时让用户掌控其可访问的内容。
Codex
2026
作者
OpenAI
致谢
特别感谢 David Wiesen、Charlie Weems、Viyat Bhalodia 和 Fotis Chantzis 对本文的贡献。
正文为 AI 译文。