OpenClaw macOS 트러블슈팅 2026
OpenClaw는 데몬이 안정적으로 떠 있을 때는 마법처럼 느껴지지만, macOS 업데이트 후 조용히 종료되거나 TCC 권한을 잃거나 게이트웨이 포트에서 충돌이 나면 곧바로 답답해집니다. 이 글은 이미 기준 설치를 마친 엔지니어(자세한 내용은 전체 설치·배포 가이드 참조)를 위해 재현 가능한 사고 대응 절차를 정리합니다. 처음 15분에 무엇을 확인할지, 어떤 로그가 중요한지, 헤드리스 구성의 VmMac Mac mini M4 노드를 어떻게 강화해야 야간 장시간 워크로드에서도 에이전트가 살아남는지를 다룹니다.
증상 매트릭스, launchd 체크리스트, 포트·권한 복구 단계와 함께 도움말 문서, GUI 전용 프롬프트를 위한 VNC 접근, 단일 데몬을 넘어 확장할 때의 멀티 에이전트 오케스트레이션 링크를 제공합니다.
첫 15분: 데몬이 「그냥 멈췄을」 때의 분류 체크리스트
아래 순서로 확인하세요. 임대 Mac mini에서 관찰되는 프로덕션 회귀의 약 80%를 포착합니다.
openclaw status(또는 패키지별 게이트웨이 상태 명령) — 표준 출력·표준 오류를 티켓에 그대로 보관합니다.launchctl list | grep -i openclaw— LaunchAgent 로드 여부와 마지막 종료 코드가 있으면 기록합니다.lsof -nP -iTCP -sTCP:LISTEN | grep -i openclaw— 실패한 재시작 후 중복 리스너를 찾습니다.node --version— LaunchAgent를 소유한 동일 macOS 사용자(관리자 계정 아님)에서 v22+인지 확인합니다.- 디스크 압박:
df -h ~— 대용량 트레이스를 쓰는 에이전트는 여유 공간이 5 GB 미만이면 바로 실패합니다.
OPENCLAW_STATE_DIR를 iCloud Drive, Dropbox, OneDrive 안에 두지 마세요. 파일 제공자 잠금은 「데몬 재시작 루프」를 일으키며 메모리 누수처럼 보이지만 실제로는 동기화 경합입니다.
Node.js, PATH, 「SSH에서는 되는데 launchd에서는 안 됨」
LaunchAgent는 최소 환경만 상속합니다. 대화형 SSH에서는 되는데 plist 로그에 command not found: node가 나오는 것이 전형적입니다. 오래 유지되는 수정책:
- 에이전트를 실행하는 동일 macOS 사용자 아래에서
nvm으로 Node 설치; 보안 정책이 허용할 때만 알려진 Node 바이너리를/usr/local/bin/node에 심볼릭 링크. - LaunchAgent plist의
PATH앞에/Users/ci/.nvm/versions/node/v22.x.x/bin과/usr/bin:/bin:/usr/sbin:/sbin추가. - 프로덕션에서 OpenClaw 패키지 버전 고정(
npm install -g [email protected]) — 「항상 latest」와 자동 npm 업데이트 조합은 수요일 아침 장애의 흔한 원인입니다.
대화형 로그인 셸과 sudo -u ci -H bash -lc 'which node'로 만든 비대화형 셸 모두에서 which node && node -p "process.execPath" 결과가 같아야 합니다.
launchd 진단: ThrottleInterval, 종료 코드, 조용한 크래시 루프
작업이 너무 빨리 종료되면 Apple의 launchd가 공격적으로 백오프합니다. 디버깅 중에는 로그 가독성을 위해 ThrottleInterval을 최소 10초로 설정하세요. 최근 크래시는 다음으로 확인합니다.
log show --style syslog --predicate 'process == "launchd"' --last 30m | grep -i openclaw
빠른 재기동이 보이면 일시적으로 에이전트를 unload하고 데몬을 120초 정도 포그라운드에서 실행한 뒤 근본 원인을 고친 다음 reload합니다.
launchctl unload ~/Library/LaunchAgents/ai.openclaw.daemon.plist
openclaw daemon start --foreground
게이트웨이 포트 충돌과 리버스 프록시 문제
증상: 헬스 체크가 들쭉날쭉하고, WebSocket 클라이언트가 1006으로 끊기거나, CI가 간헐적으로 「게이트웨이 도달 불가」를 보고합니다. 2026년 흔한 겹침에는 로컬 Prometheus exporter, 방치된 Docker Desktop 프록시 포트, 이전 사용자 계정에 남은 두 번째 OpenClaw 설치 등이 있습니다.
| 신호 | 가능한 충돌 | 조치 | 검증 |
|---|---|---|---|
| 시작 시 Bind EADDRINUSE | 중복 데몬 또는 떠도는 node 프로세스 | 모든 에이전트 중지; 안전하면 오래된 PID 파일 삭제; 설정에서 새 포트 지정 | lsof -i :PORT가 단일 소유자만 반환 |
| 리버스 프록시에서 502 | 업스트림 TLS 불일치 또는 HTTP/2 다운그레이드 | 프록시에서 TLS 종료; localhost에는 평문 HTTP | curl -sv http://127.0.0.1:PORT/healthz |
| CI에서만 타임아웃 | Runner NAT 헤어핀 | 게이트웨이를 127.0.0.1에 바인딩하고 SSH -L로 터널 |
CI가 터널 경유 curl을 200 ms 이내에 완료 |
| 슬립 후 불안정 | macOS Power Nap 또는 디스플레이 절전 | caffeinate 래퍼 또는 디스크 절전 방지 설정 |
워치독 재시작 없이 가동 시간 48 h 초과 |
TCC: 화면 기록, 손쉬운 사용, 보안 업데이트 후 권한 회수
macOS Sequoia는 소규모 보안 패치 후에도 재검증을 자주 요구합니다. OpenClaw가 손쉬운 사용이나 화면 기록을 잃으면 GUI 자동화가 불투명한 스택 트레이스로 실패합니다. 복구 경로:
- 시스템 설정 → 개인 정보 보호 및 보안에서 영향 카테고리별로 확인합니다.
- 오래된 항목을 제거하고
which openclaw가 보여 주는 정확한 바이너리 경로를 다시 추가합니다. - SSH에서 데몬을 재시작한 뒤 간단한 스크린샷 작업으로 검증합니다.
- 바이너리 경로를 내부 위키에 문서화합니다 — 이 단계를 건너뛰는 팀은 다음 리빌드 후 반드시 다시 깨집니다.
상태 디렉터리, 디스크 증가, 손상된 WAL 파일
중간 부하의 단일 에이전트 호스트는 로그와 작업 산출물으로 주당 약 300–800 MB를 예상하세요. 멀티 에이전트 플릿은 두 배일 수 있습니다. logging.retainDays를 규정에 맞게 7~21일로 두고, 산출물은 VmMac 인스턴스에 제공된 로컬 NVMe에만 두며 네트워크 마운트는 사용하지 마세요.
하드 리부트 후 SQLite나 WAL이 손상되면 손상 디렉터리를 치우고, 마지막으로 알려진 정상 tarball에서 복원(~/.openclaw는 매일 밤 스냅샷해야 함), git에 있는 IaC 스크립트로 설정을 재적용합니다.
24/7 에이전트용 로그 보존 플레이북
| 심각도 | 페이징 시점 | 담당자 조치 |
|---|---|---|
| P1 — 데몬 종료 | 근무 시간 중 계획되지 않은 모든 종료 | plist + 통합 로그 슬라이스 수집; 직전 설정 변경 롤백 |
| P2 — 20분간 작업 실패율 15% 초과 | 지속적인 API 또는 디스크 오류 | 동시성 제한; 공급자 상태 페이지 확인 |
| P3 — 느린 작업 | 6시간 동안 P95 지연이 기준의 2배 초과 | 오래된 워크스페이스 GC; 두 번째 VmMac 노드로 샤딩 |
VmMac 클라우드 Mac mini 노드에서 OpenClaw 강화
노트북 개념 증명에서 홍콩, 일본, 한국, 싱가포르, 미국의 VmMac 프로덕션 노드로 옮길 때는 다른 서버와 같이 취급합니다. 불필요한 공유 서비스를 끄고, SSH는 키만 허용하며, 스테이징과 프로덕션마다 겹치지 않는 포트 대역을 에이전트 플릿에 매핑합니다.
메모리 적정화는 요금 페이지를 참고하세요. 24 GB 통합 메모리는 무거운 에이전트 세 개를 동시에 돌리면서 Xcode 부가 작업 여유를 남깁니다. 16 GB도 가능하지만 maxConcurrentTasks를 더 엄격히 제한해야 합니다.
FAQ: 지원팀이 실제로 필요로 하는 짧은 답
데몬을 root로 돌려야 하나요? 아니요. 최소 권한의 전용 openclaw 또는 ci 사용자를 쓰세요. root는 TCC 프롬프트를 망가뜨리고 감사를 어렵게 합니다.
순수 SSH로 전부 고칠 수 있나요? 대부분 예 — 다만 최초 TCC 승인과 일부 Safari 기반 자동화는 제외입니다. 짧은 VNC 창을 예약하세요.
업그레이드를 안전하게 테스트하려면? 상태를 스냅샷하고 설정을 스테이징 VmMac 노드에 복제한 뒤, 합성 워크로드로 72시간 돌린 다음 승격합니다.
2026년에도 Mac mini M4가 OpenClaw에 적합한 이유
OpenClaw는 서브프로세스 생성, 저장소 읽기, 때때로 네이티브 툴체인 컴파일에 시간을 씁니다. Mac mini M4의 통합 메모리 아키텍처는 이런 작업을 빠르게 유지하고, 구형 Intel mini에서 흔한 PCIe 병목을 피합니다. 민감한 프롬프트를 서드파티 API 밖에 두고 싶다면 Neural Engine 기반 MLX 실험도 가능합니다.
VmMac으로 임대하면 하드웨어 조달·통관 대기·창고형 랙 구축 없이 Apple Silicon 성능을 얻습니다. 이 트러블슈팅 플레이북을 최초 설치 단계 및 멀티 에이전트 확장 가이드와 함께 쓰고, 모델 공급자까지 RTT를 줄이려면 요금 페이지에서 가장 가까운 리전을 고르세요.
