권한
파일 시스템 및 네트워크 액세스를 위한 베타 Codex 권한 프로필 구성
관리형 allowed_permission_profiles는 예외입니다. 이 설정은 Codex가
권한 프로필을 사용하도록 합니다. 관리형 프로필 허용 목록을 배포하기 전에
sandbox_mode 및 [sandbox_workspace_write] 같은 이전 설정을 제거하세요.
여러 버전이 혼재하는 엔터프라이즈 롤아웃에서는 모든 클라이언트가 Codex 0.138.0
이상을 실행할 때까지 관리형 allowed_sandbox_modes 요구 사항을 임시 호환성
제약 조건으로 유지할 수 있습니다.
권한 프로필을 사용하면 Codex가 사용자를 대신해 실행하는 로컬 명령에 최소 권한 경계를 적용할 수 있습니다. 프로필은 명령이 읽거나 쓸 수 있는 항목을 정의하는 파일 시스템 규칙과 명령이 연결할 수 있는 대상을 정의하는 네트워크 규칙을 결합한 명명된 정책입니다.
프로필을 사용하면 컴퓨터나 네트워크에 광범위한 액세스 권한을 부여하지 않고도 현재 채팅에 필요한 만큼 Codex에 액세스 권한을 제공할 수 있습니다. 예를 들어 읽기 전용 프로필을 사용하면 Codex가 프로젝트를 편집하지 않고 검사할 수 있고, 쓰기 가능 프로필을 사용하면 편집 범위를 선택한 워크스페이스 루트로 제한할 수 있습니다.
로컬 권한 프로필은 macOS, Linux, WSL 및 네이티브 Windows에서 지원됩니다. 플랫폼별 세부 정보와 주의 사항은 범위 및 적용을 참조하세요.
현재 Codex Cloud 네트워크 설정은 서비스 연결을 참고하세요. Codex Cloud (Legacy)는 인터넷 액세스를 참고하세요.
프로필 정의 및 선택
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" = trueserver가 활성화되면 두 워크스페이스 루트가 모두 유효
프로필에 포함됩니다.
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를 확장하면
워크스페이스 루트의 .git, .agents, .codex, .aws 경로는 읽기 전용으로 유지됩니다.
이 규칙을 명시적으로 재정의한 경우는 예외입니다. 상위 프로필을 한 번 설정한 다음
차이가 있는 규칙만 추가하거나 재정의합니다.
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는 알 수 없는 상위 프로필과 상속 순환도 거부합니다.
구성 사양
| 항목 | 유형 / 값 | 기본값 | 세부 정보 |
|---|---|---|---|
default_permissions |
문자열 프로필 이름 | 없음 | Codex가 기본적으로 적용할 권한 프로필의 이름을 지정합니다. [permissions] 아래의 프로필이나 :workspace 같은 기본 제공 프로필과 일치해야 합니다. 예측 가능한 동작을 위해 명시적으로 설정하세요. 관리형 요구 사항에서는 :workspace 및 :read-only가 모두 명시적으로 허용된 경우에만 이를 생략할 수 있습니다. 관리형 allowed_permission_profiles에서 이 설정에 권한 프로필을 사용하도록 지정하지 않으면 Codex는 이전 샌드박스 설정을 사용합니다. |
[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 |
숫자 | 없음 | Codex가 샌드박스를 시작하기 전에 일치 항목의 스냅샷을 생성할 때 Linux, WSL, 네이티브 Windows에서 읽기 거부 glob 확장의 범위를 제한합니다. 값이 클수록 시작 시 검사 작업이 늘어날 수 있습니다. 무제한 ** 패턴을 제한된 범위로 사전 확장해야 할 때는 최소 1 이상의 값을 사용하세요. |
[permissions.<name>.filesystem]."<path>" |
read, write 또는 deny |
없음 | 지원되는 경로에 대한 직접 액세스를 허용합니다. deny는 액세스를 거부하며 구체성이 동일한 write 또는 read 항목보다 우선합니다. Codex는 활성 런타임이 강제할 수 없는 직접 쓰기 규칙을 거부합니다. |
[permissions.<name>.filesystem."<path>"]."<subpath>" |
read, write 또는 deny |
없음 | <path>의 하위 경로에 대한 액세스를 허용합니다. 기본 경로에는 .를 사용하세요. 다른 하위 경로는 상대 하위 경로여야 하며 . 또는 .. 구성 요소를 포함할 수 없습니다. |
[permissions.<name>.network] |
테이블 | 없음 | 명령의 네트워크 액세스와 활성 네트워크 프록시가 강제하는 정책을 구성합니다. 관리자가 관리하는 네트워크 요구 사항에서 프록시를 시작하지 않는 한 features.network_proxy를 활성화하세요. |
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_PROXY, HTTPS_PROXY, WebSocket 프록시 변수 및 관련 도구 프록시 환경 변수에 사용되는 HTTP 프록시 리스너입니다. |
permissions.<name>.network.enable_socks5 |
불리언 | true |
ALL_PROXY 및 FTP 프록시 변수에 사용되는 SOCKS5 리스너를 활성화합니다. |
permissions.<name>.network.socks_url |
URL 문자열 | http://127.0.0.1:8081 |
SOCKS5 리스너 주소입니다. |
permissions.<name>.network.enable_socks5_udp |
불리언 | true |
SOCKS5 리스너가 활성화되어 있을 때 SOCKS5 UDP 지원을 활성화합니다. |
permissions.<name>.network.allow_upstream_proxy |
불리언 | true |
네트워크 샌드박스 프록시가 아웃바운드 요청에 업스트림 HTTP(S)_PROXY 및 ALL_PROXY 설정을 반영하도록 허용합니다. |
permissions.<name>.network.allow_local_binding |
불리언 | false |
true이면 로컬/사설 네트워크 보호 기능을 비활성화합니다. false이면 localhost 또는 127.0.0.1 같은 정확한 로컬 리터럴을 허용 목록에 명시적으로 추가해야 하며, 로컬 또는 사설 IP로 해석되는 호스트 이름은 계속 차단됩니다. |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
불리언 | false |
프록시 리스너가 루프백이 아닌 주소에 바인딩하도록 허용합니다. 일반적인 로컬 개발에서는 설정하지 마세요. |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
불리언 | false |
Unix 소켓 프록시가 지원되는 환경에서 Unix 소켓 허용 목록을 우회합니다. 이는 로컬 제한을 광범위하게 우회하는 수단입니다. |
파일 시스템 권한
파일 시스템 항목은 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 |
macOS/Linux/WSL의 /path 또는 네이티브 Windows의 C:\path 같은 플랫폼 절대 경로 |
예 |
~/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으로 읽기 거부
더 광범위한 프로필 규칙이 인접 영역에 액세스 권한을 부여하더라도 Codex가 읽어서는
안 되는 파일이나 하위 트리에는 deny를 사용하세요. 정확한 경로는
~/.ssh 같은 고정된 위치에 적합합니다. glob 패턴은 정확한 위치가 저장소마다
달라지는 민감한 파일 모음을 프로필에서 처리해야 할 때 더 적합합니다.
glob이 :workspace_roots 아래에 있으면 Codex는 각 유효 워크스페이스 루트를
기준으로 이를 해석합니다. 예를 들면 다음과 같습니다.
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"이 규칙은 각 런타임 또는 프로필 정의 워크스페이스 루트 아래에서 발견된 일치하는
.env 파일의 읽기를 거부합니다. 일반적인 워크스페이스 쓰기 권한은 유지하면서
환경 파일, 생성된 보안 비밀 또는 이와 유사한 자격 증명 포함 파일을 읽을 수 없게
하려는 경우 사용하세요.
Linux, WSL 및 MXC 또는 elevated를 사용하는 네이티브 Windows에서는 읽기 거부 glob에 일치하는 파일을
각 샌드박스 프로세스가 시작될 때 열거합니다. 이후에 생성된 일치 파일은
해당 프로세스의 거부 목록에 추가되지 않으며, 다른 권한이
접근을 허용하면 계속 읽을 수 있습니다. 예를 들어 장시간 실행되는 셸, 스크립트, 감시 프로그램 또는 개발
서버는 시작된 후에 생성된 일치하는 .env 파일을 읽을 수 있습니다.
이 스냅샷은 전체 Codex 세션이 아니라 샌드박스 프로세스가 실행되는 동안 유지됩니다. Codex를 통해 새 샌드박스 프로세스를 시작하면 일치하는 파일을 다시 열거합니다. 이미 실행 중인 프로세스를 계속 사용해도 거부 목록은 갱신되지 않습니다. 실행 중인 프로세스에서 새로 생성된 파일을 차단하는 데 glob에 의존하지 마세요. Windows 관련 제한 사항은 Windows MXC 호환성을 참고하세요.
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를 사용하세요.
프로필은 세션의 기본 로컬 보안 태세를 설명합니다. 조직 관리형 요구 사항은 사용자 구성으로 완화해서는 안 되는 제한을 계속 추가할 수 있습니다. 관리자가 적용하는 파일 시스템 및 네트워크 제약 조건은 관리형 구성을 참조하세요.
범위 및 적용
Work Cloud를 통한 로컬 컴퓨터 액세스 및 환경 정책
Work Cloud를 통한 로컬 컴퓨터 액세스가 실행되는 각 환경의 정책을 검토하세요.
- 엔터프라이즈 요구 사항: 로컬 액세스를 사용하는 Work 및 dots에서는 관리형 정책이 활성화되어 있으면 지원되는 Global 정책이 공유 클라우드 오케스트레이터를 제어하고, 해당 로컬 실행 요구 사항이 연결된 컴퓨터를 제어합니다.
- 클라우드 실행: Work 클라우드 컨테이너는 기존 Work Cloud 정책을 사용합니다.
- 로컬 정책 순서: MDM 및 기존 관리형 기기 요구 사항은 Agent Security보다 우선합니다. 기기의 시스템 요구 사항 파일은 Agent Security보다 우선순위가 낮습니다.
- 정책 우선순위: 우선순위가 낮은 정책이 더 구체적이더라도 우선순위가 높은 정책이 우선합니다. 한 정책 내에서는 OS별 환경 재정의가 모든 OS에 대한 환경 재정의보다 우선하며, 그다음은 Global입니다.
일부 요구 사항에는 필드별 병합 규칙이 있습니다. 지원되는 필드와 런타임 제한은 관리형 구성 및 구성 참조를 참고하세요. Work Cloud가 여기에 제시된 Codex 권한 프로필을 지원한다고 가정하지 마세요.
권한 프로필은 로컬 샌드박스 명령 실행의 경계를 정의합니다. 승인 정책 및 웹 검색, 커넥터, MCP server, 기본 제공 브라우저, Computer Use, Codex 클라우드를 위한 별도의 제어 기능과 함께 사용하세요.
프로필에서 제어하는 항목
- 로컬 명령 실행: 권한 프로필은 사용자의 컴퓨터에서 실행되는 샌드박스 명령을 제어합니다. 커넥터, MCP server, 브라우저 또는 Computer Use 인터페이스, Codex 클라우드 환경 설정 및 승인된 권한 상승에는 각각 별도의 제어 기능이 사용됩니다.
- 파일 시스템 쓰기: 쓰기 가능 프로필은 영구적인 변경 사항을 만들 수 있습니다. 후속 도구나 사용자가 원래의 샌드박스 컨텍스트 밖에서 해당 파일을 실행할 수 있으므로 스크립트, 빌드 단계, 패키지 관리자 훅, 셸 시작 파일 및 공유 디렉터리에 대한 쓰기를 민감한 작업으로 취급하세요.
- 아웃바운드 대상: 네트워크 도메인 규칙은 네트워크 프록시가 활성 상태일 때만 샌드박스 명령 트래픽의 대상을 제한합니다. 이 규칙은 허용된 대상의 신뢰성을 판단하지 않으며, 와일드카드 허용 규칙의 범위는 계속 넓습니다.
- 로컬 서비스: 활성 네트워크 프록시는 기본적으로 로컬 및 사설 네트워크
대상을 차단합니다.
localhost, 사설 IP, Unix 소켓을 허용 목록에 추가하거나allow_local_binding = true를 설정하면 로컬 서비스에 대한 액세스가 명시적으로 열립니다.
네트워크 프록시에서 제어하지 않는 항목
네트워크 프록시는 샌드박스 안에서 실행되는 로컬 명령의 트래픽만 필터링합니다. 다음 항목에는 프로필의 도메인 허용 목록이 적용되지 않습니다.
- 웹 검색: 호스팅된 검색 도구는 자체 액세스 설정을 사용합니다.
web_search를 사용하고, 관리형 클라이언트에서는allowed_web_search_modes도 사용하여 이를 제어하세요.tools.web_search.allowed_domains는 명령의 네트워크 액세스가 아니라 검색 결과를 필터링합니다. - 앱 및 커넥터: 커넥터 기반 도구는 자체 서비스 측 연결, 작업 공간 권한, 앱 또는 도구 설정을 사용합니다.
- MCP server: 로컬 및 원격 MCP server는 자체 프로세스 또는
전송 방식을 사용합니다.
mcp_servers구성과 관리형 서버 허용 목록으로 제어하세요. - 브라우저 및 Computer Use: 브라우저 탐색과 컴퓨터 사용 작업은 자체 기능 및 승인 제어를 사용합니다.
- Codex 서비스 트래픽: 모델, 인증 및 기타 클라이언트 서비스 요청은 클라이언트의 별도 HTTP 및 시스템 프록시 설정을 사용합니다.
- Codex Cloud: 이러한 작업은 해당 환경의 자체 네트워크 설정을 사용합니다. Codex Cloud (Legacy)에는 별도의 인터넷 액세스 설정이 있습니다.
이러한 인터페이스를 제한하려면 각 기능을 직접 구성하세요. 명령 네트워크 허용 목록은 Codex가 수행할 수 있는 모든 작업에 적용되는 전역 네트워크 정책이 아닙니다.
적용 방식
- macOS에서 Codex는 Seatbelt 샌드박스 프로필을 사용합니다. 선택한 정책을 플랫폼 샌드박스에서 적용할 수 없으면, Codex는 샌드박스 없이 명령을 조용히 실행하는 대신 명령 실행을 거부합니다.
- Linux와 WSL에서 Codex는 bubblewrap
및 seccomp를
사용하여 파일 시스템 제한을 적용합니다. 기존 Landlock 옵션은
app-server Unix 소켓을 격리할 수 없으므로 파일 시스템을 제한하는 정책에서는 사용할 수 없습니다.
업그레이드할 때
features.use_legacy_landlock을 비활성화합니다. 필수 bubblewrap 작업을 차단하는 호스트에서는 이러한 정책을 실행할 수 없습니다. - Windows에서 MXC는 프로세스 격리를 사용하여 파일 시스템 및 네트워크 권한을 적용합니다.
활성화하기 전에 MXC 호환성을
검토합니다. 기존
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
# paths such as .git/, .agents/, .codex/, and .aws/ 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"공개 네트워크 액세스를 허용하려는 경우에만 전역 "*" 허용 규칙을
사용하세요. 거부 규칙을 사용하면 광범위한 허용 목록의 범위를 좁힐 수 있습니다.