이미 프로덕션에서 OpenClaw를 돌리는 팀이 2026년에 가장 두려워하는 세 가지는 다음과 같습니다. latest 표류, 상태 디렉터리 없이 올리기, Gateway를 잘못된 순서로 내려 토큰과 볼륨이 엇갈리는 일입니다. 본문은 신규 설치가 아니라 《플랫폼별 설치》《Docker 프로덕션》《설치 후 분류》《Linux systemd＋Tunnel》과 역할을 나누고, 통증 유형, 로컬과 컨테이너 대조표, 증상—롤백 표, 백업 스니펫, 여섯 단계 업그레이드 Runbook, 당번용 세 문장을 정리합니다. Secrets와 노출면은 《고급 실전》을 이어서 읽으세요.
설치 글은 「어떻게 설치하는가」, Docker 프로덕션은 「상시 구동과 흔한 컨테이너 오류」, 설치 후 글은 「안 뜰 때 증상별로」, Linux＋Tunnel은 「systemd로 공인 바인딩 없이」를 다룹니다. 본문은 「이미 돌아가는」 전제의 업그레이드, 호스트 이전, 배포 형태 변경, 롤백만 다루며 변경 티켓에 그대로 붙일 수 있게 씁니다. 실제 당번에서 자주 보는 여섯 유형은 변경 설명에 복사해 넣으면 됩니다.
latest나 떠다니는 태그를 쓰면 이전 digest로 되돌릴 수 없습니다.~/.openclaw(또는 문서화된 경로)의 키·워크스페이스·게이트웨이 설정이 볼륨과 함께 스냅샷되지 않습니다.리뷰에서 「이번 릴리스는 어느 경로로 올리는가」를 고정할 때 씁니다. 필드 이름은 사용 중인 fork·릴리스 노트에 맞춥니다.
| 차원 | 로컬 경로 | Docker Compose 경로 |
|---|---|---|
| 버전 앵커 | npm/pnpm과 lockfile 고정, Node 마이너 기록 | 이미지 tag 또는 digest 고정, silent latest 금지 |
| 상태 위치 | ~/.openclaw와 로컬 워크스페이스 | bind mount 또는 이름 있는 볼륨을 호스트에 매핑 |
| 키·토큰 | 환경 변수, 키체인, .env(커밋 금지) | .env, Docker secrets, 오케스트레이션 변수. 승격 전보내기 |
| 헬스 | CLI/로컬 포트 프로브 | compose ps, 컨테이너 내부 헬스, 호스트 포트 |
| 롤백 지점 | 지정 패키지 버전 재설치＋디렉터리 tar 복원 | 이전 digest로 되돌림＋볼륨 스냅샷 복원 |
《설치 후 분류》와 보완 관계이며, 여기서는 업그레이드 창 안의 결정 순서를 강조합니다. Control UI와 공개 노출은 고급 실전 글의 노출 전략과 맞춥니다.
| 증상 | 먼저 의심 | 먼저 할 일 | 그래도 실패 시 |
|---|---|---|---|
| Gateway 재시작 루프 | 바인드 주소와 UI 허용 목록 불일치 | loopback 바인딩으로 맞추거나 allowedOrigins 류 설정을 보완한 뒤 재시도 | 직전 이미지 digest로 되돌리고 볼륨 스냅샷 복원 |
| 페어링·기기 승인 이상 | 이중 인스턴스 또는 토큰 로테이션이 클라이언트에 전달되지 않음 | 옛 인스턴스를 완전히 중지하고 CLI로 기기를 나열해 공식 절차로 재설정 | 백업에서 토큰 파일 복원 후 잠시 버전도 롤백 |
| 모델 연결 타임아웃 | 아웃바운드, 프록시, 키 변경 | 컨테이너/호스트에서 각각 curl로 탐색, 키는 최소 변경으로 시험 | 벤더 상태 페이지와 방화벽 정책 대조 |
| 디스크 급증 후 업그레이드 실패 | 워크스페이스·로그 로테이션 부재 | 로그 정리 전 스냅샷, 업그레이드 전 공급사 권장 여유 공간 확보 | 디스크 확장 또는 워크스페이스를 별 볼륨으로 |
# 예: 업그레이드 전 상태 디렉터리 묶기(경로는 환경에 맞출 것. 아카이브는 git에 넣지 않음) tar czf openclaw-state-$(date +%Y%m%d).tgz -C "$HOME" .openclaw # Compose: .env 또는 compose에서 digest/마이너 고정 후 pull & up # docker compose pull && docker compose up -d
주의: 비밀이 들어간 백업 파일 권한은 운영 역할로 제한합니다. 복원 후 노출될 수 있는 토큰은 순환하고, 고급 실전 글의 Secrets 감사 주기와 맞춥니다.
.env 안전 사본(감사용은 마스킹).노트북과 서버에 Gateway를 각각 돌리면 모니터링에 인스턴스 라벨을 달아야 합니다. 알림이 down만 뜨면 DNS를 어디로 돌릴지 모르는데, 이는 Docker 프로덕션 글의 토큰·노출 계약의 연장입니다.
절전, OS 업데이트, 예기치 않은 디스크 사용이 창을 무작위로 만듭니다. 스냅샷과 임대 기간이 맞지 않은 단기 VPS는 롤백할 디스크가 없는 경우가 많습니다. Gateway를 생산 구성요소로 보려면 예측 가능한 가동 시간, 복구 가능한 디스크, 리전 선택이 필요하고 Runbook을 모니터링에 묶어야 합니다.
파편화된 호스트는 Secrets 거버넌스·감사 추적과 맞지 않습니다. 누가 마지막으로 토큰을 바꿨는지, 어떤 머신이 digest X인지 말하기 어렵습니다. MACCOME은 여러 리전에서 Mac Mini M4 / M4 Pro 베어메탈을 제공하며 OpenClaw 안정 실행층이나 전용 Gateway 호스트에 적합합니다.《멀티리전·임대 기간 가이드》《SSH 대 VNC 결정》과 함께 검토한 뒤 대여 요금으로 플랜을 맞추고 고객 센터에서 청구·접속 문구를 확인하세요.
파일럿이라면 대상 리전에서 단기 대여로 백업—업그레이드—롤백 연습을 한 뒤 장기 계약으로 옮기는 편이 안전합니다.
자주 묻는 질문
업그레이드 전에 생략하면 안 되는 세 가지는 무엇인가요?
이미지·패키지 버전 앵커 고정, 상태 디렉터리와 볼륨 전체 백업, 창 안에서 롤백 책임자와 검증 시나리오 기록입니다. 상업 조항은 대여 요금과 고객 센터를 열어 확인하세요.
Gateway 업그레이드 후 Control UI가 이상하면 무엇을 먼저 보나요?
바인딩과 헬스, Docker에서는 loopback과 UI 허용 목록 류, 로컬에서는 포트와 토큰입니다. 증상별 흐름은 《설치 후 분류》를 주로 따릅니다.
Docker 프로덕션 글과 어떻게 맞추나요?
프로덕션 글은 상시 구동과 흔한 컨테이너 장애, 본문은 업그레이드 전후 백업 순서·앵커·롤백입니다.《Docker 프로덕션》과 같은 운영 매뉴얼 목차에 넣으세요.