Sandboxing

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

이것은 완벽한 보안 경계는 아니지만, 모델이 멍청한 짓을 할 때 파일시스템과 프로세스 액세스를 실질적으로 제한합니다.

샌드박스되는 것

  • Tool 실행 (exec, read, write, edit, apply_patch, process 등).
  • 선택적 샌드박스 브라우저 (agents.defaults.sandbox.browser).
    • 기본적으로 sandbox 브라우저는 browser tool이 필요할 때 자동 시작됩니다 (CDP 연결 가능 보장). agents.defaults.sandbox.browser.autoStart 및 agents.defaults.sandbox.browser.autoStartTimeoutMs로 구성합니다.
    • agents.defaults.sandbox.browser.allowHostControl은 샌드박스 세션이 호스트 브라우저를 명시적으로 대상으로 지정할 수 있게 합니다.
    • 선택적 허용 목록이 target: "custom"을 게이트합니다: allowedControlUrls, allowedControlHosts, allowedControlPorts.

샌드박스되지 않는 것:

  • Gateway 프로세스 자체.
  • 호스트에서 실행되도록 명시적으로 허용된 모든 tool (예: tools.elevated).
    • Elevated exec은 호스트에서 실행되며 샌드박싱을 우회합니다.
    • 샌드박싱이 꺼져 있으면, tools.elevated는 실행을 변경하지 않습니다 (이미 호스트에 있음). Elevated Mode를 참조하세요.

모드

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

  • "off": 샌드박싱 없음.
  • "non-main": non-main 세션만 샌드박스 (호스트에서 일반 채팅을 원한다면 기본값).
  • "all": 모든 세션이 sandbox에서 실행됩니다. 참고: "non-main"은 session.mainKey (기본값 "main")를 기반으로 하며, agent id가 아닙니다. 그룹/채널 세션은 자체 키를 사용하므로 non-main으로 계산되어 샌드박스됩니다.

Scope

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

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

Workspace 액세스

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

  • "none" (기본값): tool은 ~/.openclaw/sandboxes 아래의 sandbox workspace를 봅니다.
  • "ro": /agent에 agent workspace를 읽기 전용으로 마운트 (write/edit/apply_patch 비활성화).
  • "rw": /workspace에 agent workspace를 읽기/쓰기로 마운트.

인바운드 미디어는 활성 sandbox workspace (media/inbound/*)로 복사됩니다. Skills 참고: read tool은 sandbox에 루트를 둡니다. workspaceAccess: "none"을 사용하면, OpenClaw는 적격 skill을 sandbox workspace (.../skills)로 미러링하여 읽을 수 있게 합니다. "rw"를 사용하면, workspace skill을 /workspace/skills에서 읽을 수 있습니다.

커스텀 바인드 마운트

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

전역 및 agent별 바인드가 병합됩니다 (교체되지 않음). scope: "shared" 아래에서는 agent별 바인드가 무시됩니다.

예제 (읽기 전용 소스 + docker 소켓):

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

보안 참고사항:

  • 바인드는 sandbox 파일시스템을 우회합니다: 설정한 모드 (:ro 또는 :rw)로 호스트 경로를 노출합니다.
  • 민감한 마운트 (예: docker.sock, 비밀, SSH 키)는 절대적으로 필요하지 않는 한 :ro여야 합니다.
  • workspace에 대한 읽기 액세스만 필요한 경우 workspaceAccess: "ro"와 결합하세요; 바인드 모드는 독립적으로 유지됩니다.
  • 바인드가 tool 정책 및 elevated exec과 상호 작용하는 방법은 Sandbox vs Tool Policy vs Elevated를 참조하세요.

이미지 + 설정

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

한 번 빌드:

scripts/sandbox-setup.sh

참고: 기본 이미지에는 Node가 포함되어 있지 않습니다. skill에 Node (또는 다른 런타임)가 필요한 경우, 커스텀 이미지를 굽거나 sandbox.docker.setupCommand를 통해 설치하세요 (네트워크 egress + 쓰기 가능한 root + root 사용자 필요).

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

scripts/sandbox-browser-setup.sh

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

Docker 설치 및 컨테이너화된 gateway는 여기에 있습니다: Docker

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

setupCommand는 sandbox 컨테이너가 생성된 후 한 번 실행됩니다 (실행할 때마다가 아님). sh -lc를 통해 컨테이너 내부에서 실행됩니다.

경로:

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

일반적인 함정:

  • 기본 docker.network는 "none" (egress 없음)이므로 패키지 설치가 실패합니다.
  • readOnlyRoot: true는 쓰기를 방지합니다; readOnlyRoot: false로 설정하거나 커스텀 이미지를 굽습니다.
  • user는 패키지 설치를 위해 root여야 합니다 (user를 생략하거나 user: "0:0" 설정).
  • Sandbox exec은 호스트 process.env를 상속하지 않습니다. skill API 키에는 agents.defaults.sandbox.docker.env (또는 커스텀 이미지)를 사용합니다.

Tool 정책 + 탈출구

Tool allow/deny 정책은 여전히 sandbox 규칙 전에 적용됩니다. tool이 전역적으로 또는 agent별로 거부되면, 샌드박싱이 되돌리지 않습니다.

tools.elevated는 호스트에서 exec을 실행하는 명시적 탈출구입니다. /exec 지시문은 승인된 발신자에게만 적용되며 세션당 지속됩니다; exec을 완전히 비활성화하려면, tool 정책 deny를 사용하세요 (Sandbox vs Tool Policy vs Elevated 참조).

디버깅:

  • openclaw sandbox explain을 사용하여 유효한 sandbox 모드, tool 정책 및 수정 config 키를 검사합니다.
  • "왜 이것이 차단되었나?" 멘탈 모델은 Sandbox vs Tool Policy vs Elevated를 참조하세요. 잠가 두세요.

멀티 agent 재정의

각 agent는 sandbox + tool을 재정의할 수 있습니다: agents.list[].sandbox 및 agents.list[].tools (sandbox tool 정책의 경우 agents.list[].tools.sandbox.tools). 우선순위는 Multi-Agent Sandbox & Tools를 참조하세요.

최소 활성화 예제

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

관련 문서

← 문서로 돌아가기