2026 OpenClaw 설치 후 Gateway 미등록: command not found, npm prefix, gateway install --force, 원격 Mac launchd

npm install -g openclaw 이후 터미널에 빨간 에러가 없어도 openclaw ask 가 멈추거나 openclaw-gateway: command not found 가 뜨면, 우선 모델 장애가 아니라 npm 글로벌 prefix·PATH 드리프트, Gateway 등록 누락, Node 22 불일치, launchd와 대화형 SSH 환경 차이를 의심해야 합니다. 본문은 증상—증거—조치 매트릭스, 5단계 콜드 스타트 Runbook, 수치 게이트, FAQ를 제공하며 install.sh 운영·LaunchAgent·token·Chrome Relay 18792·v2026.5.x 계층 운영과 교차합니다. 깨끗한 대조면으로 MACGPU 원격 Mac 에 동일 절차를 복제하세요.

1. 문제 분해

글로벌 bin 이 PATH 에 없음, openclaw gateway install 미실행, 설치 시점과 실행 시점의 Node 경로 불일치, launchd 최소 환경 등이 대표 원인입니다. CI 배지만 보고 야간 장애를 맞는 팀은 2026년에도 여전히 많습니다. 공유 자동화 계정에서 병렬 npm 이 돌면 which 결과가 흔들립니다. 읽기 전용/네트워크 마운트에 로그를 두면 설치는 성공한 듯 보이나 프로세스는 반복 크래시할 수 있습니다.

2. 증상 매트릭스

신호	1차 의심	증거
command not found	PATH	`which openclaw`, `npm prefix -g`
gateway status 미설치	등록 누락	`gateway install --force` 전후
대화형 OK, launchd NG	plist 환경	`EnvironmentVariables`
원격에서만	비로그인 셸	`ssh -t`, 홈 일치

3. 5단계 Runbook

Step 1 런타임 삼중 고정

node -v(22+), which node 절대경로 기록.

Step 2 prefix·PATH

npm config get prefix 확인, zshrc 반영, sudo npm 금지.

Step 3 Gateway 명시 등록

점검 창에서 openclaw gateway install, 필요 시 --force, token 글과 LaunchAgent 정합.

Step 4 포트·헬스 의미

루프백과 SSH 터널을 분리, Chrome Relay 글의 18792 프로브 활용.

Step 5 콜드 재시작·로그 슬라이스

완전 종료 후 기동, install/register/first-ask 시간창으로 openclaw logs 분리 첨부.

node -v; which node; npm prefix -g; which openclaw || true; which openclaw-gateway || true
openclaw doctor
openclaw gateway status || true
openclaw gateway install --force
openclaw gateway status
                

4. 세 가지 하드 게이트

A: which openclaw-gateway 비어 있으면 성공 선언 금지. B: gateway status 가 문서의 건강 신호에 도달하기 전까지 생산 채널 전환 금지. C: 비대화 launchd 콜드 스타트 전까지 노트북 터널만 믿지 말 것. B 이후에는 모든 SSH 세션을 닫고 PATH 수동 export 없이 재검증하세요.

5. 사례 연구

npm 성공, 낮 SSH 정상, 밤에 전부 실패 → plist 에 ~/.npm-global/bin 누락.

2026년 5월 원격 Mac mini 24/7 팀은 낮에는 nvm 이 PATH 를 채워 오탐, 밤에는 시스템 구형 Node 가 선택되어 Gateway 가 비어 있는 채 API 키만 교체했습니다. Node 22 절대경로를 plist 에 고정하고 openclaw gateway install --force 와 channels probe 후 첫 토큰이 안정화되었습니다. v2026.5.x 글이 말하듯 상위 플러그인·TTS 분리는 건강한 베이스가 있어야 의미가 있습니다.

6. 산업 관점

2026년 에이전트 스택은 CLI·Gateway·플러그인이 독립 버전으로 배포됩니다. 단일 npm 성공이 곧 폐루프는 아닙니다. Windows/Linux 검증도 가능하지만 브라우저·데스크톱 세션이 섞이면 변수가 늘어납니다. Apple Silicon 원격 전용 노드로 대조면 「미등록 vs 네트워크」 논의가 빨리收斂합니다. 하드만 늘리기 전에 감사 가능한 체크리스트와 콜드 스타트 증적을 갖추는 편이 ROI 가 높습니다.

원격 Mac 을 직접 사지 않고도 동일한 대조 실험을 하려면 MACGPU 원격 Mac 렌탈로 본 Runbook 을 릴리스 템플릿에 박아 넣을 수 있습니다. Windows/Linux 만으로도 Gateway 는 돌아가지만, 그래픽·AI 툴체인과 24/7 안정성을 동시에 요구할 때는 macOS 대조면이 변수를 줄입니다. 결론은 브랜드가 아니라 재현성과 로그 일관성에 기반합니다.

7. 수치 임계값

건강한 gateway status 까지 콜드 스타트 90초 초과 시 디스크·백신 스캔 검토. 로컬 루프 첫 ask 25초 무응답이면 모델 전에 Gateway. 동일 창에서 gateway install --force 2회 초과 시 수동 diff. plist PATH 핵심 항목 3개 미만은 기본 불합격. 로그를 읽기 전용/네트워크 볼륨에 두면 성공 로그 직후 크래시 루프가 날 수 있습니다. 공유 자동화 계정에는 독립 npm prefix·홈을 부여하고 병렬 글로벌 설치를 금지하세요.

8. FAQ

doctor 녹색인데 which? 필수입니다. token_mismatch? 401 계열은 token 글, 프로세스 부재는 본문. sudo npm? 비추천. Relay 빨강 gateway 녹색? Chrome Relay 글. install.sh+npm 혼용? 이중 메타데이터 위험, 하나로 통일.