Codex 权限 | 权限配置档案与沙箱网络

权限配置档案不会和旧版沙箱设置叠加。请二选一：要么配置 default_permissions 和 [permissions]，要么配置 sandbox_mode / sandbox_workspace_write，不要同时使用。如果任何已加载的配置文件出现 sandbox_mode，你传入了 --sandbox，或当前选中的配置档案设置了 sandbox_mode，Codex 会使用这些旧版沙箱设置，而不是 default_permissions。

托管的 allowed_permission_profiles 是例外：它会让 Codex 使用权限配置档案。部署托管配置档案允许列表前，请移除 sandbox_mode 和 [sandbox_workspace_write] 等旧设置。如果企业需要混合版本分阶段发布（rollout），可以暂时保留托管的 allowed_sandbox_modes 要求作为兼容约束，直到所有客户端都运行 Codex 0.138.0 或更新版本。

权限配置档案让你对 Codex 代你运行的本地命令应用最小权限边界。一个配置档案是一条具名策略，由文件系统规则和网络规则组合而成：文件系统规则定义命令可以读取或写入什么，网络规则定义命令可以访问哪些目的地。

使用配置档案可以只给 Codex 当前任务所需的访问权限，而不是广泛开放你的机器或网络。例如，只读配置档案可以让 Codex 检查项目但不能编辑；可写配置档案可以把编辑范围限制在选定的工作区根目录内。

本地权限配置档案支持 macOS、Linux、WSL 和原生 Windows。平台特定的细节和注意事项见作用范围和强制执行。

Codex 云端网络设置请参见网络访问。

定义并选择配置档案

Codex 内建三个权限配置档案：

:read-only 让本地命令执行保持只读。
:workspace 允许写入当前活动的工作区根目录和系统临时目录。
:danger-full-access 移除本地沙箱限制，只应在你确实需要这种宽访问时使用。

在 [permissions.<name>] 下创建具名配置档案，然后把顶层 default_permissions 设置为该配置档案名称，或设置为上述内建名称之一。下面示例中的 project-edit 是用户自定义配置档案名，不是内建值。

企业管理员可以通过托管的 requirements.toml 定义配置档案，并限制用户能选择哪些配置档案。一旦存在 allowed_permission_profiles，被省略的配置档案都会被拒绝，包括省略的内建配置档案以及未来 Codex 版本新增的配置档案。推荐的托管配置方式见控制可用权限配置档案。

自定义配置档案使用两个相关概念：

[permissions.<name>.workspace_roots] 添加应纳入该配置档案工作区根目录集合的具体目录。
[permissions.<name>.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。

扩展配置档案

当某个配置档案和内建配置档案或另一个具名配置档案大体相同时，可以使用 extends。优先扩展内建配置档案，而不是完全从零开始，这样基础保护会继续保留。例如扩展 :workspace 时，工作区根目录下的 .codex 目录仍会保持只读，除非你显式覆盖它。先设置一次父配置档案，再只添加或覆盖差异规则。

default_permissions = "project-edit"

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"

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

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

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

这个配置档案会先继承 :workspace，继续拒绝匹配到的 .env 文件，并允许访问 api.openai.com。一个配置档案可以扩展 :read-only、:workspace 或另一个具名配置档案。它不能扩展 :danger-full-access；Codex 也会拒绝未知父级和继承循环。

配置规格

条目	类型 / 值	默认值	说明
`default_permissions`	String 配置档案名称	None	Codex 默认应用的权限配置档案名称。值必须匹配 `[permissions]` 下的配置档案，或 `:workspace` 等内建配置档案。请显式设置它，以获得可预测行为；托管 requirements 只有在 `:workspace` 和 `:read-only` 都被显式允许时才可以省略它。除非托管的 `allowed_permission_profiles` 要求 Codex 在此设置中使用权限配置档案，否则旧版沙箱设置仍会优先生效。
`[permissions.<name>]`	Table	None	定义一个具名配置档案。`default_permissions` 选择默认配置档案；其他权限配置档案设置也使用配置档案名。
`permissions.<name>.description`	String	None	为配置档案提供人类可读说明。配置档案不会通过 `extends` 继承父级的 description。
`permissions.<name>.extends`	String 配置档案名称	None	从另一个具名配置档案或内建 `:read-only` / `:workspace` 配置档案开始构建该配置档案。Codex 会拒绝 `:danger-full-access`、未知父级和继承循环。
`[permissions.<name>.workspace_roots]`	Table	None	添加由配置档案定义的工作区根目录，它们会和当前会话的运行时工作区根目录一起接收 `:workspace_roots` 文件系统规则。
`permissions.<name>.workspace_roots."<path>"`	Boolean	`false`	为 `true` 时，把该路径加入配置档案的工作区根目录集合。值为 `false` 的条目保持不生效。
`[permissions.<name>.filesystem]`	Table	None	把文件系统路径映射到访问值，或映射到带作用域的子路径表。缺失或为空的 filesystem 表会让文件系统访问保持受限，并在启动时发出警告。
`permissions.<name>.filesystem.glob_scan_max_depth`	Number	None	在 Linux、WSL 和原生 Windows 上，限制 deny-read glob 在沙箱启动前快照匹配结果时的展开深度。较大值可能增加启动扫描开销。当无界 `**` pattern 需要有界预展开时，至少设为 `1`。
`[permissions.<name>.filesystem]."<path>"`	`read`, `write`, or `deny`	None	为受支持路径授予直接访问权限。`deny` 拒绝访问，并优先于同等具体度的 `write` 或 `read`。如果当前运行时不能执行直接写规则，Codex 会拒绝该配置。
`[permissions.<name>.filesystem."<path>"]."<subpath>"`	`read`, `write`, or `deny`	None	为 `<path>` 的后代路径授权。用 `.` 表示基础路径。其他子路径必须是相对后代，不能包含 `.` 或 `..` 组件。
`[permissions.<name>.network]`	Table	None	为该配置档案配置网络沙箱代理和沙箱网络策略。
`permissions.<name>.network.enabled`	Boolean	`false`	为该配置档案中的沙箱化命令启用网络访问。这会改变沙箱网络策略，但不会自行启动网络代理。
`[permissions.<name>.network.domains]`	Table	None	把主机模式映射到 `allow` 或 `deny`。如果没有任何 `allow` 条目，域名请求会被阻止。`deny` 条目优先于 `allow`。
`permissions.<name>.network.domains."<pattern>"`	`allow` or `deny`	None	支持精确主机、仅匹配子域的 `.example.com`、匹配 apex 加子域的 `.example.com`，以及只能用于 allow 的全局通配符 ``。主机模式会被 trim、小写、移除尾部点，并剥离简单端口或括号。
`[permissions.<name>.network.unix_sockets]`	Table	None	映射 Unix socket 允许列表覆盖项。仅用于 Docker 等本地集成。
`permissions.<name>.network.unix_sockets."<path>"`	`allow` or `deny`	None	用 `allow` 把某个绝对 Unix socket 路径加入有效允许列表，或用 `deny` 拒绝该路径。被拒绝的条目会从有效允许列表中省略。
`permissions.<name>.network.proxy_url`	URL string	`http://127.0.0.1:3128`	HTTP 代理监听器，用于 `HTTP_PROXY`、`HTTPS_PROXY`、websocket proxy 变量和相关工具代理环境变量。
`permissions.<name>.network.enable_socks5`	Boolean	`true`	启用 SOCKS5 监听器，用于 `ALL_PROXY` 和 FTP proxy 变量。
`permissions.<name>.network.socks_url`	URL string	`http://127.0.0.1:8081`	SOCKS5 监听器地址。
`permissions.<name>.network.enable_socks5_udp`	Boolean	`true`	启用 SOCKS5 监听器时，是否启用 SOCKS5 UDP 支持。
`permissions.<name>.network.allow_upstream_proxy`	Boolean	`true`	允许网络沙箱代理遵循上游 `HTTP(S)_PROXY` 和 `ALL_PROXY` 设置。
`permissions.<name>.network.allow_local_binding`	Boolean	`false`	为 `true` 时关闭本地 / 私有网络保护。为 `false` 时，`localhost` 或 `127.0.0.1` 等精确本地字面量必须显式加入允许列表，解析到本地或私有 IP 的主机名仍会被阻止。
`permissions.<name>.network.dangerously_allow_non_loopback_proxy`	Boolean	`false`	允许代理监听器绑定非 loopback 地址。普通本地开发请保持未设置。
`permissions.<name>.network.dangerously_allow_all_unix_sockets`	Boolean	`false`	在支持 Unix socket proxying 的地方绕过 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/ 保持可读但不可写，匹配的环境文件仍然不可用。

更具体的路径也可以在较宽的 deny 中重新打开一个更窄的子树：

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

支持的路径形式：

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

在原生 Windows 上，home 相对路径也可以使用反斜杠，例如 ~\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 拒绝读取

即使附近有较宽的配置档案规则授予访问权限，也可以用 deny 标记 Codex 不应读取的文件或子树。精确路径适合 ~/.ssh 这类稳定位置；glob pattern 适合覆盖一类在不同仓库中位置会变化的敏感文件。

当 glob 位于 :workspace_roots 下时，Codex 会把它解释为相对于每个有效工作区根目录。例如：

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

这条规则会拒绝读取每个运行时或由配置档案定义的工作区根目录下匹配到的 .env 文件。适合你希望保留正常工作区写权限，同时让环境文件、生成密钥或类似凭据文件保持不可读的场景。

deny glob pattern 支持作为 deny-read 规则。read 或 write glob 在 Linux、WSL 和原生 Windows 沙箱中可移植性较弱，因此应优先使用精确路径，或 "docs/**" = "read" 这类子树规则。

在 Linux、WSL 和原生 Windows 上，无界 ** deny-read pattern 可能需要在沙箱启动前有界预展开。使用 "**/*.env" = "deny" 这类无界 pattern 时，请设置 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"   # apex 和子域名
"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 rebinding 和对本地服务的意外访问。若要刻意允许某个本地字面量目标，请把精确主机或 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 proxying 是面向 Docker 等工具的本地逃生口，应谨慎使用：

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

使用 deny 可以拒绝某个 socket 路径，包括从继承配置中得到的 allow 条目。被拒绝的 socket 路径会从有效允许列表中省略。

启用 Unix sockets 时，请让代理监听器继续绑定到 loopback 地址。

从旧版沙箱设置迁移

当你希望用一个可复用配置档案同时描述文件系统和网络行为时，权限配置档案会替代旧版 sandbox_mode 与 sandbox_workspace_write 组合。一个会话中请只使用其中一套系统。

建议起点：

对只读工作流，使用内建 :read-only 配置档案，或定义一个只在必要位置授予读取权限的自定义配置档案。
对工作区编辑，使用内建 :workspace 配置档案，或定义一个通过 :workspace_roots 写入、并只添加任务所需临时目录或缓存路径的自定义配置档案。
对不受限本地执行，只有当你确实想要最宽本地访问模型时，才使用 :danger-full-access。

配置档案描述的是一个会话的本地默认姿态。组织托管 requirements 仍可添加不应被用户配置放宽的限制。关于管理员强制执行的文件系统和网络约束，请参见托管配置。

范围与执行

权限配置档案定义的是本地沙箱化命令执行的边界。请把它们和审批策略，以及其他 Codex 使用界面的独立控制一起使用。

配置档案控制什么

本地命令执行： 权限配置档案管理在你机器上运行的沙箱化命令。App 连接器、MCP servers、浏览器或 Computer Use（计算机操作）相关界面、Codex 云端环境设置，以及已批准的提权操作，都使用各自的控制。
文件系统写入： 可写配置档案可以创建持久改动。对脚本、构建步骤、package manager 钩子、shell 启动文件和共享目录的写入要视为敏感，因为后续工具或用户可能在原始沙箱上下文之外执行这些文件。
出站目的地： 网络域名规则限制沙箱化命令流量可以通过网络代理访问哪里。它们不判断允许的目的地是否可信，通配符 allow 规则仍然很宽。
本地服务： 本地和私有网络目标默认被阻止。把 localhost、私有 IP、Unix sockets 加入允许列表，或设置 allow_local_binding = true，都会显式打开本地服务访问。

安全限制

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

操作建议

选择仍能完成任务的最窄配置档案，尤其是在你授予写权限或出站网络访问时。请让审批策略、密钥处理和 allow 规则与该访问级别保持一致。

常见配置档案

带网络允许列表的只读配置档案

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"

只有当你确实打算允许公共网络访问时，才使用全局 "*" allow 规则。Deny 规则可以收窄较宽的允许列表。

最近搜索

推荐搜索

权限

定义并选择配置档案

扩展配置档案

配置规格

文件系统权限

用精确路径或 glob 拒绝读取

网络权限

本地和私有网络

Unix sockets

从旧版沙箱设置迁移

范围与执行

配置档案控制什么

安全限制

操作建议

常见配置档案

带网络允许列表的只读配置档案

无网络的工作区写入

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