教程2026-11-19 · 智涌AI

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

Codex 沙箱权限教程头图:左侧 Codex 沙箱权限大字和 3 个内置权限档、读写拒绝 3 种规则、代理默认端口 3128 数据卡,右侧终端展示 dev 权限档继承 workspace、拒绝读取 .env、.vscode 只读,写入 settings.json 被拒并显示 Operation not permitted,以及域名白名单配置

Codex 在你电脑上跑的每一条命令,都在一个由系统内核把关的沙箱里执行。OpenAI 11 月 18 日发了一篇工程文章,把这套沙箱怎么设计、怎么配讲清楚了,配置入口是 config.toml 里的 permission profiles(权限配置档)。这篇按官方文章和文档,把内置档位、自定义档、域名白名单、企业锁定和 codex sandbox 命令过一遍,最后给本地 MCP 服务器也套上沙箱。

前置条件:先把旧的 sandbox_mode 清掉

文档顶部标了 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 或更高版本。

常见坑

完成标准

同类思路在别的 Agent 上也有:NVIDIA 的沙箱按程序加域名放行,见 OpenShell 网络策略教程。

最后

先把第三步的 .vscode 例子在自己的项目里跑一遍,确认 dev 档真的拦得住,再把它设成 default_permissions。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。