핵심 정리

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

권한 구조

샌드박스와 승인 정책은 독립된 두 축이고 둘 다 설계해야 한다

샌드박스는 "어디까지 할 수 있는가"를 정합니다. 승인 정책은 "그 행동 전에 사용자에게 물어볼 것인가"를 정합니다. 이 두 축은 독립적입니다. 승인 정책만 좁히고 샌드박스를 넓게 열면 생각보다 강한 권한이 남을 수 있습니다. 반대로 샌드박스만 좁히고 승인 정책을 풀어도 필요한 작업이 계속 실패합니다. 공식 가이드는 보통 가장 좁은 권한에서 시작해 점진적으로 넓히는 방식을 권합니다.

상황별 선택
- 코드 설명만 듣고 싶다     -> read-only
- 저장소 안 파일 수정과 테스트는 필요하다 -> workspace-write
- 네트워크 접근도 필요하다  -> workspace-write + 명시적 network_access
- 무인 자동화라 승인 대화가 없어야 한다 -> 정책 검토 후 never

sandbox_mode 선택이 에이전트 행동 범위를 실질적으로 결정한다

로컬 CLI와 IDE 기본값은 보수적입니다. 기본적으로 네트워크는 꺼져 있고, 쓰기 권한도 작업 공간 안으로 제한됩니다. read-only는 읽기 중심 대화와 계획에 적합하고, workspace-write는 저장소 안 수정과 테스트에 적합하며, 전체 권한은 꼭 필요한 경우만 써야 합니다. 네트워크 접근이 필요한 경우는 workspace-write에 network_access = true를 명시적으로 추가하는 방식이 기본 설정을 넓히는 것보다 안전합니다.

approval_policy는 에이전트 실행 전 인간 개입 여부를 결정한다

approval_policy = "on-request"는 실행 전 확인을 거치게 만들고, never는 승인 없이 계속 진행하게 만듭니다. 계획 단계에서는 on-request로 진행하다가, 자동화로 넘어갈 때만 never로 전환하는 방식이 안전합니다. 특히 무인 자동화에서 never를 쓸 때는 샌드박스 범위가 의도보다 넓지 않은지 먼저 검토해야 합니다. 세션 중에는 /permissions로 권한 수준을 바꿀 수 있어, 단계에 따라 설정을 유연하게 전환할 수 있습니다.

sandbox
  -> 기술적으로 가능한 범위

approval
  -> 실행 전에 물을지 여부

자동화에서 full access와 never 조합이 가장 위험한 이유

자동화에서 danger-full-access와 approval_policy = "never"를 함께 쓰면, 에이전트가 어떤 행동이든 확인 없이 실행할 수 있습니다. 프롬프트가 모호하거나 예상치 못한 상황이 생겼을 때 멈출 안전망이 없습니다. 자동화 설계에서는 이 조합을 피하고, 가능한 한 좁은 sandbox_mode와 명확한 프롬프트를 조합하는 것이 실패 비용을 낮추는 방법입니다.

어떤 조합을 쓸까

주의할 점

❌ approval_policy = "never"
❌ sandbox_mode = "danger-full-access"
❌ 프롬프트는 모호함

이 조합은 무인 실행에서 가장 위험합니다. 확인 없이 광범위한 행동이 가능해집니다.