OpenClaw macOS 게이트웨이는 launchd로 재부팅 후에도 살아 있어야 하지만, 2026.x 채널의 빠른 업데이트는 가끔 조용한 실패를 남깁니다: 바이너리만 올라가고 LaunchAgent는 다시 로드되지 않으며 모든 메시지 브리지가 응답하지 않습니다. 이 플레이북은 증상을 수정에 매핑하고, 복구 전술을 매트릭스로 비교하며, NodeMac Mac mini M4에서 SSH로 경로를 추측 없이 실행할 수 있는 아홉 단계를 담습니다.
OpenClaw 운영 런북(로그 위치·업그레이드 정책)과 함께 쓰고, 처음부터 다시 짓는 경우 첫 macOS 설치를 참고하세요.
LaunchAgent 드리프트 신호—「AI가 죽었다」가 아님
- 프로세스 없고 충돌 대화상자도 없음:
ps에 게이트웨이 워커가 없고 CPU 유휴—전형적인 미로드 에이전트. - 재부팅 후 모든 공급자가 HTTP 401:키는 dotenv에 있지만 plist에 필요 변수가 없어 데몬이 빈 환경을 물려받음.
- 수동 CLI는 성공, 자동 시작은 실패:터미널에선 게이트웨이가 돌아가지만 로그아웃 후 멈춤. LaunchAgent가 오래된 작업 디렉터리나 이전 레이아웃의 진입 파일명을 가리킴.
복구 옵션 매트릭스
| 전술 | 다운타임 | 언제 쓸지 |
|---|---|---|
launchctl kickstart -k |
5–15초 | 에이전트는 로드됐으나 프로세스가 멈춤. 가장 빠른 첫 수 |
| Unload + load plist | 20–40초 | ProgramArguments나 WorkingDirectory를 수정한 뒤 |
openclaw gateway install --force |
1–3분 | 벤더 CLI가 plist를 다시 쓸 수 있음. 재부팅 전 diff 확인 |
| 패키지 롤백 + plist 백업 | 5–10분 | 회귀가 프로덕션을 막음. 마지막으로 정상이던 tarball에서 복원 |
환경 변수: 데몬이 읽어야 할 위치
대화형 셸은 .zshrc를 읽지만 LaunchAgent는 읽지 않습니다. 공급자 키가 plist에 반영되지 않는 파일에만 있으면 게이트웨이는 미인증으로 부팅되고 로그에 혼란스러운 401이 쏟아집니다.
- 필수 키 나열(API 토큰, 선택적 프록시 URL)을 운영이 로테이션 후 붙여 넣을 런북 스니펫으로.
- plist의
EnvironmentVariables에 미러링 또는 시작 시 dotenv를 명시적으로 로드하는 벤더 지원 래퍼 사용. 머신마다 전략 하나만—둘 다 반쯤 하지 말 것. - 재부팅 테스트:분기마다 예약. 자격 증명 로테이션 후 24시간 안에 빠진 변수 잡기.
- plist 권한을 서비스 사용자로 제한. 전 세계 읽기 가능한 plist는 비밀을 로컬 모든 계정에 유출.
- 활성 도메인 기록(
gui/$(id -u)대 background)으로 주니어가 잘못된 작업을 unload하지 않게.
헤드리스 클라우드 Mac 팁:게이트웨이 UI를 잠깐 봐야 하면 VNC 가이드대로 VNC를 쓰고, 그렇지 않으면 SSH에 머물며 로그와 HTTP 헬스로 판단.
바이너리는 멀쩡한데 자동 시작이 깨지는 이유
패키지 업데이트는 세 가지 취약 접점을 한꺼번에 바꿀 수 있습니다: ProgramArguments 안의 실행 경로, 상대 설정이 풀리는 작업 디렉터리, 게이트웨이 번들이 기대하는 Node.js 버전. 하나만 어긋나도 launchd는 작업을 “구성됨”으로 보지만 즉시 종료—운영자는 실제로는 떠 있지 않은 UI에 녹색 체크를 봅니다.
매 업그레이드를 소규모 마이그레이션으로 다루세요: plist 스냅샷, 게이트웨이 진입 스크립트 체크섬 기록, 최소 7일간 이전 tarball 보관. 클라우드 Mac은 봇이 메시지에 답하지 않아도 비용이 나갑니다. 금요 저녁 배포가 고객 대면 자동화를 고립시키는 순간 이 규율이 보상됩니다.
- 프로덕션 게이트웨이 자동 업그레이드 속도 제한. 스테이징 카나리아가 최신을 먼저 받게.
- Node 메이저를 벤더 문서와 맞추기. 메이저 불일치는 첫 로그 줄에 모호한 모듈 해석 오류로 자주 나타남.
- 비밀 로테이션 중앙화로 plist 편집을 패닉마다가 아니라 플릿 한 번에.
아홉 단계 복구 런북(Mac mini M4 SSH)
- 연결 확인을 LaunchAgent와 동일한 SSH 사용자로. 권한 불일치는 “수동 OK·부팅 NG”의 흔한 이유.
launchctl print gui/$(id -u)캡처를 인시던트 노트와 함께 보관해 diff 가능하게.~/Library/LaunchAgents/에서 plist 찾기.ProgramArguments경로가 디스크에 존재하는지 확인.-k가 있는 kickstart로 강제 재기동. 30초 기다린 뒤 리스닝 포트 확인.- 여전히 다운면 plist를 깔끔히 unload/load. 예전에 실험했다면
/Library/LaunchDaemons에 낡은 복사본이 없는지 확인. - 환경 변수 정리. 빠진 키를 주입한 뒤 다시 로드.
- 게이트웨이 로그를 2분 tail해 크래시 루프 감시. 같은 스택 트레이스가 세 번 넘으면 롤백.
- 통합 스모크(가장 위험 낮은 채널로 테스트 메시지) 후 복구 선언.
- 내부 문서 갱신에 실제로 통한 명령 기록. HK·JP·KR·SG·US 클라우드 Mac 플릿은 하나의 정본 복구 페이지를 공유.
모델 공급자를 탓하기 전 체크리스트
| 항목 | 통과 기준 |
|---|---|
| DNS / 아웃바운드 HTTPS | 공급자 엔드포인트에 대한 curl -I가 2xx/401(타임아웃 아님) |
| 디스크 공간 | 시스템 볼륨에 최소 25 GB 여유 |
| 시계 오차 | NTP 편차 2분 미만—시계가 튀면 JWT 인증이 조용히 실패 |
자주 묻는 질문
업데이트 후 OpenClaw가 메뉴 막대에서 사라지는 이유는?
게이트웨이 프로세스는 종료됐는데 launchd가 LaunchAgent plist를 다시 로드하지 않았거나, 패키지 레이아웃이 바뀐 뒤에도 plist가 오래된 프로그램 경로를 가리킬 수 있습니다. plist를 검증하고 에이전트를 다시 로드한 뒤 환경 변수가 재부팅 후에도 남는지 확인하세요.
프로덕션 게이트웨이에서 kickstart를 실행해도 안전한가요?
수 초 다운타임을 감수할 수 있다면 예. 메시지 브리지에 의존하는 팀은 유지보수 창을 권장합니다. 재시작 후 첫 1분은 반드시 로그를 tail 하세요.
노트북을 들고 상시 게이트웨이를 지키기 싫다면 사용자와 가까운 리전의 SSH/VNC 전용 Mac mini M4가 있는 NodeMac 요금을 비교하고, 이 런북을 표준 업데이트 후 체크리스트로 쓰세요.
Mac mini M4 하드웨어는 데몬 복구를 지루할 정도로 안정적으로 만듭니다: Apple Silicon 여유 성능으로 게이트웨이, 로컬 헬퍼, 가벼운 자동화가 스왑 지옥 없이 공존하고, 통합 메모리는 로그 스파이크 시 OOM 크래시를 줄입니다. NodeMac은 전용 물리 머신(공유 VM 아님)을 홍콩·일본·한국·싱가포르·미국에서 SSH와 VNC로 제공해 업데이트 직후 원격으로 이 플레이북을 실행할 수 있습니다. 임대는 자본 지출을 피하면서 LaunchAgent 정책을 반복하기 좋고, 플랫폼 도움말과 함께 플릿 전체 접근 위생을 유지하기에 맞습니다.