샌드박스
ChatGPT 및 Codex 클라이언트 전반에서 샌드박스가 작동하는 방식
샌드박스는 에이전트에 사용자의 컴퓨터에 대한 무제한 액세스 권한을 부여하지 않고도 자율적으로 작업할 수 있게 하는 경계입니다. 로컬 채팅이 ChatGPT 데스크톱 앱, Codex CLI 또는 IDE 확장 프로그램에서 명령을 실행하면, 해당 명령은 기본적으로 전체 액세스 권한으로 실행되는 대신 제한된 환경 내에서 실행됩니다.
이 환경은 에이전트가 자체적으로 수행할 수 있는 작업, 예를 들어 수정할 수 있는 파일과 명령의 네트워크 사용 가능 여부를 정의합니다. 작업이 이러한 경계 내에 머무르는 동안 에이전트는 확인을 위해 중단하지 않고 계속 진행할 수 있습니다. 작업을 경계 너머로 확장해야 할 때는 승인 흐름이 적용됩니다.
샌드박스의 역할
샌드박스는 기본 제공 파일 작업뿐 아니라 생성된 명령에도
적용됩니다. 에이전트가 git, 패키지 관리자 또는 테스트 실행기 같은 도구를 실행하면
해당 명령에도 동일한 샌드박스 경계가 적용됩니다.
Codex는 각 OS에서 플랫폼 네이티브 방식으로 제한을 적용합니다. 구현 방식은 macOS, Linux, WSL2 및 네이티브 Windows마다 다르지만, 모든 환경에서 기본 개념은 동일합니다. 즉, 명확한 제한 내에서 일상적인 작업을 자율적으로 실행할 수 있도록 에이전트에 경계가 설정된 작업 공간을 제공합니다.
샌드박스가 중요한 이유
샌드박스는 승인 피로를 줄여 줍니다. 위험이 낮은 모든 명령을 확인하도록 요청하는 대신, 에이전트는 사용자가 이미 승인한 경계 내에서 파일을 읽고, 수정하고, 일상적인 프로젝트 명령을 실행할 수 있습니다.
또한 에이전트 기반 작업에 대해 더 명확한 신뢰 모델을 제공합니다. 단순히 에이전트의 의도를 신뢰하는 것이 아니라, 에이전트가 강제된 제한 내에서 작동한다는 사실을 신뢰할 수 있습니다. 따라서 에이전트가 언제 작업을 중단하고 도움을 요청할지 알면서도 에이전트가 독립적으로 작업하도록 맡기기가 더 쉬워집니다.
시작하기
기본 권한 모드에서는 샌드박스가 자동으로 적용됩니다.
사전 요구 사항
macOS에서는 기본 제공 Seatbelt 프레임워크를 사용하므로 별도 설정 없이 샌드박스가 작동합니다.
Windows에서 PowerShell을 실행할 때 Codex는 네이티브 Windows 샌드박스를 사용하고, WSL2를 실행할 때는 Linux 샌드박스 구현을 사용합니다.
Linux 및 WSL2에서는 먼저 패키지 관리자로 bubblewrap을 설치하세요.
Ubuntu/Debian
sudo apt install bubblewrapFedora
sudo dnf install bubblewrapCodex는 PATH에서 발견한 첫 번째 bwrap 실행 파일을 사용합니다. 사용 가능한 bwrap
실행 파일이 없으면 Codex는 번들로 제공되는 도우미로 대체하지만, 이 도우미를 사용하려면
권한 없는 사용자 네임스페이스 생성을 지원해야 합니다.
bwrap을 제공하는 배포판 패키지를 설치하면 이 설정을 안정적으로 유지할 수 있습니다.
bwrap이 없거나 도우미가 필요한 사용자 네임스페이스를
생성할 수 없으면 Codex가 시작 경고를 표시합니다. 이 AppArmor 설정을 제한하는
배포판에서는 제한을 전역적으로 비활성화하지 않고도 bwrap이 계속
작동할 수 있도록 bwrap AppArmor 프로필을 로드하는 것이 좋습니다.
권한 작동 방식
사용 중인 환경의 권한 제어를 사용하여 Codex가 로컬 작업을 처리하는 방식을 변경하세요.
승인은 Codex가 작업 전에 일시 중지하는 시점을 결정하고, 샌드박스는 명령이 액세스할 수 있는 파일과 네트워크 리소스를 결정합니다. 승인 요청에서 일회 승인이나 세션 동안 승인과 같이 서로 다른 범위를 제공하는 경우, 작업을 계속할 수 있는 가장 좁은 범위를 선택하세요. 프로젝트 경계를 기본값으로 유지하고, 관련 없는 저장소까지 액세스 범위를 넓히는 대신 별도의 프로젝트나 worktree를 사용하세요.
ChatGPT 데스크톱 앱에서는 작성기 아래의 권한 제어를 사용하세요. 구성에 따라 메뉴에는 승인 요청, 적격 승인 요청에 대한 대신 승인, 전체 액세스, 명명된 권한 프로필 또는 사용자 지정 권한 프로필이 포함될 수 있습니다.
기본값 구성
매번 동일한 동작으로 시작하려면 config.toml에서 기본값을 설정하세요.
구성 기본 사항에서는 작동 방식을 설명하고,
구성 참조에서는 sandbox_mode, approval_policy,
approvals_reviewer 및 sandbox_workspace_write.writable_roots의 정확한 키를 설명합니다. 이러한 설정을 사용하여 에이전트에
기본적으로 부여할 자율성의 정도, 쓰기 가능한 디렉터리, 승인을 위해
일시 중지해야 하는 시점, 적격 승인 요청을 검토할 주체를 결정하세요.
개괄적으로 일반적인 샌드박스 모드는 다음과 같습니다.
read-only: 에이전트는 파일을 검사할 수 있지만, 승인 없이는 파일을 수정하거나 명령을 실행할 수 없습니다.workspace-write: 에이전트는 파일을 읽고, 작업 공간 내에서 수정하며, 해당 경계 내에서 일상적인 로컬 명령을 실행할 수 있습니다. 로컬 작업을 위한 기본 저마찰 모드입니다.danger-full-access: 에이전트가 샌드박스 제한 없이 실행됩니다. 파일 시스템과 네트워크 경계가 제거되므로 에이전트가 전체 액세스 권한으로 작업하기를 원할 때만 사용해야 합니다.
일반적인 승인 정책은 다음과 같습니다.
untrusted: 에이전트가 신뢰하는 명령 집합에 포함되지 않은 명령을 실행하기 전에 승인을 요청합니다.on-request: 에이전트는 기본적으로 샌드박스 내에서 작업하며 해당 경계를 넘어야 할 때 승인을 요청합니다.never: 에이전트가 승인 프롬프트를 위해 작업을 중단하지 않습니다.
승인이 대화형인 경우 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를 참조하세요. 샌드박스와 승인에 관한 관리자 요구 사항 및 조직 수준의 제약 조건은 에이전트 승인 및 보안을 참조하세요.