OpenClaw 를 업그레이드한 뒤 어떤 종류의 문제인가요. gateway 가 기동하지 않거나, RPC 프로브가 실패하거나, CLI 는 새 버전인데 사용자 수준 systemd 서비스가 여전히 옛 경로를 가리키는지를 가늠해야 합니다. 본문은 운영 독자를 위해 먼저 일곱 가지 숨은 가정으로 split brain(신·구 바이너리 분기) 을 드러내고, 증상 표로 「설정에 찍힌 버전」 문제와 토큰·원격 URL 계열을 나눈 다음, 여섯 단계의 안전 복구 Runbook(PATH → gateway install --force → gateway restart → doctor)과 파괴적 환경 변수 게이트 를 언제 열지 설명합니다. 글 안에서는 cron 과 업그레이드 회귀, 원격 모드, 운영 관측 으로 역할을 나눕니다.
공식 트러블슈팅에 따르면, 더 새로운 OpenClaw 가 openclaw.json 을 쓰고 meta.lastTouchedVersion 같은 도장을 갱신했는데도 PATH 에서는 여전히 옛 openclaw 바이너리 가 잡히면 읽기는 될 수 있지만, 게이트웨이 서비스 설치·재시작·제거 같은 파괴적 변경 에서는 CLI 가 반절새 메타데이터를 디스크에 쓰지 않도록 거부합니다. 이것이 운영에서 말하는 split brain 에 가깝습니다.
「npm 이 성공했다」를 「서비스가 새 바이너리로 바뀌었다」와 동일시하기: npm install -g 는 전역 접두사 아래 실행 파일만 갱신합니다. launchd 나 systemd --user 유닛이 옛 절대 경로를 가리키면 재시작 후에도 그대로입니다.
로그인 셸 PATH 와 서비스 환경을 섞기: 대화형 which openclaw 가 맞다고 해서 데몬 환경 과 같다는 뜻은 아닙니다.
여러 설치원을 무시하기: Homebrew, 공식 설치 스크립트, npm 전역이 동시에 존재할 수 있으며 순서는 PATH 앞쪽이 결정합니다.
업그레이드 뒤 gateway install --force 를 건너뛰기: 공식은 바이너리가 어긋났을 때 서비스 포장을 다시 깔도록 권합니다. 수동으로 gateway 를 한 번 띄운 것만으로는 다음 재부팅에 또 갈라질 뇌관이 남습니다.
「doctor 오류는 전부 설정이 망가진 것」으로 치부하기: 때로는 바이너리와 설정 가드 불일치입니다. 키를 고치기 전에 버전을 맞춥니다.
원격 모드와 로컬 모드를 설정 캡처 없이 번갈아 시도하기: 원격 모드 글 과 같은 규율로, 먼저 openclaw config get gateway.mode 로 프로브 대상을 정합니다.
업그레이드 후 channels 만 보고 스케줄 면을 보지 않기: cron 과 Gateway 는 같은 계열입니다. 회귀는 cron 글 체크리스트를 읽습니다.
공통된 착오는 「설정을 읽을 수 있다」를 「실행 면이 일치한다」와 혼동하는 것입니다. 올바른 관점은, 설정 도장은 누가 파일을 마지막에 썼는지 를 보여 줄 뿐이고, 서비스를 실제로 돌리는 바이너리는 따로 증명해야 한다는 것입니다.
아래 표는 당직 메모를 「업그레이드가 망가진 느낌」에서 「서명할 수 있는 분기」로 옮기기 위한 것입니다.
| 신호 | split brain 에 가깝다 | 인증·세션에 가깝다 | 원격 URL·토폴로지에 가깝다 |
|---|---|---|---|
| doctor 키워드 | 신·구 바이너리 분기를 짚고 gateway 파괴 동작을 막는다 | 토큰·디바이스 오류 코드이며 바이너리 버전과 무관하다 | RPC 프로브가 실패하고 로컬 gateway status --deep 이 뜻밖의 호스트를 가리킨다 |
| gateway status | 런타임 동작이 CLI --version 과 뚜렷이 다르다 | 런타임은 정상인데 unauthorized 이다 | 로컬은 stopped 인데 원격에서 실제로 돌아간다 |
| 우선 조치 | PATH 맞추기 → gateway install --force → 재시작 | 토큰·디바이스 핸드셰이크를 교체하거나 맞춘다 | gateway.remote.url 과 환경 변수가 원격 모드 글 과 일치하는지 본다 |
업그레이드 밤의 황금 질문: (A) 어떤 바이너리가 도는가. (B) 어떤 도장이 누가 설정을 썼는가. 둘이 맞춰진 뒤에 채널과 cron 을 논한다.
Tailscale·사설 터널 과 함께 배포할 때 「터널이 연결됨」과 「RPC 가 정상」을 한데 묶지 마세요. Tailscale 사설 노출 글로 양 끝을 함께 검수합니다.
아래는 순서에 민감합니다. 한 단계에서 여전히 신·구가 어긋나면 설정과 바이너리를 동시에 만지지 말고 이전 단계로 돌아갑니다.
현장 고정: openclaw --version, 유닛에 보이는 바이너리 절대 경로, doctor 출력을 스크린샷으로 남깁니다.
PATH 와 별칭 수정: 비대화 세션에서도 which openclaw 가 의도한 업그레이드 빌드 를 가리키게 하고, 경로를 가리는 셸 별칭은 제거합니다.
설치원 단일화: 문서가 권하는 npm·설치 스크립트 등 하나의 유지 채널을 정하고, brew 와 npm 을 오래 섞지 않습니다.
서비스 포장 재설치: PATH 가 맞다는 것을 확인한 뒤 같은 사용자 로 openclaw gateway install --force 를 실행해 launchd/systemd 메타데이터를 갱신합니다.
Gateway 콜드 스타트: openclaw gateway restart 후 gateway status 와 RPC 프로브를 돌립니다.
회귀 체크: openclaw doctor → channels status --probe → cron list 등록이 기대대로인지 확인합니다.
openclaw --version command -v openclaw openclaw gateway status openclaw doctor openclaw gateway install --force openclaw gateway restart openclaw channels status --probe
안내: 로그에 포트 충돌, 메모리 스파이크, compose 기동 순서가 보이면 Gateway not ready 실무 와 closed(1000) RPC 를 함께 읽어 자원 계열 장애를 split brain 과 혼동하지 마세요.
공식 트러블슈팅은 「더 새로운 설정 + 더 오래된 바이너리」를 위험한 조합으로 봅니다. 오래된 프로세스가 게이트웨이 서비스 메타데이터를 바꿀 권한을 얻으면 디스크 상태가 되돌리기 어려운 혼합이 될 수 있습니다. 사용자를 보호하기 위해 새 OpenClaw 는 gateway 관련 파괴 작업에 단단한 문 을 둘 수 있습니다. 해당 OPENCLAW_* 환경 변수(이름과 의미는 해당 버전 공식 문서 기준)는 응급으로 옛 바이너리로 한 번 복구해야 할 때만 씁니다.
주의: 이런 스위치는 모든 검사를 건너뛰는 만능 스위치가 아닙니다. 위험을 이해하고 서비스 포장이 손상될 수 있음을 받아들이는 좁은 경우 용입니다. 문서에 롤백 항목이 없다면 기본값은 설정하지 않은 채로 둡니다.
유지보수에 유리한 방법은 보통 PATH 를 고치고 서비스를 다시 깔아 새 바이너리로 업그레이드를 끝내는 것입니다. 구 패키지 다운로드가 막힌 등 드문 경우에만 별도 변경 티켓에 다운그레이드 경로를 적고 감사용 사본을 남깁니다.
플랫폼 측에서 내부 정렬에 쓸 수 있는 정량적 앵커입니다.
openclaw --version 출력 스크린샷 을 남기고, 복구 후 완전히 같아야 합니다.doctor 정리 결과를 기록합니다.노트북이나 공유 개발기의 Gateway 는 절전, OS 업데이트, 다중 사용자와 충돌하기 쉽고, OpenClaw 를 7×24 상주·SSH 가능·디스크와 네트워크 전제를 계약에 적을 수 있는 전용 원격 Mac 에 두는 편이 반복되는 「업그레이드 뒤 다시 갈림」보다 장기적으로 낫습니다. NodeMini 클라우드 Mac Mini 렌탈 은 고정 SSH 와 단독 연산을 제공해 AI 게이트웨이와 사내 자동화 호스트에 맞습니다. 사양과 온보딩은 소형 렌탈 요금 과 도움말 센터 를 보세요. OpenClaw 실무 글은 블로그에서 OpenClaw 필터 로 모아 「관측 → cron → 원격 모드 → 본문 업그레이드 갈림」 순으로 읽으면 이해가 잇달아집니다.
「어떤 OpenClaw 빌드가 설정 파일을 마지막으로 썼는지」에 대한 버전 도장으로 보면 됩니다. PATH 가 여전히 더 오래된 바이너리를 가리키면 「서비스 메타데이터에 쓰기를 거부한다」 같은 보호적 동작이 나옵니다. PATH를 바로잡고 Runbook 대로 서비스를 재설치한 뒤 doctor 를 다시 보통 JSON 을 한 줄씩 고치기 전에 봅니다.
split brain 이 배제되기 전에는 cron 목록은 「정상처럼」 보여도 실행 층이 거부할 수 있습니다. 먼저 본문 제3절을 마친 뒤 cron 안내서 로 주기 회귀를 합니다. 더 많은 글은 OpenClaw 필터 에서 확인하세요.