샌드박싱

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

샌드박스화되는 항목

• 도구 실행(exec, read, write, edit, apply_patch, process 등).
• 선택적 샌드박스화된 브라우저(agents.defaults.sandbox.browser).

• Gateway 프로세스 자체.
• 샌드박스 외부에서 실행하도록 명시적으로 허용된 모든 도구(예: tools.elevated).
  • 승격된 exec는 샌드박스화를 우회하고 구성된 이스케이프 경로를 사용합니다(기본값은 gateway, exec 대상이 node인 경우 node).
  • 샌드박스화가 꺼져 있으면 tools.elevated는 실행을 변경하지 않습니다(이미 호스트에서 실행 중). 승격 모드를 참조하세요.

​

모드

​

범위

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

​

백엔드

• "docker"(샌드박스화가 활성화된 경우 기본값): 로컬 Docker 기반 샌드박스 런타임.
• "ssh": 범용 SSH 기반 원격 샌드박스 런타임.
• "openshell": OpenShell 기반 샌드박스 런타임.

​

백엔드 선택

​

Docker 백엔드

​

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

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

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

​

워크스페이스 모드

​

OpenShell 수명 주기

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

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

​

작업 공간 액세스

• mirror 모드는 여전히 exec 턴 사이에 로컬 작업 공간을 정본 소스로 사용합니다.
• remote 모드는 초기 시드 후 원격 OpenShell 작업 공간을 정본 소스로 사용합니다.
• workspaceAccess: "ro" 및 "none"은 여전히 동일한 방식으로 쓰기 동작을 제한합니다.

​

사용자 지정 바인드 마운트

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

​

이미지 및 설정

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

​

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

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

​

도구 정책과 탈출 수단

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

​

멀티 에이전트 오버라이드

​

최소 활성화 예시

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

​

관련 항목

• 멀티 에이전트 샌드박스 및 도구 — 에이전트별 오버라이드와 우선순위
• OpenShell — 관리형 샌드박스 백엔드 설정, 워크스페이스 모드, config 참조
• 샌드박스 구성
• 샌드박스 vs 도구 정책 vs Elevated — “왜 이것이 차단되나요?” 디버깅
• 보안