개요
OpenClaw의 샌드박스 격리 환경은 시스템 보안을 보장하는 핵심 구성 요소입니다. AI 에이전트가 도구 작업을 실행할 때, 샌드박스는 이러한 작업이 호스트 시스템의 보안이나 안정성을 손상시키지 않도록 합니다. 이 문서에서는 세 가지 핵심 샌드박스 기능인 도구 경로 제약, 컨테이너 실행, 브라우저 브리지 설정을 상세히 다룹니다.
샌드박스 아키텍처
OpenClaw은 Pi 코딩 에이전트 SDK를 직접 내장하기 때문에(서브프로세스로 호출하는 것이 아님) 샌드박스 메커니즘이 도구 실행 레이어에 깊이 통합되어 있습니다. 모든 도구 호출은 샌드박스 검사를 거칩니다 — 7단계 도구 파이프라인의 정책 필터링 단계에서 권한 확인이 완료된 후에도, 실제 실행 중에는 샌드박스의 런타임 제약이 여전히 적용됩니다.
도구 경로 제약
기본 개념
경로 제약은 도구가 접근할 수 있는 파일 시스템 범위를 제한합니다. 설정 파일에서 허용된 경로 접두사를 선언하여 AI 에이전트의 파일 작업 범위를 정밀하게 제어할 수 있습니다.
설정
OpenClaw 설정 파일에서 sandbox.allowedPaths 필드를 사용하여 접근 가능한 경로를 선언합니다:
sandbox:
allowedPaths:
- /home/openclaw/workspace
- /tmp/openclaw
deniedPaths:
- /etc
- /var/log
- /home/openclaw/.ssh
maxFileSize: 10MB
maxDepth: 10
경로 해석 규칙
샌드박스는 검사 중 경로를 정규화합니다: 심볼릭 링크를 해석하고, .. 경로 탐색을 제거하며, 경로 구분자를 통일합니다. 이는 ../../etc/passwd 같은 경로로 제약을 우회하려는 시도가 효과가 없음을 의미합니다.
임시 파일 처리
도구 실행 중 생성된 임시 파일은 기본적으로 /tmp/openclaw/<session-id>/에 저장됩니다. 각 세션은 자체 임시 디렉토리를 가지며, 세션이 종료되면 샌드박스가 자동으로 정리합니다.
컨테이너 실행
컨테이너 격리 모드
임의의 코드를 실행해야 하는 시나리오(예: 코드 실행 스킬)의 경우, OpenClaw은 컨테이너 내에서 도구 작업을 실행하는 것을 지원합니다. 컨테이너 실행은 경로 제약만으로는 달성할 수 없는 더 강력한 격리 수준을 제공합니다.
컨테이너 런타임 설정
sandbox:
containerExec:
enabled: true
runtime: docker
image: openclaw/sandbox:latest
memoryLimit: 512m
cpuLimit: 1.0
networkMode: none
timeout: 30s
주요 매개변수 설명
- runtime: 컨테이너 런타임, Docker와 Podman 지원
- image: 샌드박스 컨테이너 이미지; 공식 사전 빌드 이미지에는 일반적인 프로그래밍 언어 런타임이 포함
- memoryLimit: 리소스 고갈 공격을 방지하기 위한 메모리 상한
- cpuLimit: CPU 사용량 제한
- networkMode: 네트워크 모드;
none은 완전히 격리된 네트워크,restricted는 제한된 외부 접근 허용 - timeout: 실행 시간 제한; 초과 시 컨테이너가 강제 종료
파일 시스템 마운트
컨테이너 실행 중 샌드박스는 필요한 파일을 읽기 전용 모드로 컨테이너에 마운트합니다. 도구가 생성한 출력 파일은 전용 출력 디렉토리를 통해 호스트 시스템으로 매핑됩니다.
sandbox:
containerExec:
mounts:
- source: /home/openclaw/workspace
target: /workspace
readonly: true
- source: /tmp/openclaw/output
target: /output
readonly: false
브라우저 브리지
브리지 메커니즘
OpenClaw의 브라우저 도구는 실제 브라우저 인스턴스와 상호작용해야 합니다. 샌드박스는 브라우저 브리지 URL을 통해 제어된 통신 채널을 설정하여, AI 에이전트가 브라우저를 조작하면서도 브라우저 작업이 샌드박스 경계를 벗어나지 않도록 합니다.
브라우저 브리지 설정
sandbox:
browserBridge:
enabled: true
bridgeUrl: "ws://localhost:9222"
allowedDomains:
- "*.example.com"
- "docs.openclaw.com"
blockedDomains:
- "*.internal.corp"
maxTabs: 3
maxPageLoadTime: 15s
screenshotFormat: png
screenshotQuality: 80
도메인 필터링
브라우저 브리지는 도메인 화이트리스트와 블랙리스트를 지원합니다. 허용 목록에 있는 도메인만 접근할 수 있어, AI 에이전트가 브라우저를 사용하여 내부 네트워크 리소스나 민감한 서비스에 접근하는 것을 방지합니다.
브리지 보안
브라우저 브리지는 WebSocket 프로토콜을 통해 통신합니다. 연결 설정 시 토큰 인증이 필요하며, 각 세션은 고유한 토큰을 갖습니다. 브리지 레이어는 실행 파일 다운로드나 file:// 프로토콜 접근 같은 위험한 작업도 차단합니다.
샌드박스 모니터링
리소스 사용량 모니터링
샌드박스는 런타임에 리소스 사용량을 지속적으로 모니터링합니다:
- 파일 시스템 작업 수 및 총 데이터량
- 컨테이너 CPU 및 메모리 사용량
- 브라우저 브리지 네트워크 트래픽
- 도구 호출 빈도
알림 설정
리소스 사용량이 한계에 근접하면 시스템이 알림을 트리거합니다. 설정에서 알림 임계값과 알림 방법을 설정할 수 있습니다.
문제 해결
일반적인 샌드박스 관련 문제:
- 경로 접근 거부:
allowedPaths에 대상 경로가 포함되어 있는지 확인; 심볼릭 링크 해석에 주의 - 컨테이너 시작 실패: 컨테이너 런타임이 설치되어 있고 이미지가 풀되었는지 확인
- 브라우저 브리지 타임아웃: 브라우저 인스턴스가 정상적으로 실행 중이고 브리지 URL이 올바른지 확인
- 리소스 제한 초과:
memoryLimit및cpuLimit매개변수 조정
요약
OpenClaw의 샌드박스 메커니즘은 경로 제약, 컨테이너 실행, 브라우저 브리지를 통해 세 겹의 보호를 제공하여, AI 에이전트의 기능을 유지하면서 시스템 보안을 보장합니다. 이 세 가지 차원을 적절히 설정하면 보안과 기능 사이의 최적 균형을 달성할 수 있습니다.