​

샌드박싱

​

무엇이 샌드박싱되는가

• 도구 실행(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 allowlist(예: 172.21.0.1/32)로 컨테이너 경계의 CDP 인그레스를 제한합니다.
  • noVNC 관찰자 액세스는 기본적으로 비밀번호로 보호되며, OpenClaw는 로컬 bootstrap 페이지를 제공하고 URL 프래그먼트(쿼리/헤더 로그 아님)에 비밀번호를 담아 noVNC를 여는 짧은 수명의 토큰 URL을 출력합니다.
  • agents.defaults.sandbox.browser.allowHostControl은 샌드박스 세션이 호스트 브라우저를 명시적으로 대상으로 삼도록 허용합니다.
  • 선택적 allowlist가 target: "custom"을 제어합니다: allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Gateway 프로세스 자체.
• 샌드박스 밖에서 실행이 명시적으로 허용된 모든 도구(예: tools.elevated).
  • elevated exec는 샌드박싱을 우회하며 구성된 탈출 경로(gateway가 기본값, exec 대상이 node일 때는 node)를 사용합니다.
  • 샌드박싱이 꺼져 있으면 tools.elevated는 실행을 바꾸지 않습니다(이미 호스트에서 실행 중). Elevated Mode를 참조하세요.

​

모드

• "off": 샌드박싱 안 함.
• "non-main": non-main 세션만 샌드박싱(일반 채팅은 호스트에서 실행하고 싶을 때의 기본값).
• "all": 모든 세션이 샌드박스에서 실행됩니다. 참고: "non-main"은 agent id가 아니라 session.mainKey(기본값 "main")를 기준으로 합니다. 그룹/채널 세션은 자체 키를 사용하므로 non-main으로 간주되어 샌드박싱됩니다.

​

범위

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

​

백엔드

• "docker" (기본값): 로컬 Docker 기반 샌드박스 런타임.
• "ssh": 일반 SSH 기반 원격 샌드박스 런타임.
• "openshell": OpenShell 기반 샌드박스 런타임.

​

백엔드 선택

​

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

• OpenClaw는 sandbox.ssh.workspaceRoot 아래에 범위별 원격 루트를 생성합니다.
• 생성 또는 재생성 후 처음 사용할 때, OpenClaw는 로컬 workspace에서 해당 원격 workspace로 한 번 시드합니다.
• 그 이후에는 exec, read, write, edit, apply_patch, 프롬프트 미디어 읽기, 인바운드 미디어 스테이징이 SSH를 통해 원격 workspace를 직접 대상으로 실행됩니다.
• OpenClaw는 원격 변경 사항을 자동으로 로컬 workspace에 다시 동기화하지 않습니다.

• identityFile, certificateFile, knownHostsFile: 기존 로컬 파일을 사용하고 OpenSSH config를 통해 전달합니다.
• identityData, certificateData, knownHostsData: 인라인 문자열 또는 SecretRef를 사용합니다. OpenClaw는 일반 secrets 런타임 스냅샷을 통해 이를 해석하고, 0600 권한으로 임시 파일에 기록한 뒤 SSH 세션이 끝나면 삭제합니다.
• 같은 항목에 대해 *File과 *Data가 모두 설정되면, 해당 SSH 세션에서는 *Data가 우선합니다.

• 시드 단계 이후 OpenClaw 밖에서 이루어진 호스트 로컬 편집은 샌드박스를 재생성하기 전까지 원격에 보이지 않습니다.
• openclaw sandbox recreate는 범위별 원격 루트를 삭제하고 다음 사용 시 로컬에서 다시 시드합니다.
• 브라우저 샌드박싱은 SSH 백엔드에서 지원되지 않습니다.
• sandbox.docker.* 설정은 SSH 백엔드에 적용되지 않습니다.

​

OpenShell 백엔드

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

• mirror (기본값): 로컬 workspace가 정본으로 유지됩니다. OpenClaw는 exec 전에 로컬 파일을 OpenShell로 동기화하고 exec 후 원격 workspace를 다시 동기화합니다.
• remote: 샌드박스가 생성된 뒤에는 OpenShell workspace가 정본이 됩니다. OpenClaw는 로컬 workspace에서 원격 workspace로 한 번 시드한 뒤, 변경 사항을 다시 동기화하지 않고 파일 도구와 exec를 원격 샌드박스에 직접 실행합니다.

• OpenClaw는 openshell sandbox ssh-config <name>을 통해 샌드박스별 SSH config를 OpenShell에 요청합니다.
• 코어는 그 SSH config를 임시 파일에 기록하고 SSH 세션을 열며 backend: "ssh"에서 사용하는 것과 동일한 원격 파일 시스템 브리지를 재사용합니다.
• 수명 주기만 mirror 모드에서 다릅니다: exec 전 로컬에서 원격으로 동기화하고, exec 후 다시 역동기화합니다.

• 샌드박스 브라우저는 아직 지원되지 않음
• sandbox.docker.binds는 OpenShell 백엔드에서 지원되지 않음
• sandbox.docker.* 아래의 Docker 전용 런타임 옵션은 여전히 Docker 백엔드에만 적용됨

​

Workspace 모드

mirror

• exec 전에 OpenClaw가 로컬 workspace를 OpenShell 샌드박스로 동기화합니다.
• exec 후 OpenClaw가 원격 workspace를 다시 로컬 workspace로 동기화합니다.
• 파일 도구는 여전히 샌드박스 브리지를 통해 동작하지만, 턴 사이의 기준은 로컬 workspace입니다.

• OpenClaw 밖에서 로컬 파일을 편집하며 그 변경 사항이 샌드박스에 자동으로 반영되길 원할 때
• OpenShell 샌드박스가 가능한 한 Docker 백엔드처럼 동작하길 원할 때
• 각 exec 턴 이후 호스트 workspace가 샌드박스 쓰기 결과를 반영하길 원할 때

• exec 전후에 추가 동기화 비용이 발생함

remote

• 샌드박스가 처음 생성될 때 OpenClaw는 로컬 workspace에서 원격 workspace로 한 번 시드합니다.
• 그 이후에는 exec, read, write, edit, apply_patch가 원격 OpenShell workspace를 직접 대상으로 동작합니다.
• OpenClaw는 exec 후 원격 변경 사항을 로컬 workspace로 동기화하지 않습니다.
• 프롬프트 시점 미디어 읽기는 파일 및 미디어 도구가 로컬 호스트 경로를 가정하지 않고 샌드박스 브리지를 통해 읽기 때문에 계속 동작합니다.
• 전송 계층은 openshell sandbox ssh-config가 반환한 OpenShell 샌드박스로의 SSH입니다.

• 시드 이후 호스트에서 OpenClaw 밖으로 파일을 편집하면 원격 샌드박스는 그 변경 사항을 자동으로 보지 못합니다.
• 샌드박스를 재생성하면 원격 workspace는 다시 로컬 workspace에서 시드됩니다.
• scope: "agent" 또는 scope: "shared"에서는 그 원격 workspace가 같은 범위 내에서 공유됩니다.

• 샌드박스가 주로 원격 OpenShell 측에 존재해야 할 때
• 턴당 동기화 오버헤드를 줄이고 싶을 때
• 호스트 로컬 편집이 원격 샌드박스 상태를 조용히 덮어쓰지 않길 원할 때

​

OpenShell 수명 주기

• openclaw sandbox list는 Docker 런타임뿐 아니라 OpenShell 런타임도 표시합니다
• openclaw sandbox recreate는 현재 런타임을 삭제하고 다음 사용 시 OpenClaw가 다시 생성하게 합니다
• prune 로직도 백엔드를 인식합니다

• recreate는 해당 범위의 정본 원격 workspace를 삭제합니다
• 다음 사용 시 로컬 workspace에서 새 원격 workspace를 시드합니다

​

Workspace 액세스

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

• mirror 모드는 여전히 exec 턴 사이에 로컬 workspace를 정본으로 사용합니다
• remote 모드는 초기 시드 이후 원격 OpenShell workspace를 정본으로 사용합니다
• workspaceAccess: "ro" 및 "none"는 여전히 같은 방식으로 쓰기 동작을 제한합니다

​

사용자 지정 바인드 마운트

• 설정되면([] 포함) 브라우저 컨테이너에 대해 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, 그리고 이를 노출할 수 있는 상위 마운트).
• OpenClaw는 또한 ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm, ~/.ssh 같은 일반적인 홈 디렉터리 자격 증명 루트도 차단합니다.
• 바인드 검증은 단순 문자열 비교가 아닙니다. OpenClaw는 소스 경로를 정규화한 뒤, 가장 깊은 기존 상위 경로를 통해 다시 해석하여 차단된 경로와 허용된 루트를 다시 검사합니다.
• 즉 최종 리프가 아직 존재하지 않더라도 심볼릭 링크 상위 경로를 통한 탈출은 여전히 fail-closed로 처리됩니다. 예: run-link가 그 위치를 가리키면 /workspace/run-link/new-file도 여전히 /var/run/...으로 해석됩니다.
• 허용된 소스 루트도 같은 방식으로 정규화되므로, 심볼릭 링크 해석 전에는 allowlist 내부처럼 보여도 해석 후에는 outside allowed roots로 거부됩니다.
• 민감한 마운트(secrets, SSH 키, 서비스 자격 증명)는 정말 필요한 경우가 아니면 :ro여야 합니다.
• workspace 읽기만 필요하다면 workspaceAccess: "ro"와 함께 사용하세요. 바인드 모드는 별개로 유지됩니다.
• 바인드가 도구 정책 및 elevated exec와 어떻게 상호작용하는지는 Sandbox vs Tool Policy vs Elevated를 참조하세요.

​

이미지 + 설정

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.
• 세 가지 그래픽 강화 플래그(--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 우회 위험).
• 비상 해제용 재정의: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

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

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

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

​

도구 정책 + 탈출 경로

• openclaw sandbox explain을 사용해 실제 적용되는 샌드박스 모드, 도구 정책, 수정용 config 키를 확인하세요.
• “왜 차단되었지?”에 대한 사고 방식은 Sandbox vs Tool Policy vs Elevated를 참조하세요. 강하게 잠가 두세요.

​

멀티 에이전트 재정의

​

최소 활성화 예시

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

​

관련 문서

• OpenShell — 관리형 샌드박스 백엔드 설정, workspace 모드 및 구성 참조
• Sandbox Configuration
• Sandbox vs Tool Policy vs Elevated — “왜 차단되었지?” 디버깅
• Multi-Agent Sandbox & Tools — agent별 재정의와 우선순위
• Security