샌드박스 CLI

격리된 에이전트 실행을 위한 샌드박스 런타임(Docker 컨테이너, SSH 대상 또는 OpenShell 백엔드)을 관리합니다.

명령어

openclaw sandbox list

샌드박스 런타임의 상태, 백엔드, 구성 일치 여부, 생성 후 경과 시간, 유휴 시간 및 연결된 세션/에이전트를 나열합니다.

openclaw sandbox listopenclaw sandbox list --browser  # 브라우저 컨테이너만openclaw sandbox list --json

openclaw sandbox recreate

현재 구성으로 강제로 다시 생성하도록 샌드박스 런타임을 제거합니다. 다음에 에이전트를 사용할 때 런타임이 자동으로 다시 생성됩니다.

openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot        # agent:mybot:* 하위 세션 포함openclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all      # 브라우저 컨테이너만openclaw sandbox recreate --all --force        # 확인 생략

옵션:

• --all: 모든 샌드박스 컨테이너를 다시 생성
• --session <key>: 이 정확한 범위 키(sandbox list에 표시된 값)의 런타임을 다시 생성하며, 짧은 이름은 확장하지 않음
• --agent <id>: 한 에이전트의 런타임을 다시 생성(agent:<id> 및 agent:<id>:*와 일치)
• --browser: 브라우저 컨테이너에만 적용
• --force: 확인 프롬프트 생략

--all, --session, --agent 중 정확히 하나를 전달하세요.

ssh 및 OpenShell remote에서 다시 생성은 Docker보다 더 중요합니다. 초기 시드 이후 원격 작업 공간이 기준 작업 공간이 되며, recreate는 선택한 범위의 해당 기준 원격 작업 공간을 삭제하고 다음 실행 시 현재 로컬 작업 공간에서 다시 시드합니다.

openclaw sandbox explain

적용되는 샌드박스 모드/범위/작업 공간 접근 권한, 샌드박스 도구 정책 및 권한 상승 도구 게이트를 검사합니다(수정에 필요한 구성 키 경로 포함).

보고서에서는 workspaceRoot를 구성된 샌드박스 루트로 유지하면서 적용되는 호스트 작업 공간, 백엔드 런타임 작업 디렉터리 및 Docker 마운트 표를 별도로 표시합니다. workspaceAccess: "rw"인 경우 적용되는 호스트 작업 공간은 workspaceRoot 아래의 디렉터리가 아니라 에이전트 작업 공간입니다.

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

recreate --session과 달리 이 명령은 짧은 세션 이름(예: main)을 허용하며, 확인된 에이전트를 기준으로 해당 이름을 확장합니다.

다시 생성해야 하는 이유

샌드박스 구성을 업데이트해도 실행 중인 컨테이너에는 영향을 주지 않습니다. 기존 런타임은 이전 설정을 유지하며, 유휴 런타임은 prune.idleHours(기본값 24시간)가 지난 후에만 정리됩니다. 정기적으로 사용하는 에이전트에서는 오래된 런타임이 무기한 유지될 수 있습니다. openclaw sandbox recreate는 이전 런타임을 제거하여 다음 사용 시 현재 구성으로 다시 빌드되도록 합니다.

일반적인 실행 계기

레지스트리 마이그레이션

샌드박스 런타임 메타데이터는 공유 SQLite 상태 데이터베이스에 저장됩니다. 이전 설치에는 일반적인 읽기 작업으로 더 이상 다시 기록되지 않는 레거시 레지스트리 파일이 있을 수 있습니다.

• ~/.openclaw/sandbox/containers.json
• ~/.openclaw/sandbox/browsers.json
• ~/.openclaw/sandbox/containers/ 또는 ~/.openclaw/sandbox/browsers/ 아래의 컨테이너/브라우저별 JSON 샤드 하나

유효한 레거시 항목을 SQLite로 마이그레이션하려면 openclaw doctor --fix를 실행하세요. 손상된 이전 레지스트리가 현재 런타임 항목을 숨길 수 없도록 유효하지 않은 레거시 파일은 격리됩니다.

구성

샌드박스 설정은 ~/.openclaw/openclaw.json의 agents.defaults.sandbox 아래에 있습니다(에이전트별 재정의는 agents.list[].sandbox에 설정).

{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off, non-main, all        "backend": "docker", // docker, ssh, openshell (Plugin 제공)        "scope": "agent", // session, agent, shared        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... 추가 Docker 옵션        },        "prune": {          "idleHours": 24, // 24시간 유휴 후 자동 정리          "maxAgeDays": 7, // 7일 후 자동 정리        },      },    },  },}

관련 문서

• CLI 참조
• 샌드박싱
• 에이전트 작업 공간
• Doctor: 샌드박스 설정을 확인합니다.