Beta。Permission profiles 仍在积极开发中，可能会发生变化。
Permission profiles 不会与较旧的 sandbox settings 组合使用。请配置 default_permissions 和 [permissions]，或配置 sandbox_mode / sandbox_workspace_write，二者不要同时使用。如果任何已加载 config file 中出现 sandbox_mode、你传入 --sandbox，或所选 config profile 设置了 sandbox_mode，Codex 会使用这些较旧的 sandbox settings，而不是 default_permissions。
Managed allowed_permission_profiles 是例外：它会让 Codex 使用 permission profiles。部署 managed profile allowlist 前，请移除 sandbox_mode 和 [sandbox_workspace_write] 等旧设置。对于混合版本 enterprise rollout，可以暂时保留 managed allowed_sandbox_modes requirement 作为兼容性约束，直到所有 client 都运行 Codex 0.138.0 或更高版本。
Permission profiles 让你可以对 Codex 代表你运行的 local commands 应用 least-privilege boundaries。profile 是一个具名 policy，它组合了 filesystem rules 和 network rules：前者定义命令可以读取或写入什么，后者定义命令可以访问哪些 destinations。
使用 profiles 为 Codex 提供当前任务所需的足够访问权限，而不是授予对机器或网络的宽泛访问。例如，read-only profile 可以让 Codex 检查项目但不编辑；具有写入能力的 profile 可以把编辑限制在选定的 workspace roots 中。
Local permission profiles 支持 macOS、Linux、WSL 和 native Windows。有关平台特定细节和注意事项，请参阅 Scope and enforcement 。
有关 Codex cloud network settings，请参阅 Internet Access 。
定义并选择 profile
Codex 包含三个内置 permission profiles：
:read-only 让 local command execution 保持只读。
:workspace 允许在 active workspace roots 和 system temp directories 内写入。
:danger-full-access 会移除 local sandbox restrictions，只有在明确需要这种宽泛访问时才应使用。
在 [permissions.<name>] 下创建 named profile，然后把顶层 default_permissions key 设置为该 profile name，或设置为上面的某个内置值。在这个示例中，project-edit 是用户定义的 profile name，不是内置值。
Enterprise administrators 可以通过 managed requirements.toml 定义 profiles，并限制用户可选择哪些 profiles。一旦出现 allowed_permission_profiles，未列出的 profiles 都会被拒绝，包括未列出的内置 profiles 和未来 Codex 版本中新增的 profiles。推荐的 managed configuration 请参阅 Control available permission profiles 。
Custom profiles 使用两个相关概念：
[permissions.<name>.workspace_roots] 添加应被视为该 profile workspace roots 的具体 directories。
[permissions.<name>.filesystem.":workspace_roots"] 定义 Codex 在每个 effective workspace root 内应用的 filesystem rules：包括当前 session 的 runtime workspace roots，以及上面由 profile 定义的 roots。
Profiles 也使用常规 config-layer model。更高优先级的 layers 可以在同一个 profile name 下添加或替换 entries，而无需重述整个 profile。
例如，organization-level config 和 user-level config 可以独立扩展同一个 profile：
# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true当 server 处于 active 状态时，这两个 workspace roots 都会参与 effective profile。
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"这个 profile 会：
读取 common developer tools 所需的 minimal runtime paths。
对当前 session 和 profile-defined roots 应用相同的 workspace-root rules。
让 .devcontainer/ 等 IDE-adjacent settings 在每个 root 下保持只读。
使用 glob rule 拒绝匹配的 environment files。
仅通过已配置的 domain policy 允许 network access。
在 active profile 中，即使更宽泛的 path 可读或可写，更窄的 deny rules 仍然有效。例如，profile 可以让 workspace roots 可写，同时仍把匹配的 .env path 设置为 deny。
扩展 profile
当某个 profile 与内置 profile 或另一个 named profile 基本相同时，请使用 extends。优先扩展内置 profile，而不是从零开始，这样 baseline protections 会继续保留。例如扩展 :workspace 会让 workspace root 中的 .codex directory 保持只读，除非你显式 override。设置一次 parent，然后只添加或 override 不同的 rules。
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"这个 profile 从 :workspace 开始，保持匹配的 .env files 被 deny，并允许访问 api.openai.com。profile 可以扩展 :read-only、:workspace 或另一个 named profile。它不能扩展 :danger-full-access；Codex 也会拒绝 unknown parents 和 inheritance cycles。
Configuration spec
| Entry | Type / values | Default | Details |
|---|---|---|---|
| default_permissions | String profile name | None | 命名 Codex 默认应用的 permissions profile。它必须匹配 [permissions] 下的 profile，或 :workspace 等内置值。为获得可预测行为，请显式设置它；只有当 :workspace 和 :read-only 都被显式允许时，managed requirements 才可以省略它。除非 managed allowed_permission_profiles 要求 Codex 在此 setup 中使用 permission profiles，否则 Codex 会使用旧 sandbox settings。 |
| [permissions.<name>] | Table | None | 定义 named profile。default_permissions 会选择一个 profile 作为默认值；其他 permission-profile settings 也使用 profile name。 |
| permissions.<name>.description | String | None | 为 profile 提供 human-readable description。profile 不会通过 extends 继承 parent 的 description。 |
| permissions.<name>.extends | String profile name | None | 从另一个 named profile 或内置 :read-only / :workspace profile 开始构建此 profile。Codex 会拒绝 :danger-full-access、unknown parents 和 inheritance cycles。 |
| [permissions.<name>.workspace_roots] | Table | None | 添加 profile-defined workspace roots，这些 roots 会与当前 session 的 runtime workspace roots 一起接收 :workspace_roots filesystem rules。 |
| permissions.<name>.workspace_roots."<path>" | Boolean | false | 为 true 时，将 path 添加到该 profile 的 workspace root set。设置为 false 的 entries 保持 inactive。 |
| [permissions.<name>.filesystem] | Table | None | 将 filesystem paths 映射到 access values 或 scoped subpath maps。缺失或空 filesystem tables 会让 filesystem access 保持受限，并发出 startup warning。 |
| permissions.<name>.filesystem.glob_scan_max_depth | Number | None | 在 Linux、WSL 和 native Windows 上，当 Codex 在 sandbox startup 前 snapshot deny-read glob matches 时，限制 glob expansion 深度。更大的值可能增加 startup scanning work。当无界 ** pattern 需要 bounded pre-expansion 时，请使用至少 1 的值。 |
| [permissions.<name>.filesystem]."<path>" | read, write, or deny | None | 为 supported path 授予 direct access。deny 会拒绝访问，并优先于同等具体度的 write 或 read entries。Codex 会拒绝 active runtime 无法 enforce 的 direct write rules。 |
| [permissions.<name>.filesystem."<path>"]."<subpath>" | read, write, or deny | None | 为 <path> 的 descendant 授权。使用 . 表示 base path。其他 subpaths 必须是 relative descendants，且不能包含 . 或 .. components。 |
| [permissions.<name>.network] | Table | None | 为 profile 配置 network sandbox proxy 和 sandbox network policy。 |
| permissions.<name>.network.enabled | Boolean | false | 为 profile 中的 sandboxed commands 启用 network access。这会改变 sandbox network policy；它本身不会启动 network proxy。 |
| [permissions.<name>.network.domains] | Table | None | 将 host patterns 映射为 allow 或 deny。如果没有 allow entries，domain requests 会被 blocked。Deny entries 会覆盖 allow entries。 |
| permissions.<name>.network.domains."<pattern>" | allow or deny | None | 支持 exact hosts、用于 subdomains 的 *.example.com、用于 apex plus subdomains 的 **.example.com，以及仅可作为 allow 的 global wildcard *。Host patterns 会通过 trim、lowercase、移除 trailing dot、移除简单 ports 或 brackets 来 normalized。 |
| [permissions.<name>.network.unix_sockets] | Table | None | 映射 Unix socket allowlist overrides。仅用于 Docker 等 local integrations。 |
| permissions.<name>.network.unix_sockets."<path>" | allow or deny | None | 将 absolute Unix socket path 以 allow 添加到 effective allowlist，或以 deny 拒绝它。Denied entries 会从 effective allowlist 中省略。 |
| permissions.<name>.network.proxy_url | URL string | http://127.0.0.1:3128 | HTTP proxy listener，用于 HTTP_PROXY、HTTPS_PROXY、websocket proxy variables 和相关 tool proxy environment variables。 |
| permissions.<name>.network.enable_socks5 | Boolean | true | 启用 SOCKS5 listener，用于 ALL_PROXY 和 FTP proxy variables。 |
| permissions.<name>.network.socks_url | URL string | http://127.0.0.1:8081 | SOCKS5 listener address。 |
| permissions.<name>.network.enable_socks5_udp | Boolean | true | 当 SOCKS5 listener 启用时，启用 SOCKS5 UDP support。 |
| permissions.<name>.network.allow_upstream_proxy | Boolean | true | 允许 network sandbox proxy 对 outbound requests 遵循 upstream HTTP(S)_PROXY 和 ALL_PROXY settings。 |
| permissions.<name>.network.allow_local_binding | Boolean | false | 为 true 时禁用 local/private-network guard。为 false 时，localhost 或 127.0.0.1 等 exact local literals 必须显式 allowlisted，且解析到 local 或 private IPs 的 hostnames 仍会被 blocked。 |
| permissions.<name>.network.dangerously_allow_non_loopback_proxy | Boolean | false | 允许 proxy listeners 绑定 non-loopback addresses。普通 local development 请保持 unset。 |
| permissions.<name>.network.dangerously_allow_all_unix_sockets | Boolean | false | 在支持 Unix socket proxying 的位置绕过 Unix socket allowlist。这是宽泛的 local escape hatch。 |
Filesystem permissions
Filesystem entries 使用 read、write 或 deny：
| Access | Meaning |
|---|---|
| read | 允许 commands 读取 path 下的 files 并列出 directories。Commands 不能在那里创建、修改、重命名或删除 files。 |
| write | 允许 commands 读取并修改 path 下的 files，包括在 OS 允许时创建、重命名和删除 files。 |
| deny | 拒绝 path 下的 reads 和 writes。用于从更宽泛的 read 或 write grant 中切出 denied subpath。 |
更具体的 entries 会 override 更宽泛的 entries。当两个 entries 指向同一个 path 时，deny 优先于 write，write 优先于 read。
这种 precedence 允许 profile 先描述一个宽泛工作区域，再切出应该保持不可读的 files 或 directories：
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"在这个示例中，workspace root 保持可写，.devcontainer/ 保持可读但不会变成可写，匹配的 environment files 对 sandboxed commands 保持不可用。
更具体的 path 也可以在更宽泛的 deny 内重新打开一个更窄的 subtree：
[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"支持的 path forms：
| Path | Meaning | Scoped subpaths |
|---|---|---|
| :root | filesystem root | 仅 . |
| :minimal | common tools 所需的 platform 和 runtime paths | 仅 . |
| :workspace_roots | 当前 session 的 workspace roots 加上任何已启用的 profile-defined workspace roots | Yes |
| :tmpdir | 可用时的 $TMPDIR location | 仅 . |
| :slash_tmp | /tmp folder（如果存在） | 仅 . |
| /absolute/path | platform absolute path，例如 macOS/Linux/WSL 上的 /path，或 native Windows 上的 C:\path | Yes |
| ~/path | 当前用户 home directory 下的 path | Yes |
在 native Windows 上，home-relative paths 也可以使用反斜杠，例如 ~\work。
只有当 profile 有意需要宽泛 read coverage 时，才使用 :root：
[permissions.audit.filesystem]
":root" = "read"在 :workspace_roots 下使用 nested entries，将 access 限定到 workspace-root relative subpaths：
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write" # each workspace root
"docs" = "read" # each workspace-root docs directory
"generated" = "deny" # each workspace-root generated directoryNested subpaths 必须留在其 workspace root 内。../other-repo 这样的 parent traversal 会被 rejected。
用 exact paths 或 globs 拒绝 reads
对于 Codex 不应读取的 files 或 subtrees，请使用 deny，即使附近已有更宽泛的 profile rule 授予 access。Exact paths 适合 ~/.ssh 这类稳定位置。Glob patterns 更适合覆盖一组 sensitive files，因为这些文件的确切位置可能在不同 repositories 中变化。
当 glob 位于 :workspace_roots 下时，Codex 会相对于每个 effective workspace root 解释它。例如：
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"这个 rule 会拒绝读取每个 runtime 或 profile-defined workspace root 下匹配的 .env files。当你希望保留正常 workspace writes，同时让 environment files、generated secrets 或类似 credential-bearing files 保持不可读时，请使用它。
deny glob patterns 支持作为 deny-read rules。read 或 write globs 在 Linux、WSL 和 native Windows sandboxing 上可移植性较弱，因此尽可能优先使用 exact paths 或 subtree rules，例如 "docs/**" = "read"。
在 Linux、WSL 和 native Windows 上，无界 ** deny-read pattern 可能需要在 sandbox 启动前进行 bounded pre-expansion。使用 "**/*.env" = "deny" 这类 unbounded pattern 时，请设置 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。更高的值会在 sandbox startup 前扫描更深层级，这可能在 Linux、WSL 和 native Windows 上增加 startup work。如果你不想使用 bounded expansion，请枚举显式 depths，例如 *.env、*/*.env 和 */*/*.env。
当相同 rules 应用于当前 session root 之外的更多 roots 时，请向 profile 添加 reusable workspace roots：
[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true当这个 profile 处于 active 状态时，Codex 会把 :workspace_roots rules 应用于当前 session 的 runtime workspace roots，以及每个已启用的 profile-defined workspace root。
在 native Windows 上，D:\work 这样的 drive-letter paths 和 \\server\share 这样的 UNC paths 都支持作为 absolute paths。
Network permissions
设置 enabled = true，为所选 profile 允许 network access：
[permissions.project-edit.network]
enabled = true当 network access 启用时，Codex 默认使用 full network behavior。大多数 profiles 还应该定义 domain rules：
[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 allownetwork sandbox proxy 默认绑定到 local listeners：
[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除非你正在与特定 runtime 集成，否则请保持这些 listener settings 为默认值。dangerously_* network keys 是面向 specialized environments 的 escape hatches，不应在普通 local development 中使用。
Local 和 private networks
Codex 默认应用 local/private-network guard，作为针对 DNS rebinding 和意外访问 local services 的防御。要有意允许 literal local target，请 allowlist exact host 或 IP literal：
[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"只有当 profile 必须访问解析到 local 或 private addresses 的 allowlisted hostnames 时，才设置 allow_local_binding = true：
[permissions.project-edit.network]
enabled = true
allow_local_binding = true
[permissions.project-edit.network.domains]
"localhost" = "allow"Unix sockets
Unix socket proxying 是 Docker 等 tools 的 local escape hatch。请谨慎使用：
[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"使用 deny 拒绝 socket path，包括 inherited allow entry。Denied socket paths 会从 effective allowlist 中省略。
启用 Unix sockets 时，请让 proxy listeners 继续绑定到 loopback addresses。
从旧 sandbox settings 迁移
当你希望一个 reusable profile 同时描述 filesystem 和 network behavior 时，permission profiles 会替代旧的 sandbox_mode 与 sandbox_workspace_write 组合。一个 session 中请使用其中一个 system，不要两者同时使用。
建议的 starting points：
对于 read-only workflow，使用内置 :read-only profile，或定义只在需要位置授予 read access 的 custom profile。
对于 workspace editing，使用内置 :workspace profile，或定义通过 :workspace_roots 写入，并只添加 workflow 需要的额外 temp 或 cache paths 的 custom profile。
对于 unrestricted local execution，只有当你有意使用最宽泛 local access model 时，才使用 :danger-full-access。
Profiles 描述 session 的 local default posture。Organization-managed requirements 仍然可以添加 user configuration 不应放宽的 restrictions。有关 admin-enforced filesystem 和 network constraints，请参阅 Managed configuration 。
Scope and enforcement
Permission profiles 定义 local sandboxed command execution 的边界。请将它们与 approval policies 以及其他 Codex surfaces 的独立 controls 配合使用。
Profiles 控制什么
Local command execution：Permission profiles 管理在你机器上运行的 sandboxed commands。App connectors、MCP servers、browser 或 computer-use surfaces、Codex cloud environment settings，以及已批准的 escalations 都使用各自的 controls。
Filesystem writes：具有写入能力的 profile 可以创建 persistent changes。请把写入 scripts、build steps、package manager hooks、shell startup files 和 shared directories 视为敏感操作，因为后续 tools 或 users 可以在原 sandbox context 之外执行这些 files。
Outbound destinations：Network domain rules 限制 sandboxed command traffic 可以通过 network proxy 到达哪里。它们并不判断 allowed destination 是否可信，wildcard allow rules 仍然很宽泛。
Local services：Local 和 private network targets 默认会被 blocked。Allowlisting localhost、private IPs、Unix sockets，或设置 allow_local_binding = true，都会显式打开对 local services 的访问。
Enforcement 如何工作
在 macOS 上，Codex 使用 Seatbelt sandbox profiles。如果所选 policy 无法由 platform sandbox enforce，Codex 会拒绝运行 command，而不是静默地 unsandboxed 运行。
在 Linux 和 WSL 上，Codex 使用 bubblewrap 和 seccomp ，并在 compatibility fallback paths 中提供 Landlock。最强 enforcement path 取决于 user namespaces 和 kernel support；受限 container hosts 可能强制使用 compatibility paths，不支持的 split policies 会被拒绝。
在 native Windows 上， elevated sandboxing 最强，因为它可以使用专用低权限 sandbox users、filesystem permission boundaries 和 firewall rules。un elevated sandboxing 是更弱的 fallback，network isolation 更弱，且不能 enforce 每一种 split read/write carveout，因此不支持的 policies 会被拒绝。当你需要 Linux sandbox model 时，请使用 WSL。
Operational guidance
选择仍能让任务完成的最窄 profile，尤其是在授予 writes 或 outbound network access 时。请让 approval policy、secret handling 和 allow rules 与该 access level 保持一致。
常见 profiles
带 network allowlist 的 read-only
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"File access 限制在 workspace 内
下面是一个 permission profile 示例：它会让 Codex 可以写入你的 workspace folders，同时拒绝读取 filesystem 的其他部分（有限例外由 :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"无 network 的 workspace write
default_permissions = "project-edit"
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
[permissions.project-edit.network]
enabled = false带 public web access 的 workspace write
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"只有当你确实打算允许 public network access 时，才使用 global "*" allow rule。Deny rules 可以缩窄宽泛 allowlist。