权限

受管的 allowed_permission_profiles 是一个例外：它会让 Codex 使用 权限配置档案。部署受管配置档案允许列表之前，请移除 sandbox_mode 和 [sandbox_workspace_write] 等旧版设置。对于企业混合版本发布，可以暂时保留 托管的 allowed_sandbox_modes 要求作为兼容性约束， 直到所有客户端均运行 Codex 0.138.0 或更高版本。

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

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

本地权限配置档案支持 macOS、Linux、WSL 和原生 Windows。有关各平台的具体详情和注意事项，请参阅范围和强制执行。

有关当前 Codex Cloud 的网络设置，请参阅连接到服务。有关 Codex Cloud (Legacy)，请参阅互联网访问。

定义并选择配置档案

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"

[features]
network_proxy = true

[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"

此配置档案：

• 读取常用开发者工具所需的最少运行时路径。
• 对当前会话和配置档案定义的根目录应用相同的工作区根目录规则。
• 将每个根目录下与 IDE 相邻的设置（例如 .devcontainer/）保持为只读。
• 使用 glob 规则拒绝匹配的环境文件。
• 仅允许通过已配置的域名策略访问网络。

在活动配置档案内，即使更宽泛的路径可读或可写，范围更窄的拒绝规则 仍然有效。例如，配置档案可以让工作区根目录 可写，同时仍将匹配的 .env 路径设为 deny。

扩展配置档案

当某个配置档案与内置配置档案或另一个具名配置档案大致相同时，请使用 extends。 优先扩展内置配置档案，而不是从头开始，以便 继承基线保护。例如，扩展 :workspace 会让 工作区根目录中的 .codex 目录保持只读，除非你明确 覆盖它。只需设置一次父配置档案，然后仅添加或覆盖有差异的 规则。

default_permissions = "project-edit"

[features]
network_proxy = true

[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 也会拒绝未知父项和继承 循环。

配置规范

文件系统权限

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

更具体的条目会覆盖更宽泛的条目。当两个条目指向 同一路径时，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"

支持的路径形式：

在原生 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 路径作为绝对路径。

网络权限

网络访问和网络过滤是两项独立设置。设置 permissions.<name>.network.enabled = true 以允许命令访问网络， 并启用 features.network_proxy 以强制执行配置档案的域名规则：

[features]
network_proxy = true

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

[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.<name>.network.domains] 或设置 permissions.<name>.network.enabled = true 不会启用 features.network_proxy。或者，管理员可以在 requirements.toml 中使用 [experimental_network] 启用代理。请参阅 受管配置。

处于活动状态时，网络沙箱代理默认绑定到本地监听器：

[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。

配置档案描述会话的本地默认安全基线。组织管理的 要求仍可添加用户配置不应放宽的限制。有关管理员强制执行的文件系统和网络约束， 请参阅受管配置。

范围和强制执行

Work Cloud 的本地计算机访问与环境策略

请评审使用 Work Cloud 本地计算机访问功能的每个环境的策略：

• 企业要求： 对于具有本地访问权限的 Work 和 dots，启用托管策略后，受支持的 Global 策略会约束共享的云端编排器；适用的本地执行要求会约束已连接的计算机。
• 云端执行： Work 云容器使用现有的 Work Cloud 策略。
• 本地策略顺序： MDM 和旧版托管设备要求的优先级高于 Agent Security。设备的系统要求文件的优先级低于 Agent Security。
• 策略优先级： 优先级较高的策略优先，即使优先级较低的策略更具体。在同一策略内，特定操作系统的环境覆盖设置优先于适用于所有操作系统的环境覆盖设置，其次是 Global。

某些要求具有特定于字段的合并规则。有关受支持的字段和运行时限制，请参阅受管配置和配置参考。不要假定 Work Cloud 支持此处展示的 Codex 权限配置。

权限配置档案定义本地沙箱命令执行的边界。 请将其与审批策略，以及针对网页搜索、连接器、MCP server、 内置浏览器、Computer Use 和 Codex cloud 的独立控制措施配合使用。

配置档案控制的内容

• 本地命令执行： 权限配置档案管控在你的计算机上运行的沙箱命令。 连接器、MCP server、浏览器或 computer-use 界面、Codex cloud 环境设置以及已批准的 权限提升使用各自的控制措施。
• 文件系统写入： 可写配置档案可以产生持久更改。 对脚本、构建步骤、包管理器钩子、shell 启动 文件和共享目录的写入应视为敏感操作，因为其他工具或用户稍后可以 在原始沙箱上下文之外执行这些文件。
• 出站目标： 仅当网络代理处于活动状态时，网络域名规则才会限制沙箱 命令流量的目标。它们无法判定允许的目标 是否可信，而且通配符允许规则的范围仍然很广。
• 本地服务： 活动网络代理默认阻止本地和私有网络 目标。将 localhost、私有 IP、Unix 套接字加入允许列表，或设置 allow_local_binding = true，都会明确开放对本地服务的访问。

网络代理不控制的内容

网络代理只过滤在沙箱内运行的本地命令所产生的流量。 它不会将配置档案的域名允许列表应用于：

• 网页搜索： 托管搜索工具使用自身的访问设置。使用 web_search，以及针对托管客户端的 allowed_web_search_modes 来控制 此功能。tools.web_search.allowed_domains 过滤的是搜索结果，而非命令的 网络访问。
• 应用和连接器： 由连接器支持的工具使用自身的服务端 连接、工作区权限以及应用或工具设置。
• MCP server： 本地和远程 MCP server使用自身的进程或 传输方式。通过 mcp_servers 配置和托管服务器 允许列表来控制它们。
• 浏览器和 Computer Use： 浏览器导航和计算机操作 使用各自的功能与审批控制。
• Codex 服务流量： 模型、身份验证和其他客户端服务 请求使用客户端独立的 HTTP 和系统代理设置。
• Codex Cloud： 这些任务使用各自环境的 网络设置。 Codex Cloud (Legacy) 使用单独的 互联网访问设置。

若要限制这些界面，请直接配置各项能力。命令网络 允许列表并不是针对 Codex 可执行的每项操作的全局网络策略。

强制执行方式

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

操作指南

请选择仍能完成任务的最窄配置档案，尤其是在 授予写入或出站网络访问权限时。请确保审批策略、敏感信息 处理方式和允许规则与该访问级别一致。

常用配置档案

只读并使用网络允许列表

default_permissions = "readonly-net"

[features]
network_proxy = true

[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

可写入工作区并可访问公共网络

default_permissions = "workspace-net"

[features]
network_proxy = true

[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"

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