샌드박싱

OpenClaw는 Docker 컨테이너 내부의 도구를 실행하여 폭발 반경을 줄일 수 있습니다. 이는 선택 사항이며 구성(agents.defaults.sandbox에 의해 제어됩니다. 또는 agents.list[].sandbox). 샌드박스가 꺼져 있으면 도구가 호스트에서 실행됩니다. 게이트웨이는 호스트에 유지됩니다. 도구 실행은 격리된 샌드박스에서 실행됩니다. 활성화되면.

이는 완벽한 보안 경계는 아니지만 파일 시스템을 실질적으로 제한합니다. 모델이 멍청한 짓을 할 때 접근을 처리합니다.

샌드박스 대상

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

샌드박스 처리되지 않음:

게이트웨이 프로세스 자체.
호스트에서 실행이 명시적으로 허용된 모든 도구(예: tools.elevated).
- 상승된 exec는 호스트에서 실행되며 샌드박싱을 우회합니다.
- 샌드박스가 꺼져 있으면 tools.elevated는 실행을 변경하지 않습니다(이미 호스트에 있음). 승격 모드를 참조하세요.

모드

agents.defaults.sandbox.mode는 샌드박싱이 사용되는 때를 제어합니다.

"off": 샌드박싱이 없습니다.
"non-main": 메인이 아닌 세션 전용 샌드박스(호스트에서 일반 채팅을 원하는 경우 기본값).
"all": 모든 세션은 샌드박스에서 실행됩니다. 참고: "non-main"는 에이전트 ID가 아닌 session.mainKey(기본값 "main")을 기반으로 합니다. 그룹/채널 세션은 자체 키를 사용하므로 기본이 아닌 세션으로 간주되어 샌드박스 처리됩니다.

범위

agents.defaults.sandbox.scope 생성되는 컨테이너 수를 제어합니다.

"session"(기본값): 세션당 하나의 컨테이너입니다.
"agent": 에이전트당 하나의 컨테이너입니다.
"shared": 모든 샌드박스 세션에서 공유되는 하나의 컨테이너입니다.

작업공간 액세스

agents.defaults.sandbox.workspaceAccess는 샌드박스가 볼 수 있는 것을 제어합니다.

"none"(기본값): 도구는 ~/.openclaw/sandboxes 아래에 샌드박스 작업 공간을 표시합니다.
"ro": /agent에 에이전트 작업 영역을 읽기 전용으로 마운트합니다(write/edit/apply_patch 비활성화).
"rw": 에이전트 작업공간 읽기/쓰기를 /workspace에 마운트합니다.

인바운드 미디어는 활성 샌드박스 작업 공간(media/inbound/*)에 복사됩니다. 기술 참고 사항: read 도구는 샌드박스 루트입니다. workspaceAccess: "none"를 사용하면, OpenClaw는 적합한 기술을 샌드박스 작업 공간(.../skills)에 미러링하므로 읽을 수 있습니다. "rw"를 사용하면 작업 공간 기술을 다음에서 읽을 수 있습니다. /workspace/skills.

사용자 정의 바인드 마운트

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

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

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

json5

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

보안 참고 사항:

바인딩은 샌드박스 파일 시스템을 우회합니다. 설정한 모드(:ro 또는 :rw)로 호스트 경로를 노출합니다.
민감한 마운트(예: docker.sock, 비밀, SSH 키)는 꼭 필요한 경우가 아니면 :ro여야 합니다.
작업공간에 대한 읽기 액세스만 필요한 경우 workspaceAccess: "ro"와 결합합니다. 바인딩 모드는 독립적으로 유지됩니다.
바인드가 도구 정책 및 상승된 실행과 상호 작용하는 방식은 샌드박스 vs 도구 정책 vs Elevated를 참조하세요.

이미지 + 설정

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

한 번만 빌드해 보세요.

bash

scripts/sandbox-setup.sh

참고: 기본 이미지에는 Node.js가 포함되지 않습니다. 스킬에 노드(또는 다른 런타임), 사용자 정의 이미지를 굽거나 다음을 통해 설치합니다. sandbox.docker.setupCommand (네트워크 송신 + 쓰기 가능한 루트 필요 + 루트 사용자).

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

bash

scripts/sandbox-browser-setup.sh

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

Docker 설치 및 컨테이너화된 게이트웨이는 여기에 있습니다. 도커

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

setupCommand 샌드박스 컨테이너가 생성된 후 한 번 실행됩니다(매 실행마다 아님). sh -lc를 통해 컨테이너 내부에서 실행됩니다.

경로:

글로벌: agents.defaults.sandbox.docker.setupCommand
에이전트별: agents.list[].sandbox.docker.setupCommand

일반적인 함정:

기본값 docker.network는 "none"(송신 없음)이므로 패키지 설치가 실패합니다.
readOnlyRoot: true 쓰기를 방지합니다. readOnlyRoot: false를 설정하거나 사용자 정의 이미지를 굽습니다.
user는 패키지 설치를 위해 루트여야 합니다(user 생략 또는 user: "0:0" 설정).
Sandbox exec는 호스트 process.env를 상속하지 않습니다. 사용 스킬 API 키에 대한 agents.defaults.sandbox.docker.env (또는 사용자 정의 이미지).

도구 정책 + 탈출구

도구 허용/거부 정책은 샌드박스 규칙 이전에 계속 적용됩니다. 도구가 거부된 경우 전체적으로 또는 에이전트별로 샌드박스를 사용하면 다시 가져오지 않습니다.

tools.elevated는 호스트에서 exec를 실행하는 명시적인 탈출구입니다. /exec 지시어는 승인된 발신자에게만 적용되며 세션별로 지속됩니다. 하드 비활성화 exec, 도구 정책 거부를 사용합니다(샌드박스 대 도구 정책 대 상승 참조).

디버깅:

openclaw sandbox explain를 사용하여 효과적인 샌드박스 모드, 도구 정책 및 수정 구성 키를 검사합니다.
“이것이 왜 차단됩니까?”에 대해서는 샌드박스 vs 도구 정책 vs Elevated를 참조하세요. 정신 모델. 잠가 두세요.

다중 에이전트 재정의

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

최소 활성화 예

json5

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

샌드박싱 ​

샌드박스 대상 ​

모드 ​

범위 ​

작업공간 액세스 ​

사용자 정의 바인드 마운트 ​

이미지 + 설정 ​

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

도구 정책 + 탈출구 ​

다중 에이전트 재정의 ​

최소 활성화 예 ​

관련 문서 ​