2026 OpenClaw: 공식 설치 스크립트와 npm 전역 경로(pin, 프록시 폴백)

2026년, 종료 코드 0인데도 OpenClaw 설치가 깨질 수 있는 이유

공식 설치기는 Node를 감지하고 부트스트랩을 받아 전역 CLI를 등록하지만, 비대화형 셸과기업 TLS에서는 “성공”이 다운로드 직전에서 멈출 수 있다. 바이너리는 사용자 프리픽스에 놓이는데 CI 서비스 계정 PATH에는 없다. npm 전역은 설치됐는데 로그인 셸이 아니면 rc를 건너뛰어 PATH가 비어 보인다. 아래는 자주 나는 여섯 가지 오독이다.

1. 문서화된 Node 메이저 하한을 무시: 오래된 LTS도 일부 명령은 돌아가지만 Gateway 시작에서 실패한다. node -v를 공식 요구 표와 맞추고 “npm이 돈다”로 충분하다고 보지 않는다.
2. 스크립트 트랙과 npm 트랙 소스를 섞음: 둘 다 실행하면 which openclaw가 다른 프리픽스를 가리킨다. 설정을 보기 전에 해석 경로를 항상 출력한다.
3. 프록시는 레지스트리는 허용하지만 스크립트 호스트는 차단: curl을 반복해도 잘 나아지지 않는다. 트랙을 바꾸고 보안 검토 후 HTTPS_PROXY, npm config set cafile, 내부 레지스트리 미러를 쓴다.
4. Windows 실행 정책과 프로필 공백: PowerShell은 성공해도 세션에 npm 전역 bin이 없다. 또는 정책이 서명 없는 원격 스크립트를 막는다. 조직 승인 래퍼나 npm으로 수렴한다.
5. pin과 변경 기록 없음: 모두 @latest를 쓰면 Gateway 동작이 밤새 드리프트한다. Gateway 무응답 분기 글의 “채널은 정상처럼 보임” 사례와 상관되기 쉽다.
6. 지문 채취 전에 온보딩으로 점프: 원격 Mac에서는 설치 사용자와 데몬 사용자가 어긋나 “설치됐는데 HOME이 다름”이 된다. systemd·launchd와 Docker 프로덕션 런북 전에 이 글의 검사로 맞춘다.

트랙 선택은 세 플랫폼 가이드의 토폴로지에 묶는다. 대화형 개발은 스크립트 빠른 길, 무인 빌더는pin 친화적 npm 또는 내부 아티팩트로 Node와 CLI 버전을 변경 티켓에 적는다.

표준이 pnpm·corepack이어도 규칙은 같다.감사 가능한 진입점만 쓰고 systemd·launchd의 Environment를 대화형 셸과 맞춘다. 공개 문서는 latest인데 베이스라인은 semver로 pin한다면 이주를 문서화한다.

한 호스트에 여러 Node 프로젝트가 있으면 OpenClaw 런타임 메이저를 앱 런타임에서 분리해 업그레이드 연쇄를 막는다. 멀티 프로젝트 풀 글과 같은 사고를 Node에 적용한다.

매트릭스: 공식 스크립트 트랙 vs npm 전역 트랙

스크립트 호스트 도달성, 감사 필요성, 무인 운영으로 채점한다. 취향으로 결정하지 않는다.

실행 스니펫: 설치 직후 세 줄 지문

출력을 티켓이나 위키에 붙인다. 원격 Mac에서는 최종 데몬과같은 로그인 맥락에서 실행한다.

여섯 단계 런북: “설치됨”에서 롤백 가능한 베이스라인으로

1. Node 베이스라인 고정: fnm·nvm 또는 OS 패키지로 문서화된 메이저를 설치하고 CI 이미지에는 같은 다이제스트를 pin한다.
2. 로그와 함께 스크립트 트랙 시도: 문서의 공식 curl·bash 또는 PowerShell 진입을 쓰고, 실패 시 TLS 오류 전문을 남긴다.
3. npm으로 폴백: 프록시와 cafile을 적용한 뒤 npm install -g openclaw@<pin>. npm ls -g --depth=0로 단일 버전인지 확인한다.
4. PATH 계약 수정: 대화형 rc뿐 아니라 systemd·launchd Environment나 러너 환경에 전역 bin을 주입한다.
5. doctor 전 점검: 설치 사용자와 Gateway 사용자가 일치하는지 확인한 뒤 설치 후 분기 표로 간다.
6. 롤백 기록: 이전 semver와 제거 순서를 보관해 몇 분 안에 되돌린다.

Ansible·Salt에서는 멱등하게 만든다. 재실행이 조용히 latest로 올라가면 안 된다. Windows 환경에서는 실행 정책과 npm 전역 경로를 GPO 메모와 파일럿 OU에 적은 뒤 전체 배포한다.

주간 검토용 세 KPI

1. 설치부터 첫 통과 openclaw doctor까지 지연: 늘어나면 대개 PATH, 권한, 프록시이지 모델 노브가 아니다.
2. 전역 중복 개수: 빌더에서는 OpenClaw semver가 정확히 하나인지 자동 검사한다.
3. 지역별 스크립트 다운로드 실패율: 지역 스파이크면 DNS·MITM을 먼저 보고 모델 파라미터는 나중에 튠한다.

현장 메모(벤치마크 아님): 2025~2026 기업 롤아웃에서 “pin 없는 스크립트 트랙”이 수십 대에 걸쳐 밤새 표류 티켓을 더 자주 만들고, “npm 트랙+명시 pin+변경 창”이 격차를 벌인다. 격차는 피크 CPU가 아니라 반복 가능성이다.

OpenClaw가 iOS 빌드와 같은 원격 Mac을 쓰면 메이저 Xcode 점프와 Node·OpenClaw 업그레이드를 최소 한 유지보수 주기 이상 어긋나게 해 이분 탐색을 유지한다.

읽기 전용 빌더에서는 세 줄 지문을 잡 요약에 붙이고(비밀은 삭제) Gateway 시작 타임스탬프와 비교한다. 지문은 안정적인데 동작만 바뀌면 재설치 루프보다 모델 쿼터나 채널 설정을 우선한다. 무응답 글의 네 계층 분기를 운영에 옮긴다.

노트북에서 빠른 스크립트가 곧바로 프로덕션 안정 데몬을 뜻하지 않는 이유

대화형 머신은 시행착오에 관대하지만 프로덕션은감사된 트랙, pin된 버전, 데몬에 맞춘 PATH 계약이 필요하다. 항상 @latest를 당기는 일회성 클라우드 호스트는 분기를 업스트림 릴리스 추측으로 되돌린다. 예측 가능한 이그레스, 디스크, 로그로 리모트 Mac에서 Gateway를 켜 두려는 팀은 자주 돌아가는 일회 VM보다유연한 대여 조건의 전용 Apple Silicon을 고른다.MACCOME은 다지역 Mac mini M4·M4 Pro와 공개 요금을 제공해 OpenClaw 베이스라인을 빌더와 같은 지역 전략으로 맞출 수 있다.

수평 확장 전에 한 대로 이 런북을 시험하고, 실패 지문을 무응답 트리와 맞춰 중복 작업을 줄인다.

분기마다 설치기 도메인과 npm 레지스트리 허용 목록을 검토한다. 사후 프록시 고고학보다 싸다.

이 런북을 내부 변경 템플릿에 묶어 새 클러스터가 기본으로 pin과 PATH를 물려받게 한다.