权限

身份 非官方简体中文镜像

翻译状态 AI 翻译 / AI 审校

来源版本 官方未提供

同步日期 2026-07-26

官方原文 learn.chatgpt.com

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

权限配置文件不能与旧版沙箱设置组合使用。请配置 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] 等旧版设置。对于混合版本的企业部署，在所有客户端都运行 Codex 0.138.0 或更高版本之前，你可以暂时保留托管的 allowed_sandbox_modes 要求作为兼容性约束。

权限配置文件让你能够为 Codex 代表你运行的本地命令应用最小权限边界。配置文件是一项命名策略，将文件系统规则与网络规则结合起来：文件系统规则定义命令可以读取或写入的内容，网络规则定义命令可以访问的目标。

使用配置文件为 Codex 当前聊天提供足够的访问权限，同时不授予它对你的计算机或网络的广泛访问权限。例如，只读配置文件可以让 Codex 检查项目而不进行编辑，而支持写入的配置文件则可以将编辑范围限制在选定的工作区根目录内。

macOS、Linux、WSL 和原生 Windows 均支持本地权限配置文件。有关平台特定的详细信息和注意事项，请参阅范围与强制执行。

有关 Codex cloud 的网络设置，请参阅 Internet Access。

定义和选择配置文件

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 规则拒绝匹配的环境文件。
• 仅通过配置的域名策略允许网络访问。

在活动配置文件中，即使更宽泛的路径可读或可写，更具体的拒绝规则仍然有效。例如，配置文件可以允许写入工作区根目录，同时仍将匹配的 .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	字符串配置文件名	None	指定 Codex 默认应用的权限配置文件。必须匹配 [permissions] 下的配置文件，或 :workspace 等内置配置文件。请显式设置此项以获得可预测的行为；仅当 :workspace 和 :read-only 均被显式允许时，托管要求才可以省略此项。在此配置中，只有托管的 allowed_permission_profiles 告知 Codex 使用权限配置文件时，Codex 才会使用权限配置文件；否则会使用旧版沙箱设置。
[permissions.<name>]	表	None	定义一个命名配置文件。default_permissions 选择一个配置文件作为默认配置；其他权限配置文件设置也使用该配置文件名称。
permissions.<name>.description	字符串	None	为配置文件提供人类可读的描述。配置文件不会通过 extends 继承其父配置文件的描述。
permissions.<name>.extends	字符串配置文件名	None	从另一个命名配置文件，或内置的 :read-only、:workspace 配置文件开始配置。Codex 会拒绝 :danger-full-access、未知父配置文件以及继承循环。
[permissions.<name>.workspace_roots]	表	None	添加由配置文件定义的工作区根目录，使其与当前会话的运行时工作区根目录一起获得 :workspace_roots 文件系统规则。
permissions.<name>.workspace_roots."<path>"	布尔值	false	当值为 true 时，将该路径添加到配置文件的工作区根目录集合中。值为 false 的条目保持未激活状态。
[permissions.<name>.filesystem]	表	None	将文件系统路径映射到访问值或作用域子路径映射。缺失或为空的文件系统表会使文件系统访问保持受限，并发出启动警告。
permissions.<name>.filesystem.glob_scan_max_depth	数字	None	当 Codex 在沙箱启动前对匹配项创建快照时，限制 Linux、WSL 和原生 Windows 上拒绝读取的 glob 展开深度。值越大，启动扫描工作量可能越大。当无界的 ** 模式需要有界预展开时，请使用至少为 1 的值。
[permissions.<name>.filesystem]."<path>"	read、write 或 deny	None	为受支持的路径授予直接访问权限。deny 会拒绝访问，并优先于同等具体程度的 write 或 read 条目。Codex 会拒绝活动运行时无法强制执行的直接写入规则。
[permissions.<name>.filesystem."<path>"]."<subpath>"	read、write 或 deny	None	为 <path> 的后代路径授予访问权限。基础路径使用 .。其他子路径必须是相对后代路径，且不能包含 . 或 .. 组件。
[permissions.<name>.network]	表	None	配置该配置文件的网络沙箱代理和沙箱网络策略。
permissions.<name>.network.enabled	布尔值	false	为该配置文件启用沙箱命令的网络访问。这会更改沙箱网络策略，但不会自行启动网络代理。
[permissions.<name>.network.domains]	表	None	将主机模式映射到 allow 或 deny。如果没有 allow 条目，域名请求将被阻止。deny 条目优先于 allow 条目。
permissions.<name>.network.domains."<pattern>"	allow 或 deny	None	支持精确主机名、用于子域名的 *.example.com、用于顶级域名及其子域名的 **.example.com，以及仅可用于允许规则的全局通配符 *。主机模式会经过规范化处理：去除空格、转换为小写、去除末尾句点，以及去除简单端口或方括号。
[permissions.<name>.network.unix_sockets]	表	None	映射 Unix 套接字允许列表的覆盖项。仅用于 Docker 等本地集成。
permissions.<name>.network.unix_sockets."<path>"	allow 或 deny	None	使用 allow 将绝对 Unix 套接字路径添加到有效允许列表，或使用 deny 拒绝该路径。被拒绝的条目会从有效允许列表中移除。
permissions.<name>.network.proxy_url	URL 字符串	http://127.0.0.1:3128	用于 HTTP_PROXY、HTTPS_PROXY、WebSocket 代理变量及相关工具代理环境变量的 HTTP 代理监听器。
permissions.<name>.network.enable_socks5	布尔值	true	启用用于 ALL_PROXY 和 FTP 代理变量的 SOCKS5 监听器。
permissions.<name>.network.socks_url	URL 字符串	http://127.0.0.1:8081	SOCKS5 监听器地址。
permissions.<name>.network.enable_socks5_udp	布尔值	true	当 SOCKS5 监听器启用时，启用 SOCKS5 UDP 支持。
permissions.<name>.network.allow_upstream_proxy	布尔值	true	允许网络沙箱代理在发出请求时遵循上游的 HTTP(S)_PROXY 和 ALL_PROXY 设置。
permissions.<name>.network.allow_local_binding	布尔值	false	为 true 时禁用本地/私有网络防护。为 false 时，必须将 localhost 或 127.0.0.1 等精确的本地字面量显式加入允许列表；解析为本地或私有 IP 的主机名仍会被阻止。
permissions.<name>.network.dangerously_allow_non_loopback_proxy	布尔值	false	允许代理监听器绑定到非回环地址。普通本地开发应保持未设置。
permissions.<name>.network.dangerously_allow_all_unix_sockets	布尔值	false	在支持 Unix 套接字代理的情况下，绕过 Unix 套接字允许列表。这是一个范围很广的本地逃生通道。

文件系统权限

文件系统条目使用 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 位置（如果可用）	仅 .
:slash_tmp	/tmp 文件夹（如果存在）	仅 .
/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"          # each workspace root
"docs" = "read"        # each workspace-root docs directory
"generated" = "deny"   # each workspace-root generated directory

嵌套子路径必须位于其工作区根目录内。诸如 ../other-repo 的父目录遍历会被拒绝。

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

对于 Codex 不应读取的文件或子树，即使附近存在更宽泛的配置文件规则授予了访问权限，也应使用 deny。对于 ~/.ssh 等位置稳定的路径，精确路径非常适用。当配置文件需要覆盖一组确切位置会因仓库而异的敏感文件时，glob 模式更为适用。

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

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

此规则会拒绝读取每个运行时工作区根目录或配置文件定义的工作区根目录下匹配的 .env 文件。当你希望保留正常的工作区写入权限，同时让环境文件、生成的密钥或其他包含凭据的文件不可读时，可以使用此规则。

deny glob 模式支持作为拒绝读取规则。在 Linux、WSL 和原生 Windows 沙箱中，read 或 write glob 的可移植性较差，因此应尽可能优先使用精确路径或子树规则，例如 "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"      # exact host
"*.example.com" = "allow"    # subdomains only
"**.example.com" = "allow"   # apex and subdomains
"ads.example.com" = "deny"   # deny wins over 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 套接字

Unix 套接字代理是 Docker 等工具使用的本地逃生口。请谨慎使用：

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

使用 deny 可拒绝某个套接字路径，包括继承的允许条目。被拒绝的套接字路径会从有效允许列表中排除。

启用 Unix 套接字后，请确保代理监听器绑定到回环地址。

从旧版沙箱设置迁移

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

建议的起点：

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

配置文件描述了会话的本地默认安全态势。组织管理的要求仍可能添加限制，而用户配置不应扩大这些限制。请参阅托管配置，了解管理员强制实施的文件系统和网络约束。

作用域和强制执行

权限配置文件定义了本地沙箱命令执行的边界。请将其与批准策略，以及连接器、MCP 服务器、内置浏览器、Computer Use 和 Codex cloud 的独立控制机制结合使用。

配置文件控制的内容

• **本地命令执行：**权限配置文件管理在你的计算机上运行的沙箱命令。连接器、MCP 服务器、浏览器或 Computer Use 界面、Codex cloud 环境设置，以及获批准的升级操作均使用各自的控制机制。
• **文件系统写入：**具有写入能力的配置文件可以创建持久性更改。请将对脚本、构建步骤、包管理器钩子、Shell 启动文件和共享目录的写入视为敏感操作，因为后续工具或用户可能在原始沙箱上下文之外执行这些文件。
• **出站目标：**网络域名规则限制沙箱命令流量可以通过网络代理访问的位置。它们不会决定允许的目标是否可信，通配符允许规则仍然具有宽泛的范围。
• **本地服务：**默认会阻止本地和私有网络目标。将 localhost、私有 IP、Unix 套接字加入允许列表，或显式设置 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"

仅限工作区的文件访问

下面是一个权限配置文件示例：它允许 Codex 写入你的工作区文件夹，同时拒绝读取文件系统的其他部分（由 :minimal 确定的有限例外除外）。

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# subfolders such as .codex/ and .git/ within a workspace root are read-only
# while the rest of the folder is writable.
extends = ":workspace"

[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"

# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"

# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"

无网络的工作区写入

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"

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