Codex 샌드박스 권한 프로필: 전체 접근 권한 없이 npm 허용하기

Codex 작업 공간의 보호 규칙을 유지하면서 패키지 레지스트리 접근을 허용합니다. 권한 프로필과 네트워크 프록시를 설정하고 허용 및 차단 동작을 검증합니다. 넓은 파일 읽기 권한, 운영체제의 샌드박스 제한, 기업 관리 요구 사항에 따른 프로필 선택 제한도 살펴봅니다.

목차
Codex 샌드박스 권한 프로필: 전체 접근 권한 없이 npm 허용하기

Codex가 저장소 파일은 수정하지만 npm 패키지를 다운로드하지 못한다면, API 설정을 바꾸기 전에 샌드박스 권한 프로필부터 확인합니다. 기본 제공 프로필 :workspace는 명령의 네트워크 접근을 차단하므로, 로컬 Codex 세션에서 의존성을 설치하는 개발자가 이 제한을 겪게 됩니다. 전체 접근 권한으로 전환하는 대신 :workspace를 상속한 프로필을 만들고, 네트워크 프록시를 활성화한 뒤 레지스트리 호스트 이름을 허용합니다.

2026-11-19 기준으로 OpenAI는 권한 프로필을 베타 기능으로 안내합니다. 이 글에서는 로컬에서 명령을 실행할 때 적용되는 권한을 설정합니다. 예제에 사용하는 셸은 Bash이며, macOS, Linux 또는 WSL2에서 설정과 동작을 확인하는 절차를 다룹니다.

기본 작업 공간 프로필은 무엇을 허용합니까?

Git 저장소를 작업 공간 루트로 사용하면 :workspace는 샌드박스 명령이 소스 파일을 수정하도록 허용하면서 일부 디렉터리를 보호합니다. 각 작업 공간 루트 아래의 .git, .codex, .agents, .aws는 읽기 전용으로 유지됩니다. 따라서 .codex/config.toml 같은 저장소 설정이나 .git/hooks 아래의 훅을 직접 변경할 수 없습니다. 이 보호는 작업 공간 루트 아래의 경로에 적용됩니다. 컴퓨터에 있는 모든 동명 디렉터리를 보호하는 규칙은 아닙니다.

읽기 권한은 더 넓게 허용됩니다. 운영체제에서 사용자가 가진 권한이 허용하면 명령은 저장소 밖의 파일도 읽을 수 있습니다. OpenAI의 기본 샌드박스 경계 설명은 이렇게 해야 다른 위치의 컴파일러, SDK, 라이브러리와 설정을 사용할 수 있다고 설명합니다. 그렇다고 이 파일들이 Codex 명령으로부터 숨겨지는 것은 아닙니다.

기본적으로 네트워크를 끄는 이유는 데이터를 읽을 수 있는 명령에 외부 전송 권한까지 자동으로 주지 않기 위해서입니다. 같은 이유로 의존성을 다운로드할 때도 추가 접근 권한이 필요합니다. OpenAI는 자식 프로세스가 부모 프로세스의 샌드박스 제한을 상속한다고 명시합니다. 원래 명령이 종료된 뒤에도 실행 중인 하위 프로세스에 이 제한이 계속 적용됩니다.

가끔 다운로드하는 정도라면 기본 프로필을 바꾸기보다 네트워크 접근 요청을 검토합니다. 네트워크 프록시 설명에 따르면 Codex는 요청을 사용자에게 보내거나 자동 검토로 넘길 수 있습니다. 의존성을 자주 다운로드한다면 해당 레지스트리에 접근을 허용한 전용 프로필을 사용합니다. 네트워크가 필요하지 않은 작업에서는 비활성 상태를 유지합니다.

npm 레지스트리용 dev 프로필 설정하기

설치된 Codex CLI는 문서에 나온 codex sandbox --permission-profile 인터페이스를 지원해야 합니다. 아래 검증에는 npm, curl, Bash도 필요합니다. 정책을 검증할 때는 평소 개발에 쓰는 저장소 대신, 검증 후 버려도 되는 임시 Git 작업 사본을 사용합니다. 아래 명령은 해당 작업 사본의 루트에서 실행합니다.

개인 설정 파일 ~/.codex/config.toml을 수정합니다. 아래 설정을 기존 테이블에 합치고, 같은 테이블을 중복 정의하지 않습니다. 설정을 적용하면 이후 사용할 기본 권한 프로필로 dev가 선택됩니다.

이 설정을 기존의 sandbox_mode 또는 [sandbox_workspace_write] 설정과 함께 사용하지 않습니다. 권한 프로필 문서는 두 설정 방식을 섞지 말고 한 가지를 선택하도록 안내합니다.

default_permissions = "dev"

[features]
network_proxy = true

[permissions.dev]
description = "Workspace editing with npm registry access."
extends = ":workspace"

[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
".env" = "deny"
".env.local" = "deny"
"secrets" = "deny"

[permissions.dev.network]
enabled = true

[permissions.dev.network.domains]
"registry.npmjs.org" = "allow"
"example.com" = "deny"

extends = ":workspace"는 .git과 .codex의 읽기 전용 보호를 포함한 기본 보호 규칙을 유지합니다. 추가 파일 시스템 항목은 편집기와 개발 컨테이너 설정을 읽기 전용으로 만듭니다. 또한 각 작업 공간 루트 아래에서 지정한 환경 변수 파일과 secrets 디렉터리 및 그 하위 항목에 대한 접근을 차단합니다. OpenAI의 파일 시스템 권한 값 정의에서 read는 읽기 전용, write는 읽기와 쓰기, deny는 접근 차단을 뜻합니다.

네트워크 설정은 통신 자체를 허용하는 스위치와 도메인 규칙을 적용하는 스위치로 나뉩니다. permissions.dev.network.enabled = true는 네트워크 사용을 허용하고, **network_proxy = true**는 도메인 규칙 적용을 활성화합니다. 네트워크 권한 문서에 따르면 활성 프록시 없이 네트워크를 켜면 직접 네트워크 접근이 허용됩니다. 이때는 도메인 규칙이 적용되지 않습니다. 따라서 프록시 설정을 빠뜨리지 않아야 합니다.

OpenAI의 기업용 보안 가이드는 의존성 접근 예제에 registry.npmjs.org를 포함합니다. 여기서 example.com은 차단 동작을 확인하려고 명시적으로 금지한 대상입니다. 문서에 나온 도메인 규칙 처리 방식에서는 명시적 차단이 일치하는 허용 규칙보다 우선합니다. 다른 대상에 보내는 요청은 승인이 필요하거나 차단됩니다.

이 설정이 패키지 설치 중 접속할 수 있는 모든 호스트에 무제한 접근을 허용하는 것은 아닙니다. 다른 호스트 이름을 추가하기 전에 프로젝트에 그 대상이 필요한 이유부터 확인합니다.

허용과 차단이 모두 작동하는지 확인하기

codex sandbox를 사용하면 해당 프로필을 직접 적용해 명령을 시험할 수 있습니다. --include-managed-config를 포함하면 프로필을 결정할 때 관리자가 지정한 요구 사항도 반영됩니다. 기업 정책에 따라 선택 가능한 프로필이 제한되는 환경이라면, 관리자가 지정한 요구 사항까지 포함한 상태에서 검증하는 것이 중요합니다.

먼저 Bash에서 레지스트리 연결을 확인합니다.

codex sandbox --permission-profile dev --include-managed-config -- \
  npm ping --registry=https://registry.npmjs.org \
  --cache="$PWD/.npm-cache"

npm ping이 성공하면 PONG이 표시됩니다. 이 예제의 cache 옵션은 npm 캐시를 작업 공간 안에 둡니다. 이렇게 캐시를 작업 공간 안에 두면, 작업 공간 외부에 캐시를 저장할 때와 달리 해당 경로에 쓰기 권한을 별도로 부여할 필요가 없습니다. 이 결과는 레지스트리에 연결된다는 뜻일 뿐, 모든 의존성이나 설치 스크립트가 끝까지 실행된다는 보장은 아닙니다.

다음으로 작업 공간 쓰기, Git 메타데이터 보호, 금지된 도메인 접근을 확인합니다. 각 검증은 따로 실행합니다. Git 검증에서는 .git이 실제 디렉터리여야 하며, 실제 저장소 디렉터리를 가리키는 포인터 파일이어서는 안 됩니다.

# Expect success: create and remove a temporary workspace file.
codex sandbox --permission-profile dev --include-managed-config -- \
  bash -c 'p=$(mktemp ./codex-write-check.XXXXXX) && rm "$p"'

# Expect a filesystem permission denial.
codex sandbox --permission-profile dev --include-managed-config -- \
  bash -c 'p=$(mktemp .git/codex-write-check.XXXXXX) && rm "$p"'

# Expect a proxy policy rejection.
codex sandbox --permission-profile dev --include-managed-config -- \
  curl --fail --head --max-time 15 https://example.com

예상 결과는 작업 공간 쓰기 성공, .git 쓰기 거부, 네트워크 요청 거부입니다. 설정 오류, 존재하지 않는 디렉터리, 정책과 무관한 연결 실패는 의도한 제한이 작동했다는 증거가 아닙니다. 금지한 쓰기 작업이나 네트워크 요청 중 하나라도 성공한다면 검증을 멈춥니다. 평소 개발 작업에서 이 프로필을 사용하기 전에, 실제로 어떤 설정이 적용되었는지부터 확인해야 합니다. 위 내용은 독자의 환경에서 직접 실행하고 결과를 확인할 검증 절차입니다. 이미 테스트를 수행해서 얻은 결과를 보고하는 내용은 아닙니다.

예상 결과를 확인한 뒤 저장소 루트에서 새 Codex 세션을 시작합니다. /permissions를 실행하고 OpenAI의 프로필 설정 예제에 설명된 dev 항목과 설명 문구를 확인합니다. 해당 프로필이 활성화된 상태에서 원래 시도하던 의존성 설치 작업을 다시 실행합니다. 캐시는 작업 공간 안에 두거나, 꼭 필요한 외부 캐시 디렉터리에만 write 권한을 부여합니다.

다운로드가 계속 실패하면 무엇을 확인해야 합니까?

프로필이 적용되지 않는다면 먼저 로드된 설정에 기존 샌드박스 설정이 남아 있는지 확인합니다. 다음으로 설정 우선순위를 살펴봅니다. 명령줄 옵션이나 신뢰한 프로젝트의 설정이 개인 기본값을 덮어쓸 수 있습니다. 세션에서 사용하지 않는 프로필에 계속 권한을 추가하지 않도록 합니다.

npm ping은 성공하지만 설치가 실패한다면 실패한 요청의 대상과 파일 시스템 경로를 따로 확인합니다. 다른 호스트 이름에 접근하려면 별도의 네트워크 허용 여부를 결정해야 합니다. 작업 공간 밖의 캐시에 쓰려면 알맞은 파일 시스템 규칙이 필요합니다. 파일 시스템 권한과 네트워크 권한은 별개이므로, 네트워크를 허용해도 파일 쓰기 권한은 늘어나지 않습니다.

허용된 대상에서도 실패한다면 클라이언트가 프록시 설정을 따르는지 확인합니다. OpenAI의 네트워크 프록시 구현 설명에 따르면 일부 프로그램은 프록시 환경 변수를 따르지 않습니다. 샌드박스 제한을 없애는 대신 해당 클라이언트나 설정의 문제를 진단합니다.

Codex 자체가 모델 제공업체에 연결하지 못하는 문제는 샌드박스 안의 패키지 관리자 명령이 차단되는 문제와 다릅니다. 제공업체 인증, Base URL 또는 프로토콜 설정은 별도의 Codex API 연결 가이드를 참고합니다.

넓은 읽기 권한으로 API 키도 읽을 수 있습니까?

그렇습니다. 읽기 전용 보호는 수정을 막을 뿐, 읽기를 막지는 않습니다. OpenAI는 Codex 샌드박스를 설명하는 글에서 이 절충점을 명시합니다. 해당 문장의 번역은 다음과 같습니다.

그 대가로 컴퓨터의 다른 위치에 있는 민감한 파일도 계속 읽을 수 있는 상태로 남을 수 있습니다. API 키를 포함한 설정 파일이 그 예입니다.

따라서 기본 프로필이 저장소 밖의 비밀 정보를 숨겨준다고 보장하지는 않습니다.

예제는 루트 기준으로 지정한 .env와 .env.local 경로, 그리고 secrets 디렉터리와 그 하위 항목만 차단합니다. 인증 정보가 들어 있는 모든 파일 이름과 저장 위치를 포괄하는 설정은 아닙니다. 환경에 맞게 민감한 경로에 deny 규칙을 추가하며, 필요하면 작업 공간 밖의 경로도 포함합니다. 실제 인증 정보를 출력하지 말고 민감한 내용이 없는 테스트 파일로 확인합니다.

쓰기 가능한 파일에도 위험은 남아 있습니다. OpenAI는 node_modules/prettier 같은 설치된 패키지를 수정하면 편집기가 나중에 샌드박스 밖에서 실행하는 포매터에 영향을 줄 수 있다고 설명합니다. node_modules는 Git에서 무시하는 경우가 많으므로 변경 내용이 git status에 나타나지 않을 수 있습니다. 추적 중인 소스 변경뿐 아니라 쓰기 가능한 도구와 생성된 의존성 파일도 검토합니다.

여러 코딩 에이전트를 사용하는 팀이라면 비밀 정보와 Git을 보호하는 Claude Code 권한 설정도 확인합니다. Codex의 권한 설정 키를 다른 클라이언트에 복사하지 않고 각 도구에 맞는 설정을 사용합니다.

Docker 대신 운영체제의 샌드박스 기능을 쓰는 이유는 무엇입니까?

운영체제의 샌드박스 기능을 사용하면 Codex가 기존 개발 도구를 그대로 이용하면서 실행하는 명령에 운영체제 수준의 제한을 적용할 수 있습니다. OpenAI는 네이티브 샌드박스 설계를 개발 환경 전체를 컨테이너 안에 다시 만드는 방식의 대안으로 설명합니다.

구체적인 예는 Mac에서 iOS 앱을 개발하는 경우입니다. OpenAI가 설명한 작업 방식에서 Docker 컨테이너는 Mac의 네이티브 빌드 도구를 실행하거나 iPhone 시뮬레이터를 시작할 수 없습니다. 이 작업을 Mac 호스트에 맡기면 컨테이너의 샌드박스 밖에서 실행됩니다. 따라서 호스트에서 수행하는 작업에는 별도의 제한이 필요합니다.

macOS에서 Codex는 Seatbelt를 사용합니다. Linux와 WSL2에서는 OpenAI의 샌드박스 설정 안내에 따라 배포판의 패키지 관리자로 bubblewrap을 설치하는 것이 권장됩니다. 샌드박스 시작 실패와 레지스트리 요청 거부는 다른 문제로 구분해 확인합니다.

Windows에서 직접 실행할 때는 별도 검증이 필요합니다. Windows 샌드박스 문서는 호환되는 장치에서 MXC를 권장합니다. 또한 기존 unelevated 구현은 경로별 읽기 차단을 지원하지 않는다고 경고합니다. WSL2에서 Bash 검증을 통과했다고 해서 네이티브 Windows에서도 같은 제한이 적용되는지 확인한 것은 아닙니다.

모든 작업이 컨테이너 안에서 끝난다면 컨테이너도 선택지가 됩니다. 호스트 도구가 필요한 경우에는 호스트에서 실행하는 작업을 식별하고 제한해야 합니다. 호스트에 맡긴 작업까지 컨테이너가 보호한다고 가정하지 않습니다.

기업에서 dev 프로필 선택을 막을 수 있습니까?

그렇습니다. 관리자는 관리형 requirements.toml을 사용해 사용자가 선택할 수 있는 프로필을 제한할 수 있습니다. 로컬에서 프로필을 정의해도 이 제한을 덮어쓸 수 없습니다. OpenAI의 관리 요구 사항 예제는 다음 정책을 제시합니다.

default_permissions = ":read-only"

[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false

allowed_permission_profiles가 있으면 최종 병합된 테이블이 허용 프로필의 전체 목록이 됩니다. 이 테이블에 없는 프로필과 명시적으로 false로 설정된 프로필은 모두 금지됩니다. 위 예제가 관리 요구 사항을 합친 최종 허용 목록이라면, 사용자 정의 dev 프로필은 허용되지 않았으므로 사용할 수 없습니다. 정책을 우회하려 하지 말고 관리자에게 빌드에 적합한 프로필을 승인해 달라고 요청합니다.

관리형 설정 문서에는 중요한 버전 조건이 있습니다. 권한 프로필 허용 목록은 Codex 0.138.0 이상이 필요합니다. Codex 0.137.0 이하 버전은 allowed_permission_profiles와 관리형 default_permissions를 무시합니다. 이 기능으로 제한을 강제할 수 있다고 전제하기 전에, 관리 대상인 각 클라이언트의 버전을 모두 확인해야 합니다.

배포 전에는 지원하는 각 운영체제에서 허용된 빌드와 의도적으로 차단한 작업을 검증합니다. 레지스트리 권한은 필요한 범위로 제한하고, 의도한 프로필이 선택되었는지 확인합니다. 클라이언트를 업데이트할 때도 차단 검증을 계속 수행합니다.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.

무료로 시작하기