​

Sandboxing

​

무엇이 샌드박싱되는가

• 도구 실행 (exec, read, write, edit, apply_patch, process 등)
• 선택적인 sandboxed browser (agents.defaults.sandbox.browser)
  • 기본적으로 브라우저 도구가 필요할 때 sandbox browser가 자동 시작되어 CDP가 닿을 수 있게 합니다. agents.defaults.sandbox.browser.autoStart, agents.defaults.sandbox.browser.autoStartTimeoutMs로 설정합니다.
  • 기본적으로 sandbox browser 컨테이너는 전역 bridge 대신 전용 Docker network(openclaw-sandbox-browser)를 사용합니다. agents.defaults.sandbox.browser.network로 조정합니다.
  • 선택적인 agents.defaults.sandbox.browser.cdpSourceRange는 container-edge CDP ingress를 CIDR allowlist(예: 172.21.0.1/32)로 제한합니다.
  • noVNC observer access는 기본적으로 비밀번호로 보호되며, OpenClaw는 로컬 bootstrap 페이지용 단기 token URL을 발급하고 URL fragment에 비밀번호를 담아 noVNC를 엽니다. query/header 로그에는 남지 않습니다.
  • agents.defaults.sandbox.browser.allowHostControl을 켜면 sandboxed session이 호스트 브라우저를 명시적으로 대상으로 삼을 수 있습니다.
  • target: "custom"에는 선택적 allowlist인 allowedControlUrls, allowedControlHosts, allowedControlPorts가 적용됩니다.

• Gateway 프로세스 자체
• 명시적으로 호스트 실행이 허용된 도구(예: tools.elevated)
  • Elevated exec는 호스트에서 실행되며 샌드박싱을 우회합니다.
  • 샌드박싱이 꺼져 있으면 tools.elevated는 실행 위치를 바꾸지 않습니다. 이미 호스트이기 때문입니다. Elevated Mode를 참고하세요.

​

Modes

• "off": 샌드박싱 안 함
• "non-main": non-main 세션만 샌드박싱. 일반 채팅은 호스트에서 유지하고 싶을 때 기본값으로 많이 씁니다.
• "all": 모든 세션을 샌드박스에서 실행

​

Scope

• "session" (기본값): 세션당 컨테이너 1개
• "agent": agent당 컨테이너 1개
• "shared": 모든 sandboxed session이 컨테이너 1개를 공유

​

Workspace access

• "none" (기본값): 도구는 ~/.openclaw/sandboxes 아래의 sandbox workspace만 봅니다.
• "ro": agent workspace를 /agent에 읽기 전용으로 마운트합니다. (write / edit / apply_patch 비활성화)
• "rw": agent workspace를 /workspace에 읽기/쓰기 가능하게 마운트합니다.

​

Custom bind mounts

• 값이 설정되면([] 포함) 브라우저 컨테이너에서는 agents.defaults.sandbox.docker.binds를 대체합니다.
• 생략되면 브라우저 컨테이너는 이전 호환성을 위해 agents.defaults.sandbox.docker.binds를 fallback으로 사용합니다.

{
  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"],
          },
        },
      },
    ],
  },
}

• bind는 샌드박스 파일시스템을 우회합니다. 지정한 모드(:ro 또는 :rw) 그대로 호스트 경로가 노출됩니다.
• OpenClaw는 위험한 bind source(docker.sock, /etc, /proc, /sys, /dev 및 이를 노출하는 상위 mount)를 차단합니다.
• secrets, SSH keys, service credentials 같은 민감 mount는 꼭 필요한 경우가 아니면 :ro를 사용하세요.
• workspace 읽기만 필요하다면 workspaceAccess: "ro"와 함께 쓰세요. bind 모드는 여전히 별도로 적용됩니다.
• bind와 tool policy, elevated exec의 관계는 Sandbox vs Tool Policy vs Elevated를 참고하세요.

​

Images + setup

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --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
• 세 개의 graphics hardening flag(--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 기본값을 유지합니다.

• network: "host"는 차단됩니다.
• network: "container:<id>"도 기본적으로 차단됩니다. namespace join 우회 위험이 있기 때문입니다.
• break-glass override: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true

​

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

• 전역: agents.defaults.sandbox.docker.setupCommand
• agent별: agents.list[].sandbox.docker.setupCommand

• 기본 docker.network는 "none"이라 패키지 설치가 실패합니다.
• docker.network: "container:<id>"는 dangerouslyAllowContainerNamespaceJoin: true가 있어야 하며 break-glass 전용입니다.
• readOnlyRoot: true이면 쓰기가 막힙니다. readOnlyRoot: false로 바꾸거나 custom image를 쓰세요.
• 패키지 설치는 root user가 필요합니다. user를 생략하거나 user: "0:0"을 사용하세요.
• sandbox exec는 호스트 process.env를 상속하지 않습니다. skill API key는 agents.defaults.sandbox.docker.env 또는 custom image로 전달해야 합니다.

​

Tool policy + escape hatches

• openclaw sandbox explain으로 실제 sandbox mode, tool policy, fix-it config key를 확인하세요.
• “왜 막히는가?”를 빠르게 판단하려면 Sandbox vs Tool Policy vs Elevated를 참고하세요.

​

Multi-agent overrides

​

최소 활성화 예시

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

​

관련 문서

• Sandbox Configuration
• Multi-Agent Sandbox & Tools
• Security