npm install -g openclaw → openclaw onboard --install-daemon → openclaw gateway status → 제어판 스킬·스트리밍 → 롤백 → openclaw doctor 병합 순서를 고정합니다. 관측·인증은 Model Auth·게이트웨이 로그, 임베딩·RAG는 embeddings 가이드, 목록은 기술 블로그（로그인 불필요）.
문서화하지 않으면 흔들리는 세 가지
엔지니어는 자신의 계정으로 SSH하지만 launchd는 다른 사용자로 떠서 스킬·설정 경로가 엇갈립니다. 둘째, openclaw@ 시맨틱 버전을 고정하지 않으면 제어판과 바이너리가 서로 다른 열차에 올라탑니다. 셋째, 헬스는 200이어도 스트리밍은 리버스 프록시 버퍼 때문에 끊깁니다. 아래 매트릭스와 순서 고정으로 재현 가능한 운영 루프를 만듭니다.
공개 CLI 문서의 onboard 페이지에 따르면 --install-daemon에서는 토큰·SecretRef 검증이 더 엄격하고, 자동화는 --non-interactive·--skip-health 계약을 릴리스 노트와 동일하게 맞춰야 합니다.
역할 분담：CLI·제어판·doctor
| 관심사 | CLI 우선 | 제어판 | doctor 병합 |
|---|---|---|---|
| OpenClaw 설치 | npm install -g openclaw@<pin>·node -v |
문서·링크 확인용, 패키지 고정 대체 금지 | 설치 직후 openclaw doctor로 PATH·권한 드리프트 점검 |
| 상시 서비스 | openclaw onboard --install-daemon（macOS launchd） |
노출 시 데몬 실행 사용자 확인 | plist 사용자와 doctor 경고(권한·토큰) 정합 |
| 스킬·스트리밍 UX | UI 지연 시 동기화 보조 | 카탈로그 설치·워크스페이스 할당·스트리밍 토글 | 정책·샌드박스 차단을 UI 이슈로 오인하기 전에 doctor로 확인 |
| 롤백 | 이전 npm 태그 재설치·데몬 재시작 | 문제 스킬 번들 비활성화·이전 카탈로그 버전 | doctor --fix 전 설정 스냅샷 필수 |
HowTo：복붙 순서 체크리스트
운영 문서에 v2026.3.24 게이트웨이와 같은 시맨틱 핀을 명시합니다. 공식 문서는 Node 20+·npm 9+를 전제로 하며, 팀 표준은 22 LTS로 맞추는 것이 안전합니다.
node -v npm install -g openclaw@latest openclaw --version
검증이 끝난 뒤에는 latest 대신 내부에서 승인한 정확한 버전 문자열로 바꿉니다.
openclaw onboard --install-daemon
마법사에서 모델·포트·인증을 마친 뒤 --install-daemon으로 macOS launchd 백그라운드 서비스를 등록합니다. 비대화형은 공식 --non-interactive 계약과 릴리스 노트를 함께 고정하세요.
openclaw gateway status
리스너·런타임 배너·프로브 결과를 CLI에서 먼저 확정합니다. 릴리스가 지원하면 JSON 출력으로 CI에 붙입니다.
openclaw gateway status # openclaw gateway status --json
openclaw dashboard로 로컬 제어 UI를 열고 카탈로그에서 스킬을 설치·워크스페이스에 연결합니다. 스트리밍 토글이 있으면 켜 긴 응답을 토큰 단위로 받고, 127.0.0.1은 SSH 터널·승인된 TLS로만 노출한 뒤 짧은 대화로 도구 호출까지 검증합니다.
업그레이드 전 ~/.openclaw·스킬 디렉터리·환경 변수 표를 아카이브합니다. 실패 시 이전 npm 태그로 재설치하고 데몬을 재시작한 다음 제어판에서 문제 버전을 끕니다.
openclaw doctor는 읽기 전용 점검으로 자주 돌리고, openclaw doctor --fix는 백업·스테이징 검증 뒤에만 실행합니다. 아래처럼 gateway status와 한 스크립트에 묶으면 티켓 시스템에 단일 합격·불합격 로그를 남길 수 있습니다.
#!/bin/sh set -euo pipefail openclaw doctor openclaw gateway status # openclaw doctor --fix # 백업 후·변경 창에만
티켓에 붙일 최소 증거 번들
- 런타임 줄：
node -v·openclaw --version·게이트웨이 핀（v2026.3.24）. - 포트·바인딩：루프백 대시보드 포트와 TLS 종료 위치（localhost vs 엣지）.
- 스트리밍 계약：프록시 버퍼 해제 여부·idle 타임아웃·SSE 헤더 검증 curl 한 줄.
자주 묻는 오류 FAQ
Q. npm install -g 후에도 command not found: openclaw
A. 비대화형 셸의 PATH에 전역 bin이 빠졌습니다. npm prefix -g를 확인하고 plist EnvironmentVariables에 동일 경로를 넣거나 심볼릭 링크를 추가합니다.
Q. 온보딩은 성공했는데 로그아웃 뒤 데몬이 사라짐
A. --install-daemon 생략 또는 GUI 세션 전용 작업에 묶였을 수 있습니다. 의도한 사용자로 plist를 로드했는지·영구 에이전트인지 확인합니다.
Q. status 정상·스킬만 오프라인?
A. OPENCLAW_HOME 등 데이터 루트 불일치—경로 통일 후 doctor로 동일 트리 확인.
Q. 도구 호출 직후 스트리밍 정지?
A. 프록시 버퍼·짧은 읽기 타임아웃—버퍼 해제·idle 상향.
원격 Mac에서 OpenClaw를 안정적으로 돌릴 가치
전용 Apple Silicon은 NVMe·전원·이웃을 예측 가능하게 하고, 데몬·스킬·doctor+status 한 루프가 끊기지 않게 합니다. CLI 핀·제어판·점검 스크립트를 한 런북에 두면 업그레이드가 절차가 됩니다.