OpenClaw openclaw update 또는 이미지 업그레이드 전후에 Control UI는 열리는데 gateway probe가 타임아웃하거나 2026.3.13+ ACP / CLI device 스트림 회귀가 발생하면, 본 글은 다음을 정리합니다. ①업그레이드 전 openclaw backup create로 복구 가능 스냅샷 남기기; ②업그레이드 후 status → gateway status → gateway probe → doctor 수락 사다리로 「가동 가능/롤백 필수」 판정; ③probe / WebSocket 1006 / ACP「queue owner unavailable」증상별 런북. 버전 이전 총 체크리스트·불량 digest 롤백과 보완하며, 본 글은 백업 + probe/ACP 수락에 집중합니다.
backup create를 하지 않음: 롤백 시 설정을 기억에 의존해 「직전 양호 상태」의 페어링·채널 상태를 증명할 수 없습니다.acpx 직결은 정상일 수 있습니다. 본 글의 ACP 트리아지를 먼저 수행하고 모델 교체는 후순위로 두십시오.2026년 상류·커뮤니티 문서는 「업그레이드」를 단순 npm install -g가 아닌 가역 상태 이전으로 정의하는 흐름이 강합니다. openclaw backup create는 현재 ~/.openclaw(또는 Docker 볼륨에 대응하는 디렉터리)를 이름 있는 아카이브로 만들어, probe 연속 실패·ACP 등록 소실 시 수 분 내 업그레이드 전 조합으로 복귀할 선택지를 남깁니다. 이는 릴리스 채널 고정 매트릭스의 「알려진 양호 tag/digest」와 같은 FinOps 사고의 양면입니다. 하나는 바이너리를 고정하고, 다른 하나는 런타임 설정·페어링을 고정합니다.
실무에서 많은 팀이 첫 프로덕션 업그레이드 변경 티켓에 「OpenClaw 버전 업데이트」만 적고 백업 경로·SHA·복구 리허설 날짜를 빠뜨립니다. 야간 피크에 이미지 pull과 전량 probe를 겹치면 대역·디스크 I/O 포화로 「probe 타임아웃」을 「ACP 장애」로 오인해 채팅에서 같은 프롬프트를 반복하며 릴리스 창을 잃습니다. 호위 런북의 가치는 이 숨은 비용을 감사 가능·재현 가능·담당자 지정 가능한 단계열로 바꾸는 데 있습니다.
Gateway를 7×24로 제공해야 한다면 변경 창 전에 권위 Gateway 프로세스가 하나만 권위 포트를 listen하는지 확인하고, 원격 Mac에 충분한 디스크 워터마크와 대역 여유를 확보하십시오. 노트북은 SSH 로컬 포워딩으로 Control UI만 접근하면 「절전으로 인한 Gateway 유사 정지」와 「probe 경로·업무 경로 불일치」 두 가지 위양성을 동시에 줄이기 쉽습니다.
업그레이드마다 「증거 팩」폴더(버전 출력, probe JSON, doctor 요약, backup 경로)를 변경 티켓 번호로 90일 보관하는 것을 권장합니다. probe 위양성 비율이 급등할 때 과거 팩과 비교하면 기동 체인 지연인지 모니터 임계치 문제인지 구분할 수 있어, 「지난주도 빨갔을 것」 같은 기억 의존 논쟁을 줄입니다. 증거 팩은 감사에도 유효하며, 업그레이드 전 backup과 이후 사다리 실행을 입증합니다. SOC2나 내부 변경 관리를 요구하는 고객에게 특히 유용합니다.
| 사이트 기존 장문 | 본 글이 다룸 | 본 글이 반복하지 않음 |
|---|---|---|
| 버전 이전 총 체크리스트 | 업그레이드 전 backup create + 업그레이드 후 probe 사다리 | 전체 디렉터리 이전·다중 Gateway 전환 세부 |
| 불량 digest 롤백 | probe 실패 후 롤백 결정 시점 | Compose pull/digest 고정 단계 명령 |
| tools.profile 트리아지 | 수락 사다리의 「최소 도구 프로브」 | allowlist 3층 전문 글 |
| Gateway 무응답 | probe 전 「완전 무응답」 배제 | 채널 OAuth·모델 라우팅 전문 글 |
openclaw backup create와 디렉터리 경계 체크리스트변경 창 시작 전 백업 → 버전 지문 기록 → 권위 Gateway 하나만을 고정 실행합니다. 명령은 설치한 CLI 기준입니다(2026 문서의 전형 예는 아래). 하위 명령 이름은 채널마다 다를 수 있으나 openclaw backup --help를 정으로 하고, 원칙은 동일합니다: 업그레이드 전 복구 가능한 로컬 아카이브가 필수입니다.
백업은 「선택 보험」이 아니라 호위의 첫 번째 하드 게이트입니다. 증거 없는 변경 티켓은 사후 검토에서 「직전 양호 페어링·채널」에 답하기 어렵습니다. Docker Compose 사용 시 bind mount가 호스트 고정 경로를 가리키고 iCloud·클라우드 동기화 밖인지 확인하십시오. 원격 Mac 상시 배포에서는 OPENCLAW_STATE_DIR과 담당자를 티켓에 적어 타임존 당번 인수인계를 돕습니다.
Token·페어링 파일은 보통 상태 트리에 포함됩니다. 아카이브는 기밀로 보관하고 복구 전 로테이션 여부를 평가하십시오. 프로덕션 Gateway를 전용 원격 Mac에 올릴 계획이면 임대 요금과 고객 센터 연결 절차를 먼저 확인해, 노트북에서 백업한 뒤 디스크·대역 부족으로 전체 상태 트리를 못 실는 상황을 피하십시오.
openclaw --version
node -v # 목표: v24.x. 불일치 시 Node 기선 정렬 후 OpenClaw 업그레이드
openclaw backup create
ls -la ~/.openclaw/backup 2>/dev/null || ls -la "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/backup"
openclaw gateway status
openclaw config get gateway.auth.token 2>/dev/null | head -c 8; echo "…(redacted)"
| 점검 항목 | 로컬 npm | Docker Compose | 원격 Mac 상시 |
|---|---|---|---|
| 상태 디렉터리 | ~/.openclaw가 iCloud/동기화 밖 | bind mount가 호스트 고정 경로 | OPENCLAW_STATE_DIR이 전용 디스크·티켓 추적 가능 |
| 백업에 민감 정보 포함 | 보통 Token/페어링 포함. 기밀 보관, 복구 전 로테이션 검토 | ||
| 이중 Gateway | launchd+수동 이중 기동 | compose·호스트가 18789 경합 | 노트 포워딩+원격 이중 기동 |
| 디스크 워터마크 | 백업 전 df -h 여유 ≥ 상태 트리 2배 | ||
주의: 공식 백업 없이 tar ~/.openclaw만 하면 버전 메타데이터·증분 인덱스를 놓칠 수 있습니다. 프로덕션 창에서는 backup create를 우선하고, 수동 tar는 제2 냉백업으로만 두십시오.
업그레이드 완료 후 Control UI나 채팅 한마디만 보고 변경을 닫지 마십시오. 고정 사다리(단계 실패 시 중단, stderr·버전 기록)를 권장합니다.
openclaw status — CLI·설정 읽기 가능openclaw gateway status — 프로세스/포트/바인드 요약openclaw gateway probe(또는 --json) — loopback 핸드셰이크·지연openclaw doctor — 설정·의존성 경고channels status --probe「가동 가능」은 1–4단계 연속 통과且 5단계가 실제 채널/도구 면에서 통과한 상태로 정의하는 것이 좋습니다. 「롤백 필수」는 reload/재시작 후에도 동일 단계가 두 번 연속 실패하고 프로덕션 Agent에 영향이 있을 때입니다. 먼저 백업 복구 또는 digest 롤백으로 티켓에 기록된 tag/digest로 돌아가고, 불량 버전 위에 설정 패치를 쌓지 마십시오.
probe와 dashboard 분리는 2026년 대표적인 「가짜 성공」입니다. daemon 요약은 healthy인데 loopback probe가 타임아웃합니다. Windows에서는 provider 확장 기동 지연, Docker에서는 동일 compose 프로젝트 단일 reload 누락이 흔합니다. 티켓 템플릿에 「업그레이드 후 한 번 reload」를 넣고 launchd·수동 이중 18789를 피하십시오.
ACP를 쓰면 bridge 등록과 openclaw devices list를 6단계에 포함하십시오. 2026.3.x 알려진 회귀 기간에는 CLI device 스트림·Gateway 버전 불일치가 「모델 고장」처럼 보이나 host acpx는 정상일 수 있습니다. 본 글 증상표를 먼저 쓰고 모델·라우팅 변경은 후순위로 두십시오.
openclaw status openclaw gateway status openclaw gateway probe openclaw doctor # docker compose pull && docker compose up -d # docker compose restart <gateway-service> openclaw channels status --probe
| 증상 | 우선 의심 | 첫 조치 |
|---|---|---|
| probe 타임아웃, gateway status는 healthy | provider 플러그인 기동 지연, loopback 경합 | 문제 provider 일시 비활성, probe 전 대기 연장, Windows는 이전 patch |
| WebSocket 1006 closed before connect | Token/바인드/리버스 프록시 Upgrade 헤더 | 페어링·1006 런북, 먼저 프록시 제외 |
| ACP「queue owner unavailable」 | ACP bridge 등록 회귀(2026.3.x) | host acpx 확인, 이슈에 맞춰 고정 또는 minor 롤백 |
openclaw devices list 타임아웃 | CLI device 스트림·Gateway 버전 불일치 | CLI/Gateway 동일 버전 정렬, 필요 시 backup 복구 후 단계 업그레이드 |
| 채널 완전 무응답 | 채널/모델 층 | 무응답 전문 글로 이동, 본 글은 일시 중단 |
on-call은 「config 한 번 더」와 「즉시 롤백」 사이에서 흔들립니다. 아래 표로 빠르게 결정하고 결과를 티켓에 남겨 다음 당번이 같은 시행착오를 반복하지 않게 하십시오.
| 영향 범위 | 설정/플러그인 계속 | 버전 고정/롤백 | ACP·문제 provider 일시 중단 |
|---|---|---|---|
| probe만 적색, 업무 채널 정상 | 모니터링 잡음으로 기록, 기동 시간 개선 | SLA가 probe 녹색을 요구하면 patch 롤백 | 기동 지연 provider 비활성 |
| ACP 전단, 채팅 정상 | bridge 등록·플러그인 discovery 조사 | 알려진 회귀 기간 minor 롤백 | ACP 임시 off로 채널 SLA 우선 |
| probe+채널+도구 전단 | backup 복구 후 단계 시도만 | 우선 backup restore 또는 digest 롤백 | 1순위 아님 |
compose pull/up. 티켓당 한 단계만(beta→stable 건너뛰지 않음).분기마다 비프로덕션 트래픽 전용 원격 Mac에서 가벼운 테이블탑 연습을 권장합니다. digest A→B→A를 의도적으로 수행해 백업 복구·사다리 스크립트가 문서와 일치하는지 검증하십시오. 로그 tarball·compose SHA는 검색 가능한 티켓에 남겨 감사·타임존 당번 인수인계에 활용하십시오.
6개 지역 원격 Mac에서는 업그레이드 창을 안정성 수락·디스크 워터마크 점검과 병렬 계획하십시오. 피크에 이미지 pull+전량 probe를 겹치면 「네트워크 지터」를 「ACP 장애」로 오인하기 쉽습니다. 상시 전원·전용·티켓화 가능한 노드에서 업그레이드·수락을 끝내고 노트북은 SSH 포워딩만 쓰는 편이 안정적입니다.
채팅에서 「올라갔나요?」 한 번, YAML 몇 필드 수동 수정만으로는 감사·두 번째 머신 재현에 버티지 못합니다. backup create, 수락 사다리, ACP/probe 트리아지를 런북에 쓰면 「업그레이드 사고」는 밤샘 맹시도에서 백업·복귀점·지표가 있는 십여 분 사건으로 압축됩니다.
개인 노트북에서 최신 채널을 쫓으면 절전 유사 정지, probe·업무 경로 불일치, 전원 정책 충돌이라는 세 가지 숨은 비용을 감수해야 합니다. 7×24·Node 24 기선·변경 티켓화가 필요한 프로덕션 Gateway라면 MACCOME Mac mini(M4/M4 Pro)와 6개 지역 유연 리스에 올리는 편이 덮개 닫힌 노트북에서 probe 타임아웃과 싸우는 것보다 총소유비용에서 유리한 경우가 많습니다. 공개 요금은 다중 지역 노드·리스 가이드를 보고 토폴로지는 SSH 상시 런북으로 연결하십시오.
자주 묻는 질문
업그레이드 전 backup create에 Token이 포함됩니까?
보통 상태 트리의 인증·페어링 자료를 포함합니다. 기밀로 보관하고 복구 전 로테이션을 검토하십시오. 프로덕션 전용 노드 계획은 임대 요금을 참고하십시오.
gateway probe 실패인데 dashboard가 열리면 반드시 롤백합니까?
반드시 그렇지 않습니다. 증상표로 probe 타임아웃·1006·ACP 등록을 구분하고, 사다리 1–5가 두 번 연속 실패하며 업무 피해가 있을 때 digest 롤백으로 진행하십시오.
원격 Mac에서 업그레이드 창 시 주의점은?
빌드 피크·디스크 포화를 피하고, 백업은 전용 상태 디렉터리에 둡니다. 수락은 원격에서 probe를 실행하고 노트북은 포워딩만 합니다. 연결은 고객 센터를 보십시오.