OpenClaw Sandboxing으로 안전한 도구 실행 환경 구축하기

샌드박스 처리 대상

OpenClaw는 모델이 의도치 않은 동작을 수행할 때 파일 시스템과 프로세스 접근을 실질적으로 제한하기 위해 도구 실행을 격리합니다. 이 기능은 완벽한 보안 경계는 아니지만, 잠재적인 위험 범위를 최소화하는 데 도움을 줍니다.

도구 실행(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 허용 목록(예: 172.21.0.1/32)을 사용하여 컨테이너 에지 CDP 접근을 제한합니다.
- noVNC 관찰자 접근은 기본적으로 암호로 보호됩니다. OpenClaw는 로컬 부트스트랩 페이지를 제공하고 URL 조각(쿼리나 헤더 로그가 아님)에 암호를 포함하여 noVNC를 여는 단기 토큰 URL을 생성합니다.
- agents.defaults.sandbox.browser.allowHostControl을 설정하면 샌드박스 세션이 호스트 브라우저를 명시적으로 제어할 수 있습니다.
- target: "custom"을 사용하는 경우 allowedControlUrls, allowedControlHosts, allowedControlPorts를 통해 접근을 제한할 수 있습니다.

샌드박스 처리되지 않는 항목:

Gateway 프로세스 자체.
샌드박스 외부에서 실행되도록 명시적으로 허용된 도구(예: tools.elevated).
- Elevated exec는 샌드박싱을 우회하며 설정된 탈출 경로(기본값은 gateway, exec 대상이 node인 경우 node)를 사용합니다.
- 샌드박싱이 꺼져 있으면 tools.elevated는 실행 방식에 변화를 주지 않습니다(이미 호스트에서 실행 중이므로). Elevated Mode를 참조하세요.

모드

agents.defaults.sandbox.mode 설정은 샌드박싱을 언제 사용할지 결정합니다.

"off": 샌드박싱을 사용하지 않습니다.
"non-main": 메인이 아닌 세션만 샌드박스에서 실행합니다(호스트에서 일반적인 채팅을 유지하려는 경우 기본값).
"all": 모든 세션이 샌드박스에서 실행됩니다. 참고: "non-main"은 에이전트 ID가 아닌 session.mainKey(기본값 "main")를 기준으로 합니다. 그룹/채널 세션은 고유한 키를 사용하므로 메인이 아닌 것으로 간주되어 샌드박스 처리됩니다.

범위

agents.defaults.sandbox.scope 설정은 몇 개의 컨테이너를 생성할지 결정합니다.

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

백엔드

agents.defaults.sandbox.backend 설정은 샌드박스를 제공할 런타임을 결정합니다.

"docker" (샌드박싱 활성화 시 기본값): 로컬 Docker 기반 샌드박스 런타임입니다.
"ssh": 범용 SSH 기반 원격 샌드박스 런타임입니다.
"openshell": OpenShell 기반 샌드박스 런타임입니다.

SSH 관련 설정은 agents.defaults.sandbox.ssh 아래에 위치하며, OpenShell 관련 설정은 plugins.entries.openshell.config 아래에 위치합니다.

Workspace access

agents.defaults.sandbox.workspaceAccess 설정은 sandbox가 무엇을 볼 수 있는지를 제어합니다.

"none" (기본값): 도구들이 ~/.openclaw/sandboxes 경로 아래의 sandbox 작업 공간을 참조합니다.
"ro": 에이전트 작업 공간을 /agent 경로에 읽기 전용으로 마운트합니다 (write, edit, apply_patch 기능이 비활성화됩니다).
"rw": 에이전트 작업 공간을 /workspace 경로에 읽기/쓰기 가능하도록 마운트합니다.

OpenShell 백엔드를 사용할 경우의 동작 방식은 다음과 같습니다:

mirror 모드는 exec 턴 사이에서 로컬 작업 공간을 표준 소스로 계속 사용합니다.
remote 모드는 초기 시드 이후 원격 OpenShell 작업 공간을 표준 소스로 사용합니다.
workspaceAccess: "ro" 및 "none" 설정은 여전히 동일한 방식으로 쓰기 동작을 제한합니다.

인바운드 미디어는 활성 sandbox 작업 공간(media/inbound/*)으로 복사됩니다. Skills 관련 참고 사항으로, read 도구는 sandbox를 루트로 합니다. workspaceAccess: "none" 설정 시, OpenClaw는 적절한 스킬들을 sandbox 작업 공간(.../skills)으로 미러링하여 읽을 수 있게 합니다. "rw" 설정 시에는 작업 공간의 스킬들을 /workspace/skills에서 읽을 수 있습니다.

Custom bind mounts

agents.defaults.sandbox.docker.binds 설정은 추가적인 호스트 디렉토리를 컨테이너 내부로 마운트합니다. 형식은 host:container:mode입니다 (예: "/home/user/source:/source:rw").

전역 설정과 에이전트별 설정의 binds는 병합되며, 대체되지 않습니다. scope: "shared" 설정 하에서는 에이전트별 binds가 무시됩니다.

agents.defaults.sandbox.browser.binds 설정은 sandbox browser 컨테이너에만 추가적인 호스트 디렉토리를 마운트합니다.

설정 시([] 포함), 브라우저 컨테이너에 대해 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"],
          },
        },
      },
    ],
  },
}

보안 참고 사항:

Binds는 sandbox 파일 시스템을 우회합니다. 즉, 설정한 모드(:ro 또는 :rw)에 따라 호스트 경로를 노출합니다.
OpenClaw는 위험한 bind 소스를 차단합니다 (예: docker.sock, /etc, /proc, /sys, /dev 및 이들을 노출할 수 있는 상위 마운트 경로).
OpenClaw는 또한 ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm, ~/.ssh와 같은 일반적인 홈 디렉토리 자격 증명 루트를 차단합니다.
Bind 유효성 검사는 단순한 문자열 일치 방식이 아닙니다. OpenClaw는 소스 경로를 정규화한 뒤, 차단된 경로와 허용된 루트를 다시 확인하기 전에 가장 깊은 기존 상위 경로를 통해 다시 해석합니다.
따라서 심볼릭 링크를 이용한 상위 경로 탈출 시도는 최종 리프 노드가 아직 존재하지 않더라도 차단됩니다. 예: run-link가 /var/run/...을 가리키고 있다면 /workspace/run-link/new-file은 여전히 해당 경로로 해석되어 차단됩니다.
허용된 소스 루트도 동일한 방식으로 정규화되므로, 심볼릭 링크 해석 전에는 허용 목록 내부처럼 보이더라도 실제로는 outside allowed roots로 거부될 수 있습니다.
민감한 마운트(비밀 키, SSH 키, 서비스 자격 증명)는 반드시 필요한 경우가 아니라면 :ro로 설정해야 합니다.
작업 공간에 대한 읽기 권한만 필요한 경우 workspaceAccess: "ro"와 함께 사용하세요. bind 모드는 독립적으로 유지됩니다.
binds가 도구 정책 및 권한 상승된 exec와 어떻게 상호작용하는지 확인하려면 Sandbox vs Tool Policy vs Elevated 문서를 참조하세요.

AI Setup Assistant

이미지 및 설정

기본 Docker 이미지는 openclaw-sandbox:bookworm-slim입니다.

이미지를 한 번 빌드하려면 다음 명령어를 사용하세요:

scripts/sandbox-setup.sh

참고: 기본 이미지에는 Node.js가 포함되어 있지 않습니다. 스킬에서 Node.js나 다른 런타임이 필요한 경우, 커스텀 이미지를 만들거나 sandbox.docker.setupCommand를 통해 설치하세요(네트워크 송신 권한, 쓰기 가능한 루트 디렉터리, 루트 사용자 권한이 필요합니다).

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

기본적으로 Docker 샌드박스 컨테이너는 네트워크 없이 실행됩니다. agents.defaults.sandbox.docker.network를 사용하여 이를 재정의할 수 있습니다.

번들로 제공되는 샌드박스 브라우저 이미지는 컨테이너화된 워크로드를 위해 보수적인 Chromium 시작 기본값을 적용합니다. 현재 컨테이너 기본값은 다음과 같습니다:

--remote-debugging-address=127.0.0.1
--remote-debugging-port=<derived from 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의 기본값을 유지합니다.

다른 런타임 프로필이 필요한 경우 커스텀 브라우저 이미지를 사용하고 고유한 entrypoint를 제공하세요. 로컬(비컨테이너) Chromium 프로필의 경우 browser.extraArgs를 사용하여 추가 시작 플래그를 추가할 수 있습니다.

보안 기본값은 다음과 같습니다:

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

Docker 설치 및 컨테이너화된 Gateway는 다음 위치에 있습니다: Docker

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

setupCommand (컨테이너 1회 설정)

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가 루트여야 합니다(user를 생략하거나 user: "0:0"으로 설정).
샌드박스 실행은 호스트의 process.env를 상속받지 않습니다. 스킬 API 키를 사용하려면 agents.defaults.sandbox.docker.env를 사용하거나 커스텀 이미지를 활용하세요.

도구 정책 및 이스케이프 해치

도구 허용/거부 정책은 샌드박스 규칙보다 우선하여 적용됩니다. 만약 특정 도구가 전역적으로 또는 에이전트별로 거부된 상태라면, 샌드박스 환경을 사용하더라도 해당 도구를 다시 사용할 수는 없습니다.

tools.elevated는 샌드박스 외부에서 명령을 실행할 수 있는 명시적인 이스케이프 해치입니다. 기본적으로 Gateway에서 실행되지만, 실행 대상이 Node.js인 경우에는 Node.js 환경에서 실행됩니다. /exec 지시어는 승인된 발신자에게만 적용되며 세션별로 유지됩니다. exec 기능을 완전히 비활성화하려면 도구 정책 거부 설정을 사용하세요(자세한 내용은 Sandbox vs Tool Policy vs Elevated 문서를 확인하세요).

디버깅 방법은 다음과 같습니다.

openclaw sandbox explain 명령어를 사용하여 현재 적용 중인 샌드박스 모드, 도구 정책 및 fix-it 설정 키를 확인하세요.
“왜 이 기능이 차단되었는지”에 대한 논리적 모델을 이해하려면 Sandbox vs Tool Policy vs Elevated 문서를 참고하세요. 보안을 위해 설정을 엄격하게 유지하는 것이 좋습니다.

멀티 에이전트 재정의

각 에이전트는 샌드박스 및 도구 설정을 개별적으로 재정의할 수 있습니다.

agents.list[].sandbox 및 agents.list[].tools 설정을 사용하며, 샌드박스 도구 정책의 경우 agents.list[].tools.sandbox.tools를 통해 제어합니다. 우선순위에 대한 자세한 내용은 Multi-Agent Sandbox & Tools 문서를 확인하세요.

최소 활성화 예시

이 설정은 OpenClaw의 샌드박스 기능을 최소한으로 활성화하여 기본적인 격리 환경을 구성하는 방법을 보여줍니다. 아래의 JSON 설정을 통해 에이전트의 샌드박스 동작을 제어할 수 있습니다.

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

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.