การจัดการสิทธิ์ใน Codex

กำหนดค่า Permission Profile สำหรับการควบคุมการเข้าถึง Filesystem และ Network ของ Codex

Configure beta Codex permission profiles for filesystem and network access

Beta. Permission profiles are under active development and may change.

Permission profiles do not compose with the older sandbox settings. Configure either default_permissions and [permissions], or sandbox_mode / sandbox_workspace_write, but not both. If sandbox_mode appears in any loaded config file, you pass --sandbox, or the selected config profile sets sandbox_mode, Codex uses those older sandbox settings instead of default_permissions.

Managed allowed_permission_profiles is the exception: it makes Codex use permission profiles. Remove older settings such as sandbox_mode and [sandbox_workspace_write] before deploying a managed profile allowlist. For a mixed-version enterprise rollout, you can keep the managed allowed_sandbox_modes requirement as a temporary compatibility constraint until every client runs Codex 0.138.0 or later.

Permission profiles let you apply least-privilege boundaries to local commands Codex runs on your behalf. A profile is a named policy that combines filesystem rules, which define what commands can read or write, with network rules, which define which destinations commands can reach.

Use profiles to give Codex enough access for the current task without granting broad access to your machine or network. For example, a read-only profile can let Codex inspect a project without editing it, while a write-capable profile can limit edits to selected workspace roots.

Local permission profiles are supported on macOS, Linux, WSL, and native Windows. See Scope and enforcement for platform-specific details and caveats.

For Codex cloud network settings, see Internet Access.

Define and select a profile

Codex includes three built-in permission profiles:

:read-only keeps local command execution read-only.

:workspace allows writes inside the active workspace roots and system temp directories.

:danger-full-access removes local sandbox restrictions and should be used only when that broad access is intentional.

Create a named profile under [permissions.<name>], then set the top-level default_permissions key to that profile name or to one of the built-ins above. In this example, project-edit is a user-defined profile name, not a built-in value.

Enterprise administrators can define profiles and restrict which profiles users may select through managed requirements.toml. Once allowed_permission_profiles is present, omitted profiles are denied, including omitted built-ins and profiles added in future Codex versions. See Control available permission profiles for the recommended managed configuration.

Custom profiles use two related concepts:

[permissions.<name>.workspace_roots] adds concrete directories that should count as workspace roots for that profile.

[permissions.<name>.filesystem.":workspace_roots"] defines the filesystem rules Codex applies inside every effective workspace root: the current session’s runtime workspace roots plus the profile-defined roots above.

Profiles also use the normal config-layer model. Higher-precedence layers can add or replace entries under the same profile name without restating the whole profile.

For example, an organization-level config and a user-level config can extend the same profile independently:

/etc/codex/config.toml [permissions.server.workspace_roots] "~/code/server" = true # /.codex/config.toml [permissions.server.workspace_roots] "/code/mobile-app" = true When server is active, both workspace roots participate in the 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" This profile:

Reads the minimal runtime paths common developer tools need.

Applies the same workspace-root rules to the current session and the profile-defined roots.

Keeps IDE-adjacent settings such as .devcontainer/ read-only under each root.

Denies matching environment files with a glob rule.

Allows network access only through the configured domain policy.

Inside an active profile, narrower deny rules stay in force even when a broader path is readable or writable. For example, a profile can make workspace roots writable while still setting a matching .env path to deny.

Extend a profile

Use extends when a profile is mostly the same as a built-in or another named profile. Prefer extending a built-in profile over starting from scratch so baseline protections carry forward. Extending :workspace, for example, keeps the workspace root’s .codex directory read-only unless you explicitly override it. Set the parent once, then add or override only the rules that differ.

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" This profile starts with :workspace, keeps matching .env files denied, and allows requests to api.openai.com. A profile can extend :read-only, :workspace, or another named profile. It cannot extend :danger-full-access; Codex also rejects unknown parents and inheritance cycles.

Configuration spec

Entry

Type / values

Default

Details

default_permissions

String profile name

None

Names the permissions profile Codex applies by default. It must match a profile under [permissions] or a built-in such as :workspace. Set it explicitly for predictable behavior; managed requirements may omit it only when both :workspace and :read-only are explicitly allowed. Codex uses older sandbox settings unless managed allowed_permission_profiles tells it to use permission profiles in this setup.

[permissions.<name>]

Table

None

Defines a named profile. default_permissions selects one profile as the default; other permission-profile settings also use the profile name.

permissions.<name>.description

String

None

Provides a human-readable description for the profile. A profile does not inherit its parent’s description through extends.

permissions.<name>.extends

String profile name

None

Starts this profile from another named profile or the built-in :read-only or :workspace profile. Codex rejects :danger-full-access, unknown parents, and inheritance cycles.

[permissions.<name>.workspace_roots]

Table

None

Adds profile-defined workspace roots that receive :workspace_roots filesystem rules alongside the current session’s runtime workspace roots.

permissions.<name>.workspace_roots."<path>"

Boolean

false

Adds the path to the profile’s workspace root set when true. Entries set to false remain inactive.

[permissions.<name>.filesystem]

Table

None

Maps filesystem paths to access values or scoped subpath maps. Missing or empty filesystem tables keep filesystem access restricted and emit a startup warning.

permissions.<name>.filesystem.glob_scan_max_depth

Number

None

Limits deny-read glob expansion on Linux, WSL, and native Windows when Codex snapshots matches before sandbox startup. Larger values can increase startup scanning work. Use a value of at least 1 when an unbounded ** pattern needs bounded pre-expansion.

[permissions.<name>.filesystem]."<path>"

read, write, or deny

None

Grants direct access for a supported path. deny denies access and wins over equally specific write or read entries. Codex rejects direct write rules that the active runtime cannot enforce.

[permissions.<name>.filesystem."<path>"]."<subpath>"

read, write, or deny

None

Grants access to a descendant of <path>. Use . for the base path. Other subpaths must be relative descendants and cannot contain . or .. components.

[permissions.<name>.network]

Table

None