싱가포르, 일본, 한국, 홍콩, 미국 동부, 미국 서부 베어메탈 Mac mini M4 Pro에서 OpenClaw를 운영 중인데 2026.5.2 이후 릴리스를 따라가며 외부 플러그인 누락으로 Gateway가 기동되지 않거나 npm install -g @openclaw/discord 이후에도 missing plugin이 남는다면, 원인은 모델 키가 아니라 플러그인 설치 루트가 전역 npm에서 ~/.openclaw/npm으로 옮겨졌는데 설정이 구 경로를 가리키는 경우가 많습니다. 본문은 4.x / 초기 5.x에서 올라온 운영 담당자를 위해 설치 경로 의사결정 매트릭스, 10단계 이행 체크리스트, openclaw doctor --fix / --lint / --non-interactive 적용 경계, OPENCLAW_PLUGIN_STAGE_DIR을 원격 Mac에서 나누는 방법을 정리합니다. 가격은 요금 페이지, 주문은 주문 페이지, 원격 접속은 고객 센터를 기준으로 합니다. 첫 실행 글, npm 업그레이드 글, 2026.5.x 헬스체크 글과 함께 읽는 것을 권장합니다.
읽은 뒤에는 다음을 판단할 수 있습니다. ① 플러그인을 전역 npm에 둘지 ~/.openclaw/npm/node_modules에 둘지. ② Gateway가 이미 내려갔을 때 오프라인 순서로 패키지를 먼저 채운 뒤 doctor를 실행하는 방법. ③ 256GB·512GB 원격 Mac에서 플러그인 stage, 로그, 모델 산출물을 어느 볼륨에 둘지. CLI 하위 명령과 디렉터리 규약은 OpenClaw 공식 문서와 GitHub 릴리스 노트를 기준으로 하며, 배포 후 링크를 다시 확인하십시오.
[ SECTION_01 ] // PLUGIN_FAILURE 2026.5.x 업그레이드 후 Gateway가 외부 플러그인 때문에 뜨지 않는 다섯 가지 근본 원인
첫째는 설치 위치 불일치입니다. 유지보수 창에서 npm install -g만 실행하고 Gateway가 2026.5.2 이후 manifest-first로 ~/.openclaw/npm/node_modules만 스캔하면, 로그에는 configured plugin not found가 뜨는데 팀은 전역 node_modules만 뒤집니다. 둘째는 패키지명과 설정 키 불일치입니다. Discord·Voice 등 scope가 openclaw.json id와 다르면 doctor는 stale install을 보여 주지만, 프로덕션 채널을 지울까 봐 fix를 누르지 못합니다.
셋째는 doctor와 Gateway의 순환 의존입니다. 플러그인이 없어 Gateway가 거부 기동할 때 openclaw gateway restart만 반복하면, openclaw doctor --fix나 올바른 경로의 npm install로 해야 할 일이 공회전합니다. 원격 Mac에서 설정 백업 없이 비대화형 fix를 돌리면 allow-only 플러그인이 매니페스트에서 빠져 새벽 cron이 조용히 실패합니다. 넷째는 디스크 경합입니다. 256GB 기종에서 stage, pnpm 캐시, Gateway 로그를 시스템 볼륨에 두면 npm install 피크와 APFS 스냅샷이 겹쳐 설치는 성공했는데 Gateway 타임아웃처럼 보입니다. 다섯째는 노드 간 반쪽 복제입니다. A에서 ~/.openclaw만 rsync하고 npm 하위 트리를 빼면 B는 설정만 있고 패키지가 없습니다.
- 경로 표류:전역 npm과
~/.openclaw/npm이중 체계, 설정 미이전. - 패키지명 모호:Brave, Discord, Voice 등 scope와 설정 불일치.
- 잘못된 복구 순서:Gateway 재시작을 패키지 설치보다 먼저 수행.
- 비대화형 fix 부작용:
doctor --fix가 allow-only 항목 삭제. - 디스크 수위:stage와 로그가 동일 볼륨에서 용량 경보.
- 반쪽 이전:설정만 동기화하고
npm하위 디렉터리 누락.
외부 플러그인 이슈의 본질은 설정에 적은 모든 id가 하나의 약속 디렉터리에서 실제 패키지로 해석되는 것이며, 전역 CLI를 한 번 더 설치하는 것이 아닙니다.
[ SECTION_02 ] // PATH_MATRIX 전역 npm, ~/.openclaw/npm, ClawHub: 설치 경로 의사결정 매트릭스
2026.5.x는 채널·확장 플러그인을 npm-first로 밀고 manifest 메타데이터로 Gateway 콜드 스타트 스캔을 줄입니다. runbook에서는 먼저 단일 정본 디렉터리를 고정한 뒤 버전을 고정합니다.
| 관점 | A · 전역 npm (-g) | B · ~/.openclaw/npm (권장 기본) | C · ClawHub / 내장 채널 |
|---|---|---|---|
| 적용 상황 | CLI 본체만, 시험, 4.x 문서와의 과도기 | 2026.5.2+ 프로덕션 Gateway, 다중 채널 | 공식 내장 또는 ClawHub 고정 확장 |
| Gateway 가시성 | 설치는 되나 스캔 안 되는 경우 다수 | doctor 복구 로직과 일치 | manifest·채널 스위치에 따름 |
| 롤백 난이도 | 중: 전역과 설정을 함께 정리 | 낮음: npm 하위 트리 tar 스냅샷 |
낮음~중: 플러그인 id 단위 버전 복귀 |
| 원격 Mac 디스크 | 시스템 볼륨 전역 node_modules | STAGE_DIR과 조합해 별도 볼륨 가능 | 플러그인 수에 비례해 캐시 증가 |
다중 워크스페이스 글에서 ClawHub 버전을 고정했다면, 외부 npm 플러그인도 워크스페이스 단위로 대장에 등록해 A 프로젝트의 Discord 업데이트가 B의 공유 디렉터리를 덮어쓰지 않게 합니다.
[ SECTION_03 ] // DOCTOR_STAGE openclaw doctor 복구 모드와 OPENCLAW_PLUGIN_STAGE_DIR 계층 분리
공식 doctor는 읽기 전용 --lint와 자동 복구 --fix를 제공합니다. 변경 창에서는 먼저 lint로 누락 패키지·stale install·없는 디렉터리 참조를 텍스트로 남기고, 유지보수 슬롯에서 fix를 적용합니다. Gateway가 이미 기동 불가라면 Gateway를 띄우지 않은 채 부족한 @openclaw/*를 ~/.openclaw/npm에 넣은 뒤 fix하는 편이 안전합니다. 2026.5.2 이행기에는 전역에 넣었으나 스캔 경로가 다른 사례가 많아, 수동 보완 후 fix가 restart 루프보다 짧은 경우가 많습니다.
OPENCLAW_PLUGIN_STAGE_DIR은 압축 해제 루트와 실행 시 로드 루트를 나눕니다. 원격 Mac에서는 stage를 데이터 디스크에, 핫 경로는 내장 SSD에 두는 구성이 일반적입니다. launchd plist가 환경 변수를 상속하는지 릴리스 후 다시 확인하십시오.
아래는 OpenClaw 공식 doctor 및 릴리스 정보입니다. 상류 저장소가 갱신되면 링크를 다시 여십시오.
https://docs.openclaw.ai/gateway/doctor
https://github.com/openclaw/openclaw/releases
openclaw doctor --lint > /tmp/oc-doctor-lint.txt
cd ~/.openclaw/npm && npm install @openclaw/discord@<pinned>
export OPENCLAW_PLUGIN_STAGE_DIR="/Volumes/data/openclaw-stage"
openclaw doctor --fix --non-interactive
openclaw gateway status
[ SECTION_04 ] // RUNBOOK 10단계로 4.x→2026.5.x 외부 플러그인 이행 완료 (원격 Mac 재현 가능)
- 플러그인 대장 고정:활성 id, 버전, 채널 의존성을 변경 티켓에 기록합니다.
- 전체 백업:
~/.openclaw(npm포함)와 launchd plist를 묶고openclaw --version을 남깁니다. - CLI 본체 업그레이드:릴리스 노트에 따라 OpenClaw를 올리고 중간 버전 이행 주의를 건너뛰지 않습니다.
- npm 루트 생성:
~/.openclaw/npm/package.json을 두고 전역에만 패키지를 두지 않습니다. - 대장대로 설치:각 외부 플러그인을 버전 지정으로
~/.openclaw/npm에 넣고 allow-only를 먼저 설치합니다. - STAGE_DIR 설정:512GB 이상은 stage를 비시스템 볼륨으로. 256GB는 플러그인·캐시에 최소 20GB를 확보합니다.
- lint 후 fix:
doctor --lint로 configured but missing이 없을 때--fix합니다. - Gateway 검증:
openclaw gateway status와 18789 프로브를 헬스체크 글과 대조합니다. - 채널 스모크:활성 채널마다 테스트 메시지를 보내 지연과 로그 경로를 기록합니다.
- runbook 반영:최종 디렉터리 트리, 고정 버전, 롤백 tar 경로를 wiki에 등록하고 분기마다 검토합니다.
소규모 팀 사례(익명):3인 팀이 도쿄 리전 M4 Pro에서 2026.4.27→2026.5.4로 올렸을 때 Gateway가 discord 누락을 보고했고, 전역 npm i만 반복해 해결되지 않았습니다. 본문 순서로 ~/.openclaw/npm에 패키지를 넣고 STAGE를 확장 볼륨으로 둔 뒤 doctor --fix가 한 번에 통과해, 예상 90분 중단이 28분으로 줄었습니다.
[ SECTION_05 ] // DATA_FAQ 인용 가능한 기술 정보, 디스크 예산과 FAQ
아래 수치는 용량 계획에 자주 쓰는 구간이며 실측이 아닙니다. 릴리스 후 공식 문서를 우선하십시오.
- 플러그인 루트:2026.5.2+ 프로덕션은
~/.openclaw/npm/node_modules를 정본으로 하고npm root -g와 혼용하지 않습니다. - 디스크 예산:256GB 원격 Mac은 stage·npm 캐시에 ≥20GB. 다중 워크스페이스·대용량 로그면 1TB/2TB 확장을 검토합니다.
- doctor 모드:
--lint는 CI·변경 전 읽기 전용,--non-interactive는 무인 유지보수,--deep은 중복 설치 잔여 정리용입니다. - 릴리스 페이스:2026.5.3~5.4는 파일 전송 도구와 Gateway 지연 로드를 강화해, 플러그인이 많을수록 manifest 캐시와 디렉터리 계층 분리 이득이 큽니다.
FAQ:
- Q: 전역 npm 패키지를 계속 써도 되나요?A: 프로덕션 기본값으로는 권장하지 않습니다.
~/.openclaw/npm으로 옮기고 설정을 맞추지 않으면 업그레이드 후에도 스캔되지 않을 수 있습니다. - Q: Gateway가 내려가도 doctor를 돌릴 수 있나요?A: 가능합니다. doctor는 Gateway 대기에 의존하지 않지만, fix 전에 누락 패키지를 수동으로 넣으면 항목 오삭제를 줄일 수 있습니다.
- Q: 업그레이드 글과 역할은?A: 업그레이드 글은 CLI·LaunchAgent, 본문은 외부 플러그인 npm·경로 이전입니다.
- Q: 6리전은 어떻게 고르나요?A: 플러그인 설치와 Gateway는 동일 호스트면 충분합니다. 국경을 넘어 장애 대응한다면 가장 자주 조작하는 멤버에 가까운 리전을 주 운영으로 두십시오.
대안을 펼치면, 노트북에서만 플러그인을 시험해도 원격 베어메탈의 launchd 환경 변수는 검증되지 않습니다. 확장 불가한 시스템 볼륨에 플러그인 디렉터리를 두면 반복 npm 업데이트로 일찍 용량 한계에 닿습니다. 사무실 자체 Mac은 유지보수 창에 리전 변경·스토리지 증설이 어렵습니다. OpenClaw 2026.5.x 외부 플러그인과 iOS CI, AI Agent를 프로덕션에 올리면서 doctor와 ~/.openclaw/npm 경로를 감사·롤백 가능하게 유지하려는 팀에게 NOVAKVM Mac mini 클라우드 임대는 보통 더 나은 선택입니다. 전용 Apple Silicon, 6리전 베어메탈, 일·주 임대 검증에서 M4 Pro 고사양·스토리지 확장까지 단계적으로 올릴 수 있어, 단일 변경 티켓에서 패키지 위치 정합과 머신 안정성을 함께 맞추기 쉽습니다. 다음 마이너 업그레이드 전에 플러그인 대장과 npm 하위 트리를 백업에 넣으십시오. 새벽에 패키지 위치를 다시 추측하는 것보다 수면을 지키는 편이 낫습니다.