Docker/Compose로 OpenClaw Gateway는 돌릴 수 있으나, 에이전트 샌드박스를 켜면 컨테이너가 뜨지 않거나, 워크스페이스가 쓰기 불가, 샌드에 명령이 없거나, 빌드 중 137 OOM으로 끊기는 상황이 흔합니다. 본문은 2026년 주요 도입 흐름을 실행 순서로 끄기→켜기→검증→처리로 압축하고, 설정 키, docker.user와 볼륨 권한 정렬, 이미지·OOM 분기표를 기존 Docker·볼륨·doctor 문서와 맞춥니다. 읽고 나면 잘못된 이미지, 마운트 UID 문제, 한도·로그 시그니처를 구분할 수 있습니다.
원인은 흔히 프로세스 경계이며, 설치가 망가졌다기보다는 다음에 가깝습니다.
brew install한 것이 이미지에 없거나 마운트를 더하지 않으면 샌드 PATH에 올라오지 않습니다.501:20이고 컨테이너는 1000:1000이면 Permission denied·EROFS 형태의 거부가 흔합니다.| 모드 | 적합 | 지불하는 비용 | 흔한 착오 |
|---|---|---|---|
| Docker 샌드 | 신뢰할 수 없는 쉘·스크립트를 강하게 격리하고 「깨끗한」 환경을 복제 | 이미지 크기, 풀·빌드, UID·GID·볼륨 정합 | 호스트 툴이 그대로 붙는다고 가정 |
| SSH/원격 셸 | 도구가 온전한, 신뢰한 원격 Mac에서 곧장 실행(전담 빌드기 등) | 노출·계정 모델이 커짐 | 로컬을 샌드 본뜨다 감사를 잊음 |
| 샌드 없음·온로컬 | 내망, 저위험, 빠른 분기 | 모델이 돌리는 코드 실행 시 위험 큼 | CI·프로덕션에서도 샌드를 끄고 두는 실수 |
agents.defaults.sandbox.docker와 sandbox-setup.sh개념은 둘로 갈립니다. 어떤 샌드 구현을 쓰는가(이미지·런타임)와 이미지를 어디서 오게 하는가입니다. 일반적으로 저장소는 호스트 docker가 보는 이미지를 미리 빌드·풀하는 scripts/sandbox-setup.sh를 제공합니다(이름은 클론에 따름). 설정의 agents.defaults.sandbox.docker.image는 세션이 돌아가는 이미지입니다. 둘이 어긋나면 Gateway는 샌드 켜진 것으로 보이나 docker run에서 manifest not found나 pull access denied가 나는 전형이 나옵니다.
다른 글과 역할을 나눕니다. OPENCLAW_IMAGE·Control UI에서 막히면 먼저 공식 Docker·GHCR 이미지를, 볼륨·권한·영구화· Skills 경로이면 볼륨·권한 체크리스트를 보십시오. 본 글은 샌드 하위·OOM/137에만 둡니다.
docker.user와 OPENCLAW_HOME 마운트: 증상에 맞게, chmod 777 남발은 금지권장 순서는 다음과 같습니다.
docker.user를, 볼륨에 쓰기가 맞는 UID:GID로 둡니다(키는 문서 기준, 버전에 따라 sandbox.docker 하위일 수 있음).chown이 안 되면 컨테이너로 넣는 하위 경로를 먼저 다루고, 디스크 전체는 열지 않습니다.리눅스와 원격 Mac 차이로 이름 붙은 볼륨·bind·SELinux 라벨이(일부 배포) 「Compose는 맞다」가「컨테이너는 틀리다」를 키웁니다. 모델 대화가 아니라 Gateway·샌드 기동 로그의 첫 I/O 오류 한 줄을 잡는 것이 중요합니다.
PATH에 있는가? docker exec로 command -v로 확인하는 것이 말뿐보다 낫습니다.~/.cache 같은 읽기 bind가 꼭 필요한가? 그렇다면 호스트에 임의로 뚫는 대신 이미지/공용층을 검토합니다.HTTP(S)_PROXY가 없으면 실패가 command not found로 보일 수 있습니다.exit 137: 도커에서 죽음과 메모리 부족137 = 128 + 9 (SIGKILL)는 흔히 OOM 킬러와 연상되나, 사용자 docker kill·cgroup 메모리 제한일 수도 있습니다. 분기에서는 최소한 빌드 단계인가(docker build 대 docker run) 엔진에서 동시 빌드가 Docker Desktop/VM을 채웠는가, 원격 Mac이면 실질 남는 메모리·스왑을 씁니다. 또한 exit 1/2이면서 Cannot allocate memory가 많이 찍힌 경우는 메모리/임시 디스크와 같은 꼭지에 두는 편이 좋습니다.
「빌드 OOM」이면 먼저 병렬을 낮추기(--parallel 등), 멀티스테이지, Docker VM 용량 상향, 더 큰 메모리의 전담 원격 Mac 상품을 고정 밑받이로 쓰는 순이 흔합니다. IDE·로컬 모델·도커가 겹쳐 우연히 된 일과는 다릅니다. 공용 스토리지를 쓰면 inode·작은 파일 폭주로 OOM처럼 느껴지는 멈춤도 봅니다. 필요 시 볼륨 분리와 청소 정책을 조정하십시오.
sandbox-setup으로 풀·빌드, 설정과 갈 이미지명·ID를 기록합니다.docker.user·마운트 A/B: 변수 하나만 바꾸고 diff를 둡니다. 세 곳이 동시에 흔들리면 못 돌아옵니다.{
"agents": {
"defaults": {
"sandbox": { "mode": "docker" },
"docker": { "user": "1000:1000" }
}
}
}
// 실제는 sandbox.docker 아래일 수 있음. openclaw doctor·상위 문서 확인
docker events·엔진, 호스트 memory pressure도 붙여 업무 OOM과 docker build 병렬 OOM을 섞지 않습니다.chown -R 1000:1000를 한 프로젝트에만 할지 집 전체에 할지 위험이 다릅니다. 티켓·롤백점이 있어야 합니다.pip, 영속 없이 반복 다운로드는 “한번 통과”와 “수백 번” 비용이 다릅니다. 용량에 최초 기동 수치를 넣습니다.대개 동시에 겹치는 메모리·I/O 피크와 재현 가능한 환경 경계에서 갈립니다. Agent가 바쁠 땐 137과 쓰기 곱절이 함께 맞닿습니다. 7×24 Gateway+샌드가 필요하면 전담 Apple Silicon·명확한 디스크·로그·예측 가능한 임기 쪽이 덜 흔들립니다. 그 전제에서 MACCOME 원격 Mac 클라우드는 OpenClaw를 상시 둘 기반에 맞고, 로컬 랜덤 환경과 씨름하던 시간을 툴체인과 납품에 돌릴 수 있습니다.
자주 묻는 질문
호스트에 설치한 명령이 샌드에서 안 보일 때
이미지에 넣거나 마운트·PATH를 정책에 맞게 조정합니다. MCP/Skills에서 “Gateway 측 가시성”과 취지는 비슷하나 경계는 컨테이너 입니다.
137이면 항상 OOM인가요?
아닐 수 있습니다. cgroup, 시스템 OOM, 수동 kill을 나누고 같은 시각의 엔진·기억곡선을 씁니다. 일과로는 doctor/무응답 로그 읽기를 먼저 씁니다.