本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/permissions

权限

配置 beta Codex 权限配置文件以控制文件系统和网络访问

Beta。权限配置文件仍在积极开发中，后续可能会发生变化。

权限配置文件不能与旧版沙箱设置组合使用。请配置 default_permissions 和 [permissions]，或 sandbox_mode / sandbox_workspace_write，但不要同时配置两者。如果任一活动配置层中 出现 sandbox_mode、你传入了 --sandbox，或者某个配置 profile 设置了 sandbox_mode，Codex 将使用这些旧版沙箱设置，而不是 default_permissions。

权限配置文件允许你为 Codex 代表你运行的本地命令应用最小权限边界。配置文件是一个具名策略，它将文件系统规则（定义命令可以读取或写入什么）与网络规则（定义命令可以访问哪些目标）结合起来。

使用配置文件可以让 Codex 获得完成当前任务所需的足够访问权限，而不会向你的机器或网络授予过于宽泛的权限。例如，只读配置文件可以让 Codex 检查项目而不进行编辑，而具备写入能力的配置文件则可以将编辑限制在选定的工作区根目录内。

本地权限配置文件支持 macOS、Linux、WSL 和原生 Windows。平台特定的强制执行细节和注意事项见安全限制。

关于 Codex cloud 网络设置，请参见互联网访问。

定义并选择一个配置文件

Codex 内置了三个权限配置文件：

• :read-only 使本地命令执行保持只读。
• :workspace 允许在活动工作区根目录内写入。
• :danger-full-access 会移除本地沙箱限制，应仅在确实有意授予这种广泛访问权限时使用。

在 [permissions.] 下创建一个具名配置文件，然后将顶层 default_permissions 键设置为该配置文件名或上述某个内置值。 在此示例中，project-edit 是用户自定义的配置文件名，而不是内置值。

自定义配置文件使用两个相关概念：

• [permissions..workspace_roots] 添加应被视为该配置文件工作区根目录的具体目录。
• [permissions..filesystem.":workspace_roots"] 定义 Codex 在每个有效工作区根目录内应用的文件系统规则：当前会话的运行时工作区根目录，加上上面由配置文件定义的根目录。

配置文件也使用常规的配置层模型。优先级更高的层可以在同一配置文件名下添加或替换条目，而无需重述整个配置文件。

例如，组织级配置和用户级配置可以独立扩展同一个配置文件：

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

当 server 处于活动状态时，这两个工作区根目录都会参与构成有效配置文件。

default_permissions = "project-edit"

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

此配置文件会：

• 读取常见开发工具所需的最小运行时路径。
• 将相同的工作区根目录规则应用于当前会话以及配置文件定义的根目录。
• 让 .devcontainer/ 这类邻近 IDE 的设置在每个根目录下保持只读。
• 通过 glob 规则拒绝匹配的环境文件。
• 仅通过已配置的域名策略允许网络访问。

在活动配置文件内部，即使较宽泛的路径可读或可写，范围更窄的 deny 规则仍然生效。例如，一个配置文件可以让工作区根目录可写，同时仍将匹配的 .env 路径设置为 deny。

配置规范

条目	类型 / 值	默认值	详情
default_permissions	字符串配置文件名	None	指定 Codex 默认应用的权限配置文件。该值必须匹配 [permissions] 下的某个配置文件，或匹配 :workspace 之类的内置配置文件。启用权限配置文件时为必填。如果旧版沙箱设置处于活动状态，Codex 将改用这些旧版沙箱设置。
[permissions.]	表	None	定义一个配置文件及其标识符。default_permissions 选择其中一个配置文件作为默认值；其他权限配置文件选择器也使用该配置文件名。
[permissions..workspace_roots]	表	None	添加由配置文件定义的工作区根目录，这些根目录会与当前会话的运行时工作区根目录一起接收 :workspace_roots 文件系统规则。
permissions..workspace_roots.""	Boolean	false	当值为 true 时，将该路径添加到配置文件的工作区根目录集合中。设置为 false 的条目保持不启用状态。
[permissions..filesystem]	表	None	将文件系统路径映射到访问值或作用域子路径映射。缺失或为空的文件系统表会使文件系统访问保持受限，并在启动时发出警告。
permissions..filesystem.glob_scan_max_depth	Number	None	在 Linux、WSL 和原生 Windows 上，当 Codex 在沙箱启动前通过快照预先展开匹配项时，限制 deny-read glob 的展开深度。较大的值可能增加启动时的扫描工作量。当无界的 ** 模式需要有界预展开时，请使用至少为 1 的值。
[permissions..filesystem].""	read, write, or deny	None	为受支持的路径授予直接访问权限。deny 会拒绝访问，并且优先于同等特异性的 write 或 read 条目。对于活动运行时无法强制执行的直接写入规则，Codex 会拒绝。
[permissions..filesystem.""].""	read, write, or deny	None	为 `` 的某个后代路径授予访问权限。对基础路径请使用 .。其他子路径必须是相对后代路径，且不能包含 . 或 .. 组件。
[permissions..network]	表	None	为该配置文件配置网络沙箱代理和沙箱网络策略。
permissions..network.enabled	Boolean	false	为该配置文件中的沙箱命令启用网络访问。这会更改沙箱网络策略；它本身不会启动网络代理。
[permissions..network.domains]	表	None	将主机模式映射为 allow 或 deny。如果没有任何 allow 条目，域名请求会被阻止。deny 条目会覆盖 allow 条目。
permissions..network.domains.""	allow or deny	None	支持精确主机、用于子域名的 *.example.com、用于顶级域加子域名的 **.example.com，以及作为仅允许用途的全局通配符 *。主机模式会经过规范化处理：去除首尾空白、转为小写、去掉末尾点号，并去掉简单端口或方括号。
[permissions..network.unix_sockets]	表	None	映射 Unix socket 允许列表覆盖项。仅用于 Docker 等本地集成。
permissions..network.unix_sockets.""	allow or none	None	使用 allow 将绝对 Unix socket 路径添加到有效允许列表中，或使用 none 清除继承的允许条目。none 并不是单独的拒绝列表判定。
permissions..network.proxy_url	URL string	http://127.0.0.1:3128	用于 HTTP_PROXY、HTTPS_PROXY、websocket 代理变量及相关工具代理环境变量的 HTTP 代理监听地址。
permissions..network.enable_socks5	Boolean	true	启用用于 ALL_PROXY 和 FTP 代理变量的 SOCKS5 监听器。
permissions..network.socks_url	URL string	http://127.0.0.1:8081	SOCKS5 监听地址。
permissions..network.enable_socks5_udp	Boolean	true	在启用 SOCKS5 监听器时启用 SOCKS5 UDP 支持。
permissions..network.allow_upstream_proxy	Boolean	true	允许网络沙箱代理在出站请求中遵循上游 HTTP(S)_PROXY 和 ALL_PROXY 设置。
permissions..network.allow_local_binding	Boolean	false	当值为 true 时，禁用本地/私有网络保护机制。当值为 false 时，像 localhost 或 127.0.0.1 这样的精确本地字面量必须被显式加入允许列表，而解析到本地或私有 IP 的主机名仍会被阻止。
permissions..network.dangerously_allow_non_loopback_proxy	Boolean	false	允许代理监听器绑定到非 loopback 地址。普通本地开发时请保持未设置。
permissions..network.dangerously_allow_all_unix_sockets	Boolean	false	在支持 Unix socket 代理的场景下绕过 Unix socket 允许列表。这是一个宽泛的本地逃逸开口。

文件系统权限

文件系统条目使用 read、write 或 deny：

访问权限	含义
read	允许命令读取文件并列出该路径下的目录。命令不能在该处创建、修改、重命名或删除文件。
write	允许命令读取并修改该路径下的文件，包括在操作系统允许时创建、重命名和删除文件。
deny	拒绝该路径下的读取和写入。可用它从更宽泛的 read 或 write 授权中划出一个被拒绝的子路径。

更具体的条目会覆盖更宽泛的条目。当两个条目针对同一路径时，deny 的优先级高于 write，而 write 的优先级高于 read。

这种优先级允许配置文件先描述一个宽泛的工作区域，然后再划出应保持不可读的文件或目录：

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

在此示例中，工作区根目录保持可写，.devcontainer/ 保持可读而不会变成可写，匹配的环境文件则对沙箱命令保持不可用。

更具体的路径也可以在更宽泛的拒绝范围内重新开放一个更窄的子树：

[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"

支持的路径形式：

路径	含义	限定子路径
:root	文件系统根	仅 .
:minimal	常用工具所需的平台和运行时路径	仅 .
:workspace_roots	当前会话的工作区根，以及任何已启用的、由配置文件定义的工作区根	是
:tmpdir	$TMPDIR 位置（如果可用）	仅 .
/absolute/path	平台绝对路径，例如 macOS/Linux/WSL 上的 /path 或原生 Windows 上的 C:\path	是
~/path	当前用户主目录下的路径	是

在原生 Windows 上，相对主目录的路径也可以使用反斜杠，例如 ~\work。

仅当某个配置文件确实需要广泛的读取覆盖范围时才使用 :root：

[permissions.audit.filesystem]
":root" = "read"

在 :workspace_roots 下使用嵌套条目，可以将访问范围限定到相对于工作区根的子路径：

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"          # 每个工作区根
"docs" = "read"        # 每个工作区根下的 docs 目录
"generated" = "deny"   # 每个工作区根下的 generated 目录

嵌套子路径必须保持在其工作区根内部。像 ../other-repo 这样的父级遍历会被拒绝。

使用精确路径或 glob 拒绝读取

对于 Codex 不应读取的文件或子树，请使用 deny，即使附近有更宽泛的配置规则授予了访问权限。精确路径很适合 ~/.ssh 这样的稳定位置。glob 模式更适合这样的情况：某个配置文件需要覆盖一类敏感文件，但其精确位置会因仓库而异。

当某个 glob 位于 :workspace_roots 下时，Codex 会将其解释为相对于每个生效的工作区根。例如：

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

此规则会拒绝读取在每个运行时工作区根或配置文件定义的工作区根下找到的匹配 .env 文件。当你希望保留正常的工作区写入能力，同时让环境文件、生成的密钥或类似包含凭据的文件保持不可读时，可以使用它。

deny glob 模式支持作为拒绝读取规则。read 或 write glob 在 Linux、WSL 和原生 Windows 的沙箱中可移植性较差，因此在可能的情况下，优先使用精确路径或子树规则，例如 "docs/**" = "read"。

在 Linux、WSL 和原生 Windows 上，无边界的 ** 拒绝读取模式可能需要在沙箱启动前进行有边界的预展开。当你使用像 "**/*.env" = "deny" 这样的无边界模式时，请设置 glob_scan_max_depth：

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

glob_scan_max_depth 必须至少为 1。更高的值会在沙箱启动前扫描得更深，这可能会增加 Linux、WSL 和原生 Windows 上的启动工作量。如果你不想使用有边界展开，可以枚举显式深度，例如 *.env、*/*.env 和 */*/*.env。

如果相同规则应适用于不止当前会话根目录，请将可复用的工作区根添加到配置文件中：

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

当此配置文件处于活动状态时，Codex 会将 :workspace_roots 规则应用于当前会话的运行时工作区根，以及每个已启用的、由配置文件定义的工作区根。

在原生 Windows 上，支持像 D:\work 这样的盘符路径以及像 \\server\share 这样的 UNC 路径作为绝对路径。

网络权限

将 enabled = true 设为允许所选配置文件进行网络访问：

[permissions.project-edit.network]
enabled = true

启用网络访问后，Codex 默认使用完整网络行为。大多数配置文件还应定义域名规则：

[permissions.project-edit.network.domains]
"example.com" = "allow"      # 精确主机
"*.example.com" = "allow"    # 仅子域名
"**.example.com" = "allow"   # 顶级域和子域名
"ads.example.com" = "deny"   # deny 优先于 allow

网络沙箱代理默认绑定到本地监听器：

[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = true

除非你要与特定运行时集成，否则请保持这些监听器设置为默认值。dangerously_* 网络键是为专门环境准备的逃生口，不应用于普通的本地开发。

本地和私有网络

Codex 默认应用本地/私有网络保护，以防御 DNS 重绑定以及对本地服务的意外访问。若要有意允许某个字面量本地目标，请将精确主机名或 IP 字面量加入允许列表：

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

仅当配置文件必须访问解析为本地或私有地址的已允许主机名时，才设置 allow_local_binding = true：

[permissions.project-edit.network]
enabled = true
allow_local_binding = true

[permissions.project-edit.network.domains]
"localhost" = "allow"

Unix sockets

Unix socket 代理是面向 Docker 等工具的本地逃生口。请谨慎使用：

[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "none"

使用 none 可以清除从更低优先级配置层继承而来的 socket 允许条目。它不是类似域名规则中的拒绝规则。

启用 Unix sockets 时，请将代理监听器保持绑定到回环地址。

从旧版沙箱设置迁移

当你希望使用一个可复用的配置文件同时描述文件系统和网络行为时，权限配置文件可替代旧的 sandbox_mode 与 sandbox_workspace_write 组合。对于一个会话，请使用其中一种系统，不要同时使用两者。

建议的起点：

• 对于只读工作流，使用内置的 :read-only 配置文件，或定义一个仅在需要处提供读取权限的自定义配置文件。
• 对于工作区编辑，使用内置的 :workspace 配置文件，或定义一个通过 :workspace_roots 写入并仅添加该工作流所需额外临时或缓存路径的自定义配置文件。
• 对于不受限制的本地执行，仅在你有意采用最宽泛的本地访问模型时使用 :danger-full-access。

配置文件描述的是会话的本地默认姿态。由组织管理的要求仍然可以添加限制，而用户配置不应放宽这些限制。参见 Managed configuration 了解由管理员强制执行的文件系统和网络约束。

作用域与强制执行

权限配置文件定义了本地沙箱命令执行的边界。请将它们与审批策略以及针对其他 Codex 表面的独立控制一起使用。

配置文件控制的内容

• 本地命令执行： 权限配置文件管理在你的机器上运行的沙箱命令。应用连接器、MCP 服务器、浏览器或 computer-use 界面、Codex 云环境设置以及已批准的提权使用各自的控制机制。
• 文件系统写入： 具备写入能力的配置文件可以创建持久性更改。应将对脚本、构建步骤、包管理器钩子、shell 启动文件和共享目录的写入视为敏感操作，因为后续工具或用户可能会在原始沙箱上下文之外执行这些文件。
• 出站目标： 网络域规则会限制沙箱命令流量可通过网络代理访问的位置。它们并不决定某个已允许目标是否可信，而且通配符允许规则仍然具有很宽泛的范围。
• 本地服务： 默认会阻止本地和私有网络目标。将 localhost、私有 IP、Unix sockets 加入允许列表，或设置 allow_local_binding = true，都会显式开放对本地服务的访问。

强制执行方式

• 在 macOS 上，Codex 使用 Seatbelt 沙箱配置文件。如果所选策略无法由平台沙箱强制执行，Codex 会拒绝运行该命令，而不是在未加沙箱的情况下悄悄运行它。
• 在 Linux 和 WSL 上，Codex 使用 bubblewrap 和 seccomp，并提供 Landlock 作为兼容性回退路径。最强的强制执行路径取决于用户命名空间和内核支持；受限的容器宿主机可能会强制使用兼容路径，而不受支持的拆分策略会被拒绝。
• 在原生 Windows 上，elevated 沙箱 最强，因为它可以使用专用的低权限沙箱用户、文件系统权限边界和防火墙规则。unelevated 沙箱是一种回退方案，网络隔离较弱，且无法强制执行每一种拆分读/写例外，因此不受支持的策略会被拒绝。需要 Linux 沙箱模型时，请使用 WSL。

操作指导

选择在仍能完成任务的前提下最严格的配置文件，尤其是在授予写入权限或出站网络访问权限时。让审批策略、密钥处理和允许规则与该访问级别保持一致。

常见配置文件

带网络允许列表的只读

default_permissions = "readonly-net"

[permissions.readonly-net.filesystem]
":minimal" = "read"

[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"

[permissions.readonly-net.network]
enabled = true

[permissions.readonly-net.network.domains]
"api.openai.com" = "allow"

无网络的工作区写入

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"

[permissions.project-edit.network]
enabled = false

带公共 Web 访问的工作区写入

default_permissions = "workspace-net"

[permissions.workspace-net.filesystem]
":minimal" = "read"

[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"

[permissions.workspace-net.network]
enabled = true

[permissions.workspace-net.network.domains]
"*" = "allow"

仅当你确实打算允许公共网络访问时，才使用全局 "*" 允许规则。拒绝规则可以缩小宽泛允许列表的范围。