샌드박싱

OpenClaw은 피해 범위를 줄이기 위해 샌드박스 백엔드 내에서 도구 실행을 수행할 수 있습니다. 샌드박싱은 기본적으로 꺼져 있으며 agents.defaults.sandbox(전역) 또는 agents.list[].sandbox(에이전트별)로 제어합니다. Gateway 프로세스는 항상 호스트에 유지되며, 활성화된 경우 도구 실행만 샌드박스로 이동합니다.

샌드박싱되는 항목

• 도구 실행: exec, read, write, edit, apply_patch, process 등.
• 선택적 샌드박스 브라우저(agents.defaults.sandbox.browser).

샌드박싱되지 않는 항목:

• Gateway 프로세스 자체.
• tools.elevated를 통해 샌드박스 외부에서 실행하도록 명시적으로 허용된 모든 도구. 승격된 exec는 샌드박싱을 우회하며 구성된 탈출 경로(기본값은 gateway, exec 대상이 node이면 node)에서 실행됩니다. 샌드박싱이 꺼져 있으면 exec가 이미 호스트에서 실행되므로 tools.elevated는 아무것도 변경하지 않습니다. 승격 모드를 참조하세요.

모드, 범위 및 백엔드

서로 독립적인 세 가지 설정이 샌드박스 동작을 제어합니다.

모드는 샌드박싱이 적용되는 시점을 제어합니다.

• off: 샌드박싱하지 않습니다.
• non-main: 에이전트의 기본 세션을 제외한 모든 세션을 샌드박싱합니다. 기본 세션 키는 항상 agent:<agentId>:main이며(session.scope가 "global"이면 global), 구성할 수 없습니다. 그룹/채널 세션은 자체 키를 사용하므로 항상 비기본 세션으로 간주되어 샌드박싱됩니다.
• all: 모든 세션이 샌드박스에서 실행됩니다.

범위는 생성되는 컨테이너/환경의 수를 제어합니다.

• agent: 에이전트당 컨테이너 하나.
• session: 세션당 컨테이너 하나.
• shared: 모든 샌드박스 세션이 하나의 컨테이너를 공유합니다(이 범위에서는 에이전트별 docker/ssh/browser 재정의가 무시됨).

백엔드는 샌드박스 도구를 실행하는 런타임을 제어합니다. SSH 전용 구성은 agents.defaults.sandbox.ssh 아래에 있으며, OpenShell 전용 구성은 plugins.entries.openshell.config 아래에 있습니다.

Docker 백엔드

샌드박싱이 활성화되면 Docker가 기본 백엔드입니다. Docker 데몬 소켓(/var/run/docker.sock)을 통해 도구와 샌드박스 브라우저를 로컬에서 실행하며, 격리는 Docker 네임스페이스에서 제공합니다.

기본값: network: "none"(외부 통신 없음), readOnlyRoot: true, capDrop: ["ALL"], 이미지 openclaw-sandbox:bookworm-slim.

호스트 GPU를 노출하려면 agents.defaults.sandbox.docker.gpus(또는 에이전트별 재정의)를 "all"이나 "device=GPU-uuid" 같은 값으로 설정하세요. 이 값은 Docker의 --gpus 플래그로 전달되며 NVIDIA Container Toolkit과 같은 호환 가능한 호스트 런타임이 필요합니다.

샌드박스 브라우저

• 브라우저 도구에 필요할 때 샌드박스 브라우저가 자동으로 시작됩니다(CDP에 접근 가능한지 확인). agents.defaults.sandbox.browser.autoStart(기본값 true) 및 autoStartTimeoutMs(기본값 12초)로 구성하세요.
• 샌드박스 브라우저 컨테이너는 전역 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(기본값 false)을 사용하면 샌드박스 세션이 호스트 브라우저를 명시적으로 대상으로 지정할 수 있습니다.
• 선택적 허용 목록 allowedControlUrls, allowedControlHosts, allowedControlPorts는 target: "custom" 사용을 제한합니다.

SSH 백엔드

임의의 SSH 접근 가능 머신에서 exec, 파일 도구 및 미디어 읽기를 샌드박싱하려면 backend: "ssh"를 사용하세요.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // Or use SecretRefs / inline contents instead of local files:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

기본값: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• 수명 주기: OpenClaw은 sandbox.ssh.workspaceRoot 아래에 범위별 원격 루트를 생성합니다. 생성 또는 재생성 후 처음 사용할 때 로컬 워크스페이스에서 해당 원격 워크스페이스로 한 번 시드합니다. 이후 exec, read, write, edit, apply_patch, 프롬프트 미디어 읽기 및 인바운드 미디어 스테이징은 SSH를 통해 원격 워크스페이스에서 직접 실행됩니다. OpenClaw은 원격 변경 사항을 로컬 워크스페이스로 자동 동기화하지 않습니다.
• 인증 자료: identityFile/certificateFile/knownHostsFile은 기존 로컬 파일을 참조합니다. identityData/certificateData/knownHostsData는 인라인 문자열 또는 SecretRef를 허용하며, 일반적인 비밀 런타임 스냅샷을 통해 확인되고 모드 0600의 임시 파일에 기록된 뒤 SSH 세션이 종료되면 삭제됩니다. 동일한 항목에 *File 및 *Data 변형이 모두 설정되어 있으면 해당 세션에서는 *Data가 우선합니다.
• 원격 기준의 결과: 최초 시드 후 원격 SSH 워크스페이스가 실제 샌드박스 상태가 됩니다. 시드 단계 이후 OpenClaw 외부에서 수행한 호스트 로컬 편집 내용은 샌드박스를 재생성할 때까지 원격에서 보이지 않습니다. openclaw sandbox recreate는 범위별 원격 루트를 삭제하며, 다음 사용 시 로컬에서 다시 시드합니다. 이 백엔드는 브라우저 샌드박싱을 지원하지 않으며 sandbox.docker.* 설정도 적용되지 않습니다.

OpenShell 백엔드

OpenShell 관리형 원격 환경에서 도구를 샌드박싱하려면 backend: "openshell"을 사용하세요. OpenShell은 일반 SSH 백엔드와 동일한 SSH 전송 및 원격 파일 시스템 브리지를 재사용하고, OpenShell 수명 주기(sandbox create/get/delete/ssh-config)와 선택적 mirror 워크스페이스 동기화 모드를 추가합니다.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote        },      },    },  },}

mode: "mirror"(기본값)는 로컬 워크스페이스를 기준 상태로 유지합니다. OpenClaw은 exec 실행 전에 로컬 내용을 샌드박스로 동기화하고 실행 후 다시 동기화합니다. mode: "remote"는 로컬에서 원격 워크스페이스로 한 번 시드한 다음, 다시 동기화하지 않고 원격 워크스페이스에서 exec/read/write/edit/apply_patch를 직접 실행합니다. 시드 후 로컬 편집 내용은 openclaw sandbox recreate를 실행할 때까지 보이지 않습니다. scope: "agent" 또는 scope: "shared"에서는 해당 원격 워크스페이스가 동일한 범위에서 공유됩니다. 현재 제한 사항: 샌드박스 브라우저는 아직 지원되지 않으며 sandbox.docker.binds는 이 백엔드에 적용되지 않습니다.

openclaw sandbox list/recreate/prune은 모두 OpenShell 런타임을 Docker 런타임과 동일하게 취급하며, 정리 로직은 백엔드를 인식합니다.

전체 사전 요구 사항, 구성 참조, 워크스페이스 모드 비교 및 수명 주기 세부 정보는 OpenShell을 참조하세요.

워크스페이스 접근

agents.defaults.sandbox.workspaceAccess는 샌드박스에서 볼 수 있는 항목을 제어합니다.

OpenShell 백엔드에서 mirror 모드는 실행 전환 사이에 로컬 작업 공간을 계속 정식 소스로 사용하고, remote 모드는 초기 시드 이후 원격 OpenShell 작업 공간을 정식 소스로 사용하며, workspaceAccess: "ro"/"none"은 쓰기 동작을 동일한 방식으로 계속 제한합니다.

수신 미디어는 활성 샌드박스 작업 공간(media/inbound/*)으로 복사됩니다.

사용자 지정 바인드 마운트

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

전역 바인드와 에이전트별 바인드는 병합됩니다(대체되지 않음). scope: "shared"에서는 에이전트별 바인드가 무시됩니다.

agents.defaults.sandbox.browser.binds는 추가 호스트 디렉터리를 샌드박스 브라우저 컨테이너에만 마운트합니다. 설정하면([] 포함) 브라우저 컨테이너에서 docker.binds를 대체하며, 생략하면 브라우저 컨테이너가 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"],          },        },      },    ],  },}

이미지 및 설정

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

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

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

Docker 설치 및 컨테이너화된 Gateway에 관한 내용은 다음을 참조하세요. Docker

Docker Gateway 배포에서는 scripts/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

도구 정책 및 탈출구

도구 허용/거부 정책은 샌드박스 규칙보다 먼저 계속 적용됩니다. 도구가 전역 또는 에이전트별로 거부되면 샌드박스를 사용해도 다시 활성화되지 않습니다.

tools.elevated는 샌드박스 외부에서 exec를 실행하는 명시적인 탈출구입니다(기본값은 gateway, 실행 대상이 node이면 node). /exec 지시문은 승인된 발신자에게만 적용되고 세션별로 유지됩니다. exec를 강제로 비활성화하려면 도구 정책 거부를 사용하세요(샌드박스와 도구 정책 및 권한 상승 참조).

디버깅:

• openclaw sandbox list는 샌드박스 컨테이너, 상태, 이미지 일치 여부, 사용 기간, 유휴 시간 및 연관된 세션/에이전트를 표시합니다.
• openclaw sandbox explain [--session <key>] [--agent <id>]는 유효한 샌드박스 모드, 호스트 작업 공간, 런타임 작업 디렉터리, Docker 마운트, 도구 정책 및 수정용 구성 키를 검사합니다. workspaceRoot 필드는 구성된 샌드박스 루트를 그대로 나타내고, effectiveHostWorkspaceRoot는 활성 작업 공간이 실제로 있는 위치를 나타냅니다.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force]는 컨테이너/환경을 제거하여 다음 사용 시 현재 구성으로 다시 생성되도록 합니다.
• "왜 이것이 차단되었는가?"를 이해하기 위한 사고 모델은 샌드박스와 도구 정책 및 권한 상승을 참조하세요.

다중 에이전트 재정의

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

최소 활성화 예시

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

관련 문서

• 다중 에이전트 샌드박스 및 도구 -- 에이전트별 재정의 및 우선순위
• OpenShell -- 관리형 샌드박스 백엔드 설정, 작업 공간 모드 및 구성 참조
• 샌드박스 구성
• 샌드박스와 도구 정책 및 권한 상승 비교 -- "왜 이것이 차단되나요?" 디버깅
• 보안