权限
如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加
.md来获取 URL。
Beta。权限配置文件仍在积极开发中，可能会发生变化。
权限配置文件不会与旧版沙箱设置组合使用。请配置
要么 default_permissions 和 [permissions]，要么 sandbox_mode /
sandbox_workspace_write，但不能同时配置两者。如果 sandbox_mode 出现在任何
已加载的配置文件中、你传入了 --sandbox，或所选配置配置文件设置了
sandbox_mode， Codex 会使用这些旧版沙箱设置，而不是
default_permissions。
Managed allowed_permission_profiles 是例外：它会让 Codex 使用
权限配置文件。移除旧版设置，例如
sandbox_mode 和 [sandbox_workspace_write] 然后再部署托管的
配置文件允许列表。对于混合版本的企业级推出，你可以暂时保留
managed allowed_sandbox_modes 要求作为兼容性
约束，直到每个客户端都运行 Codex 0.138.0 或更高版本。
权限配置文件可让你为本地命令应用最小权限边界， Codex 会代表你运行这些命令。配置文件是一项命名策略，它将文件系统 规则与网络规则组合在一起；前者定义命令可以读取或写入什么，后者 定义命令可以访问哪些目标。
使用配置文件为 Codex 提供当前聊天所需的足够访问权限，而无需授予 对你的机器或网络的广泛访问权限。例如，只读配置文件可以 让 Codex 检查项目而不编辑它，而具备写入能力的配置文件 可以将编辑限制在选定的工作区根目录内。
本地权限配置文件支持 macOS、Linux、 WSL以及原生 Windows。请参阅 范围和强制执行 了解特定平台的 详细信息和注意事项。
有关 Codex cloud 的网络设置，请参阅Internet Access。
定义和选择配置文件
Section titled “定义和选择配置文件”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 在每个有效工作区根目录内应用：当前 会话的运行时工作区根目录，以及上方由配置文件定义的根目录。
配置文件也使用常规的配置层模型。优先级更高的层可以 在同一配置文件名称下添加或替换条目，而无需重述整个 配置文件。
例如，组织级配置和用户级配置可以分别扩展 同一个配置文件：
[permissions.server.workspace_roots]"~/code/server" = true[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。
扩展配置文件
Section titled “扩展配置文件”当配置文件大体上与内置配置文件或另一个命名 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 |
字符串配置文件名称 | 无 | 命名默认应用的权限配置文件 Codex 。它必须匹配 [permissions] 下的某个配置文件，或内置项，例如 :workspace。请显式设置它以获得可预测的行为；只有当 :workspace 和 :read-only 都被显式允许时，托管要求才可以省略它。 Codex 会使用旧版沙箱设置，除非托管 allowed_permission_profiles 指示它在此设置中使用权限配置文件。 |
[permissions.<name>] |
表 | 无 | 定义一个命名配置文件。 default_permissions 选择一个配置文件作为默认值；其他权限配置文件设置也使用该配置文件名称。 |
permissions.<name>.description |
字符串 | 无 | 为配置文件提供人类可读的描述。配置文件不会通过 extends继承其父级的描述。 |
permissions.<name>.extends |
字符串配置文件名称 | 无 | 从另一个命名配置文件或内置 :read-only 或 :workspace 配置文件开始此配置文件。 Codex 会拒绝 :danger-full-access、未知父级以及继承循环。 |
[permissions.<name>.workspace_roots] |
表 | 无 | 添加由配置文件定义的工作区根目录，这些根目录会接收 :workspace_roots 文件系统规则，并与当前会话的运行时工作区根目录并列。 |
permissions.<name>.workspace_roots."<path>" |
布尔值 | false |
当 true时，将该路径添加到配置文件的工作区根目录集合。设置为 false 的条目保持非活动状态。 |
[permissions.<name>.filesystem] |
表 | 无 | 将文件系统路径映射到访问值或限定范围的子路径映射。缺失或为空的文件系统表会使文件系统访问保持受限，并发出启动警告。 |
permissions.<name>.filesystem.glob_scan_max_depth |
数字 | 无 | 限制 Linux、 WSL和原生 Windows 上的拒绝读取 glob 展开，当 Codex 在沙箱启动前对匹配项进行快照时。较大的值可能会增加启动扫描工作量。当无界 1 模式需要有界预展开时，请使用至少为 ** 的值。 |
[permissions.<name>.filesystem]."<path>" |
read、 write或 deny |
无 | 为受支持的路径授予直接访问权限。 deny 拒绝访问，并优先于同等具体的 write 或 read 条目。 Codex 会拒绝活动运行时无法强制执行的直接写入规则。 |
[permissions.<name>.filesystem."<path>"]."<subpath>" |
read、 write或 deny |
无 | 授予对 <path>后代路径的访问权限。将 . 用于基路径。其他子路径必须是相对后代路径，且不能包含 . 或 .. 组件。 |
[permissions.<name>.network] |
表 | 无 | 为配置文件配置网络沙箱代理和沙箱网络策略。 |
permissions.<name>.network.enabled |
布尔值 | false |
为配置文件中的沙箱命令启用网络访问。这会更改沙箱网络策略；它本身不会启动网络代理。 |
[permissions.<name>.network.domains] |
表 | 无 | 将主机模式映射到 allow 或 deny。如果没有 allow 条目，则域请求会被阻止。拒绝条目会覆盖允许条目。 |
permissions.<name>.network.domains."<pattern>" |
allow 或 deny |
无 | 支持精确主机、 *.example.com 用于子域、 **.example.com 用于根域及其子域，以及 * 作为仅允许的全局通配符。主机模式会通过去除首尾空白、转为小写、去除尾随点，以及去除简单端口或括号来规范化。 |
[permissions.<name>.network.unix_sockets] |
表 | 无 | 映射 Unix 套接字允许列表覆盖项。仅用于 Docker 等本地集成。 |
permissions.<name>.network.unix_sockets."<path>" |
allow 或 deny |
无 | 使用 allow将绝对 Unix 套接字路径添加到有效允许列表，或使用 deny拒绝它。被拒绝的条目会从有效允许列表中省略。 |
permissions.<name>.network.proxy_url |
URL 字符串 | http://127.0.0.1:3128 |
HTTP 用于 HTTP_PROXY、 HTTPS_PROXY、websocket 代理变量以及相关工具代理环境变量的代理监听器。 |
permissions.<name>.network.enable_socks5 |
布尔值 | true |
启用用于 SOCKS5 和 ALL_PROXY 代理变量的 FTP 监听器。 |
permissions.<name>.network.socks_url |
URL 字符串 | http://127.0.0.1:8081 |
SOCKS5 监听器地址。 |
permissions.<name>.network.enable_socks5_udp |
布尔值 | true |
当 SOCKS5 UDP 监听器启用时，启用 SOCKS5 支持。 |
permissions.<name>.network.allow_upstream_proxy |
布尔值 | true |
允许网络沙箱代理遵循上游 HTTP(S)_PROXY 和 ALL_PROXY 设置来处理出站请求。 |
permissions.<name>.network.allow_local_binding |
布尔值 | false |
当 local/private-network 时，禁用 true保护。当 false时，诸如 localhost 或 127.0.0.1 等精确本地字面量必须显式加入允许列表，并且解析为本地或私有 IPs 的主机名仍会被阻止。 |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
布尔值 | false |
允许代理监听器绑定非环回地址。普通本地开发请保持未设置。 |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
布尔值 | false |
在支持 Unix 套接字代理的地方绕过 Unix 套接字允许列表。这是一个范围很广的本地逃生口。 |
文件系统权限
Section titled “文件系统权限”文件系统条目使用 read、write 或 deny：
| 访问权限 | 含义 |
|---|---|
read |
允许命令读取该路径下的文件并列出目录。命令不能在那里创建、修改、重命名或删除文件。 |
write |
允许命令读取和修改该路径下的文件，包括在 OS 允许时创建、重命名和删除文件。 |
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 |
平台绝对路径，例如 /path 在 macOS/Linux/WSL 或 C:\path 在原生 Windows 上 |
是 |
~/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 拒绝读取
Section titled “使用精确路径或 glob 拒绝读取”使用 deny 用于 Codex 不应读取的文件或子树，即使更宽泛的
配置文件规则已在附近授予访问权限。精确路径适合稳定位置，
例如 ~/.ssh。当配置文件需要覆盖一组
具体位置因仓库而异的敏感文件时，glob 模式更合适。
当 glob 位于 :workspace_roots下时， Codex 会将其解释为相对于每个
有效工作区根目录。例如：
[permissions.project-edit.filesystem.":workspace_roots"]"**/*.env" = "deny"此规则会拒绝读取匹配的 .env 文件，这些文件位于每个运行时或
由配置文件定义的工作区根目录下。当你想保留正常的
工作区写入，同时让环境文件、生成的密钥或类似的
包含凭据的文件不可读时，请使用它。
deny glob 模式可作为拒绝读取规则使用。 read 或 write glob
在 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 = trueproxy_url = "http://127.0.0.1:3128"enable_socks5 = truesocks_url = "http://127.0.0.1:8081"enable_socks5_udp = true除非你正在与
特定运行时集成，否则请将这些监听器设置保留为默认值。 dangerously_* 网络键是
专门环境的逃生口，不应在普通本地开发中使用。
本地和私有网络
Section titled “本地和私有网络”Codex 默认应用 local/private-network 防护，以防御 DNS 重绑定以及意外访问本地服务。若要有意允许 字面本地目标，请将确切主机或 IP 字面量加入允许列表：
[permissions.project-edit.network.domains]"localhost" = "allow""127.0.0.1" = "allow"设置 allow_local_binding = true 仅当配置文件必须访问已加入允许列表的
解析为本地或私有地址的主机名时：
[permissions.project-edit.network]enabled = trueallow_local_binding = true
[permissions.project-edit.network.domains]"localhost" = "allow"Unix 套接字
Section titled “Unix 套接字”Unix 套接字代理是面向 Docker 等工具的本地逃生口。请 谨慎使用：
[permissions.project-edit.network.unix_sockets]"/var/run/docker.sock" = "allow""/tmp/old.sock" = "deny"使用 deny 拒绝某个套接字路径，包括继承的允许条目。被拒绝的
套接字路径会从有效允许列表中省略。
启用 Unix 套接字后，请确保代理监听器绑定到回环地址。
从旧版沙箱设置迁移
Section titled “从旧版沙箱设置迁移”当你想用一个可复用配置文件同时描述 sandbox_mode 文件系统和网络行为时，权限配置文件会替代旧的
sandbox_workspace_write 组合。
一个会话请使用其中一种系统，不要
同时使用两者。
建议的起点：
- 对于只读工作流，请使用内置
:read-only配置文件，或定义一个 仅在需要处具有读取访问权限的自定义配置文件。 - 对于工作区编辑，请使用内置
:workspace配置文件，或定义一个 通过:workspace_roots写入，并仅添加工作流所需的额外 临时或缓存路径的自定义配置文件。 - 对于不受限制的本地执行，仅当你
:danger-full-access有意需要最宽泛的本地访问模型时才使用 。
配置文件描述会话的本地默认姿态。组织管理的 要求仍可添加用户配置不应 放宽的限制。请参阅 托管配置 了解管理员强制执行的文件系统和网络约束。
作用域和强制执行
Section titled “作用域和强制执行”权限配置文件定义了本地沙箱化命令 执行的边界。请将它们与审批策略以及单独的控制项配合使用 用于连接器、 MCP 服务器、内置浏览器、Computer Use，以及 Codex cloud。
配置文件控制的内容
Section titled “配置文件控制的内容”- 本地命令执行： 权限配置文件管控在你的机器上运行的沙箱化命令。 连接器、 MCP 服务器、浏览器或 computer-use 界面、 Codex cloud 环境设置以及已批准的 提权使用各自的控制项。
- 文件系统写入： 具备写入能力的配置文件可以创建持久更改。 应将对脚本、构建步骤、包管理器钩子、shell 启动 文件和共享目录的写入视为敏感，因为后续工具或用户可能会 在原始沙箱上下文之外执行这些文件。
- 出站目标： 网络域名规则限制沙箱化 命令流量可通过网络代理到达的位置。它们不决定 允许的目标是否可信，通配符允许规则仍然 范围宽泛。
- 本地服务： 本地和私有网络目标默认被阻止。
将
localhost、私有 IPs、Unix 套接字加入允许列表，或设置allow_local_binding = true都会显式开放对本地服务的访问。
强制执行的工作方式
Section titled “强制执行的工作方式”- 在 macOS上， Codex 使用 Seatbelt 沙箱配置文件。如果所选策略无法 由平台沙箱强制执行， Codex 会拒绝运行该命令，而不是 静默地以非沙箱方式运行。
- 在 Linux 和 WSL上， Codex 使用 bubblewrap 和 seccomp， 并提供 Landlock 作为兼容性回退路径。最强的 强制执行路径取决于用户命名空间和内核支持；受限的 容器主机可能会强制使用兼容性路径，不支持的拆分策略 会被拒绝。
- 在原生 Windows 上，
elevated沙箱 最强，因为它可以使用专用的低权限沙箱用户、 文件系统权限边界和防火墙规则。unelevated沙箱是回退方案，网络隔离较弱，且无法强制执行 每个拆分 read/write 划出项，因此不支持的策略会被拒绝。当你需要 Linux 沙箱模型时，请使用 WSL 。
请选择仍能完成任务的最窄配置文件，尤其是在 授予写入或出站网络访问时。请让审批策略、密钥 处理和允许规则与该访问级别保持一致。
常用配置文件
Section titled “常用配置文件”具有网络允许列表的只读模式
Section titled “具有网络允许列表的只读模式”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"仅限工作区的文件访问
Section titled “仅限工作区的文件访问”下面是一个权限配置文件示例：它允许 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"无网络的工作区写入
Section titled “无网络的工作区写入”default_permissions = "project-edit"
[permissions.project-edit.filesystem]":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]"." = "write"
[permissions.project-edit.network]enabled = false具有公共 Web 访问权限的工作区写入
Section titled “具有公共 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"仅当你打算允许公共网络 "*" 访问时，才使用全局
允许规则。拒绝规则可以缩小宽泛允许列表的范围。