OpenClaw launchd: ThrottleInterval, KeepAlive, 헬스 프로브—2026 임대 Mac mini 매트릭스
플랫폼 엔지니어가 VmMac에서 임대한 Apple Silicon Mac mini 위에 OpenClaw를 LaunchAgent로 돌릴 때, 기본값은 미묘합니다. 크래시 루프를 숨기는 ThrottleInterval, 중독된 프로세스를 되살리는 KeepAlive, 업그레이드 중 Node 게이트웨이 종료 의미와 어긋나는 SuccessfulExit 해석까지요. 이 2026 매트릭스는 안전한 조합, 오탐 재시작 폭풍이 생기는 방식, 헤드리스 헬스 프로브 패턴을 정리하고, 홍콩·일본·한국·싱가포르·미국 동등성과 관측 가능성을 연결합니다. 게이트웨이 복구, 스테이징 대 프로덕션 격리, 구조화 로그와 디스크 로테이션을 함께 읽고 plist 수정이 추측이 되지 않게 하십시오.
기준 경로는 설치 및 배포 가이드, 액세스는 도움말, 캐너리 전용 호스트 분리 비용은 요금을 참고하십시오. Spotlight·mds로 콜드 스타트가 늘어나는지는 인덱싱·CI 디스크 매트릭스와 상관 분석하십시오.
Node 바이너리 버전보다 launchd 정책이 더 중요한 이유
OpenClaw 시맨틱 버전을 완벽히 고정해도, 헬스 프로브가 LLM 지연을 죽음으로 오인해 게이트웨이를 12초마다 다시 띄우면 plist가 SLA 계약의 일부입니다. 성공·실패·백오프를 OS가 어떻게 해석하는지 정의합니다. VmMac에는 하이퍼바이저 감독자가 없으므로 launchd가 감독자입니다.
Node 게이트웨이는 macOS 시그널 의미를 물려받습니다. 배포 중 SIGTERM은 HTTP 서버를 닫고 구조화 로그를 플러시한 뒤 launchd가 SIGKILL로 올리기 전에 종료해야 합니다. 업스트림 WebSocket이 걸려 SIGTERM을 무시하면 대화형 셸에서는 “성공한” 수동 재시작처럼 보이지만 에이전트는 들쭉날쭉해 보입니다. Node LTS를 고정한 README와 같은 문서에 예상 시그널 사다리를 적고, 프로덕션 plist를 건드리기 전 폐기용 VmMac 미니에서 리허설하십시오.
ThrottleInterval은 버그 수정 대체재가 아니라 실패 소음만 바꿉니다. OS 수준 백오프와 함께 애플리케이션 회로 차단기를 짝지어 잘못된 모델 설정이 사고 중 모든 리전에서 CPU를 고정하지 못하게 하십시오. 한국·미국 등 사용자 근처에 게이트웨이를 두더라도 plist 숫자는 동일하게 유지하고, 지연 실험이 필요한 경우에만 문서화된 예외를 두십시오.
- ThrottleInterval: 재시작 빈도를 제한하지만 지속적인 부분 장애를 가릴 수 있습니다.
- KeepAlive: 데몬을 상주시키지만 드레이닝 업그레이드를 복잡하게 합니다.
- ExitTimeOut: SIGKILL 전 우아한 종료에 허용하는 시간입니다.
매트릭스: ThrottleInterval vs KeepAlive vs ExitTimeOut
| 목표 | 주요 손잡이 | 위험 | 완화 |
|---|---|---|---|
| 크래시 루프 중지 | ThrottleInterval ≥ 30초 | 진짜 크래시 후 복구가 느려짐 | 종료 코드로 외부 페이저 병행 |
| 상시 게이트웨이 | KeepAlive true + SuccessfulExit false | 의도적 종료 중에도 재기동 | 별도 유지보수 레이블 사용 |
| 우아한 드레인 | ExitTimeOut 25–40초 | 종료 교착이 재시작을 막음 | 예산 후 watchdog SIGKILL |
| 재부팅 후 떼 재앙 방지 | Staggered StartCalendarInterval 또는 래퍼 난수 슬립 | 피어 대비 준비 지연 | 헬스 게이트는 벽시계가 아니라 의존성 대기 |
같은 사용자 세션에 OpenClaw와 다른 launchd 에이전트를 두면 plist의 Nice와 LowPriorityIO를 고려해 로그 배선기가 게이트웨이 이벤트 루프를 굶기지 않게 하십시오. 용량 계획 대체는 아니지만 부분 장애 중 몇 분을 벌어 ThrottleInterval을 의도적으로 넓히는 대신 실수 폭탄 건강 래퍼와 싸우지 않게 합니다.
오탐 재시작 폭풍: 증상과 근본 원인
폭풍은 디스크 압력으로 모듈 로딩이 늦어진 뒤 게이트웨이가 소켓을 바인딩하기 전에 헬스가 127.0.0.1을 두드릴 때 자주 시작합니다. 또 다른 패턴은 Spotlight나 mds 스파이크가 콜드 스타트를 길게 만들어 프로브 타임아웃을 건드리는 경우입니다. OpenClaw 자체를 탓하기 전에 인덱싱 정책과 상관하십시오.
또 다른 폭풍 패턴은 의존성 플랩입니다. 프로브가 localhost 준비 전에 외부 SaaS를 먼저 확인하면 일본이나 싱가포르의 지역 라우팅 깜빡임이 프로세스는 멀쩡한데 게이트웨이를 비정상으로 표시하게 만듭니다. 프로브를 층으로 나누어 루프백을 먼저 검사하고 외부 캐너리는 더 느슨한 타임아웃으로 선택적으로 샘플링하십시오. 그렇게 하면 launchd가 제어하지 않는 제3자 SLA에 프로세스 수명이 묶이지 않습니다.
디스크 가득 에피소드는 잔인한 크래시 루프 착시를 만듭니다. 게이트웨이가 JSONL을 쓰다 APFS가 ENOSPC를 반환하면 비정상 종료, KeepAlive가 되살리고 로그가 즉시 다시 실패합니다. 종종 ThrottleInterval이 시스템을 식히기 전보다 빠릅니다. 구조화 로그 로테이션의 디스크 가드레일을 미러링해 재시작이 “올바른 이유”로만 느려지게 하십시오.
VNC 없이 동작하는 헤드리스 헬스 프로브 패턴
작은 래퍼가 루프백에서만 TLS 검증을 끈 curl로 헬스 포트를 두드리거나, 버전이 노출한다면 OpenClaw 자체 CLI 상태 명령을 호출하는 편이 낫습니다. 프로브 후 HTTP 상태, TLS 핸드셰이크 ms, PID를 로그에 남겨 온콜이 “프로세스는 살아 있지만 멈춤”과 “프로세스 다운”을 구분하게 하십시오.
가능하면 합성 X-Probe-Trace-Id 헤더를 쏘고 게이트웨이 로그에 에코해 프로브 실패와 느린 쿼리를 한 줄로 꿰맵십시오. 이 상관 한 가지가 plist 조정보다 더 많은 Sev2를 끝냈습니다. launchd가 가진 데이터로 올바르게 행동했는지 증명하기 때문입니다.
curl -fsS --max-time 3 http://127.0.0.1:18789/health || exit 1
2026년 여덟 단계 튜닝 사다리
- plist를 바꾸기 전 7일간 기준 종료 코드를 수집합니다.
- 20초 미만 재시작 패턴을 멈추도록 ThrottleInterval을 둡니다.
- 문서화된 우아한 종료 SLA에 ExitTimeOut을 맞춥니다.
- 재시작 사유마다 구조화 로그를 추가합니다.
- 한 VmMac 리전에서 72시간 캐너리를 돌립니다.
- 홍콩·일본·한국·싱가포르·미국 재시작 횟수를 비교합니다.
- 롤백 plist를 git 태그
launchd-YYYYMMDD에 문서화합니다. - 분기별 게임 데이:
kill -9후 복구 시간을 측정합니다.
4단계와 5단계 사이에 지표가 녹색이어도 72시간 동안 캐너리 레이블의 기능 작업을 멈추십시오. 주말 트래픽 형태에서만 나타나는 재시작 폭풍이 많습니다. 캐너리 기간에 sample과 footprint 스냅샷을 남겨 VmMac 리전 간 메모리 회귀를 추측하지 않게 하십시오.
이 매트릭스가 게이트웨이 복구 런북과 맞닿는 방식
복구 글은 무엇을 재시작할지 설명하고, 이 매트릭스는 OS가 언제 대신 재시작해야 하는지를 설명합니다. 숫자가 어긋나면 사람이 신뢰를 잃고 kill -9 습관으로 갑니다. 스테이징 격리에 따라 스테이징과 프로덕션에서 같은 수치 손잡이를 유지해 승격이 부족이 아니라 diff 가능하게 하십시오.
관측 표: 재시작마다 무엇을 로그할지
| 필드 | 목적 |
|---|---|
launchd_exit_status |
OOM과 깨끗한 종료 구분 |
uptime_s |
유아 사망 루프 탐지 |
rss_mb |
SIGKILL 전 누수와 상관 |
fds_open |
keepalive가 증폭하는 디스크립터 누수 포착 |
last_http_5xx_ts |
업스트림 장애와 로컬 죽음 분리 |
이 필드를 게이트웨이 요청과 같은 싱크의 JSON 라인으로 보내 SRE가 “launchd가 작업을 재시작했다”에서 “RSS가 기준 1.2배를 넘겨 재시작했다”로 피벗하게 하십시오. 첫 반복에서 완벽한 카디널리티보다 홍콩·일본·한국·싱가포르·미국 전반에 필드 이름이 같다는 것이 더 중요합니다.
FAQ: Mac mini의 launchd와 OpenClaw
LaunchDaemon 대 LaunchAgent? 명시적 보안 검토 없이는 전환하지 마십시오. 에이전트는 여러분이 의존할 사용자 TCC 경계를 물려받습니다.
리전마다 튜닝? 서면 예외가 있을 때만이고 기본은 동등성입니다.
업그레이드는? npm 마이그레이션 동안 ThrottleInterval을 일시적으로 넓히십시오.
SuccessfulExit false가 항상 “어떤 종료든 재시작”인가요? 대부분의 게이트웨이에서 사실상 그렇습니다. 드레인 완료와 크래시를 구분하는 애플리케이션 종료 코드와 짝지지 않으면 블루/그린 배포가 launchd와 싸웁니다.
헬스 프로브를 root로? 파일 권한과 키체인·TCC 가정이 맞도록 게이트웨이와 같은 사용자를 선호하고, 읽기 전용 프로브가 정말 필요할 때만 상승하십시오.
알림을 알려진 유지보수 동안 끄려면? 래퍼가 실패하기 전에 확인하는 유지보수 파일을 켜고, 긴 주말에 잊히지 않게 자동 만료하십시오.
Mac mini M4와 VmMac이 상시 게이트웨이에 맞는 이유
Mac mini M4는 공격적인 프로브에 걸리기 전에 가끔 있는 콜드 스타트를 흡수할 만큼 지속 성능을 주고, 통합 메모리는 과도하게 구독된 VPS보다 OOM 플랩을 줄입니다. VmMac은 홍콩·일본·한국·싱가포르·미국에 게이트웨이를 사용자와 데이터 상주 요구 가까이 두고, 프로덕션 재시작 의미를 위험에 빠뜨리지 않고 plist 실험용 두 번째 미니를 임대할 수 있게 합니다.
임대는 Apple이 macOS 보안 패치로 launchd 동작을 미묘하게 바꿀 때 피드백 루프를 짧게 합니다. plist 매트릭스를 스냅샷하고 비프로덕션 미니에 패치를 적용한 뒤 같은 헬스 프로브 하네스를 재생해 고객 자동화를 건드리기 전에 검증하십시오. 문서화되지 않은 재시작 정책 변경으로 생긴 야간 온콜 한 번보다 저렴합니다.
