샌드박싱

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 백엔드

OpenClaw가 OpenShell 관리 원격 환경에서 도구를 샌드박스화하도록 하려면 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 모드에서는 recreate가 특히 중요합니다.

• recreate는 해당 범위의 정본 원격 작업 공간을 삭제합니다.
• 다음 사용 시 로컬 작업 공간에서 새로운 원격 작업 공간을 시드합니다.

mirror 모드에서는 어차피 로컬 작업 공간이 정본으로 유지되기 때문에 recreate는 주로 원격 실행 환경을 재설정합니다.

작업 공간 액세스

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-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, exec 대상이 node이면 node). /exec 지시문은 승인된 발신자에게만 적용되며 세션별로 유지됩니다. exec를 강제로 비활성화하려면 도구 정책 거부를 사용하세요(샌드박스 vs 도구 정책 vs Elevated 참조).

디버깅:

• 유효한 샌드박스 모드, 도구 정책, 수정용 config 키를 확인하려면 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 — 관리형 샌드박스 백엔드 설정, 워크스페이스 모드, config 참조
• 샌드박스 구성
• 샌드박스 vs 도구 정책 vs Elevated — "왜 이것이 차단되나요?" 디버깅
• 보안