권한

관리형 allowed_permission_profiles은 예외입니다. 이 설정은 Codex가 권한 프로필을 사용하도록 합니다. 관리형 프로필 허용 목록을 배포하기 전에 sandbox_mode 및 [sandbox_workspace_write] 같은 이전 설정을 제거하세요. 여러 버전이 혼재하는 엔터프라이즈 롤아웃에서는 모든 클라이언트가 Codex 0.138.0 이상을 실행할 때까지 관리형 allowed_sandbox_modes 요구 사항을 임시 호환성 제약 조건으로 유지할 수 있습니다.

권한 프로필을 사용하면 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"

[features]
network_proxy = true

[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"

[features]
network_proxy = true

[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 경로가 절대 경로로 지원됩니다.

네트워크 권한

네트워크 액세스와 네트워크 필터링은 별도의 설정입니다. 명령이 네트워크에 액세스하도록 하려면 permissions.<name>.network.enabled = true를 설정하고, 프로필의 도메인 규칙을 적용하려면 features.network_proxy을 활성화하세요.

[features]
network_proxy = true

[permissions.project-edit.network]
enabled = true

[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.<name>.network.domains]을 추가하거나 permissions.<name>.network.enabled = true를 설정해도 features.network_proxy이 활성화되지는 않습니다. 또는 관리자가 requirements.toml에서 [experimental_network]을 사용하여 프록시를 활성화할 수 있습니다. 관리형 구성을 참조하세요.

활성 상태일 때 네트워크 샌드박스 프록시는 기본적으로 로컬 리스너에 바인딩됩니다.

[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 클라우드를 위한 별도의 제어 기능과 함께 사용하세요.

프로필에서 제어하는 항목

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

네트워크 프록시에서 제어하지 않는 항목

네트워크 프록시는 샌드박스 안에서 실행되는 로컬 명령의 트래픽만 필터링합니다. 다음 항목에는 프로필의 도메인 허용 목록이 적용되지 않습니다.

• 웹 검색: 호스팅된 검색 도구는 자체 액세스 설정을 사용합니다. 이를 제어하려면 web_search과 관리형 클라이언트의 경우 allowed_web_search_modes을 사용하세요. tools.web_search.allowed_domains은 명령 네트워크 액세스가 아니라 검색 결과를 필터링합니다.
• 앱 및 커넥터: 커넥터 기반 도구는 자체 서비스 측 연결, 워크스페이스 권한, 앱 또는 도구 설정을 사용합니다.
• MCP 서버: 로컬 및 원격 MCP 서버는 자체 프로세스 또는 전송 방식을 사용합니다. mcp_servers 구성과 관리형 서버 허용 목록으로 제어하세요.
• 브라우저 및 Computer Use: 브라우저 탐색과 Computer Use 작업에는 자체 기능 및 승인 제어가 사용됩니다.
• Codex 서비스 트래픽: 모델, 인증 및 기타 클라이언트 서비스 요청에는 클라이언트의 별도 HTTP 및 시스템 프록시 설정이 사용됩니다.
• Codex 클라우드: 이러한 작업에는 해당 환경 자체의 인터넷 액세스 설정이 사용됩니다.

이러한 인터페이스를 제한하려면 각 기능을 직접 구성하세요. 명령 네트워크 허용 목록은 Codex가 수행할 수 있는 모든 작업에 적용되는 전역 네트워크 정책이 아닙니다.

적용 방식

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

운영 지침

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

일반적인 프로필

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

default_permissions = "readonly-net"

[features]
network_proxy = true

[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"

워크스페이스로 제한된 파일 액세스

다음은 제한적인 예외(:minimal에서 결정됨)를 제외한 나머지 파일 시스템의 읽기를 거부하면서 Codex가 워크스페이스 폴더에 쓸 수 있도록 하는 권한 프로필의 예입니다.

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"

[features]
network_proxy = true

[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"

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