gateway.token에서 gateway.auth.token으로 옮겼고, 대화형 셸의 새 전역 openclaw와 launchd가 가리키는 오래된 프리픽스가 어긋나거나, gateway.bind를 lan으로 넓혔는데 인증이 따라오지 않아 게이트웨이가 리슨을 거부하는 패턴이 흔합니다. 본문은 업그레이드 전 스냅샷, openclaw doctor와 openclaw gateway status --deep의 규율 있는 순서, 이중 바이너리 복구, 포트 18789에 대한 재현 가능한 ssh -L과 Tailscale, gateway install --force의 실제 범위를 한 장의 런북으로 묶습니다. 설치 체크리스트와 24시간 안정 운용 글과 함께 읽으면 도입·업그레이드·상주 루프가 닫힙니다.2026년 업그레이드 후 다섯 가지 실패: 먼저 모델을 탓하지 않습니다
최근 OpenClaw 빌드는 로컬 게이트웨이 바인드와 인증 가드를 강화했습니다. gateway.bind가 루프백에서 벗어났는데 유효한 gateway.auth.token이 없으면 기동이 빨리 실패합니다. 대화형 셸에서는 새 전역 openclaw가 잡히는데 launchd가 오래된 프리픽스를 가리키면 doctor는 깨끗해 보이나 RPC 프로브만 실패하는 전형적인 분열이 됩니다. 세 번째 패턴은 폐지 예정인 gateway.token 키만 남아 새 스키마가 무시하고 대시보드가 401을 반복하는 경우입니다. 네 번째는 상태 디렉터리를 엔터프라이즈 동기화나 네트워크 홈 아래에 두어 업그레이드 쓰기와 데몬 읽기가 경쟁하는 경우입니다. 다섯 번째는 애플리케이션 계층 인증이 끝나기 전에 18789를 인터넷 쪽 인터페이스에 노출해 스캐너 소음과 모델 타임아웃 오진을 부르는 경우입니다.
아래 다섯 체크포인트는 순서를 강제합니다. 온도나 API 키를 건드리기 전에 버전과 파일을 고정합니다. 첫 부팅 온보딩이 끝나지 않았다면 설치 체크리스트를 먼저 마친 뒤 업그레이드 전용 경로로 돌아옵니다.
키 드리프트: npm은 올랐으나 gateway.auth.token이 plist에서 보이는 프로필에 도달하지 않아 대시보드와 CLI가 다른 조각을 읽습니다.
이중 바이너리: which openclaw와 plist 첫 ProgramArguments가 다릅니다. 새 필드는 한쪽에만 적용됩니다.
불완전한 바인드와 인증 쌍: lan인데 토큰이 없어 게이트웨이가 종료합니다. 로그에 바인드 거부 서명이 자주 보입니다.
포트 표에 소유자 없음: 18789가 디버그 잔재에 잡혀 정리 전까지 EADDRINUSE가 남습니다.
날 인터넷 노출: 터널이나 에지 ACL 전에 신뢰할 수 없는 인터페이스에서 리슨하면 무의미한 재시도가 늘어납니다.
업그레이드는 바이너리·plist 메타데이터·설정 파일을 맞추는 정렬 문제로 다룬 뒤 터널 대 제어된 바인드 전략을 고릅니다.
환경 상속 함정도 있습니다. launchd 작업은 편의를 위해 셸 프로필에 넣은 export를 자동으로 가져오지 않습니다. 대화 세션에서 토큰을 만들고 셸 rc에만 적으면 데몬은 영원히 보지 못합니다. 서비스가 이미 읽는 설정에 비밀을 두거나 패키지가 지원하는 env-file 훅을 쓰고, 재시작 후 doctor로 서비스 측 시야를 확인하는 것이 견고한 패턴입니다. 변경 티켓에는 plist 라벨 옆에 기대하는 CLI의 SHA나 시맨틱 버전을 적어 다음 업그레이드에서 사람 실행과 감독 실행의 간격이 조용히 벌어지지 않게 합니다.
여러 엔지니어가 한 대의 클라우드 Mac을 실험용으로 공유하면 짧은 로테이션 메모를 런북에 붙입니다. 누가 마지막으로 force를 돌렸는지, 어떤 프로필이 게이트웨이를 소유하는지, 임시 바인드 변경을 되돌렸는지입니다. 공유 호스트는 각자 자신의 PATH를 보편이라 가정해 분열이 증폭됩니다. 바이너리·plist 라벨·리슨 주소에 대한 권위 있는 표가 하나 있으면 금요 밤 추측이 줄어듭니다.
클라우드 이미지를 다시 굽는 CI가 있다면 빌드 후 비대화형 doctor 스모크를 넣어 정의한 경고 임계를 넘으면 파이프라인을 실패시키는 편이 값이 큽니다. 업그레이드 퇴행을 왼쪽으로 옮깁니다. 스모크 산출물은 이미지 버전 문자열 옆에 두어 화요와 목요 빌드 차이를 SSH 고고학 없이 비교합니다. 하트비트와 관측은 24시간 안정 글의 절과 맞추면 설치 런북과 충돌하지 않습니다.
비교: 루프백만, LAN+토큰, 터널된 대시보드 접속
클라우드 Mac에서는 기본 자세가 루프백에 SSH 로컬 포워딩이나 ACL이 빡센 Tailnet을 얹는 것입니다. 18789를 공인 인터페이스에 직접 바인딩하는 위협 모델과 다릅니다. 런북 첫 장에 표를 두면 당번이 바인드 변경을 즉흥으로 논쟁하지 않습니다.
| 모드 | 적합 | 전제 | 날카로운 모서리 |
|---|---|---|---|
| loopback | 단일 엔지니어 SSH와 로컬 브라우저 | 가장 단순한 기본값. 토큰은 선택 | 인터넷 헬스체크는 터널 없이는 실패 |
| lan + token | 고정 RFC1918 대역 내부 프로브 | gateway.auth.token과 최소 방화벽 구멍 | plist 환경에 토큰이 없으면 서비스가 빈손 |
| SSH -L / Tailscale | 제로트러스트 에지 너머 운용 | SSH 키 로테이션과 MagicDNS 계획 | 로컬 포트 충돌. 수면 후 재연결 스크립트 |
| 신호 | 정상일 때 의미 | 나쁠 때 먼저 의심 |
|---|---|---|
openclaw doctor | 스키마·토큰·포트·슈퍼바이저 일관성 | 레거시 키, PATH, 동기 잠금 |
openclaw gateway status | 런타임과 RPC 프로브 요약 | 프로세스는 살아 있으나 RPC 죽음, 토큰 드리프트 |
openclaw gateway status --deep | 중복 설치와 사용자 대 시스템 유닛 힌트 | 이중 launchd 작업, 오래된 plist |
누가 실행하고 어떤 설정이 로드되고 어떤 주소가 리슨하는지를 터널 전에 맞추지 않으면 불일치를 더 많은 노트북으로만 퍼뜨립니다.
상류 트러블슈팅은 openclaw status, openclaw gateway status, openclaw logs --follow, openclaw doctor로 시작합니다. 클라우드 이미지에서는 골든 이미지 갱신 후 Node와 plist 기대가 맞는지도 기록합니다.
Tailscale과 SSH 터널은 운용 비용이 다릅니다. Tailscale은 소규모 팀에 per-host SSH 플래그를 덜 기억하게 하는 DNS 이름과 ACL을 주지만 패치와 감사의 또 다른 의존 사슬을 늘립니다. SSH 포트 포워딩은 지루해서 컴플라이언스가 움직이는 부품을 최소화할 때 유리합니다. 둘을 합치는 팀도 있습니다. Tailscale로 도달성, 게이트웨이는 루프백 바인드, ACL로 업그레이드 중 LAN 바인드 사고를 막습니다. 터널이 내려갔을 때의 성능 저하도 문서화하고 에이전트가 죽은 소켓을 두드리지 않게 합니다.
용량 계획도 중요합니다. OpenClaw를 올려도 거대 툴체인의 메모리 압은 사라지지 않습니다. 로그에 OOM이 게이트웨이 재시작 옆에 있으면 인증 실패와 별 티켓으로 잡습니다. 이 사이트의 스토리지·메모리 글은 M4 Pro 여유가 안정에 도움이 되는지 감독 메타데이터 정리만으로 되는지 판단하는 재료가 됩니다.
MagicDNS 이름해석과 사내 CA 신뢰사슬이 어긋나면 브라우저만 이상해 보일 수 있습니다. 그때도 먼저 게이트웨이 본체의 루프백 연결을 자르고 터널 쪽 포트 충돌을 봅니다. 순서를 거꾸로 하면 반나절이 갑니다.
토큰 이전과 분열: 감독자가 편집한 것을 읽게 만들기
~/.openclaw/openclaw.json에 gateway.auth.token이 있는데도 대시보드가 401이면 열 번째 토큰을 발급할 단계가 아닙니다. launchd 작업 디렉터리와 OPENCLAW_STATE_DIR이 대화형 셸과 일치하는지 확인합니다. 일부 클라우드 이미지는 자동화 사용자와 로그인 사용자로 홈을 나누고 plist가 다른 계정을 가리키면 cat으로는 토큰이 보이나 서비스에는 없는 착시가 납니다.
doctor가 새 설정을 오래된 바이너리가 건드렸다고 하면 먼저 PATH를 고치고 의도한 설치에서 슈퍼바이저 메타데이터를 다시 깝니다. 오래된 바이너리가 아직 감독 중일 때 config set을 연타하면 메타 버전 가드가 UI 피드백 없이 변이를 막을 수 있습니다.
openclaw doctor openclaw config get gateway.auth.token openclaw gateway status --deep openclaw gateway install --force openclaw gateway restart
참고: 변경 창에서는 openclaw.json, plist 라벨, openclaw --version 출력을 세트로 스냅샷하고 단일 파일 복원이 아니라 세트로 롤백합니다.
인수인계에서는 위 네 명령 출력을 24시간 안정 글의 heartbeat 절 옆에 붙여 야간 근무가 포트 조정 채팅 전승에 의존하지 않게 합니다.
이미지를 굽는 CI가 있다면 빌드 후 비대화형 doctor를 돌리고 정의한 경고 한계를 넘으면 파이프라인을 실패시키는 스모크를 추가합니다. 업그레이드 퇴행을 저렴한 단계로 옮깁니다.
루프백 건전성에서 안전한 원격 18789까지 여섯 재현 단계
서버에서 루프백이 이미 동작한다고 가정합니다. 그렇지 않으면 온보딩과 데몬은 설치 체크리스트로 돌아갑니다. 네트워크 실수가 인증 실패로 가장되지 않게 한 뒤 원격 경로를 추가합니다.
로컬 증명: 호스트에서 http://127.0.0.1:18789/ 또는 문서의 헬스 경로에 curl을 걸고 HTTP 코드를 기록합니다.
경로 선택: 단일 노트북 접근은 ssh -L 18789:127.0.0.1:18789 user@cloud-mac을 선호합니다. 넓은 팀은 Tailscale과 ACL을 평가합니다.
충돌 해소: 로컬 18789가 잡혀 있으면 ssh -L 19000:127.0.0.1:18789로 높은 로컬 포트로 봅니다.
토큰 정렬: 터널에도 브라우저에는 게이트웨이 토큰이 전달됩니다. 값은 금고에 두고 채팅에 붙이지 않습니다.
끊김 계획: autossh 등으로 무인 작업이 게이트웨이 소실을 가정하지 않게 합니다.
티켓 작성: 바인드 모드, 터널 명령, 포트 소유자를 리전과 SKU와 같은 변경 기록에 담고 조달은 감사 가능한 주문 흐름으로 보냅니다.
세 가지 프로덕션 게이트와 gateway install --force가 정당한 때
버전 스탬프 일치: meta.lastTouchedVersion와 openclaw --version이 함께 움직입니다. 의도적 다운그레이드는 별 정책이지 조용한 force 남용이 아닙니다.
단일 감독 원천: 호스트당 기본은 사용자 수준 게이트웨이 유닛 하나입니다. deep에 중복이 보이면 여분을 끄고 force 전에 정리합니다.
force 경계: plist 포트가 살 설정과 다르거나 doctor가 명시적으로 슈퍼바이저 갱신을 요청할 때입니다. 비밀 로테이션이나 보안 그룹 검토 대체가 아닙니다.
경고: 로그와 doctor를 읽기 전에 force를 연타하면 단순 포트 충돌이 재시작 루프로 바뀌어 장애 창이 넓어집니다.
동료 노트북을 게이트웨이 호스트로 빌리는 것보다 KVMNODE 클라우드 Mac에 OpenClaw를 고정하면 바이너리 경로·plist 라벨·토큰·터널 명령을 한 변경 기록에 모으기 쉽습니다. 노트북은 수면과 OS 업그레이드로 시간을 잃습니다. 관측성·업그레이드 롤백·갱신을 주간 리뷰에 문서화해야 하는 팀에게는 여러 메트로에서 고를 수 있는 전용 베어메탈이 흩어진 하드웨어보다 실행하기 쉬운 경우가 많습니다. 선택한 리전에서 단기 렌트로 업그레이드와 터널을 검증하고 가격 페이지와 도움말 센터로 M4 Pro와 장기를 정한 뒤 주문 페이지로 용량을 잡는 흐름이 릴리스 밤 채팅 요청보다 추적하기 좋습니다.