샌드박싱

OpenClaw는 폭발 반경을 줄이기 위해 Docker 컨테이너 내에서 도구를 실행할 수 있습니다. 이 기능은 선택 사항이며 설정(agents.defaults.sandbox 또는 agents.list[].sandbox)으로 제어됩니다. 샌드박싱이 꺼져 있으면 도구는 호스트에서 실행됩니다. 게이트웨이는 호스트에 유지되며, 활성화 시 도구 실행만 격리된 샌드박스에서 수행됩니다.

완벽한 보안 경계는 아니지만, 모델이 잘못된 동작을 할 때 파일시스템과 프로세스 접근을 실질적으로 제한합니다.

샌드박스 대상

• 도구 실행 (exec, read, write, edit, apply_patch, process 등).
• 선택적 샌드박스 브라우저 (agents.defaults.sandbox.browser).
  • 기본적으로 샌드박스 브라우저는 브라우저 도구가 필요할 때 자동 시작됩니다 (CDP 접근 가능 확인). agents.defaults.sandbox.browser.autoStart 및 agents.defaults.sandbox.browser.autoStartTimeoutMs로 설정합니다.
  • 기본적으로 샌드박스 브라우저 컨테이너는 전역 bridge 네트워크 대신 전용 Docker 네트워크(openclaw-sandbox-browser)를 사용합니다. agents.defaults.sandbox.browser.network로 설정합니다.
  • 선택적으로 agents.defaults.sandbox.browser.cdpSourceRange가 CIDR 허용 목록으로 컨테이너 엣지 CDP 인그레스를 제한합니다 (예: 172.21.0.1/32).
  • noVNC 관찰자 접근은 기본적으로 비밀번호로 보호됩니다. OpenClaw는 로컬 부트스트랩 페이지를 제공하는 단기 토큰 URL을 생성하고 URL 프래그먼트에 비밀번호를 포함하여 noVNC를 엽니다 (쿼리/헤더 로그 아님).
  • agents.defaults.sandbox.browser.allowHostControl은 샌드박스 세션이 호스트 브라우저를 명시적으로 대상으로 지정할 수 있게 합니다.
  • 선택적 허용 목록이 target: "custom"을 게이트합니다: allowedControlUrls, allowedControlHosts, allowedControlPorts.

샌드박스 대상 아님:

• 게이트웨이 프로세스 자체.
• 호스트에서 실행이 명시적으로 허용된 도구 (예: tools.elevated).
  • 엘리베이티드 exec는 호스트에서 실행되며 샌드박싱을 우회합니다.
  • 샌드박싱이 꺼져 있으면 tools.elevated는 실행을 변경하지 않습니다 (이미 호스트에서 실행). 엘리베이티드 모드를 참고하세요.

모드

agents.defaults.sandbox.mode는 언제 샌드박싱을 사용할지 제어합니다:

• "off": 샌드박싱 없음.
• "non-main": non-main 세션만 샌드박스 처리 (일반 채팅을 호스트에서 실행하고 싶을 때 기본값).
• "all": 모든 세션이 샌드박스에서 실행됩니다. 참고: "non-main"은 에이전트 ID가 아닌 session.mainKey (기본값 "main")를 기준으로 합니다. 그룹/채널 세션은 자체 키를 사용하므로 non-main으로 취급되어 샌드박스 처리됩니다.

범위

agents.defaults.sandbox.scope는 컨테이너를 몇 개 생성할지 제어합니다:

• "session" (기본값): 세션당 하나의 컨테이너.
• "agent": 에이전트당 하나의 컨테이너.
• "shared": 모든 샌드박스 세션이 공유하는 하나의 컨테이너.

작업 공간 접근

agents.defaults.sandbox.workspaceAccess는 샌드박스가 무엇을 볼 수 있는지 제어합니다:

• "none" (기본값): 도구는 ~/.openclaw/sandboxes 아래의 샌드박스 작업 공간을 봅니다.
• "ro": 에이전트 작업 공간을 /agent에 읽기 전용으로 마운트 (write/edit/apply_patch 비활성화).
• "rw": 에이전트 작업 공간을 /workspace에 읽기/쓰기로 마운트.

인바운드 미디어는 활성 샌드박스 작업 공간(media/inbound/*)에 복사됩니다. 스킬 참고: read 도구는 샌드박스 루트를 기준으로 합니다. workspaceAccess: "none"에서는 OpenClaw가 적격한 스킬을 샌드박스 작업 공간(.../skills)에 미러링하여 읽을 수 있게 합니다. "rw"에서는 /workspace/skills에서 작업 공간 스킬을 읽을 수 있습니다.

커스텀 바인드 마운트

agents.defaults.sandbox.docker.binds는 컨테이너에 추가 호스트 디렉터리를 마운트합니다. 형식: host:container:mode (예: "/home/user/source:/source:rw").

전역 및 에이전트별 바인드는 병합됩니다 (교체 아님). scope: "shared"에서는 에이전트별 바인드가 무시됩니다.

agents.defaults.sandbox.browser.binds는 샌드박스 브라우저 컨테이너에만 추가 호스트 디렉터리를 마운트합니다.

• 설정 시 ([] 포함), 브라우저 컨테이너에서 agents.defaults.sandbox.docker.binds를 대체합니다.
• 생략 시, 브라우저 컨테이너는 agents.defaults.sandbox.docker.binds로 대체됩니다 (하위 호환성).

예시 (읽기 전용 소스 + 추가 데이터 디렉터리):

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

보안 참고:

• 바인드는 샌드박스 파일시스템을 우회합니다: 설정한 모드(:ro 또는 :rw)로 호스트 경로를 노출합니다.
• OpenClaw는 위험한 바인드 소스를 차단합니다 (예: docker.sock, /etc, /proc, /sys, /dev, 이들을 노출할 수 있는 상위 마운트).
• 민감한 마운트 (비밀 정보, SSH 키, 서비스 인증 정보)는 절대적으로 필요하지 않으면 :ro여야 합니다.
• 작업 공간에 대한 읽기 접근만 필요하면 workspaceAccess: "ro"와 결합하세요. 바인드 모드는 독립적입니다.
• 바인드가 도구 정책 및 엘리베이티드 exec과 어떻게 상호작용하는지는 샌드박스 vs 도구 정책 vs 엘리베이티드를 참고하세요.

이미지 + 설정

기본 이미지: openclaw-sandbox:bookworm-slim

한 번 빌드하세요:

scripts/sandbox-setup.sh

참고: 기본 이미지에는 Node가 포함되어 있지 않습니다. 스킬에 Node(또는 다른 런타임)가 필요하면, 커스텀 이미지를 빌드하거나 sandbox.docker.setupCommand로 설치하세요 (네트워크 이그레스 + 쓰기 가능한 루트 + root 사용자 필요).

공통 도구(예: curl, jq, nodejs, python3, git)가 포함된 더 기능적인 샌드박스 이미지가 필요하면 빌드하세요:

scripts/sandbox-common-setup.sh

그런 다음 agents.defaults.sandbox.docker.image를 openclaw-sandbox-common:bookworm-slim으로 설정하세요.

샌드박스 브라우저 이미지:

scripts/sandbox-browser-setup.sh

기본적으로 샌드박스 컨테이너는 네트워크 없이 실행됩니다. agents.defaults.sandbox.docker.network로 재정의하세요.

번들된 샌드박스 브라우저 이미지는 컨테이너화된 워크로드에 보수적인 Chromium 시작 기본값도 적용합니다. 현재 컨테이너 기본값:

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<OPENCLAW_BROWSER_CDP_PORT에서 파생>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• noSandbox 활성화 시 --no-sandbox 및 --disable-setuid-sandbox.
• 세 가지 그래픽 하드닝 플래그(--disable-3d-apis, --disable-software-rasterizer, --disable-gpu)는 선택 사항이며, 컨테이너에 GPU 지원이 없을 때 유용합니다. 워크로드에 WebGL이나 다른 3D/브라우저 기능이 필요하면 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0을 설정하세요.
• --disable-extensions는 기본적으로 활성화되며, 확장 프로그램에 의존하는 흐름의 경우 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0으로 비활성화할 수 있습니다.
• --renderer-process-limit=2는 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>으로 제어되며, 0은 Chromium 기본값을 유지합니다.

다른 런타임 프로필이 필요하면, 커스텀 브라우저 이미지를 사용하고 자체 엔트리포인트를 제공하세요. 로컬(비컨테이너) Chromium 프로필의 경우, browser.extraArgs를 사용하여 추가 시작 플래그를 추가하세요.

보안 기본값:

• network: "host"는 차단됩니다.
• network: "container:<id>"는 기본적으로 차단됩니다 (네임스페이스 합류 우회 위험).
• 긴급 조치 재정의: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

Docker 설치 및 컨테이너화된 게이트웨이는 여기를 참고하세요: Docker

Docker 게이트웨이 배포의 경우, docker-setup.sh가 샌드박스 설정을 부트스트랩할 수 있습니다. OPENCLAW_SANDBOX=1 (또는 true/yes/on)을 설정하여 해당 경로를 활성화하세요. OPENCLAW_DOCKER_SOCKET으로 소켓 위치를 재정의할 수 있습니다. 전체 설정 및 환경 변수 참고: Docker.

setupCommand (일회성 컨테이너 설정)

setupCommand는 샌드박스 컨테이너 생성 후 한 번만 실행됩니다 (매 실행마다가 아님). 컨테이너 내부에서 sh -lc를 통해 실행됩니다.

경로:

• 전역: agents.defaults.sandbox.docker.setupCommand
• 에이전트별: agents.list[].sandbox.docker.setupCommand

일반적인 문제:

• 기본 docker.network는 "none" (이그레스 없음)이므로, 패키지 설치가 실패합니다.
• docker.network: "container:<id>"는 dangerouslyAllowContainerNamespaceJoin: true가 필요하며 긴급 조치 전용입니다.
• readOnlyRoot: true는 쓰기를 방지합니다. readOnlyRoot: false를 설정하거나 커스텀 이미지를 빌드하세요.
• 패키지 설치에는 user가 root여야 합니다 (user를 생략하거나 user: "0:0"으로 설정).
• 샌드박스 exec는 호스트 process.env를 상속하지 않습니다. 스킬 API 키에는 agents.defaults.sandbox.docker.env(또는 커스텀 이미지)를 사용하세요.

도구 정책 + 탈출구

도구 허용/거부 정책은 샌드박스 규칙보다 먼저 적용됩니다. 도구가 전역 또는 에이전트별로 거부된 경우, 샌드박싱이 도구를 되살리지 않습니다.

tools.elevated는 호스트에서 exec를 실행하는 명시적 탈출구입니다. /exec 디렉티브는 권한 있는 발신자에게만 적용되며 세션별로 유지됩니다. exec를 완전히 비활성화하려면 도구 정책 거부를 사용하세요 (샌드박스 vs 도구 정책 vs 엘리베이티드 참고).

디버깅:

• openclaw sandbox explain을 사용하여 유효한 샌드박스 모드, 도구 정책, 수정 설정 키를 검사하세요.
• “왜 이것이 차단되었는가?” 멘탈 모델은 샌드박스 vs 도구 정책 vs 엘리베이티드를 참고하세요. 보안을 유지하세요.

다중 에이전트 재정의

각 에이전트는 샌드박스 + 도구를 재정의할 수 있습니다: agents.list[].sandbox 및 agents.list[].tools (샌드박스 도구 정책을 위한 agents.list[].tools.sandbox.tools 포함). 우선순위는 다중 에이전트 샌드박스 & 도구를 참고하세요.

최소 활성화 예시

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

관련 문서

• 샌드박스 설정
• 다중 에이전트 샌드박스 & 도구
• 보안