2026 OpenClaw 공식 경로: openclaw onboard 엔드투엔드—Node 24, 워크스페이스, 첫 채널, ClawHub Skill, 데몬, 채널 업데이트

“CLI 설치됨”이 “OpenClaw 배포됨”과 같지 않은 이유

상류는 onboard를 권하는 이유는 Gateway·워크스페이스·채널·기본 모델에 순서 의존성이 있기 때문입니다. 마법사를 건너뛰고 JSON을 수작업하면 “프로세스는 떴는데 메시지는 안 온다” 혹은 “Skill은 있어도 도구가 등록되지 않는다”로 이어집니다. 2026년 커뮤니티에서 자주 보는 오독 여섯 가지입니다.

1. Node가 “겨우 맞다” 수준: 기준은 Node 24(최소 22.16+)를 권장합니다. 기준 이하에서 설치는 될 수 있어도 Gateway가 네이티브 경계에서 간헐적으로 죽을 수 있습니다.
2. openclaw doctor 생략: onboard 막바지에 막혔을 때 doctor 없이는 이분할 발판이 없습니다. doctor는 장식이 아니라 관문입니다.
3. 채널보다 먼저 Skills: 설치는 되어도 대화에서 점화되지 않습니다. 흔히 Gateway 미재시작 또는 OAuth 미완입니다. 모델만 탓하지 마십시오.
4. 데몬과 대화형 셸 혼동: 노트북을 닫으면 Gateway도 멈추는데, 상류 버전 탓을 합니다.
5. 문서 없는 채널 섞기: 한 사람은 beta, 다른 사람은 stable—CLI·Gateway 드리프트는 재현 불가한 불일치를 낳습니다.
6. 일시적 상태 디렉터리: 리모트 Mac·VPS에서 언마운트된 디스크에 두면 업그레이드가 “설정 유실”처럼 보입니다.

의도적으로 컨테이너를 쓰신다면 docker-setup + GHCR 글을 1차로, 이 글을 2차로 두십시오. 서브에이전트 페어링에 싸우신다면 npm 재설치 전에 Compose 1008을 먼저 읽으십시오.

운영 측면의 보강으로, 동일한 릴리스 주 안에서 CLI·Gateway·Skills 로그의 첫 줄을 변경 티켓에 붙여 두면, 주간 리뷰에서 “누가 본서버 경로에 실험 빌드를 올렸는지”를 빠르게 추적할 수 있습니다. 사소해 보이지만, 다인 환경에서는 이 한 줄이 재발을 막는 경우가 많습니다.

다중 사이트에서 노드를 나눌 때, 변경 티켓마다 이 호스트의 node -v·openclaw CLI 버전 문자열(문서에 안내된 플래그 사용)·Gateway 프로세스 기동 UTC 시각의 세 줄을 맞춰 적으면, 주간 “원인 모를 끊김”의 상당수가 사실은 채널 드리프트임을 드러냅니다. 세 줄이 맞지 않는 주는 공급자 회선을 의심하기 전에, 내부 배포 순서를 먼저 봅니다. 또한 openclaw 작업트리를 자동 백업에 넣을 때, Secrets 파일과 일반 대화 내보내기의 암호화·전송 대상이 서로 겹치지 않게, 저장소·버킷·ACL을 표로 정리해 두면 온콜이 한 번에 흐름을 따라갈 수 있습니다.

표: 세 가지 진입(이 글은 npm onboard이 주제)

6단계 Runbook: 빈 호스트에서 최소한의 무인 루프로

1. Node 설치와 버전 기록: nvm이나 공식 설치로 고정하고, 변경 티켓에 node -v를 남깁니다.
2. CLI 설치와 doctor: npm i -g openclaw@latest 이후 openclaw doctor. onboard 전에 고위험 항목을 정리합니다.
3. openclaw onboard 실행: 워크스페이스, 기본 모델, AGENTS.md 주입, 최소 한 채널을 완료. 마법사 출력에서 Gateway 포트와 Control UI 경로를 적습니다.
4. 채널 증명: 전 경로로 짧은 테스트 메시지. 실패 시 모델과 채널을 동시에 바꾸지 말고 doctor 조치로 돌아갑니다.
5. 첫 ClawHub Skill: openclaw skills search → openclaw skills install <name> → Gateway 재시작 → openclaw skills list.
6. 데몬과 로그 경로: openclaw onboard --install-daemon(또는 동등한 마법사). openclaw update --channel beta|dev을 시도하기 전에 로그 로테이션과 디스크 임계치를 둡니다.

변경 티켓에 넣을 감사 필드 세 가지

1. Node 메이저 + 설치 출처: 예: v24.x nvm 등. OS 업그레이드마다 doctor를 다시 돌립니다.
2. Gateway listen·bind 이야기: 루프백 vs 리버스 프록시·Tailscale 선택을 기록해 Compose pairing 지침과 어긋나지 않게 합니다.
3. 채널 매핑: stable|beta|dev을 달력 창에 묶고, 롤백 시 CLI·Gateway 버전 쌍을 남깁니다.

이는 엔지니어링 감사용 필드이며 벤더 SLA가 아닙니다. CI와 Gateway가 같은 호스트를 쓰면, 빌드가 로그나 SQLite 상태를 잠식하지 않게 CPU·디스크 알람을 둡니다. OpenAI·Anthropic·로컬 LLM을 동시에 붙이는 팀이면, 모델 엔드포인트의 요금/속도/데이터 이전 조항을 주간 뉴스레터에 한 줄 요약해 두면, 채널만 갈아끼우다 API 비용이 터지는 사고를 줄일 수 있습니다.

구조적으로 onboard는 자동화의 닻입니다. 워크스페이스와 Skills 디렉터리가 고정되면 백업과 업그레이드의 단일한 진실이 생깁니다. 이걸 생략하면 회의는 “누가 openclaw.json을 고쳤는가”로 갑니다. 월간 점검 루틴에 채팅 내보내기 정책과 함께 ~/.openclaw에 해당하는 경로 용량을 합쳐 적으면, 분기마다 갑자기 터지는 긴급 삭제를 줄일 수 있습니다. 민감한 토큰이 섞이는 팀이면, 로그·세션·백업의 주기는 보안·감사 정책에 맞춰 먼저 확정한 뒤, 그에 맞게 openclaw 쪽 보존 옵션을 맞추는 순서로 진행하십시오.

항상 켜 둔 Gateway에 개인 노트북이 약한 기본값인 이유

절전, VPN 끊김, 기업 정책은 Gateway의 시간 연속성을 깨뜨립니다. OpenClaw가 팀의 사실상 제어면이 될 때는 7×24로 예측 가능한 디스크와 이그레스를 가진 호스트를 우선하고, 노트북은 필요 시 CLI 클라이언트로 남깁니다.

집·사무실 타워는 통제되지 않은 패치·전력 창이 있습니다. iOS 빌드 팜과 AI 에이전트를 함께 돌릴 때, 여러 지역에 걸친 Apple Silicon 클라우드 호스트가 개인용 노트북보다 운영 지표를 내기 쉬운 경우가 많습니다. MACCOME은 베어 메탈 노드와 유연한 임대 조건을 제공합니다. 공개 요금과 고객센터에서 채널과 접속 질문을 먼저 확인하십시오.

파일럿: 전용 리모트 Mac에서 일주일간 onboard+데몬을 돌리고 로그량과 CPU 피크를 캡처한 뒤, 베타 채널을 같은 호스트에 올릴지 결정하십시오. 첫 주부터 프로덕션 Gateway를 개인 개발 머신에 묶지 마십시오.

프로덕션 전환 전, 동일 호스트에서 openclaw doctor를 다시 돌리고(출력 캡처), 환경에 맞는 Gateway 헬스 엔드포인트·응답을 변경 티켓에 붙이면 롤아웃 검토가 짧아집니다. 베타 CLI와 stable Gateway를 잠시 병행하더라도, 주간 루틴에서 채널 정렬을 한 벌로 돌리는 규칙을 팀에 문서로 남기십시오. 패치 직후 디스크 압박은 로그 로테이션 누락에서 자주 터지므로, openclaw 상태 디렉터리와 시스템 로그 모두에 임계치 경보를 두는 편이 안전합니다. 위는 공식 SLA가 아니라, 주간 품질을 떨어뜨리지 않기 위한 엔지니어링 관행입니다. 또한 민감한 세션이 쌓이는 환경에서는 감사·보관 주기를 보안 쪽과 먼저 맞추십시오. 노트북을 CI와 공유하는 사무실이면, 주간에 openclaw 작업 경로와 Xcode DerivedData 용량을 같이 기록해 월말 용량 사고를 줄이십시오. 분기마다 ~/.openclaw에 해당하는 경로를 채팅 백업 정책과 함께 검토하면 긴급 정리 횟수가 줄어듭니다. 터널·리버스 프록시·원격 데스크톱 동시 세션 수를 주간에 숫자로 남기면, “어제까지 됐는데” 류의 모호한 장애를 채널 이슈와 네트워크 이슈로 빨리 갈릅니다. 마지막으로, mDNS / Bonjour 이름 충돌이 뜨는 사무망이면, Gateway 바인딩 전에 한 번 dns-sd 로그를 스냅샷으로 남기면 월초 “갑자기 느려짐”을 줄이는 데 도움이 됩니다.