Codex 沙箱权限配置:无需完整访问权限,按域名放行 npm
保留 Codex 工作区的保护规则,同时允许访问包注册表。设置权限配置方案与网络代理,验证允许和禁止的操作,并重试依赖安装。了解工作区外文件仍可能可读的风险、操作系统原生沙箱与 Docker 的边界,以及企业管理要求对配置方案选择的限制。
本文内容

如果 Codex 能修改仓库文件,却无法下载 npm 包,先检查沙箱的权限配置方案,而不是调整 API 设置。内置的 :workspace 配置方案默认禁止命令联网,因此在本地 Codex 会话中安装依赖的开发者会遇到这一限制。基于 :workspace 创建配置方案,启用网络代理并放行包注册表的主机名,不必切换到完整访问权限。
截至 2026-11-19,OpenAI 仍将权限配置方案标记为测试版功能。本文配置的是本地命令的执行权限,示例使用 Bash,适用于 macOS、Linux 或 WSL2。
默认工作区配置方案允许哪些操作?
以 Git 仓库作为工作区根目录时,:workspace 允许沙箱内的命令修改源码文件,同时保护指定目录。每个工作区根目录下的 .git、.codex、.agents 和 .aws 都保持只读。因此,命令无法直接修改 .codex/config.toml 之类的仓库配置,也无法直接改写 .git/hooks 下的钩子。这些保护针对工作区根目录下的路径,并不覆盖计算机上所有同名目录。
读取权限的范围更广。只要操作系统中现有的用户权限允许,命令就能读取仓库外的文件。OpenAI 在默认沙箱边界的说明中解释,这样才能使用存放在其他位置的编译器、SDK、库和配置。这并不意味着这些文件对 Codex 命令不可见。
默认禁网,是为了避免“可以读取数据的命令”自动获得向外上传数据的能力。同样,下载依赖也需要额外访问权限。OpenAI 还明确说明,子进程会继承父进程的沙箱限制。即使原始命令已经结束,仍在运行的后代进程也继续受限。
如果只是偶尔下载一次,先审核网络访问请求,不必修改默认配置方案。根据网络代理机制说明,Codex 可能直接向你请求批准,也可能交给自动审核。需要反复下载依赖时,再使用专门放行注册表的配置方案;不需要网络的工作流则继续保持禁网。
为 npm 注册表配置 dev 方案
已安装的 Codex CLI 需要支持文档中的 codex sandbox --permission-profile 接口。下面的检查还需要 npm、curl 和 Bash。验证策略时,请使用检查后可以丢弃的临时 Git 工作副本,并从其根目录执行命令。
编辑个人配置文件 ~/.codex/config.toml。将下列设置合并到已有的表中,不要重复定义同一张 TOML 表。这会将 dev 设为默认权限配置方案。
不要把这套配置与旧版 sandbox_mode 或 [sandbox_workspace_write] 设置混用。权限配置方案文档要求选择其中一种配置方式,而不是同时使用两套。
default_permissions = "dev"
[features]
network_proxy = true
[permissions.dev]
description = "Workspace editing with npm registry access."
extends = ":workspace"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
".env" = "deny"
".env.local" = "deny"
"secrets" = "deny"
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"registry.npmjs.org" = "allow"
"example.com" = "deny"
extends = ":workspace" 保留内置保护,包括 .git 和 .codex 的只读限制。新增的文件系统规则将编辑器和开发容器的配置设为只读,并禁止访问每个工作区根目录下列出的环境变量文件,以及 secrets 目录和全部下级内容。OpenAI 对文件系统权限值的定义是:read 只允许读取,write 允许读写,deny 禁止访问。
网络配置包含两个独立开关。permissions.dev.network.enabled = true 允许联网;network_proxy = true 则启用域名规则的执行。网络权限文档说明,如果启用网络却没有启用代理,命令会获得直接网络访问权限,域名规则也不会生效。因此,不要省略代理设置。
OpenAI 的企业安全配置指南在依赖访问示例中使用了 registry.npmjs.org。这里的 example.com 是明确禁止的目标,用于后面的拒绝测试。按照文档中的域名规则,显式禁止规则优先于匹配的允许规则;访问其他目标则需要审批,或会被阻止。
这套配置不会无限制放行安装包时可能联系的所有主机。确认项目为什么需要某个主机后,再添加它的主机名。
同时验证允许和禁止的操作
使用 codex sandbox,直接在指定配置方案下测试命令。加上 --include-managed-config,使解析配置方案时也纳入管理员下发的要求。当企业策略限制可选方案时,这一步尤其重要。
先在 Bash 中检查注册表连接:
codex sandbox --permission-profile dev --include-managed-config -- \
npm ping --registry=https://registry.npmjs.org \
--cache="$PWD/.npm-cache"
成功的 npm ping 会输出 PONG。这里的 cache 选项将 npm 缓存放在工作区内,避免为工作区外的缓存额外授予写入权限。这只能证明注册表连接成功,不代表每个依赖都能安装,也不代表所有安装脚本都能执行完成。
接着检查工作区写入、Git 元数据保护和禁止访问的域名。请分别运行这些命令。Git 检查要求 .git 是已存在的目录,而不是指向实际仓库目录的文件。
# Expect success: create and remove a temporary workspace file.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp ./codex-write-check.XXXXXX) && rm "$p"'
# Expect a filesystem permission denial.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp .git/codex-write-check.XXXXXX) && rm "$p"'
# Expect a proxy policy rejection.
codex sandbox --permission-profile dev --include-managed-config -- \
curl --fail --head --max-time 15 https://example.com
预期结果是:工作区写入成功,.git 写入被拒绝,网络请求被拒绝。配置错误、目录不存在或无关的连接故障,都不能证明目标限制已经生效。如果任一禁止操作反而成功,请先停止使用该方案,检查实际生效的配置,再用于正常工作。以上是供你运行的验证步骤,不是已经完成的实测结果。
得到预期结果后,从仓库根目录启动新的 Codex 会话。运行 /permissions,查看 dev 条目及其说明,这一点可参考 OpenAI 的配置方案示例。确认该方案处于启用状态后,重试原本的依赖安装任务。将缓存保留在工作区内,或者只给确实需要的外部缓存目录授予 write 权限。
下载仍然失败时,应该检查什么?
如果配置方案没有生效,先检查已加载的配置中是否还包含旧版沙箱设置。然后查看配置优先级:命令行覆盖项或受信任项目的配置,都可能覆盖个人默认设置。不要持续给当前会话根本没有使用的方案增加权限。
如果 npm ping 成功,但安装仍然失败,应分别检查失败请求的目标地址和报错的文件系统路径。访问其他主机名需要单独决定是否放行;向工作区外写入缓存需要对应的文件系统规则。文件系统权限与网络权限相互独立,允许联网并不会增加文件写入权限。
如果已允许的目标仍无法访问,检查客户端是否采用了代理设置。OpenAI 的网络代理实现说明指出,有些程序不会遵循代理环境变量。应排查客户端或其配置,而不是直接移除沙箱限制。
Codex 自身无法连接模型提供商,与沙箱内的包管理器命令被阻止,是两类不同的问题。有关提供商认证、Base URL 或协议配置,请参考单独的 Codex API 接入指南。
API 密钥文件仍可能被读取吗?
可能。只读保护阻止的是修改,不是读取。OpenAI 在介绍 Codex 沙箱的文章中直接说明了这一取舍,译文如下:
代价是,计算机其他位置的敏感文件也可能仍可读取,例如包含 API 密钥的配置文件。
因此,默认配置方案并不保证仓库外的秘密信息对命令不可见。
示例只禁止访问相对于根目录的指定路径 .env、.env.local,以及 secrets 目录和全部下级内容。它不会覆盖所有可能存放凭据的文件名或位置。请根据自己的环境,为敏感路径添加适当的 deny 规则,必要时也包含工作区外的路径。用不含敏感信息的测试文件验证,不要打印真实凭据。
可写文件也仍然存在风险。OpenAI 描述了修改 node_modules/prettier 之类已安装包的风险:编辑器之后可能在沙箱外运行被修改的格式化工具。由于 node_modules 经常被 Git 忽略,这类修改可能不会出现在 git status 中。除了 Git 跟踪的源码变更,也应检查可写的工具和生成的依赖文件。
同时使用多个编程代理的团队,还应检查 Claude Code 对秘密信息和 Git 的权限配置。每个工具都应采用自己的配置方式,不要把 Codex 的权限配置键复制到其他客户端。
为什么使用原生沙箱,而不是 Docker?
原生沙箱让 Codex 使用现有开发工具,同时通过操作系统限制它启动的命令。OpenAI 在原生沙箱设计说明中解释,采用这种方式,是为了避免要求用户在容器里重新搭建整个开发环境。
在 Mac 上开发 iOS 应用就是一个具体例子。在 OpenAI 描述的工作流中,Docker 容器无法运行 Mac 原生构建工具链,也无法启动 iPhone 模拟器。如果把这些操作委托给 Mac 宿主机,它们就会在容器沙箱之外执行,因此宿主机上的操作仍需要单独限制。
在 macOS 上,Codex 使用 Seatbelt。对于 Linux 和 WSL2,OpenAI 的沙箱设置指南建议通过发行版的包管理器安装 bubblewrap。沙箱启动失败和注册表请求被拒绝,应作为不同的问题排查。
Windows 原生运行环境需要单独验证。Windows 沙箱文档推荐在兼容设备上使用 MXC,同时提醒旧版 unelevated 实现不支持禁止读取指定路径。WSL2 中的 Bash 检查通过,不能替代 Windows 原生环境下的限制验证。
如果整个工作流都能在容器内完成,容器仍然是一个选择。如果工具链依赖宿主机,就应识别并限制宿主机上的操作,不要假定容器也能约束委托给宿主机的工作。
企业能否禁止选择 dev 配置方案?
可以。管理员能通过受管的 requirements.toml 限制用户可以选择哪些配置方案。本地定义一个方案,并不能覆盖这项限制。OpenAI 的管理要求示例给出了以下管理员策略:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
存在 allowed_permission_profiles 时,最终合并后的表就是完整的允许列表。表中未列出的方案,以及明确设为 false 的方案,都不允许使用。如果上面的示例就是最终合并后的管理允许列表,自定义的 dev 方案便不可用,因为它没有获准使用。请让管理员批准适合构建任务的方案,不要尝试绕过策略。
受管配置文档还说明了一条重要的版本边界:权限配置方案的允许列表要求 Codex 0.138.0 或更高版本。Codex 0.137.0 及更早版本会忽略 allowed_permission_profiles 和受管的 default_permissions。依赖这项控制之前,请检查每个受管客户端的版本。
推广配置前,应在每种受支持的操作系统上,分别验证一次允许的构建和一次明确禁止的操作。将注册表权限限制在必要范围内,确认选择了预期的配置方案,并在更新客户端时继续保留拒绝测试。