샌드박싱

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

OpenClaw가 임의의 SSH 접근 가능 머신에서 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-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가 sandbox 구성을 부트스트랩할 수 있습니다. 해당 경로를 활성화하려면 OPENCLAW_SANDBOX=1(또는 true/yes/on)을 설정하세요. OPENCLAW_DOCKER_SOCKET으로 소켓 위치를 재정의할 수 있습니다. 전체 설정 및 env 참조: Docker.

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

setupCommand는 sandbox 컨테이너가 생성된 후 한 번만 실행됩니다(매 실행마다 실행되지 않음). 컨테이너 내부에서 sh -lc를 통해 실행됩니다.

경로:

• 전역: agents.defaults.sandbox.docker.setupCommand
• 에이전트별: agents.list[].sandbox.docker.setupCommand

도구 정책 및 탈출구

도구 허용/거부 정책은 sandbox 규칙보다 먼저 계속 적용됩니다. 도구가 전역 또는 에이전트별로 거부된 경우, sandbox가 이를 다시 활성화하지 않습니다.

tools.elevated는 sandbox 외부에서 exec를 실행하는 명시적 탈출구입니다(기본값은 gateway, exec 대상이 node인 경우 node). /exec 지시문은 승인된 발신자에게만 적용되며 세션별로 유지됩니다. exec를 완전히 비활성화하려면 도구 정책 거부를 사용하세요(Sandbox vs Tool Policy vs Elevated 참조).

디버깅:

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

잠금 상태를 유지하세요.

멀티 에이전트 재정의

각 에이전트는 sandbox + 도구를 재정의할 수 있습니다: agents.list[].sandbox 및 agents.list[].tools(sandbox 도구 정책의 경우 agents.list[].tools.sandbox.tools도 포함). 우선순위는 Multi-Agent Sandbox & Tools를 참조하세요.

최소 활성화 예시

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

관련 항목

• Multi-Agent Sandbox & Tools — 에이전트별 재정의 및 우선순위
• OpenShell — 관리형 sandbox 백엔드 설정, 작업공간 모드 및 구성 참조
• Sandbox 구성
• Sandbox vs Tool Policy vs Elevated — "왜 이것이 차단되나요?" 디버깅
• 보안