2026년 OpenClaw 업데이트: CLI·게이트웨이 버전 불일치 — npm 전역과 ~/.openclaw/lib 이중 스택 동기화, LaunchAgent 재시작·원격 Mac SSH에서의 openclaw doctor — 재현 가능 체크리스트 + FAQ
OpenClaw를 업데이트한 뒤에는 CLI가 새 시맨틱 버전을 보여도 게이트웨이 프로세스가 예전 빌드를 계속 돌리는 경우가 많습니다. 원인은 npm -g로 깔린 전역 CLI와 ~/.openclaw/lib 아래 번들 트리가 어긋났는데, launchd가 오래된 바이너리를 붙잡고 있기 때문입니다. 이 글에서는 전용 원격 Mac에서 이중 스택 동기화 순서, LaunchAgent 재시작 패턴, openclaw doctor 복구를 SSH로 재현할 수 있게 정리합니다. 긴 대화형 복구 세션은 2026년 원격 Mac CI: SSH ControlMaster 다중화와 tmux 지속 세션 — 자체 호스팅 Runner 장기 잡 안정성 비교·끊김 복구 의사결정 매트릭스+FAQ를, SSH 자동화 전반은 2026년 OpenClaw & SSH 자동화 심층 실전: 함정 회피·안정적 백그라운드 실행·보안 배포와 함께 보시면 좋습니다.
1. TL;DR — 「버전 불일치」가 의미하는 것
설치 표면이 둘: npm install -g openclaw(또는 사용 중인 패키지 매니저)로 깔린 전역 CLI 심과, ~/.openclaw/lib(또는 설치 문서에 나온 경로) 아래 런타임 라이브러리·게이트웨이 페이로드입니다. 둘 중 하나만 올리면 프로토콜·설정 스키마·플러그인 ABI가 어긋날 수 있습니다.
오래 사는 프로세스 하나: 게이트웨이는 보통 LaunchAgent plist로 뜹니다. 대화형 셸에서 새 openclaw를 바로 보는 것과 달리, 서비스를 재시작하기 전까지는 새 파일을 반영하지 않습니다.
doctor 먼저, 그다음 재시작: openclaw doctor로 경로·권한·환경 힌트를 고친 뒤, 리스너와 워커가 같은 버전 라인을 쓰도록 LaunchAgent를 정해진 순서로 재기동합니다.
2. npm 전역과 ~/.openclaw/lib이 어긋나는 이유
2026년에 자주 보이는 패턴입니다.
- 부분 업그레이드:
npm update -g openclaw는 됐는데, 예전에 풀 앱 번들을~/.openclaw/lib에 풀어 둔 트리가 원자적으로 바뀌지 않았습니다. - Node/npm prefix가 여러 개: SSH 세션은 nvm/fnm 경로를 쓰는데
launchd는 최소PATH만 물려 받아 예전 Node나 예전 래퍼를 호출합니다. - 사용자 vs 데몬 정체성: LaunchAgent는 로그인 사용자로 돌지만, 다른 사용자나
sudo로 설치했다면~/.openclaw소유권 때문에 덮어쓰기가 막힐 수 있습니다. - 수동 복사: 지원되는 설치 경로 없이 개발기에서 바이너리나 심볼릭 링크를
lib로 복사한 경우.
3. 기준 상태 확립(SSH, 변경 전)
LaunchAgent를 소유한 사용자(보통 CI·운영 계정)와 동일한 권한으로 실행합니다.
which openclaw와openclaw version(또는 릴리스 노트에 따른openclaw --version).- npm 경로라면
npm list -g openclaw --depth=0. ~/.openclaw/lib수정 시각 확인:ls -lt ~/.openclaw/lib | head.- 게이트웨이 빌드: 문서화된 version 또는 health 엔드포인트를 호출하거나,
ps·로그로 프로세스 커맨드 라인을 읽어 릴리스 노트와 대조합니다. launchctl list | grep -i openclaw(레이블은 plist 이름에 맞게 조정).
4. 이중 스택 동기화: 권장 순서
표면을 한 유지보수 창 안에서 맞춥니다.
- 소비자 중지: 트래픽을 멈추거나 점검 모드로 전환해 게이트웨이가 스왑 도중 스트림 중간에 있지 않게 합니다.
- 지원되는 방식으로 업그레이드: 공식 문서대로 — 흔히
npm install -g openclaw@latest와~/.openclaw/lib를 갱신하는 설치 후 단계(일부 릴리스는openclaw install또는 번들 스크립트)를 함께 수행합니다. - 디스크 확인: 홈이 있는 볼륨에서
df -h— 압축 해제 실패 시 쓰다 만 트리가 남습니다. - doctor 실행:
openclaw doctor후 출력된 수정(경로·권한·누락 디렉터리)을 적용합니다. - LaunchAgent 재시작: unload/bootstrap 또는 게이트웨이 레이블에
kickstart -k. Mac 에이전트와 게이트웨이 plist를 나눠 쓰면 의존 순서대로(게이트웨이 먼저, 그다음 연결 워커) 재시작합니다. - 버전 재확인: CLI·디스크 lib 타임스탬프·게이트웨이 health/version이 일치해야 합니다.
5. LaunchAgent 재시작 — 재현 가능한 패턴
대화형 Mac의 GUI 사용자 에이전트 도메인: gui/$(id -u). ai.openclaw.gateway는 예시이며, 실제 레이블은 plist에 맞게 바꿉니다.
- 정상 재시작: 이미 로드된 작업이면
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway. - plist 수정 후 전체 리로드:
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist다음launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist. - 확인:
launchctl print gui/$(id -u)/ai.openclaw.gateway로 마지막 종료 상태가 깨끗한지 보고, stdout/stderr 로그를 tail합니다.
CLI 셸만 다시 띄우면 게이트웨이는 갱신되지 않습니다 — SSH 전용 호스트에서 가장 흔한 거짓 「해결」입니다.
6. openclaw doctor — 원격에서 기대할 것
openclaw doctor는 Node 최소 버전, 쓰기 가능한 설정 디렉터리, 게이트웨이 연결, 플러그인 경로 등을 점검하는 자동 일관성 패스입니다. SSH에서는 다음을 권장합니다.
launchd환경과 맞는 로그인 셸에서 실행하거나, plistEnvironmentVariables와 동일한PATH·OPENCLAW_*를 명시적으로 export합니다.- doctor가
~/.openclaw아래 권한 수정을 제안하면 적용한 뒤 에이전트를 재시작합니다 — doctor가 항상 서비스를 대신 재시작하진 않습니다. - 감사를 위해 stdout을
~/Library/Logs/OpenClaw/아래 파일로 리다이렉트해 공유 CI 머신에 기록을 남깁니다.
7. 증상 → 원인(요약 표)
| 증상 | 가능한 원인 | 첫 조치 |
|---|---|---|
| CLI는 새 버전인데 API 호출이 거절되거나 스키마 오류 | 게이트웨이가 예전 빌드 | lib 동기화 후 LaunchAgent 재시작, health 엔드포인트로 검증 |
cron/launchd에서는 openclaw를 못 찾는데 SSH에서는 됨 |
PATH 불일치 |
plist에 전체 경로 설정 또는 /usr/local/bin 등으로 심링크 |
~/.openclaw 아래 쓰기 거부 |
root/사용자 설치 혼합 | 에이전트 사용자로 chown -R 후 doctor 재실행 |
| 업그레이드 뒤 간헐적 「잘못된 프로토콜」 | 서로 다른 포트의 게이트웨이 둘 또는 남은 자식 프로세스 | pgrep -lf openclaw로 확인 후 불필요 PID 종료, 리스너 하나만 유지 |
8. 한 페이지 SSH 재현 체크리스트
- LaunchAgent 사용자로 SSH,
whoami/id확인. - 변경 전 상태 기록: CLI 버전, npm 전역,
~/.openclaw/libmtime, health/로그에서 본 게이트웨이 버전. - 지원되는 업그레이드 + lib 갱신 수행.
openclaw doctor→ 수정 적용.- 게이트웨이 LaunchAgent 재시작, 리스너 하나인지 확인(
lsof -nP -iTCP -sTCP:LISTEN). - 변경 후: 버전 일치, 게이트웨이를 치는 CLI 명령 하나로 스모크 테스트.
- 로그 발췌와 타임스탬프를 런북에 남기고, 긴 SSH 단계는 ControlMaster 또는 tmux와 묶어 운영자 경험을 정리합니다.
9. FAQ
| 질문 | 짧은 답 |
|---|---|
~/.openclaw/lib를 직접 지워도 될까요? |
문서에 있을 때만 — 설치 프로그램·doctor를 선호하고, 맹목적 삭제는 플러그인을 깨뜨립니다. |
brew와 npm 중 무엇이 맞나요? |
호스트당 지원 경로 하나만 — 패키지 매니저를 섞으면 이중 스택 드리프트의 시작입니다. |
| doctor는 통과하는데 게이트웨이는 예전 그대로 | 프로세스가 재시작되지 않음 — kickstart -k 또는 bootout/bootstrap. |
| CI에서 SSH로만 올려도 되나요? | 같은 사용자·환경이면 가능 — 점검 창을 잡고 이후 리스너를 검증하세요. |
OpenClaw 게이트웨이에 Mac mini가 잘 맞는 이유
버전을 맞추기 쉬운 환경은 기계가 조용하고 상시 가동이며 단일하게 정의된 사용자 공간을 쓸 때입니다. Apple Silicon Mac mini는 백그라운드 게이트웨이와 로그 부하 작업에 와트당 성능이 좋고, 유휴 전력이 매우 낮아 랙 소음 없이 24시간 에이전트를 돌리기에 적합합니다.
macOS는 네이티브 launchd, 예측 가능한 POSIX 의미, 헤드리스 복구에 강한 SSH를 한 번에 제공합니다. Gatekeeper와 SIP는 「버전 불일치」로 위장한 바이너리 변조 위험을 줄이고, M 시리즈 통합 메모리는 CLI·게이트웨이·CI 작업을 동시에 돌릴 때도 응답성을 유지합니다.
안정적인 업그레이드와 doctor 기반 복구가 필요한 전용 원격 Mac에 OpenClaw를 올릴 팀이라면 Mac mini M4는 작고 비용 대비 좋은 기반입니다. 이 체크리스트를 방해 없이 돌릴 하드웨어를 찾는다면 실용적인 출발점입니다.
SSHMac 홈에서 요금제를 확인하고, 게이트웨이 동시성·보존 요구에 맞춰 CPU·RAM·스토리지를 고르세요.