샌드박스

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

이 환경은 에이전트가 자체적으로 수행할 수 있는 작업을 정의합니다. 예를 들어 수정할 수 있는 파일과 명령의 네트워크 사용 가능 여부를 지정합니다. 작업이 이러한 경계 안에 머무르면 에이전트는 확인을 위해 멈추지 않고 계속 진행할 수 있습니다. 경계를 넘어야 하는 경우에는 승인 흐름이 작동합니다.

샌드박스의 역할

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

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

샌드박스가 중요한 이유

샌드박스는 승인 피로를 줄여 줍니다. 위험도가 낮은 모든 명령을 확인해 달라고 요청하는 대신, 에이전트가 이미 승인된 경계 안에서 파일을 읽고 수정하며 일상적인 프로젝트 명령을 실행할 수 있습니다.

또한 에이전트 기반 작업에 대해 더 명확한 신뢰 모델을 제공합니다. 단순히 에이전트의 의도를 신뢰하는 것이 아니라, 에이전트가 강제된 제한 내에서 작동한다는 사실을 신뢰할 수 있습니다. 따라서 에이전트가 언제 멈추고 도움을 요청할지 알 수 있는 상태를 유지하면서도 독립적으로 작업하도록 맡기기가 더 쉬워집니다.

시작하기

기본 권한 모드에서는 샌드박스가 자동으로 적용됩니다.

사전 요구 사항

macOS에서는 기본 제공 Seatbelt 프레임워크를 사용하므로 별도의 설정 없이 샌드박스를 사용할 수 있습니다.

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

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

sudo apt install bubblewrap

sudo dnf install bubblewrap

Codex는 PATH에서 처음 발견한 bwrap 실행 파일을 사용합니다. bwrap 실행 파일을 사용할 수 없으면 Codex는 번들로 제공되는 도우미로 대체하지만, 이 도우미를 사용하려면 권한 없는 사용자 네임스페이스 생성을 지원해야 합니다. bwrap을 제공하는 배포판 패키지를 설치하면 이 구성을 안정적으로 유지할 수 있습니다.

bwrap이 없거나 도우미가 필요한 사용자 네임스페이스를 생성할 수 없으면 Codex가 시작 경고를 표시합니다. 이 AppArmor 설정을 제한하는 배포판에서는 제한을 전역으로 비활성화하지 않고도 bwrap이 계속 작동하도록 bwrap AppArmor 프로필을 로드하는 것이 좋습니다.

권한 작동 방식

사용 중인 환경의 권한 제어 기능을 사용하여 Codex가 로컬 작업을 처리하는 방식을 변경할 수 있습니다.

승인은 Codex가 작업 전에 언제 일시 중지할지를 결정하고, 샌드박스는 명령이 액세스할 수 있는 파일과 네트워크 리소스를 결정합니다. 한 번만 승인하거나 세션 동안 승인하는 것처럼 승인 범위가 여러 가지로 제시되면 작업을 계속할 수 있는 가장 좁은 범위를 선택하세요. 프로젝트 경계를 기본값으로 유지하고, 관련 없는 여러 저장소에 대한 액세스를 확장하는 대신 별도의 프로젝트나 작업 트리를 사용하세요.

ChatGPT Work는 관리되는 격리 환경에서 코드와 셸 명령을 실행합니다. 워크스페이스 정책과 도구별 제어 기능에 따라 사용할 수 있는 기능이 결정됩니다. 이 설정을 사용할 수 있다면 Settings > Data controls > Work network access에서 코드와 셸 명령의 네트워크 액세스를 관리하세요. 해당 명령이 공개 인터넷에 액세스할 수 있도록 하려면 Allow public internet access를 켜세요. 이 설정이 꺼져 있으면 관리되는 허용 목록의 필수 호스트 이름에만 명령이 액세스할 수 있습니다.

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

ChatGPT 데스크톱 앱에서는 작성 영역 아래의 권한 제어 기능을 사용하세요. 구성에 따라 메뉴에 Ask for approval, 대상이 되는 승인 요청에 대한 Approve for me, Full access, 이름이 지정된 권한 프로필 또는 사용자 지정 권한 프로필이 포함될 수 있습니다.

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

IDE 확장 프로그램에서는 작성 영역 아래의 권한 제어 기능을 사용하세요. 구성에 따라 메뉴에 Ask for approval, 대상이 되는 승인 요청에 대한 Approve for me, Full access, 이름이 지정된 권한 프로필 또는 사용자 지정 권한 프로필이 포함될 수 있습니다.

기본값 구성

매번 동일한 동작으로 시작하려면 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를 참조하세요. 샌드박스와 승인에 대한 관리자 요구 사항 및 조직 수준의 제약 조건은 에이전트 승인 및 보안을 참조하세요.