Docker / Compose에서 OpenClaw Gateway를 운용하는 팀은 이미지 pull보다 재시작·업그레이드·docker compose down으로 페어링과 설정이 사라지거나, Skills 디렉터리가 읽기 전용이라 공식 트러블슈트의 네트워크 항목과 맞지 않는 Permission denied 로그에 더 많은 시간을 씁니다. 본문은 Docker 네트워크 트리아지, 설치 후 doctor 트리아지, Docker 프로덕션·Gateway 런북, 무인 원격 Mac 운용과 역할을 나눕니다. 볼륨·권한 함정 여섯 가지, 영구화 대상과 안티패턴 표 두 장, 증상→명령→수정 매트릭스, 복사해 쓰는 inspect 스니펫, 여섯 단계 런북, 대시보드 지표 세 가지를 정리합니다. 트리아지 순서는 먼저 볼륨과 UID/GID, 그다음 네트워킹과 리버스 프록시입니다.
이미지는 불변 템플릿입니다. 쓰기 가능 레이어, 익명 볼륨, 영구화되지 않은 경로에만 쓴 상태는 사라집니다. 아래 신호를 변경 티켓에 남기고 Compose 개정·이미지 태그와 같은 줄에서 검토합니다.
down -v나 정리 스크립트가 「git은 안 바꿨는데」 페어링 캐시를 지웁니다.user를 조정하지 않고 Compose를 복사하는 것이 흔한 실패입니다.:ro에 두면 업스트림 예제가 기대하는 토큰 캐시나 로컬 상태를 쓸 수 없습니다. 재시작 전까지 조용할 수 있습니다.docker commit이 매력적으로 보이나 태그 변경 시 그 레이어는 버려집니다. 프로덕션에서는 피합니다.네트워크 트리아지에서 CLI는 간헐적으로 성공하는데 재시작 후에는 반드시 실패한다면, network_mode나 프록시를 건드리기 전에 이름 지정 볼륨이 기대 디스크에 있고 프로세스 사용자가 Skills에 쓸 수 있는지 여기서 다시 확인합니다.
하위 경로는 이미지와 문서를 따릅니다. 표는 세 가지 엔지니어링 질문을 틀어줍니다: 컨테이너 수명을 넘겨 살아남는가, 백업이 필요한가, 공유 읽기 전용인가입니다. README와 온콜 플레이북에 답을 기록합니다.
| 분류 | 영구화하는 전형적 내용 | 권장 패턴 | 안티패턴 |
|---|---|---|---|
| 설정·시크릿 재료 | Gateway 엔드포인트, 공급자 선택, 채널 토큰 경로 | 호스트 bind 또는 이름 지정 볼륨. 런타임 사용자에 맞춘 권한 | 이미지에 굽기. 동기 도구가 비우는 디렉터리에 저장 |
| 런타임·페어링 | 디바이스 페어링과 세션 복원 상태 | 전용 bind 서브트리. 업그레이드 전 tar | Compose에 문서화되지 않은 익명 볼륨. 단일 prune로 전부 삭제 |
| Skills·확장 | 팀 소유 스킬 파일과 스크립트 | 리포지터리 옆에 bind. CI와 프로덕션에서 경로 일치 | 런타임 캐시는 쓰여야 하는데 :ro. UID가 쓸 수 없음 |
| 로그·버퍼 | 대용량 로그,보내기 데이터 | 별도 볼륨 또는 로테이션 있는 호스트 경로 | 쓰기 레이어를 채워 OOM이나 예기치 않은 읽기 전용 FS 유발 |
점검하는 동안 같은 셸 세션에서 이미지 ID, Compose 프로젝트 이름, 볼륨 이름을 로그에 남겨 롤백을 단순화합니다. 프로덕션 런북의 릴리스 체크리스트 페이지를 재사용합니다.
| 증상 | 먼저 확인 | 전형적 수정 | 여전히 실패하면 |
|---|---|---|---|
docker compose up마다 신규 설치 같다 | docker inspect Mounts와 기대 호스트 경로. 최근 -v 정리 | 명시적 bind 또는 이름 지정 볼륨. down에 -v 사용 여부 문서화 | 올바른 Compose 프로젝트 디렉터리인지 확인 |
| Skills 무시 또는 쓰기 실패 | 컨테이너 id 대 호스트 ls -ln 소유권 | user, chmod, Dockerfile/entrypoint에서 UID 정렬 | 마운트가 :ro가 아닌지 확인 |
| 권한 오류 연속 | Linux SELinux/AppArmor. macOS Docker Desktop 파일 공유 | Linux: 보안 기준에 맞춰 라벨 또는 :z 평가. macOS: 파일 공유에 경로 추가 | 디스크 전체 읽기 전용을 배제한 뒤 네트워크 트리아지로 복귀 |
| 이미지 범프 후 반쯤 동작 | 설정 스키마 변경. 레거시 데이터 디렉터리가 여전히 마운트됨 | 릴리스 노트 준수. 업그레이드 전 백업 | 문서화된 파괴적 변경에 대해 openclaw doctor 실행 |
# 1) 마운트가 기대 호스트 경로에 있는가? (컨테이너 이름 치환)
docker inspect -f '{{ json .Mounts }}' <container> | jq .
# 2) 컨테이너 런타임 사용자(호스트 소유권과 비교)
docker exec -it <container> id
# 3) Compose 프로젝트와 볼륨(익명 드리프트 방지)
docker compose ls
docker volume ls | grep <project>
# 4) 업그레이드 전 bind 백업 예(경로는 팀 규약에 맞춤)
tar czf openclaw-state-$(date +%Y%m%d).tgz ./openclaw-data/
참고: 원격 Mac의 Docker Desktop은 보통 bind를 사용자 홈 아래에 둡니다. Linux 클라우드 호스트는 user 줄과 권한 모델이 다를 수 있습니다. 「내 노트북에서 됨」이 「풀 호스트에서도 됨」과 같지 않습니다.
down -v가 무엇을 파괴하는지 적습니다.openclaw doctor와 채널 프로브를 실행해 거짓 음성을 줄입니다.Permission denied / EACCES를 필터링합니다. Gateway 업그레이드와 상관되면 대개 마운트 문제입니다.원격 Mac 운용 글의 디스크·로그 지표와 나란히 그립니다. 볼륨 이슈는 CPU 스파이크 전에 디스크 폭주나 읽기 전용 마운트로 드러나는 경우가 많습니다.
많은 팀이 2025–2026년에 Gateway와 Skills를 한 호스트 트리에 둡니다. 로그 전용 서브트리에 쿼터가 없으면 로그가 bind를 채워 설정 쓰기를 막습니다. 컨테이너만 재생성하지 말고 로테이션을 넣거나 볼륨을 분리합니다.
docker compose restart와 down/up도 구분합니다. 전자는 선언된 볼륨을 대개 유지하고, 후자는 정리 플래그에 따라 데이터 운명이 바뀝니다. 런북에 동사 치트시트를 공유합니다.
단일 사용자 노트북 권한은 자동 로그인 풀 호스트와 다릅니다. 절전, 동기 유틸, 수동 bind 편집이 「어제는 됐음」을 재현 불가로 만듭니다. OpenClaw를 24/7 제어 평면으로 쓰려면 계약된 경로, 되돌릴 수 있는 업그레이드, 감사 가능한 권한이 필요합니다.
개인 하드웨어 학습 루프는 괜찮지만 프로덕션 비용은 페이저 소음과 끊긴 채널로 나타납니다. 안정 마운트 없는 임시 스크래치 컨테이너는 업그레이드 때 실패 영역을 늘립니다. 항시 온·백업 친화·이식 가능한 Gateway가 필요한 팀은 개인 Docker 무한 조정보다 Apple Silicon 베어메탈과 멀티 리전 선택이 있는 전문 Mac 클라우드로 더 빨리 수렴합니다. MACCOME은 지역별 Mac mini M4 / M4 Pro 대여와 공개 도움말을 제공합니다. 고객센터와 대여 요금부터 보고 리전별 체크아웃을 고릅니다.
롤아웃 팁: 채널과 모델을 연결하기 전에 프로덕션과 같은 호스트 등급(Docker Desktop vs Linux)에서 표 2 점검을 돌려 「로컬에서는 되는데 클라우드에서는 실패」하는 UID·경로 드리프트를 피합니다.
Kubernetes도 쓰면 Pod는 Compose 스택보다 자주 교체됩니다. PVC 뒤에 없는 것은 롤링 업데이트 때 사라집니다. 명시적 영구화 규칙은 같고, kubectl describe pvc와 마운트 매니페스트로 검증합니다.
FAQ
Docker 네트워크 트리아지 글과 무엇이 다른가요?
네트워킹은 연결성과 네임스페이스를 다루고, 본문은 디스크에 데이터가 있는지·쓰기 가능한지를 다룹니다. 설치 진입점은 세 플랫폼 설치 가이드를 참고합니다. 접속과 가격: 고객센터와 대여 요금입니다.
doctor와 볼륨 중 무엇을 먼저 하나요?
먼저 볼륨과 권한, 그다음 doctor입니다. 컨테이너를 계속 재생성하면 거짓 양성이 납니다. WSL2 세부는 설치 후 doctor 글에 있습니다.
원격 Mac 운용 글과 어떻게 짝을 이루나요?
그 글은 launchd/systemd, 로그, 행(hang) 트리아지를 다루고, 본문은 Docker 영속성과 쓰기 가능 여부를 다룹니다. 둘 다 같은 변경 검토와 온콜 색인에 넣습니다.