2026 클라우드 Mac: OpenClaw doctor를 데이터 플레인으로 삼아 launchd 수정까지 연결하기
“SSH에선 CLI가 되는데 새벽에 채팅이 멈춘다”는 흔들림은 헤드리스 Mac mini 리스에서 OpenClaw를 돌릴 때 자주 나옵니다. 이 런북의 핵심은 openclaw doctor를 마케팅 문구가 아니라 1차 데이터로 취급하고, 경고 줄을 launchd plist, Node 실체, 리스닝 포트, ai.openclaw.gateway 소유 사용자 맥락의 아웃바운드 DNS에 즉시 상관시키는 것입니다. 증상 표, 숫자 체크포인트가 있는 8단계, 거짓 음성, 변경 관리용 필드, MacLogin 리전 운용 FAQ를 담았습니다.
환경 변수와 LaunchAgent 층은 OpenClaw 환경 변수+launchd, 데몬 복구는 게이트웨이 장애 분석, SSH 세션 끊김은 keepalive 가이드, 상태 디렉터리는 백업 인수인계를 참고하세요. 일반 연결은 도움말, 스테이징 추가는 요금, TCC 방해는 VNC로 보완합니다.
로컬 헬스체크가 루프백만 보면 doctor가 조용해도 외향 TLS가 깨져 있을 수 있습니다. doctor 이후에 반드시 둘째 확인을 런북에 박아 두면 야간 온콜이 줄어듭니다.
헤드리스 환경에서 doctor를 최우선하는 이유
- 리스 복제: LaunchAgent를 도쿄에서 싱가포르로 복사해도 doctor를 다시 안 돌리면 Node 경로 오차가 첫 재부팅까지 숨습니다.
- 토큰 교체: 분기마다 API 키를 바꿔도 doctor는 “파일 읽기 가능”만 볼 때가 있습니다.
- 감사 증빙: 사건 전 건강 상태를 보이려면 타임스탬프 doctor 출력이 스크린샷보다 재현성이 높습니다.
로그 tail 전 증상 표
| 사용자가 보는 증상 | 먼저 읽을 doctor 절 | 2차 확인 | MacLogin에서 흔한 원인 |
|---|---|---|---|
| launchd exit 127 | Runtime / Node | which node vs plist ProgramArguments | OS 업데이트 후 Homebrew 접두사 이동 |
| 엣지 502 | Ports / listeners | 루프백 lsof | localhost 포트 설정 드리프트 |
| LLM 타임아웃 | Network / DNS | 동일 사용자 dig | 공유 리스의 아웃바운드 제한 |
| 도구 거부 | Permissions / workspace | GUI로 TCC 한 번 확인 | 첫 실행이 SSH 밖에서 끝나지 않음 |
티켓에 붙일 8단계
- 셸 일치: root 대신 LaunchAgent 소유자 SSH.
OPENCLAW_STATE_DIR가 iCloud 밖인지 확인(상태 디렉터리). - 캡처:
openclaw doctor > ~/tmp/doctor-$(date +%Y%m%d-%H%M).txt. - 버전 고정: 같은 파일에
openclaw --version과 Node semver. - launchctl:
launchctl print gui/$(id -u)/ai.openclaw.gateway. - 포트 대조: doctor 힌트와 실제 TCP가 ±1을 넘기면 설정이 낡음.
- 채널 프로브: 본전 전 최저비용 채널로 합성 ping.
- 타임박스: 25분 내 진전 없으면 doctor+launchctl 첨부해 에스컬레이션.
- 사후: doctor 재실행으로 빨간 줄 0 또는 위험 수용 기록.
doctor 줄과 plist 필드
| doctor 힌트 | 확인할 launchd 필드 | 건전 패턴 |
|---|---|---|
| Cannot find node | ProgramArguments[0] | 대화 셸과 동일 절대 경로 |
| State dir not writable | WorkingDirectory | 700 권한 리포 루트 |
| Port in use | (없음) 프로세스 | 중복 게이트웨이 중지, 랩만 +1 |
거짓 음성과 위험 신호
헬스체크가 루프백만 보면 doctor가 조용해도 TLS 경계에서 실패합니다. 아웃바운드 TLS 실패는 P1로 취급하세요.
- 위험: doctor 녹색인데 CPU>85%가 20분 지속·트래픽 없음→도구 루프 의심.
- 위험: 여유 공간 12GB 미만 경고→캐시 손상 위험.
감사용 최소 패킷
| 산출물 | 최소 내용 | 보관 |
|---|---|---|
| doctor.txt | stdout 전문, 호스트명, 리전 코드 | 90일 |
| launchctl print | 종료 코드, 시각, uid | 90일 |
| openclaw.json diff | 비밀 마스킹 | 180일 |
FAQ
통합 테스트 대체? 아니요. 채널별 합성 페이로드 스모크를 유지하세요.
CI에서 doctor? 예. 스테이징 리스 파이프라인에서 빨간 줄이면 비정상 종료.
MacLogin이 대행? 아니요. 고객 운영이며 본문은 자가 진단 지침입니다.
Mac mini M4가 적합한 이유
arm64와 launchd 가정이 문서와 맞고, doctor를 로컬 프로브와 병행해도 게이트웨이가 굶지 않습니다. Neural Engine은 향후 온디바이스 검증에 여유를 줍니다. 사용자 근처 리전에서 doctor를 돌리면 WAN 오판이 줄어듭니다.
