macOS에서 OpenClaw 게이트웨이 복구: 에이전트 기반 재시작 실패와 2026년 LaunchAgent 강화
렌탈 Apple Silicon Mac mini에서 OpenClaw를 돌리는 플랫폼 엔지니어는 에이전트, CI 훅, 챗옵스 봇으로 게이트웨이 재시작을 걸다가, 터미널에 같은 명령을 치면 성공하는데 자동화에서는 실패하는 경우를 늘리고 있습니다. 2026년 공개 이슈 스레드가 강조하는 것은 깨진 게이트웨이 바이너리가 아니라 컨텍스트 격차입니다. 누락된 PATH, 잘못된 작업 디렉터리, 충족되지 않는 TTY 가정, 동기화 클라우드에 둔 상태 디렉터리입니다. 이 글은 Mac mini에 OpenClaw 설치 및 배포, 데몬 및 포트 문제 해결, 헤드리스 대 GUI 세션 규율과 맞춘 재현 가능한 복구 런북으로, 홍콩·일본·한국·싱가포르·미국의 VmMac 리전을 전제로 합니다.
SSH 연결 후에도 OpenClaw를 살리는 방식이 대부분 LaunchAgent가 소유한 게이트웨이이므로 그에 초점을 둡니다. 로그인 항목이나 임시 nohup 프로세스는 범위 밖입니다. 다음 재부팅까지 실패를 숨깁니다.
「터미널에서는 되고 에이전트에서는 실패」 분류
모든 인시던트를 세 필드 diff로 시작합니다. 두 컨텍스트에서 whoami, pwd, printenv PATH를 캡처합니다. 에이전트는 같은 사용자라도 환경이 잘립니다. OpenClaw CLI는 PATH의 node 등으로 셸아웃할 수 있어, /opt/homebrew/bin이 없으면 수동 실행은 성공하는데 재시작만 들쭉날쭉해 보입니다.
- 비대화형 셸:
.zprofile이 소스되지 않습니다. 필요한 export는 plist의EnvironmentVariables딕셔너리로 옮깁니다. - 키체인 잠금 해제: 무인 재시작은 프롬프트를 클릭할 수 없습니다. 통제된 유지보수 창에서
security로 사전 프로비저닝합니다. - ThrottleInterval 충돌: 빠른 재시작 루프는
launchd백오프에 걸립니다. 수치 조정은 문제 해결 글을 참고하세요.
컨텍스트 드리프트를 없애는 LaunchAgent plist 필드
2026년 OpenClaw 게이트웨이에 필요한 최소 plist 위생:
- ProgramArguments는 절대 바이너리 경로만. PATH를 명시하지 않는 한
openclaw단독 명령은 피합니다. - WorkingDirectory는 로컬 비동기 폴더(예:
/Users/laneuser/openclaw-run)를 가리킵니다. - StandardOutPath와 StandardErrorPath는 사후 분석을 위해 같은 로컬 트리 아래에 둡니다.
- ThrottleInterval은 상류 웹훅이 재시작을 몰아칠 수 있으면 10 이상.
재설치 전 증상 대응 매트릭스
| 증상 | 유력한 원인 | 첫 조치 | 에스컬레이션 |
|---|---|---|---|
stderr에 command not found: node |
LaunchAgent의 PATH | EnvironmentVariables에 Node 절대 경로 추가 | plist에서 fnm/asdf로 Node 버전 고정 |
| 게이트웨이가 뜬 뒤 5초 미만에 종료 | 포트 충돌 또는 잘못된 토큰 파일 | 문제 해결 가이드의 포트 표와 비교 | 시크릿 회전 + 재부팅 |
| PID 파일은 있는데 프로세스 없음 | 크래시 루프 / OOM | 통합 메모리 압력 로그 확인 | 동시 에이전트 축소 또는 SKU 상향 |
| 에이전트가 트리거한 재시작만 실패 | cwd 또는 샌드박스 프로필 | WorkingDirectory + 로그 래퍼 설정 | 서비스 강제 재설치 |
강제 게이트웨이 서비스 재설치(복구 경로)
plist 수술이 실패하면 사용자 에이전트를 깨끗이 launchctl bootout한 뒤 벤더 지침에 따라 강제 게이트웨이 설치를 따릅니다. 플래그는 상류 릴리스 노트에 맞춰 변하지만 순서는 항상 중지 → 에이전트 제거 → 재설치 → 검증 → 재활성화입니다. 변경 관리를 위해 OpenClaw 바이너리와 구성 템플릿의 전후 체크섬을 캡처합니다.
상태 디렉터리 배치와 동기화 폴더 리스크
2026년 커뮤니티 글은 반복해서 OpenClaw 상태를 iCloud Drive, Dropbox, OneDrive에 두지 말라고 경고합니다. 파일 공급자 가상화가 부분 쓰기를 만들어 손상된 게이트웨이 상태처럼 보입니다. 상태는 로컬 APFS에 두고 라이브 동기화 대신 객체 스토리지로의 명시적 아카이브로 백업합니다. 이전에 Dropbox로 심볼릭 링크했다면 링크를 제거하고 로컬 디렉터리를 다 만든 뒤 서비스 정의를 재설치합니다.
복구 후 검증 체크리스트
- 헤드리스 헬스: VNC 없이 SSH에서 로컬 게이트웨이 헬스 엔드포인트를 curl합니다.
- 웹훅 리플레이: 스테이징에서 서명된 테스트 페이로드를 보냅니다.
- 로그 전달: JSON 라인이 60초 안에 수집기에 도달하는지 확인합니다.
- 페일오버 리전: 호스트가 미국이어도 고객이 일본이면 완료 선언 전에 합성 RTT를 돌립니다.
웹훅 수신 강화는 웹훅 게이트웨이 글과 대조해 복구가 베어러 토큰 공백을 다시 열지 않게 하세요.
FAQ: 클라우드 Mac mini 게이트웨이 복구
터미널 재시작은 되는데 에이전트는 실패하는 이유? 환경이 다릅니다. PATH, cwd, TTY, 키체인 프롬프트. LaunchAgent에 모두 명시하세요.
상태를 iCloud에 둘 수 있나요? 아니요. 잠금 경쟁을 피하려면 로컬 APFS 경로를 씁니다.
잘못된 업그레이드 후 첫 명령? 라벨 bootout, 벤더 문서에 따른 서비스 강제 재설치, 헤드리스 검증 후 다시 bootstrap.
2026년 VmMac의 Mac mini M4가 게이트웨이 복구 루프를 단순화하는 이유
복구의 일부는 녹색까지의 시간입니다. Apple Silicon Mac mini M4는 노트북급 서멀에서 스크립트 중간에 스로틀 걸리는 것보다 재설치와 콜드 스타트 점검을 더 빨리 끝냅니다. 홍콩·일본·한국·싱가포르·미국에 병렬 호스트를 렌탈하면 깨진 레인이 재부팅하는 동안 웜 스탠바이 레인을 유지해 고객에게 보이는 다운타임을 줄입니다. 메탈 근접과 엄격한 LaunchAgent 위생, 로컬 전용 상태를 짝지으면 OpenClaw 게이트웨이는 「내 SSH 세션에서는 된다」는 유령에서 벗어납니다.
