Codex 沙箱权限怎么配:permission profiles 实战教程

Codex 在你电脑上跑的每一条命令,都在一个由系统内核把关的沙箱里执行。OpenAI 11 月 18 日发了一篇工程文章,把这套沙箱怎么设计、怎么配讲清楚了,配置入口是 config.toml 里的 permission profiles(权限配置档)。这篇按官方文章和文档,把内置档位、自定义档、域名白名单、企业锁定和 codex sandbox 命令过一遍,最后给本地 MCP 服务器也套上沙箱。
前置条件:先把旧的 sandbox_mode 清掉
- 装好 Codex CLI,或者用 ChatGPT 桌面端里的 Codex。官方文档写明权限档在 macOS、Linux、WSL 和原生 Windows 上都支持。
- 知道自己的配置文件在哪:用户级是
~/.codex/config.toml,受信任项目里还可以有.codex/config.toml,离当前目录越近优先级越高。 - 删掉旧写法。权限档和老的
sandbox_mode/[sandbox_workspace_write]不能叠加。任何一层配置里出现sandbox_mode,或启动时带了--sandbox,Codex 就改用老设置,default_permissions不生效。老写法怎么用,站内的 Codex CLI config.toml 配置教程有讲。
文档顶部标了 Beta:这套配置还在开发中,字段可能会变。下面的写法都抄自 11 月中旬的官方页面。
默认档位挡住了外网,但挡不住读你的密钥
Codex 没用虚拟机或容器隔离,而是直接调用各系统自带的沙箱机制:macOS 上是 Seatbelt,Linux 上是 bubblewrap 加 seccomp-bpf,Windows 有自己的一套。OpenAI 举的理由很实际:在 Mac 上开发 iOS 应用,原生工具链和模拟器塞不进 Docker。命令派生出来的子进程会继承同样的限制,后台进程也逃不掉。
| 内置档位 | 文件 | 网络 | 适合 |
|---|---|---|---|
:read-only | 只能读 | 默认关 | 让 Agent 看代码、做审查 |
:workspace | 工作区和系统临时目录可写;.git、.codex、.agents、.aws 只读;工作区外大范围可读 | 关 | 日常改代码 |
:danger-full-access | 不设限 | 直连 | 你明确要放开的时候 |
.git 和 .codex 设成只读,是为了不让命令偷偷改 Git hooks 或 Codex 自己的配置。官方也直说了两个缺口:工作区外的文件大多可读,放在别处的 API 密钥配置照样读得到;Agent 还能改被 Git 忽略的 node_modules,比如往本地的 Prettier 里塞代码,等你在编辑器里保存文件时,它就在沙箱外面跑起来了。
沙箱只管命令能碰到什么。模型拿这些权限去做什么,要靠训练和对齐,还要靠你自己审改动。
第一步:写一个继承 :workspace 的自定义档
官方建议从内置档位继承,基线保护会跟着带过来。下面这个 dev 档来自 OpenAI 的文章,放进 ~/.codex/config.toml:
default_permissions = "dev"
[permissions.dev]
description = "Development with extra read-only protections."
extends = ":workspace"
[permissions.dev.filesystem]
"~/build-cache" = "write"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
每条规则只有三种值:read、write、deny。:workspace_roots 下的路径对每个工作区根目录都生效:CLI 默认把当前目录当唯一的根,桌面端用项目的源码目录。路径越具体优先级越高;同一路径上 deny 压过 write,write 压过 read。反过来也行,比如先把 ~/Documents 设成 deny,再单独把 ~/Documents/codex 设成 write。
想连工作区外的读权限也收紧,文档给了一个更严的写法:在继承 :workspace 的档里加 ":root" = "deny" 和 ":minimal" = "read"。:minimal 是 Codex 判定的常用工具运行所需的最小路径集合,/usr/bin 这类目录都在里面。
写完在 CLI 里运行 /permissions,能看到可选的档和它们的 description。注意 description 不会跟着 extends 继承,自定义档要自己写一行。
第二步:只放行几个域名
网络这块最容易配错。network.enabled = true 只是允许联网,并不会启动代理;不启动代理,域名规则就不生效,命令可以直接连任何地址。要按域名过滤,得同时打开 features.network_proxy:
[features]
network_proxy = true
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"api.openai.com" = "allow"
"*.github.com" = "allow" # 只含子域名
"**.example.com" = "allow" # 主域名加子域名
"tracking.example.com" = "deny" # deny 压过 allow
代理在沙箱外运行,默认起一个 HTTP 代理(127.0.0.1:3128)和一个 SOCKS5 代理(127.0.0.1:8081),通过 HTTP_PROXY、ALL_PROXY 这些标准环境变量告诉命令。不在名单上的域名,请求会先挂起,交给你审批或自动审查,没批就拦掉。代理先判规则再做 DNS 解析,因为主机名本身也能夹带数据。
代理开着时,还有一道本地网络保护:要访问 localhost 或 127.0.0.1,得把这个字面地址单独加进白名单。只有允许的主机名会解析到内网 IP 时,才需要设 allow_local_binding = true。Docker 这类走 Unix socket 的工具,在 network.unix_sockets 里按路径放行。
第三步:用 codex sandbox 验证规则
codex sandbox 能脱离 Agent 会话,在指定档位下跑任意命令,最常见的用法就是试一下规则拦不拦得住。OpenAI 文章里的例子是模拟「往 .vscode 写一个保存时自动执行的恶意格式化器」:
codex sandbox --permission-profile dev -- \
bash -c 'cat > .vscode/settings.json' <<'JSON'
{
"prettier.prettierPath": "./node_modules/evil-prettier",
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true
}
}
JSON
codex sandbox 默认把当前目录当工作区根,所以 dev 档里 .vscode 只读这条会生效。官方文章给出的 macOS 输出是 bash: .vscode/settings.json: Operation not permitted。自己验证时可以多跑几条:读一个 .env、往 ~/build-cache 写文件、curl 一个不在名单上的域名,对照预期逐条看结果。
第四步:给 stdio MCP 服务器套上沙箱
容易漏掉的一点:config.toml 里配置的 stdio MCP 服务器,Codex 不会给它的启动命令加沙箱,因为它猜不出服务器需要哪些文件和网络。按常规写法,npx 启动的服务器拿的是和你一样的全部权限。今天早上站内写过 MCP 令牌别写进命令行,管的是凭据怎么传;这里管的是服务器进程本身能碰什么。
OpenAI 用官方的 memory 服务器做了示范:先定义一个只允许写 npm 缓存和数据目录、不许联网的档,再用 codex sandbox 包住原来的启动命令:
[permissions.memory-mcp.filesystem]
":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/server-memory@1.0.0"]
[mcp_servers.memory.env]
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"
沙箱里能往这个目录写,但不能创建它;而且断网后 npx 装不了包。所以要先在沙箱外准备好:
mkdir -p ~/mcp-data
npx -y --package=@modelcontextprotocol/server-memory@1.0.0 -c true
包进了缓存,npx --offline 就能在断网档下启动服务器。版本号要锁死,不然离线模式找不到对应缓存。
团队和企业:用 requirements.toml 锁住档位
多份 config.toml 会逐层合并:表按键递归合并,冲突时高优先级的赢,数组整个替换。所以权限档的路径和域名都用表来写,团队配置可以只加一两条,其余规则继承组织的基础配置。
管理员还能通过 requirements.toml(系统文件或云端策略)限制用户能选哪些档:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
一旦出现 allowed_permission_profiles,没列出的档一律不可用,包括以后新版本加进来的内置档。云端下发的要求优先于 /etc/codex/requirements.toml。文档提醒,团队里客户端版本参差时,可以暂时保留 allowed_sandbox_modes 做兼容,直到所有人升到 Codex 0.138.0 或更高版本。
常见坑
- 配了权限档却没生效。多半是某层配置里还留着
sandbox_mode,或者启动命令带了--sandbox。项目级.codex/config.toml也要检查。 - 写了域名白名单,结果什么都能连。只开了
network.enabled,没开features.network_proxy。反过来,代理开了却一条allow都没写,所有域名请求都会被拦。 - 新建的 .env 又能读了。在 Linux、WSL 和原生 Windows 上,
deny通配规则是在每个沙箱进程启动时展开成具体路径的。进程启动后新建的匹配文件不在拒绝列表里,长时间运行的 shell、开发服务器都读得到。无上限的**规则还建议配glob_scan_max_depth,值至少为 1。 - 继承 :danger-full-access 报错。文档写明
extends只能接:read-only、:workspace或另一个自定义档,未知父档和循环继承也会被拒。 - filesystem 表留空。文件规则为空时文件访问保持受限,启动时会给警告,不会变成全放开。
完成标准
- 所有配置层都没有
sandbox_mode,/permissions能看到你的自定义档。 codex sandbox --permission-profile dev下,写.vscode、读.env都被拒,写~/build-cache成功。- 名单外的域名会被拦下或弹出审批,名单内的域名正常访问。
- 每个本地 stdio MCP 服务器都包了一层
codex sandbox,有自己的最小档位。
同类思路在别的 Agent 上也有:NVIDIA 的沙箱按程序加域名放行,见 OpenShell 网络策略教程。
最后
先把第三步的 .vscode 例子在自己的项目里跑一遍,确认 dev 档真的拦得住,再把它设成 default_permissions。