샌드박싱

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)를 사용합니다.
  • 샌드박스가 꺼져 있으면 tools.elevated는 실행을 변경하지 않습니다(이미 호스트에서 실행 중). 상승 권한 모드를 참조하세요.

# 모드

agents.defaults.sandbox.mode는 샌드박스가 사용되는 시점을 제어합니다:

# 범위

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 아래에 있습니다.

# 백엔드 선택

# Docker 백엔드

샌드박스는 기본적으로 꺼져 있습니다. 샌드박스를 활성화하고 백엔드를 선택하지 않으면 OpenClaw는 Docker 백엔드를 사용합니다. Docker 데몬 소켓(/var/run/docker.sock)을 통해 도구와 샌드박스 브라우저를 로컬에서 실행합니다. 샌드박스 컨테이너 격리는 Docker 네임스페이스에 의해 결정됩니다.

호스트 GPU를 Docker 샌드박스에 노출하려면 agents.defaults.sandbox.docker.gpus 또는 에이전트별 agents.list[].sandbox.docker.gpus 재정의를 설정합니다. 값은 Docker의 --gpus 플래그에 별도 인수로 전달됩니다. 예를 들어 "all" 또는 "device=GPU-uuid"이며, NVIDIA Container Toolkit 같은 호환되는 호스트 런타임이 필요합니다.

# SSH 백엔드

임의의 SSH 접근 가능 머신에서 OpenClaw가 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" },
        },
      },
    },
  },
}

# OpenShell 백엔드

OpenShell 관리형 원격 환경에서 OpenClaw가 도구를 샌드박스화하도록 하려면 backend: "openshell"을 사용합니다. 전체 설정 가이드, 구성 참조, 워크스페이스 모드 비교는 전용 OpenShell 페이지를 참조하세요.

OpenShell은 범용 SSH 백엔드와 동일한 핵심 SSH 전송 및 원격 파일 시스템 브리지를 재사용하며, OpenShell 전용 수명 주기(sandbox create/get/delete, sandbox 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
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

OpenShell 모드:

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

# 워크스페이스 모드

OpenShell에는 두 가지 워크스페이스 모델이 있습니다. 실무에서 가장 중요한 부분입니다.

샌드박스를 임시 실행 환경으로 생각한다면 mirror를 선택하세요. 샌드박스를 실제 워크스페이스로 생각한다면 remote를 선택하세요.

# OpenShell 수명 주기

OpenShell 샌드박스는 여전히 일반 샌드박스 수명 주기를 통해 관리됩니다:

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

remote 모드에서는 다시 생성이 특히 중요합니다:

• 다시 생성하면 해당 범위의 기준 원격 워크스페이스가 삭제됩니다.
• 다음 사용 시 로컬 워크스페이스에서 새 원격 워크스페이스를 시드합니다.

mirror 모드에서는 로컬 워크스페이스가 어쨌든 기준으로 남아 있으므로 다시 생성은 주로 원격 실행 환경을 재설정합니다.

# 워크스페이스 접근

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

OpenShell 백엔드 사용 시:

• mirror 모드는 exec 턴 사이에 로컬 워크스페이스를 계속 기준 소스로 사용합니다.
• 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는 추가 호스트 디렉터리를 샌드박스 브라우저 컨테이너에만 마운트합니다.

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

# 이미지 및 설정

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

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["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, exec 대상이 node일 때는 node). /exec 지시문은 승인된 발신자에게만 적용되며 세션별로 유지됩니다. exec를 완전히 비활성화하려면 도구 정책 거부를 사용하세요(샌드박스 vs 도구 정책 vs Elevated 참조).

디버깅:

• 유효한 샌드박스 모드, 도구 정책, 수정용 구성 키를 검사하려면 openclaw sandbox explain을 사용하세요.
• "왜 이것이 차단되었나요?"라는 사고 모델은 샌드박스 vs 도구 정책 vs Elevated를 참조하세요.

잠긴 상태를 유지하세요.

# 다중 에이전트 재정의

각 에이전트는 샌드박스와 도구를 재정의할 수 있습니다: agents.list[].sandbox 및 agents.list[].tools(샌드박스 도구 정책의 경우 agents.list[].tools.sandbox.tools 추가). 우선순위는 다중 에이전트 샌드박스 및 도구를 참조하세요.

# 최소 활성화 예시

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

# 관련 항목

• 다중 에이전트 샌드박스 및 도구 — 에이전트별 재정의 및 우선순위
• OpenShell — 관리형 샌드박스 백엔드 설정, 작업 영역 모드 및 구성 참조
• 샌드박스 구성
• 샌드박스 vs 도구 정책 vs Elevated — "왜 이것이 차단되었나요?" 디버깅
• 보안