一句话结论:Codex sandbox 用操作系统自带的隔离机制接管 Agent 跑命令的过程,三档文件权限(read / write / deny)加一套域名代理规则就能把读写范围和网络出口都锁死,macOS 走 Seatbelt,Linux 走 bubblewrap 配 seccomp-bpf,Windows 换成微软的 MXC。
让 Agent 在本机跑命令这件事,风险点从来不在模型会不会写代码,而在它能碰到什么。删掉一个 .env、往 npm 缓存里塞一段后门、顺手把一个目录整体传出去,这些动作在终端里只需要一行。2026 年 11 月 18 日,OpenAI 工程团队公开了 Codex sandbox 的内部实现,把这套限制拆成了配置文件、权限档案、网络代理和跨平台落地四层。这篇文章按官方原文梳理每一层的实际写法,以及怎么把它套到你自己的工具上。
一、Codex sandbox 到底拦住了什么
先明确一个容易误解的点。OpenAI 没有用虚拟机,也没有用 Docker 容器把命令扔进另一个环境,而是让命令继续跑在你现有的开发环境里,用操作系统自己的沙箱设施去约束它能访问的资源和网络。
官方给出的理由很实际:开发者的笔记本本身就是一套高度定制的工作环境,把它复制进 Docker 容器成本很高,很多工作流还依赖宿主机上的原生工具链。举个具体例子,在 Mac 上用 Codex 开发 iOS 应用,如果塞进容器,Codex 就跑不了 Xcode 的原生构建工具链,也没法启动 iPhone 模拟器。容器方案得把这些操作委托回宿主机执行,那部分又跑到了沙箱之外,得再套一层限制。所以 OpenAI 的选择是:把力气花在把三套系统的原生隔离机制吃透上,让命令待在最合适的那个环境里。
对外暴露的接口只有一个函数,接收命令、工作目录、环境变量、权限档案和网络代理,返回一个子进程句柄:
def spawn_command_under_sandbox(
program_and_args: list[str],
cwd: Path,
env: dict[str, str],
permission_profile: PermissionProfile,
network_proxy: NetworkProxy | None,
) -> Child:
这里有个容易被忽略的设计细节:子进程会继承父进程的沙箱限制。也就是说,一个命令派生出的一整棵进程树都在同一个笼子里,哪怕某个后代进程活得比原始命令更久,也逃不出去。
二、权限档案怎么写:三级权限与继承
权限档案定义在 config.toml 的 [permissions] 段下,文件系统的权限只有三档。官方原文写得很直白:条目可以授予只读访问(read)、授予读写访问(write),或者完全阻断访问(deny)。
内置的 :workspace 是默认档案,它的取向是”允许有意义的工作,但守住关键目录”。具体来说,允许在工作区内写入,但把 .git 和 .codex 这类目录保持只读。这样 Codex 可以直接改源码而不用每次变更都申请权限,同时又挡住了它去改 .codex/config.toml 或者 .git/hooks 里的 Git 钩子。
文件系统的读取权限开得比较宽,遵循用户已有的操作系统权限。原因是编译器和构建工具需要读仓库之外的 SDK、库和配置,把读取限制在工作区内会直接打断大量常规流程。代价也很明确:机器上别处的敏感文件(比如存着 API key 的配置文件)可能依然可读。
网络访问在 :workspace 里是彻底关闭的。这既挡住了直接往外部服务上传,也顺带堵住了把命令能读到的数据外传的路,但副作用是下载依赖这类合法操作也做不了,需要额外授权。
内置档案的只读保护清单在配置里可以直接看到:
[permissions.":workspace".filesystem.":workspace_roots"]
".agents" = "read"
".aws" = "read"
".codex" = "read"
".git" = "read"
自己的档案可以继承内置档案再叠加规则,官方的示例长这样:
# Use the dev profile by default.
default_permissions = "dev"
[permissions.dev]
description = "Development with extra read-only protections."
# A profile can be derived from an existing profile.
# Profiles starting with ":" are provided by Codex.
extends = ":workspace"
[permissions.dev.filesystem]
"~/build-cache" = "write"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
这个 dev 档案在 :workspace 之上加了四件事。允许写 ~/build-cache。把工作区里的 .devcontainer 和 .vscode 设为只读。拒绝所有匹配 **/*.env 的文件。拒绝 secrets 目录。
带冒号的 :workspace_roots 是一组特殊键,规则会作用到每一个工作区根目录。Codex CLI 默认把当前工作目录当作唯一的 workspace root,ChatGPT 桌面应用则用项目的 source folders。路径别名 :root 代表用户主目录。
三、网络怎么限:代理端口与域名规则
网络一共有三种模式。最严格的是完全关闭,也就是 :workspace 的默认行为。最宽松的是 :danger-full-access 档案下的完整直连。第三种是通过代理按域名放行。
要让 dev 档案走代理,需要在 config.toml 里同时做两件事,缺一不可:
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"*.openai.com" = "allow"
# Allow requests to local services by hostname or by IPv4/IPv6 loopback address.
"localhost" = "allow"
"127.0.0.1" = "allow"
"::1" = "allow"
"evil.example" = "deny"
[features]
# If neither local config nor managed requirements enable the proxy,
# this profile allows direct network access; domain rules are not enforced.
network_proxy = true
这里有个容易踩的坑。[features] 里的 network_proxy = true 是全局开关,它决定了域名规则到底会不会被强制执行。如果既没有本地配置也没有托管要求打开代理,域名规则会被整体忽略,档案退化成完整的直连网络访问。也就是说光写域名规则不写 features 段,等于什么都没限制。
规则匹配上,精确域名和通配符模式都支持,显式的 deny 优先于 allow。既没被允许也没被拒绝的域名会被拦下来走审批流程,Codex 可以直接问你,也可以把请求转给 auto-review。
代理本身是 codex-network-proxy 这个 crate,既能作为库被 harness 调用,也能单独构建成命令行工具。启用后默认同时提供 HTTP 代理和 SOCKS5 代理,地址通过环境变量传给沙箱里的进程,除了常见的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY,还会注入 PIP_PROXY 这类应用专用变量。不遵循这些代理变量的程序试图直接连外网,会被操作系统沙箱规则拦下。
端口号是固定的。macOS 上的 Seatbelt 策略写得很直白:
; local HTTP proxy launched by Codex
(allow network-outbound (remote ip "localhost:3128"))
; local SOCKS proxy launched by Codex
(allow network-outbound (remote ip "localhost:8081"))
HTTP 代理在 3128,SOCKS 代理在 8081。代理还处理了一个容易被忽略的泄漏面:它先判断域名是否允许或已经获批,之后才解析主机名,避免 DNS 查询本身把编码在主机名里的信息漏出去。
四、三平台怎么落地:Seatbelt、bubblewrap、MXC
这是整篇里信息密度最高的一段,三套系统的实现路径完全不同。
macOS 用的是 Seatbelt,也就是苹果的内核级沙箱,配合基于 Scheme 的策略语言 SBPL,入口是 sandbox-exec。Codex 基础策略的第一行就是 (deny default),所以除非显式允许,进程不能主动向外发连接。SBPL 支持参数占位符,实际值在启动时通过 -Dkey=value 填进去。官方也坦承了一个现实问题:man 手册里 sandbox-exec 已经被标注为 DEPRECATED,sandbox_init() 同样如此。苹果在 /usr/share/sandbox 里仍提供 Seatbelt 配置文件,Chrome 和 Chromium 这类第三方软件还在依赖它,OpenAI 表示在可预见的未来会继续用。
Linux 走的是 bubblewrap 加 seccomp-bpf,由 codex-linux-sandbox 协调,完整结构是两段嵌套:
bwrap BWRAP_ARGS... -- \
codex-linux-sandbox --apply-seccomp-then-exec CODEX_LINUX_SANDBOX_ARGS... -- \
PROG ARGS...
文件系统视图用 bubblewrap 参数构造,--bind 给可写路径,--ro-bind 给只读路径。拒绝访问某个目录的写法是 --perms 000 --tmpfs DIR --remount-ro DIR,拒绝访问某个文件是 --perms 000 --ro-bind-data FD FILE,其中 FD 指向一个已经打开的 /dev/null。隔离选项包括 --unshare-ipc、--unshare-pid,网络禁用时再加 --unshare-net 造一个全新的 network namespace。
seccomp-bpf 过滤规则由 seccompiler 这个 crate 动态编译,在执行用户命令的 launcher 进程上应用,因为限制被父进程继承,所以覆盖整棵进程树。为了不用提权就能套上 seccomp,launcher 会设置 Linux 的 no_new_privs 标志,这个标志被子进程继承,专门用于阻止通过执行 setuid 程序提权。网络禁用时,seccomp 会直接掐掉 connect(2) 和 bind(2)。
Windows 是最新换掉的一套。旧的 Windows 沙箱设置一次需要管理员权限,ACL 检查和设置又慢又重,还会在宿主机上留下 ACL、防火墙规则、沙箱用户、控制面文件这些持久状态。OpenAI 正在把实现换成微软的 MXC,也就是 Microsoft eXecution Container,这是微软提供的跨 Windows、Linux、macOS 的沙箱化代码执行系统。
Codex 通过 MXC 的 JSON 配置 schema 创建执行请求,权限覆盖文件系统、网络、桌面、剪贴板等资源。为了兼顾兼容性和安全,官方设了几条固定策略:允许注册表读取,保留 PowerShell 启动所需的 Win32k 和桌面访问,禁止剪贴板访问,禁止输入注入,禁止桌面和系统设置控制,并且禁止 MXC 回退到直接改宿主机文件权限的老路子上。
网络策略在 MXC 里长这样,egress 和 ingress 的默认动作都是 deny:
"network": {
"egress": {
"default": "deny",
"allow": [{
"to": [
{"cidr": "127.0.0.0/8"},
{"cidr": "::1/128"}
]
}]
},
"ingress": {
"default": "deny",
"hostLoopback": "allow"
}
}
三套系统放在一起对比,差异一目了然:
| 维度 | macOS | Linux | Windows |
|---|---|---|---|
| 底层机制 | Seatbelt + SBPL | bubblewrap + seccomp-bpf | MXC(Microsoft eXecution Container) |
| 启动入口 | sandbox-exec -p PROFILE | bwrap → codex-linux-sandbox | mxc-sdk 执行请求 |
| 默认网络 | 拒绝(deny default) | –unshare-net + 拦截 connect | egress/ingress 默认 deny |
| 提权防护 | Seatbelt 策略 | no_new_privs 标志 | 禁止回退改宿主机 ACL |
| 代理端口 | 3128 / 8081 | loopback 监听器 + 沙箱外桥接 | 允许 host-loopback |
| 已知限制 | sandbox-exec 已标记弃用 | 部分发行版默认禁用 user namespace | 新实现仍在替换中 |
五、多层配置怎么合并:优先级与托管要求
Codex 会合并来自多个 config.toml 的设置。规则是 Table 递归合并,冲突时优先级更高的配置源获胜,Array 作为整体替换而不是逐项合并。
因为权限是用 Table 表示路径和域名的,团队级配置可以只覆盖单个条目,其余部分自动继承组织基础配置。管理员还可以通过 requirements.toml 限制用户能选的权限档案:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
云端下发的 requirements 优先级高于系统里的 /etc/codex/requirements.toml,系统文件不能覆盖云端明确写下的 false。最终合并结果里,值为 false 或压根不存在的档案就不可用。
六、把 MCP Server 装进沙箱:一份能直接抄的配置
这是整篇文章最实用的一段。默认情况下,通过 stdio 启动的 MCP Server 不会被沙箱化。原因是 Codex 无法可靠推断某个 Server 需要访问哪些文件或网络服务,强行套默认配置会让原本有效的 MCP 配置直接失效。
但这意味着那个 npx 命令拥有运行 Codex 的用户所拥有的全部权限,包括写文件和发网络请求。官方给的解法是用 codex sandbox 命令把它包起来:
[permissions.memory-mcp.filesystem]
# Allow broad reads for Node.js/npm dependencies and configuration.
":root" = "read"
"~/.npm" = "write"
"~/mcp-data" = "write"
[permissions.memory-mcp.network]
enabled = false
[mcp_servers.memory]
command = "codex"
args = [
"sandbox",
"--permission-profile",
"memory-mcp",
"--",
"npx",
"--offline",
"@modelcontextprotocol/[email protected]"
]
效果是能读 Node.js 和 npm 的依赖与配置,只能写 ~/.npm 和 ~/mcp-data,网络完全关闭,并且用 npx –offline 从已缓存的固定版本启动 Server。
有两个前置条件必须注意。沙箱可以往 ~/mcp-data 里写,但不能创建这个目录,所以启动前要自己 mkdir -p。安装依赖同样需要网络,得在沙箱外先跑完 npx 安装命令。
codex sandbox 也能脱离 Agent 会话单独用,验证某条限制是不是真的生效。官方给的例子是往 VS Code 设置文件里塞一个恶意格式化程序路径,在 dev 档案下因为 .vscode 是只读的,macOS 上会报 Operation not permitted。
常见问题
Codex 沙箱会限制我的网络吗,默认能下载依赖吗
不能。内置的 :workspace 档案默认关闭全部网络访问,下载依赖这类操作同样会被挡住。要放开需要显式写 network 段的 enabled = true,或者用 :danger-full-access 档案换取完整直连。前者配合域名规则更可控,后者等于放弃了这一层保护。
我已经写了域名规则,为什么程序还能随便联网
多半是漏了 [features] 段的 network_proxy = true。这个开关决定了域名规则是否被强制执行,缺了它规则会被整体忽略,档案退化成完整的直连网络访问。另外要确认程序是否遵循 HTTP_PROXY 这类环境变量,不遵循的只能靠操作系统沙箱规则去挡。
MCP Server 不沙箱化会有多大风险
默认情况下通过 stdio 启动的 MCP Server 拥有运行 Codex 的用户的全部权限,等于绕过了整套限制。修法是用 codex sandbox –permission-profile 把它包起来,同时记得先建好可写目录、先在沙箱外装好依赖。相关的 MCP 配置与启动问题,可以参考站内已有的 FastMCP 改名与 stdio 启动那篇。
Windows 上的实现和另外两个平台有什么不一样
Windows 用的是微软的 MXC 而不是自研方案,好处是不再需要管理员权限,也不再往宿主机上写 ACL 和防火墙规则这类持久状态。代价是这套实现还在替换过程中,而且 MXC 只接受具体的拒绝路径,像 **/*.env 这种通配规则需要 Codex 在启动命令前展开,运行期间新创建并匹配该通配的路径不会自动被限制。
小结
Codex sandbox 的思路是承认 Agent 必然要在你的机器上动手,那么就把边界划在操作系统这一层,别指望模型自己守规矩。三档文件权限管住读写,域名规则配代理管住网络出口,config.toml 的多层合并让团队能下发统一约束,Seatbelt、bubblewrap、MXC 三套实现保证同一份配置跨平台可用。
对你的实际意义在于,你可以拿同一套方法约束自己的 Agent 工具。用 codex sandbox 命令包一层是最低成本的改法,把网络代理开关和 features 段一起检查一遍是最容易漏的一步。
延伸阅读
- AGENTS.md 投毒实测:Codex 中招率超 90%2 周前
- OpenAI、微软高管内部承认 AI 可替代新闻文章,法院文件曝光2 月前
- Anthropic 发布 Claude Science:科研 AI 工作台上线,资助 50 个项目最高 3 万美元额度2 月前
- OpenAI 用 GPT-6 Astra 一周造硬件:跑分 0.8752 周前
继续读
往下这几篇值得接着看:
- 米哈游 Gamer 模型解析:20 倍延迟压缩与 49.7% 成功率2026-11-18
- GPT-6.2 Astra 怎么选:8 美元每百万 token 与 5.2 分涨幅2026-11-18
- OpenAI 嵌入式评估:4 家机构进驻实验室,50 亿美元收购 Goodfire 落空2026-11-17
