权限

权限配置文件允许你将最小权限边界应用于本地命令 Codex 代表你运行。配置文件是结合文件系统的命名策略 规则，定义哪些命令可以读取或写入，以及网络规则， 定义命令可以到达哪些目的地。

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

macOS、Linux、WSL 和本机支持本地权限配置文件 视窗。有关特定于平台的信息，请参阅范围和执行 详细信息和注意事项。

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"

此简介：

• 读取常见开发人员工具所需的最小运行时路径。
• 将相同的工作区根规则应用于当前会话和 配置文件定义的根。
• 将 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 发出请求。一个配置文件可以扩展:read-only， :workspace，或其他命名的配置文件。它无法延长 :danger-full-access； Codex也拒绝未知父母和继承 循环。

配置规格

文件系统权限

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

更具体的条目会覆盖更广泛的条目。当两个条目的目标是 相同路径，deny优先于write，write优先 超过 read。

这种优先顺序让配置文件首先描述广泛的工作区域，然后雕刻 out 应该保持不可读的文件或目录：

[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 位于 :workspace_roots 下时，Codex 将其解释为相对于每个 有效的工作空间根。例如：

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

此规则拒绝读取每个运行时下找到的匹配 .env 文件或 配置文件定义的工作空间根。当你想保持正常时使用它 工作区在保留环境文件、生成的机密或类似文件的同时进行写入 包含凭据的文件不可读。

支持 deny glob 模式作为拒绝读取规则。 read 或 write 全局变量 在 Linux、WSL 和本机 Windows 沙箱上的可移植性较差，因此更喜欢精确的 如果可能的话，路径或子树规则，例如 "docs/**" = "read"。

在 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 和 sandbox_workspace_write 当你想要一个可重用配置文件来描述两者时 文件系统和网络行为。使用一个系统或另一个系统进行会话，而不是 两个都。

建议的起点：

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

配置文件描述了会话的本地默认状态。组织管理 需求仍然可以添加用户配置不应添加的限制 扩大。参见托管配置 用于管理员强制执行的文件系统和网络限制。

范围和执行

权限配置文件定义本地沙盒命令的边界 执行。将它们与审批策略和单独的控件一起使用 对于连接器、MCP 服务器、内置浏览器、计算机使用和 Codex 云。

配置文件控制哪些内容

• 本地命令执行： 权限配置文件管理沙盒命令 在你的机器上运行的。连接器、MCP 服务器、浏览器或 计算机使用表面，Codex云环境设置，并批准 升级使用自己的控制。
• 文件系统写入： 可写入的配置文件可以创建持久更改。 处理对脚本的写入、构建步骤、包管理器挂钩、shell 启动 文件和共享目录同样敏感，因为以后的工具或用户可以 在原始沙箱上下文之外执行这些文件。
• 出站目的地： 网络域规则限制沙盒的位置 命令流量可以通过网络代理。他们不确定 允许的目的地是否可信，以及通配符允许规则保留 广阔。
• 本地服务： 默认情况下阻止本地和专用网络目标。 将 localhost、私有 IP、Unix 套接字或设置列入白名单 allow_local_binding = true 显式开放对本地服务的访问。

执法如何运作

• 在 macOS 上，Codex 使用 Seatbelt 沙盒配置文件。如果所选策略不能 由平台沙箱强制执行，Codex 拒绝运行该命令 静默地运行它，取消沙箱。
• 在 Linux 和 WSL 上，Codex 使用 bubbblewrap 和 seccomp, Landlock 可用于兼容性回退路径。最强 执行路径取决于用户命名空间和内核支持；受限制的 容器主机可以强制兼容路径和不支持的拆分策略 被拒绝。
• 在本机 Windows 上，elevated 沙箱 最强，因为它可以使用专用的低权限沙箱用户， 文件系统权限边界和防火墙规则。 unelevated 沙箱是网络隔离较弱的后备方案，无法强制执行 每个拆分读/写剥离，因此拒绝不支持的策略。使用 WSL 当你需要 Linux 沙箱模型时。

操作指导

选择仍然可以完成任务的最窄配置文件，尤其是在 你授予写入或出站网络访问权限。保密审批政策 处理，并允许与该访问级别一致的规则。

常用型材

具有网络允许列表的只读状态

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"

仅当你打算允许公共网络时才使用全局 "*" 允许规则 使用权。拒绝规则可以缩小广泛的允许名单范围。