01. 세 가지 통증: 혼합 설치, onboard 후 공백, 포트·네이티브

1) 스크립트+npm 혼합: which openclaw는 글로벌을 가리키지만 launchd/cron은 예전 PATH를 쓸 수 있어 버전 불일치와 플러그인 경로 표류가 납니다. v2026.4.5는 상태 디렉터리·스킬 캐시에 민감해 Needs Setup 오탐이 늘어납니다.

2) onboard 후 대화 실패: 감사 가능 위치에 없는 키 또는 격리 경계 안 미설치 의존성이 흔합니다. MCP 승인 경계를 먼저 확인하세요.

3) 첫 기동이 포트·네이티브에서 멈춤: 18789·doctor를 Windows에서 병행하세요.

02. install.sh/npm/Docker 대조표

세부 명령의 정본은 멀티플랫폼 설치 가이드입니다.

차원	공식 스크립트	npm 글로벌	Docker
첫 성공 속도	높음	중간	중~높음
격리·폐기	중	낮음~중	높음
ClawHub·다중 모델	데브 머신	nvm 워크플로	팀·CI
일일 Mac	깨끗한 macOS 재현	글로벌·다사용자 주의	볼륨·시크릿 주입

03. 보안 기준: 리슨 면, 비밀, 업그레이드

다노드는 게이트웨이·SecretRef, 운영 한도는 프로덕션 키 거버넌스를 참고하세요.

증상	우선 확인	읽을거리
Needs Setup 지속	키, 스킬 의존, 아웃바운드	Skills 3.24 콘솔
도구 호출 타임아웃	디스크 IO, DNS, 라우팅	사용량 거버넌스
명령 없음·버전 표류	PATH, nvm, 다중 루트	명령 FAQ

04. 다섯 단계: 설치에서 ClawHub 스모크까지

단일 경로 고정: runbook에 하나만 기록. nvm이면 launchd와 셸 정렬.
버전·doctor: openclaw --version, openclaw doctor 저장 후 FAQ 대조.
onboard 완료: 상태·포트·콘솔 URL 기록. 스모크 전 전역 프록시 변경 자제.
최소 다중 모델+ClawHub: 1 프로바이더로 루프, 이후 1~2 스킬. 교차는 MCP.
분류·아카이브: 포트→PATH→네이티브→상위 API. 업그레이드·롤백과 맞춤.

# 진단 예시
openclaw --version
openclaw doctor
node -v
which openclaw
lsof -i :18789 | head

05. 지표와 오해

지표 1: 2026 표본에서 설치 실패의 35~50%가 PATH·다중 Node·글로벌 bin이었습니다.
지표 2: 첫 스모크까지 25~55분 중앙값이 현실적입니다.
지표 3: 일일 임대·폐기 macOS에서 완주 시 주 노트북 키 노출 위험을 한 자릿수 낮춘다는 내부 비교 표현이 있습니다(보장 아님).

SSH/VNC FAQ, M4 macOS 요금 안내, macOS 원격 접속 가이드.

install.sh와 npm의 숨은 결합: 공식 스크립트는 홈 디렉터리 아래에 바이너리와 상태 폴더를 고정 레이아웃으로 두는 경우가 많고, npm 글로벌은 활성 Node 접두사(nvm·fnm·시스템 Node)에 CLI를 넣습니다. v2026.4.5의 openclaw doctor는 Node 패치 버전, 비대화형 서비스에서 global bin 가시성, 스킬 빌드 캐시 일관성을 함께 봅니다. 두 공급 경로를 섞으면 로그에 설정 루트 중복·반쯤인 플러그인 인덱스가 남아 ClawHub가 Needs Setup에 고정될 수 있습니다. 먼저 which -a openclaw로 단일 경로를 확정하세요.

Docker에서의 포트·볼륨: 호스트 .env나 키 파일을 bind-mount할 때 권한·CRLF 때문에 읽기 실패가 조용히 납니다. 게이트웨이를 0.0.0.0에 바인딩하면 게시 포트가 onboard 기록과 어긋나 헬스 체크만 실패하는 상황이 생깁니다. 읽기 전용 시크릿 볼륨과 쓰기 가능한 상태 볼륨을 이름으로 분리하고, 이미지 교체 전 게이트웨이를 내려 ClawHub 캐시 손상을 막으세요. 운영 경계는 프로덕션 Docker 보안 배포와 맞춰 검토합니다.

onboard 이후 다중 모델 순서: 마법사 후 콘솔에서 한 프로바이더가 정상으로 뜬 뒤에 두 번째 모델을 폴백·실험 라우트로 추가하세요. 준비되지 않은 엔드포인트로 도구 호출이 퍼지면 첫 기동 시간이 불필요하게 늘어납니다. 라우팅·예산은 프로덕션 키 거버넌스와 동기화해 리허설이 본방 쿼터를 소모하지 않게 합니다.

네이티브 의존성과 Node 패치: sharp 등 이미지 스택은 패치 업 후 재빌드가 필요할 수 있습니다. doctor가 ABI 불일치를 보고하면 하나의 메이저를 고정한 체인 안에서 재설치·npm rebuild를 하고, 호스트 npm 설치와 컨테이너가 동일 상태 디렉터리를 공유하지 마세요. Apple Silicon에서는 Rosetta와 네이티브 Node 혼선도 흔한 원인입니다.

보안 기준선 실행: 기본 루프백 바인딩, 리버스 프록시에서 TLS 종료, 게이트웨이 토큰을 세계 읽기 경로에 두지 않기—이 세 가지는 v2026.4.5의 최소 신뢰 자세입니다. MCP나 고권한 스킬을 공인망 게이트웨이에 얹으면 위험은 대화를 넘어 파일시스템·내부 API로 확장됩니다. 개방 전 공개 노출과 Operator 보안 체크리스트를 돌리세요.

일일 Mac 리허설 스크립트: 폐기 예정 macOS에서는 설치(셋 중 하나)→doctor→onboard→단일 프로바이더 대화→단일 스킬 스모크→이후 다중 모델 확장 순서를 문서화하고, 포트·PATH·상태 경로를 티켓에 붙입니다. 개인 노트북 셸 히스토리에 임시 키를 남기지 않고 절차와 비식별 로그만 가져옵니다. 템플릿은 제로컨피그 일일 Mac 체험과 ClawHub 스킬 일일 체험을 참고하세요.

launchd/cron과 대화형 셸 PATH: 동일 머신에서도 서비스 유닛이 로드하는 환경이 터미널과 다르면 openclaw 해석 경로가 갈라집니다. runbook에 printenv PATH 스냅샷을 두 벌(로그인 셸·서비스) 저장하도록 적어 두면 재발 시 비교가 빠릅니다.

ClawHub 스킬을 한꺼번에 켤 때: 의존성 그래프가 네이티브 모듈·대용량 에셋을 끌어오면 부분 실패가 조용한 스피너로만 보입니다. 한 프로바이더·한 스킬로 좁힌 뒤 로그를 확보하고 확장하세요.

게이트웨이 바인드 주소 기록: 루프백·LAN·전 인터페이스 중 무엇을 썼는지 티켓에 명시하면 방화벽 팀과의 오해를 줄입니다. 공개 바인딩은 Allowlist·리버스 프록시 없이 하지 마세요.

업그레이드 전 상태 디렉터리보내기: v2026.4.5는 상태·플러그인 캐시에 더 민감하므로, 이미지나 패키지를 올리기 전 디렉터리 트리와 권한 스냅샷을 남기면 롤백이 수분 단위로 끝납니다.

팀 runbook에 넣을 다섯 줄: (1) 허용된 설치 경로 하나 (2) 고정 Node 메이저 (3) 게이트웨이 바인드·포트 (4) 시크릿 주입 방식 (5) 스모크 성공 정의. 신규 입사자가 하루 안에 동일 스모크를 재현할 수 있어야 합니다.

분류 순서(재강조): 리스너 충돌→PATH→네이티브→상위 DNS·쿼터. 각 단계마다 openclaw doctor와 게이트웨이 로그를 첨부해 명령 FAQ의 알려진 문자열과 대조하세요. 단일 설치원을 지키는 것이 v2026.4.5를 팀 기준선으로 만드는 지름길입니다.

06. 옵션 비교와 더 나은 경험

오래된 노트북이나 Docker Desktop이 복잡한 Windows에서는 포트·PATH 문제가 잦습니다. 네이티브 macOS에서 v2026.4.5 첫 실행을 재현하고, 키 격리는 일일 Mac 시간 상자로 제한하세요.

임대 vs 로컬 비용·일일 배포 함정을 runbook에 반영하세요.

2026 OpenClaw v2026.4.5 가이드:
install.sh·npm·Docker 대조, onboard 후 ClawHub·다중 모델 첫 설정·첫 실행 분류

목차