权限

托管的 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 包含三个内置权限配置文件：

• :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。

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

范围和强制执行

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

配置文件控制的内容

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

网络代理不控制的内容

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

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

若要限制这些界面，请直接配置各项能力。命令网络 允许列表并不是针对 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"

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