샌드박싱 | JUNGWOO KIM

개요

샌드박싱은 에이전트의 도구 실행을 격리된 백엔드에서 수행하여 호스트 시스템을 보호한다. Docker, SSH, OpenShell 백엔드를 지원하며, 도구별로 샌드박스 적용 여부가 다르다.

샌드박스 대상 도구

샌드박스 적용	샌드박스 미적용
`exec` (셸 실행)	Gateway 도구
`read` (파일 읽기)	상위 권한 작업
`write` (파일 쓰기)
`edit` (파일 편집)
`process` (프로세스 관리)
`browser` (브라우저)

샌드박스 모드

모드	설명
`off`	샌드박싱 비활성화. 모든 도구가 호스트에서 직접 실행
`non-main`	서브 에이전트만 샌드박싱 (기본값)
`all`	주 에이전트 포함 모든 에이전트 샌드박싱

{
  "sandbox": {
    "mode": "all"
  }
}

샌드박스 스코프

스코프	설명
`agent`	에이전트별 독립 샌드박스 (기본값)
`session`	세션별 독립 샌드박스
`shared`	모든 에이전트가 하나의 샌드박스 공유

백엔드

Docker (로컬)

로컬 Docker 컨테이너를 사용한 격리.

{
  "sandbox": {
    "backend": "docker",
    "docker": {
      "image": "openclaw/sandbox:latest",
      "network": false,
      "memory": "512m",
      "cpus": 1
    }
  }
}

기본적으로 네트워크가 비활성화되어 있다. 에이전트가 외부 네트워크에 접근해야 하면 명시적으로 활성화해야 한다.

SSH (원격)

원격 서버에 SSH로 연결하여 격리 실행.

{
  "sandbox": {
    "backend": "ssh",
    "ssh": {
      "host": "sandbox.example.com",
      "user": "openclaw",
      "keyPath": "~/.ssh/sandbox_key"
    }
  }
}

OpenShell (매니지드)

OpenClaw에서 관리하는 클라우드 샌드박스 환경.

{
  "sandbox": {
    "backend": "openshell"
  }
}

별도의 인프라 관리 없이 즉시 사용 가능하다.

워크스페이스 접근

샌드박스 내에서 에이전트 워크스페이스에 대한 접근 수준을 설정한다.

모드	설명
`none`	워크스페이스 접근 불가
`ro`	읽기 전용 접근
`rw`	읽기/쓰기 접근

{
  "sandbox": {
    "workspaceAccess": "ro"
  }
}

Docker 보안 설정

네트워크 격리

기본적으로 Docker 샌드박스는 네트워크 비활성화 상태이다. 에이전트가 웹 검색이나 API 호출을 해야 하는 경우에만 활성화한다.

{
  "sandbox": {
    "docker": {
      "network": true,
      "allowedHosts": ["api.example.com"]
    }
  }
}

위험한 바인드 차단

다음 호스트 경로의 바인드 마운트가 자동으로 차단된다.

/ (루트)
/etc
/var/run/docker.sock
/proc, /sys
홈 디렉토리의 민감 파일 (~/.ssh, ~/.gnupg 등)

샌드박스 실행 흐름

[에이전트 도구 호출]
        │
  샌드박스 대상 확인
  ┌─────┴─────┐
  │           │
 대상        미대상
  │           │
 모드 확인    호스트 직접 실행
  │
 백엔드 선택
  │
┌─┴──┬───────┐
│    │       │
Docker SSH  OpenShell
  │    │       │
 격리 실행   격리 실행
  │    │       │
 결과 반환   결과 반환