샌드박스

샌드박스는 에이전트에 컴퓨터에 대한 무제한 접근 권한을 부여하지 않고도 자율적으로 작업할 수 있게 하는 경계입니다. 로컬 채팅이 ChatGPT 데스크톱 앱, Codex CLI 또는 IDE 확장 프로그램 에서 명령을 실행하면, 해당 명령은 기본적으로 전체 접근 권한을 갖는 대신 제한된 환경 안에서 실행됩니다.

이 환경은 수정할 수 있는 파일이나 명령의 네트워크 사용 가능 여부 등 에이전트가 스스로 할 수 있는 작업을 정의합니다. 작업이 이러한 경계 안에 있으면 에이전트는 확인을 받기 위해 멈추지 않고 계속 진행할 수 있습니다. 경계를 넘어야 할 때는 승인 절차가 적용됩니다.

샌드박스의 역할

샌드박스는 내장 파일 작업뿐 아니라 새로 실행하는 명령에도 적용됩니다. 에이전트가 git, 패키지 관리자 또는 테스트 실행기 같은 도구를 실행하면 해당 명령에도 동일한 샌드박스 경계가 적용됩니다.

Codex는 각 OS의 기본 기능으로 제한을 적용합니다. 구현 방식은 macOS, Linux, WSL2, 네이티브 Windows마다 다르지만, 모든 사용 환경에서 핵심 개념은 같습니다. 에이전트에 범위가 정해진 작업 공간을 제공하여 일상적인 작업을 명확한 한계 안에서 자율적으로 실행할 수 있게 합니다.

샌드박스가 중요한 이유

샌드박스는 반복적인 승인으로 인한 피로를 줄여 줍니다. 위험이 낮은 명령을 실행할 때마다 확인을 요청하는 대신, 에이전트는 이미 승인한 경계 안에서 파일을 읽고, 수정하고, 일상적인 프로젝트 명령을 실행할 수 있습니다.

또한 에이전트 작업에 대한 신뢰 모델을 더 명확하게 해 줍니다. 에이전트의 의도만 신뢰하는 것이 아니라, 에이전트가 강제된 제한 안에서 작동한다는 점을 신뢰하게 됩니다. 따라서 에이전트가 언제 멈추고 도움을 요청할지 알면서도 독립적으로 작업하도록 맡기기 쉬워집니다.

시작하기

기본 권한 모드는 샌드박싱을 자동으로 적용합니다.

사전 요구 사항

macOS 에서는 내장 Seatbelt 프레임워크를 사용하여 별도 설정 없이 샌드박싱이 작동합니다.

Windows 에서 Codex는 PowerShell로 실행할 때 네이티브 Windows 샌드박스를 사용하고, WSL2로 실행할 때는 Linux 샌드박스 구현을 사용합니다.

Linux 및 WSL2 에서는 먼저 패키지 관리자로 bubblewrap을 설치합니다.

sudo apt install bubblewrap

sudo dnf install bubblewrap

Codex는 bwrap 실행 파일을 PATH에서 처음 발견한 것을 사용합니다. bwrap 실행 파일이 없으면 Codex는 번들로 제공되는 보조 프로그램을 대신 사용하지만, 이 프로그램에는 비특권 사용자 네임스페이스 생성 지원이 필요합니다. bwrap을 제공하는 배포판 패키지를 설치하면 이 구성을 안정적으로 유지할 수 있습니다.

Codex는 bwrap이 없거나 보조 프로그램이 필요한 사용자 네임스페이스를 만들 수 없을 때 시작 시 경고를 표시합니다. 이 AppArmor 설정을 제한하는 배포판에서는 bwrap AppArmor 프로필을 로드하여 bwrap이 시스템 전체의 제한을 해제하지 않고도 계속 작동하도록 하는 것이 좋습니다.

사용 중인 환경의 권한 컨트롤을 사용하여 Codex가 로컬 작업을 처리하는 방식을 변경합니다.

승인은 Codex가 작업 전에 언제 멈출지를 결정하고, 샌드박스는 명령이 접근할 수 있는 파일과 네트워크 리소스를 결정합니다. 승인 시 한 번만 승인하거나 세션 전체에 대해 승인하는 등 여러 범위가 제공되면, 작업을 계속할 수 있는 가장 좁은 범위를 선택합니다. 프로젝트 경계를 기본값으로 유지하고, 관련 없는 저장소까지 접근 범위를 넓히기보다는 별도의 프로젝트나 작업 트리를 사용합니다.

ChatGPT Work는 관리되는 격리 환경에서 코드와 셸 명령을 실행합니다. 작업 공간 정책과 도구별 제어 설정에 따라 사용할 수 있는 기능이 결정됩니다. 해당 설정을 사용할 수 있다면 설정 > 데이터 제어 > Work 네트워크 접근 에서 코드 및 셸 명령의 네트워크 접근을 관리합니다. 공용 인터넷 접근 허용 을 켜면 해당 명령이 공용 인터넷에 접근할 수 있습니다. 이 설정을 끄면 명령은 관리되는 허용 목록의 필수 호스트 이름에만 접근할 수 있습니다.

웹 검색, 플러그인, 원격 브라우저에는 별도의 제어 설정이 있습니다. 변경 사항은 현재 코드 또는 셸 실행이 끝나고 Work가 실행 환경을 새로 고친 뒤에 적용됩니다. ChatGPT 웹에서는 로컬 Codex 샌드박스나 승인 모드 선택기를 제공하지 않습니다.

ChatGPT 데스크톱 앱에서는 입력창 아래의 권한 컨트롤을 사용합니다. 구성에 따라 메뉴에 승인 요청, 적격 승인 요청에 대한 대신 승인, 전체 접근, 이름이 지정된 권한 프로필 또는 사용자 지정 권한 프로필이 포함될 수 있습니다.

CLI에서는 /permissions을 입력하여 권한 선택기를 열고 활성 권한 프로필을 변경합니다.

IDE 확장 프로그램에서는 입력창 아래의 권한 컨트롤을 사용합니다. 구성에 따라 메뉴에 승인 요청, 적격 승인 요청에 대한 대신 승인, 전체 접근, 이름이 지정된 권한 프로필 또는 사용자 지정 권한 프로필이 포함될 수 있습니다.

기본값 구성

매번 같은 동작으로 시작하려면 config.toml에 기본값을 설정합니다. 구성 기초에서는 작동 방식을 설명하고, 구성 참조에서는 다음 항목의 정확한 키를 설명합니다. sandbox_mode, approval_policy, approvals_reviewer 및 sandbox_workspace_write.writable_roots. 이 설정을 사용하여 에이전트에 기본적으로 부여할 자율성의 정도, 쓰기가 가능한 디렉터리, 승인을 위해 멈춰야 하는 시점, 적격 승인 요청을 검토할 주체를 결정합니다.

일반적인 샌드박스 모드의 개요는 다음과 같습니다.

• read-only: 에이전트는 파일을 살펴볼 수 있지만, 승인 없이 파일을 편집하거나 명령을 실행할 수는 없습니다.
• workspace-write: 에이전트는 파일을 읽고, 작업 공간 안에서 편집하며, 해당 경계 안에서 일상적인 로컬 명령을 실행할 수 있습니다. 로컬 작업을 번거로움 없이 수행하기 위한 기본 모드입니다.
• danger-full-access: 에이전트가 샌드박스 제한 없이 실행됩니다. 파일 시스템과 네트워크 경계가 제거되므로 에이전트가 전체 접근 권한으로 작업하기를 원할 때만 사용해야 합니다.

일반적인 승인 정책은 다음과 같습니다.

• on-request: 에이전트는 기본적으로 샌드박스 안에서 작업하며, 경계를 넘어야 할 때 승인을 요청합니다.
• never: 에이전트가 승인 프롬프트를 표시하기 위해 멈추지 않습니다.

Codex와 ChatGPT Work는 더 이상 untrusted를 선택 가능한 승인 정책으로 지원하지 않습니다. 기존 구성에서 이 값을 사용하고 있다면 지원이 종료된 untrusted 승인 정책에서 마이그레이션을 참고하세요.

대화형 승인을 사용하는 경우 다음 설정으로 검토 주체도 선택할 수 있습니다. approvals_reviewer:

• user: 승인 프롬프트가 사용자에게 표시됩니다. 기본값입니다.
• auto_review: 적격 승인 프롬프트가 검토 에이전트로 전달됩니다( 자동 검토 참고).

전체 접근은 sandbox_mode = "danger-full-access"와 approval_policy = "never"를 함께 사용하는 것을 의미합니다. 반면 위험이 더 낮은 로컬 자동화 프리셋은 sandbox_mode = "workspace-write"와 approval_policy = "on-request"를 함께 사용하거나, 이에 해당하는 CLI 플래그 --sandbox workspace-write --ask-for-approval on-request를 사용합니다. 이후 수동 승인을 위해 approvals_reviewer = "user"를 유지하거나 자동 승인 검토를 위해 approvals_reviewer = "auto_review"를 설정할 수 있습니다.

에이전트가 여러 디렉터리에서 작업해야 한다면, 쓰기 가능한 루트를 사용하여 샌드박스를 완전히 제거하지 않고도 수정 가능한 위치를 확장할 수 있습니다. 신뢰 경계를 넓히거나 좁혀야 한다면 일회성 예외에 의존하는 대신 기본 샌드박스 모드와 승인 정책을 조정합니다.

워크플로에 특정 예외가 필요하면 규칙을 사용합니다. 규칙을 사용하면 샌드박스 밖에서 명령 접두사별로 허용하거나, 승인을 요청하거나, 금지할 수 있으므로 접근 범위를 전반적으로 넓히는 것보다 적합한 경우가 많습니다. IDE별 설정 접근 방법은 Codex IDE 확장 프로그램 설정을 참고하세요.

자동 검토를 사용할 수 있더라도 샌드박스 경계는 바뀌지 않습니다. 자동 검토는 샌드박스 권한 상향, 차단된 네트워크 접근, 여전히 승인이 필요한 상태 변경 도구 호출 등 해당 경계에서 발생하는 승인 요청에 사용할 수 있는 approvals_reviewer의 한 가지 옵션입니다. 샌드박스 안에서 이미 허용된 작업은 추가 검토 없이 실행됩니다. 검토자 수명 주기, 트리거 유형, 거부의 의미 및 구성에 관한 자세한 내용은 자동 검토를 참고하세요.

플랫폼별 세부 사항은 각 플랫폼 문서에 있습니다. 네이티브 Windows 설정, 동작 및 문제 해결은 Windows를 참고하세요. 샌드박싱과 승인에 대한 관리자 요구 사항 및 조직 수준의 제약은 에이전트 승인 및 보안을 참고하세요.