권한

권한 프로필을 사용하면 Codex가 사용자를 대신해 실행하는 로컬 명령에 최소 권한 경계를 적용할 수 있습니다. 프로필은 명령이 읽거나 쓸 수 있는 대상을 정의하는 파일 시스템 규칙과 명령이 연결할 수 있는 대상을 정의하는 네트워크 규칙을 결합한 이름 있는 정책입니다.

프로필을 사용하면 시스템이나 네트워크에 광범위한 액세스 권한을 부여하지 않고도 현재 채팅에 필요한 만큼만 Codex에 액세스 권한을 제공할 수 있습니다. 예를 들어 읽기 전용 프로필을 사용하면 Codex가 프로젝트를 편집하지 않고 검사할 수 있으며, 쓰기 가능 프로필을 사용하면 편집 범위를 선택한 작업 공간 루트로 제한할 수 있습니다.

로컬 권한 프로필은 macOS, Linux, WSL 및 네이티브 Windows에서 지원됩니다. 플랫폼별 세부 정보와 주의 사항은 범위 및 적용을 참조하세요.

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"

이 프로필은 다음과 같이 동작합니다.

• 일반적인 개발자 도구에 필요한 최소한의 런타임 경로를 읽습니다.
• 현재 세션 및 프로필에 정의된 루트에 동일한 작업 공간 루트 규칙을 적용합니다.
• 각 루트 아래에서 .devcontainer/과 같은 IDE 인접 설정을 읽기 전용으로 유지합니다.
• 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보다 우선합니다.

이 우선순위를 사용하면 프로필에서 먼저 광범위한 작업 영역을 지정한 다음, 읽을 수 없는 상태로 유지해야 하는 파일이나 디렉터리를 제외할 수 있습니다.

[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 패턴은 읽기 거부 규칙으로 지원됩니다. read 또는 write glob은 Linux, WSL, 네이티브 Windows 샌드박스에서 이식성이 떨어지므로 가능한 경우 정확한 경로나 "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 경로가 절대 경로로 지원됩니다.

네트워크 권한

선택한 프로필의 네트워크 액세스를 허용하려면 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을 통해 쓰기를 허용하고 워크플로에 필요한 추가 임시 또는 캐시 경로만 추가하는 사용자 지정 프로필을 정의하세요.
• 제한 없는 로컬 실행에는 의도적으로 가장 광범위한 로컬 액세스 모델을 사용하려는 경우에만 :danger-full-access를 사용하세요.

프로필은 세션의 기본 로컬 보안 수준을 설명합니다. 조직에서 관리하는 요구 사항은 사용자 구성이 확장할 수 없는 추가 제한을 적용할 수 있습니다. 관리자가 강제하는 파일 시스템 및 네트워크 제약 조건은 관리형 구성을 참조하세요.

범위 및 적용

권한 프로필은 로컬 샌드박스 명령 실행의 경계를 정의합니다. 승인 정책 및 커넥터, MCP 서버, 기본 제공 브라우저, Computer Use, Codex cloud에 대한 별도 제어 기능과 함께 사용하세요.

프로필이 제어하는 항목

• 로컬 명령 실행: 권한 프로필은 컴퓨터에서 실행되는 샌드박스 명령을 제어합니다. 커넥터, MCP 서버, 브라우저 또는 computer-use 인터페이스, Codex cloud 환경 설정, 승인된 권한 상승에는 각각 자체 제어 기능이 적용됩니다.
• 파일 시스템 쓰기: 쓰기 가능한 프로필은 영구적인 변경 사항을 생성할 수 있습니다. 나중에 다른 도구나 사용자가 원래 샌드박스 컨텍스트 밖에서 해당 파일을 실행할 수 있으므로 스크립트, 빌드 단계, 패키지 관리자 훅, 셸 시작 파일, 공유 디렉터리에 쓰는 작업은 민감하게 취급하세요.
• 아웃바운드 대상: 네트워크 도메인 규칙은 샌드박스 명령 트래픽이 네트워크 프록시를 통해 도달할 수 있는 위치를 제한합니다. 이러한 규칙은 허용된 대상의 신뢰성을 판단하지 않으며, 와일드카드 허용 규칙은 여전히 광범위합니다.
• 로컬 서비스: 로컬 및 사설 네트워크 대상은 기본적으로 차단됩니다. localhost, 사설 IP, Unix 소켓을 허용 목록에 추가하거나 allow_local_binding = true을 설정하면 로컬 서비스에 대한 액세스가 명시적으로 열립니다.

적용 방식

• macOS에서 Codex는 Seatbelt 샌드박스 프로필을 사용합니다. 선택한 정책을 플랫폼 샌드박스에서 적용할 수 없으면 Codex는 명령을 샌드박스 없이 자동으로 실행하는 대신 실행을 거부합니다.
• Linux 및 WSL에서 Codex는 bubblewrap과 seccomp를 사용하며, 호환성 대체 경로에는 Landlock을 사용할 수 있습니다. 가장 강력한 적용 경로는 사용자 네임스페이스와 커널 지원에 따라 달라집니다. 제한된 컨테이너 호스트에서는 호환성 경로가 강제될 수 있으며, 지원되지 않는 분리 정책은 거부됩니다.
• 네이티브 Windows에서는 전용 저권한 샌드박스 사용자, 파일 시스템 권한 경계, 방화벽 규칙을 사용할 수 있으므로 elevated 샌드박스가 가장 강력합니다. unelevated 샌드박스는 네트워크 격리가 더 약하고 모든 분리된 읽기/쓰기 제외 범위를 적용할 수 없는 대체 방식이므로 지원되지 않는 정책은 거부됩니다. Linux 샌드박스 모델이 필요한 경우 WSL을 사용하세요.

운영 지침

특히 쓰기 또는 아웃바운드 네트워크 액세스를 허용할 때는 작업을 완료할 수 있는 가장 제한적인 프로필을 선택하세요. 승인 정책, 보안 비밀 처리, 허용 규칙을 해당 액세스 수준에 맞게 유지하세요.

일반적인 프로필

네트워크 허용 목록을 사용하는 읽기 전용 프로필

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

공개 웹 액세스를 사용하는 워크스페이스 쓰기

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"

공개 네트워크 액세스를 허용하려는 경우에만 전역 "*" 허용 규칙을 사용하세요. 거부 규칙을 사용하면 광범위한 허용 목록의 범위를 좁힐 수 있습니다.