Sandbox CLI로 안전하게 에이전트 실행 환경 관리하기

에이전트를 개발하다 보면 설정을 바꾸거나 Docker 이미지를 업데이트했는데도 정작 실행해보면 예전 환경 그대로인 경우가 있죠. 일일이 Docker 컨테이너를 찾아서 지우는 것도 번거롭고, 왜 변경 사항이 반영되지 않는지 답답할 때가 많아요.

OpenClaw는 보안을 위해 에이전트를 격리된 Docker 컨테이너에서 실행하는데, sandbox 명령어를 사용하면 이런 관리 작업을 아주 간단하게 처리할 수 있어요.

필요한 것

OpenClaw 설치
Docker 환경
~/.openclaw/openclaw.json 설정 파일

빠른 시작

5분 안에 샌드박스 환경을 파악하고 초기화하는 방법이에요.

현재 상태 진단하기
openclaw sandbox explain을 입력해서 현재 적용된 sandbox 모드, 스코프, 워크스페이스 접근 권한을 확인하세요.
컨테이너 목록 확인하기
openclaw sandbox list로 실행 중인 컨테이너 이름과 상태, 설정과 이미지가 일치하는지 체크하세요.
컨테이너 재생성하기
openclaw sandbox recreate --all 명령어로 기존 컨테이너를 삭제하세요.
자동 생성 확인하기
에이전트를 다시 실행하면 현재 설정과 최신 이미지로 컨테이너가 자동 생성돼요.

주요 명령어 살펴보기

컨테이너 상태 점검

샌드박스가 의도한 대로 동작하는지 확인하고 싶을 때 사용하세요.

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

컨테이너 목록 조회

현재 생성된 모든 샌드박스 컨테이너의 상세 정보를 볼 수 있어요. 이미지 업데이트가 필요한지, 얼마나 오래되었는지 한눈에 들어와요.

openclaw sandbox list
openclaw sandbox list --browser  # 브라우저 컨테이너만 표시
openclaw sandbox list --json     # JSON 형식으로 출력

컨테이너 강제 재생성

설정이나 이미지를 바꾼 뒤에는 이 명령어가 꼭 필요해요. 기존 컨테이너를 삭제해서 새로운 설정이 적용되도록 만듭니다.

openclaw sandbox recreate --all                # 모든 컨테이너 재생성
openclaw sandbox recreate --session main       # 특정 세션만 재생성
openclaw sandbox recreate --agent mybot        # 특정 에이전트만 재생성
openclaw sandbox recreate --browser            # 브라우저 컨테이너만 재생성
openclaw sandbox recreate --all --force        # 확인 절차 없이 강제 실행

문제 해결

문제가 생겼을 때는 다음 해결 방법을 참고하세요.

설정을 바꿨는데 반영이 안 돼요: Docker 이미지를 업데이트하거나 설정을 변경해도 기존 컨테이너는 24시간 동안 유지될 수 있어요. 이럴 땐 openclaw sandbox recreate --all을 실행해서 이전 컨테이너를 강제로 삭제하세요.
수동으로 Docker 삭제를 해야 하나요?: 직접 docker rm을 쓰기보다는 openclaw sandbox recreate를 쓰는 쪽을 추천해요. Gateway가 관리하는 컨테이너 네이밍 규칙을 그대로 따르기 때문에 세션이나 스코프가 꼬이는 일을 막아줍니다.

설정 방법

샌드박스 설정은 ~/.openclaw/openclaw.json 파일의 agents.defaults.sandbox 항목에서 관리해요. 특정 에이전트에만 별도 설정을 주고 싶다면 agents.list[].sandbox에 작성하면 됩니다.

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... 기타 Docker 옵션
        },
        "prune": {
          "idleHours": 24, // 24시간 동안 사용하지 않으면 자동 삭제
          "maxAgeDays": 7, // 생성 후 7일이 지나면 자동 삭제
        },
      },
    },
  },
}

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.