터미널 크래시를 openclaw doctor로 복구: 게이트웨이 미활성·모델 인증과 6단계 구조 runbook (2026 Mac)

바로 가기를 더블클릭하거나 터미널에 openclaw를 입력하면 창이 사라집니다. 스택 트레이스도, 친절한 대화 상자도 없고, 그저 침묵뿐입니다. 한편 Slack에는 여전히 “gateway not active”가 보이고, 모델 선택기는 끝없이 돌며, 어제 거절한 권한 팝업이 빨간 글씨로 돌아옵니다. 이것은 “컴퓨터를 못 다룬다”가 아니라 환경 드리프트입니다. 잘못된 Node, 잘못된 사용자, 잘못된 설정 파일, 또는 launchd를 살아남지 못한 게이트웨이 프로세스 중 하나입니다.

openclaw doctor는 OpenClaw 공식 자가 진단 명령입니다. PATH의 CLI, 설정 읽기 가능 여부, 게이트웨이 도달성, 인증 프로필, 디스크 여유 등 구조화된 체크리스트를 출력하므로 블로그 글에서 재설치하는 대신 한 줄씩 고칠 수 있습니다. 이 튜토리얼은 초보자 구조 레인입니다. doctor가 무엇을 보는지, 노란 줄과 빨간 줄 읽는 법, 티켓에 붙일 6단계 런북, 초보자가 실제로 보는 오류용 트러블슈팅 2개를 다룹니다. 임대 Mac에서 온보딩 후 SLA급 인수는 별도 온보딩 후 doctor 매트릭스를 읽으세요. 이 글은 “오늘 또 죽었다”용입니다.

첫 언급 시 OpenClaw 제0시간 설치 계약(Node 22+ 하한), 속도 제한 및 예산 알림(재시도가 크래시처럼 보이지 않게), 클라우드 키 대신 로컬 모델을 쓸 때는 OpenClaw + Ollama와 함께 보세요. 업스트림 설치 참고: OpenClaw 설치 스크립트, 게이트웨이 설정 예제. 하드웨어 맥락: Apple Mac mini 사양.

공개: KvmZone 언급은 초보자가 임대 Mac의 깨끗한 SSH 셸에서 openclaw doctor를 실행할 수 있을 때만입니다. 대부분의 단계는 이미 소유한 Mac에서 동작합니다.

doctor가 처음부터 재설치보다 나은 이유

중국 본토에서는 npm 미러로의 느리거나 필터된 이그레스가 “OpenClaw가 고장”처럼 보일 수 있으나 실제는 레지스트리 타임아웃인 경우가 많습니다. doctor의 네트워크/TLS 줄이 첫 증거입니다. 홍콩·싱가포르 임대 Mac 호스트는 doctor 자체에 필수가 아닙니다.

아키텍처: openclaw doctor가 검사하는 것

Terminal / launchd → openclaw CLI → doctor module → reads ~/.openclaw/* → probes gateway HTTP → prints PASS/WARN/FAIL lines

파일과 역할

Doctor는 부하 테스트나 webhook POP 계획을 대체하지 않습니다—그건 온보딩 후 매트릭스 영역입니다. 반면 모델 벤더를 탓할 자격이 있는지는 알려 줍니다.

의사결정 매트릭스: 크래시 유형 → 첫 명령

권장 경로: 셸이 깜빡 닫히면 먼저 대화형으로 doctor 실행—GUI 바로 가기로 디버그하지 마세요. doctor가 녹색인데 메뉴 막대가 inactive면 LLM API 키가 아니라 launchd 사용자와 포트를 고치세요.

6단계 openclaw doctor 구조 런북

단계 1 — 진짜 셸 열기(더블클릭 별칭 아님)

# macOS: use Terminal.app or iTerm — note the user name
whoami
echo $SHELL

출력을 저장하세요. 로그인 셸을 건너뛰는 바로 가기는 PATH 수정을 숨깁니다.

단계 2 — Node 22+ 및 PATH상 CLI 확인

node -v
which openclaw
openclaw --version

통과: node가 v22 이상; which openclaw가 /opt/homebrew 또는 문서화한 글로벌 prefix 아래 단일 경로 반환.

단계 3 — doctor 실행 및 기록 저장

openclaw doctor 2>&1 | tee ~/openclaw-doctor-$(date +%Y%m%d).log

이 파일을 지원 티켓에 첨부하세요. 수정 마다 재실행—추측을 쌓지 마세요.

단계 4 — 첫 FAIL 수정(대개 PATH 또는 설정 JSON)

# Example: validate JSON before restart
python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"

JSON이 실패하면 백업에서 복원:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

단계 5 — 데몬 사용자 일치(gateway inactive 수정)

# See which user launchd uses (label varies by install)
launchctl print system/com.openclaw.gateway 2>/dev/null | head -20
# Run doctor as that user if different from Step 1
sudo -u _openclaw openclaw doctor 2>&1 | tee ~/openclaw-doctor-daemon.log

통과: 대화형과 데몬 기록이 일치하거나 모든 차이가 문서화됨.

단계 6 — 게이트웨이 재시작 및 status 검증

openclaw gateway restart   # or launchctl kickstart per your install doc
sleep 5
openclaw status
openclaw doctor

통과: status가 리슨 포트 표시; doctor에 설명 없는 FAIL 줄 없음. 그다음—그때에만—에이전트나 바로 가기를 재시도하세요.

SSH 전용 임대 호스트는 문서화된 GUI 게이트가 없는 한 픽셀 도구 대신 원격 Mac SSH 워크플로를 사용하세요.

트러블슈팅

오류 패턴: zsh: command not found: openclaw(또는 창 즉시 종료)

증상: 스크립트나 .app 래퍼가 UI 전에 종료; doctor가 한 번도 실행되지 않음.

수정:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
npm install -g openclaw@latest
openclaw doctor

동일한 PATH를 launchd plist EnvironmentVariables에 맞추세요(제0시간 계약 참고).

오류 패턴: gateway not active / ECONNREFUSED 127.0.0.1

증상: CLI는 존재; UI나 openclaw status가 로컬 게이트웨이에 닿지 않음.

수정:

lsof -iTCP -sTCP:LISTEN | grep -i openclaw
openclaw doctor
openclaw gateway restart

포트가 다른 사용자에게 점유되면 고아 프로세스를 중지하거나 ~/.openclaw/openclaw.json의 gateway.port를 변경한 뒤 doctor를 재실행하세요. 게이트웨이가 안정되면 속도 제한을 설정하세요—재시도 폭풍은 크래시처럼 느껴집니다.

FAQ

관련 읽기

• OpenClaw 제0시간 설치 계약 — Node 22+ 규율
• 온보딩 후 doctor + webhook POP — 콜백 인그레스
• OpenClaw 속도 제한 및 예산 알림 — 재시도 폭풍 vs 크래시
• 임대 M4에서 OpenClaw + Ollama — 클라우드 키 없는 로컬 모델
• 원격 Mac SSH 보안 워크플로 — SSH 전용 운영