权限

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

使用配置文件可以为 Codex 提供完成当前任务所需的足够访问权限，而无需授予对你机器或网络的广泛访问权限。例如，只读配置文件可以让 Codex 检查项目而无需编辑它，而可写配置文件可以将编辑限制在选定的工作区根目录中。

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

有关 Codex 云网络设置，请参见 互联网访问.

定义并选择配置文件

Codex 包含三个内置权限配置文件：

• :read-only 保持本地命令执行为只读。
• :workspace 允许在活跃的工作区根目录内进行写入。
• :danger-full-access 移除本地沙盒限制，应仅在有意的广泛访问需求下使用。

在以下键下创建一个命名配置文件 [permissions.<name>], 然后设置顶级的 default_permissions 键值设置为该配置文件名称或上述内置配置文件之一。在此示例中， project-edit 是一个用户自定义的配置文件名称，而不是内置值。

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

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

此配置文件：

• 读取常用开发人员工具所需的最小运行时路径。
• 将相同的工作区根目录规则应用于当前会话和配置文件定义的根目录。
• 将与 IDE 相邻的设置（例如 .devcontainer/ 保持为在每个根目录下只读。
• 通过 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。一个 profile 可以扩展 :read-only, :workspace，或另一个具名 profile。它不能扩展 :danger-full-access；Codex 还会拒绝未知的父级和继承循环。

配置规范

文件系统权限

文件系统条目使用 read, write, or 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"

更具体的路径也可以在更宽泛的拒绝规则内重新开放较窄的子树：

当前用户主目录下的路径 ~\work.

使用 :root 在原生 Windows 上，相对于主目录的路径也可以使用反斜杠，例如

[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 嵌套的子路径必须保留在其工作区根目录内。诸如

之类的父目录遍历将被拒绝。

使用 deny 拒绝读取具有精确路径或 glob 模式的文件或子树，即 Codex 不应读取的内容，即使更宽泛的配置文件规则授予了附近路径的访问权限。精确路径适用于稳定的位置，例如 ~/.ssh。当 profile 需要覆盖一系列敏感文件，而这些文件的具体位置在不同仓库中各不相同时，使用 Glob 模式效果更好。

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

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

之下时 .env 此规则拒绝读取在每个运行时或配置文件定义的工作区根目录下找到的匹配

deny 文件。当您希望保留正常的工作区写入权限，同时保持环境文件、生成的密钥或类似的含凭证文件不可读时，请使用此规则。 read or write 支持 glob 模式作为拒绝读取规则。 "docs/**" = "read" glob 在 Linux、WSL 和原生 Windows 沙盒中的可移植性较差，因此在可能的情况下，优先使用精确路径或子树规则，例如

在 Linux、WSL 和原生 Windows 上，无界的 ** 拒绝读取模式可能需要在沙盒启动之前进行有界的预扩展。设置 glob_scan_max_depth 当您使用无限制模式时，例如 "**/*.env" = "deny":

[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 和 UNC 路径例如 \\server\share 支持作为绝对路径。

网络权限

设置 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 and sandbox_workspace_write 当您希望一个可重用的配置文件同时描述文件系统和网络行为时。一个会话只能使用其中一种系统，不能同时使用两者。

建议的起点：

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

配置文件描述了会话的本地默认姿态。组织管理的要求仍可添加用户配置不应扩大的限制。请参阅 托管配置 了解管理员强制执行的文件系统和网络约束。

范围和执行

权限配置文件定义了本地沙盒命令执行的边界。请将它们与批准策略以及其他 Codex 接口的单独控制结合使用。

配置文件控制的内容

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

执行原理

• 在 macOS 上，Codex 使用 Seatbelt 沙盒配置文件。如果选定的策略无法由平台沙盒强制执行，Codex 将拒绝运行该命令，而不是在不加沙盒的情况下静默运行。
• 在 Linux 和 WSL 上，Codex 使用 bubblewrap and 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"

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