2026 원격 Mac에서 OpenClaw와 Ollama/vLLM 동거: 포트, 헬스 체크, 리소스 경합, 기동 순서 Runbook

약 16분 · MACCOME

임대하거나 직접 관리하는 원격 Mac에서 OpenClaw Gateway와 Ollama 또는 로컬 vLLM을 한 호스트에 올릴 때, 실패 원인은 대개 «모델 문자열 오류»가 아니라 포트·프로브 순서·통합 메모리와 CPU 경합·기동·중지 규율이 겹친 결과입니다. 본 글은 오프라인 프라이빗 모델 분기 글과 역할을 나눕니다. 그 글은 API 브리지·컨텍스트·무반응을 다루고, 본 글은 동일 기계 토폴로지 Runbook만 제공합니다. 리스너 분리, healthz 이전에 검증할 층, 과부하 시 먼저 모델을 낮추고 Gateway를 건드리는 이유를 정리할 수 있어야 합니다.

동거 시 자주 보이는 다섯 가지 «가짜 장애»

  1. 포트 충돌: Ollama 기본 11434, 흔한 vLLM 8000, OpenClaw Control UI는 보통 18789입니다. 로컬에 리버스 프록시나 사이드카를 더하면 이중 점유가 잘 납니다.
  2. 프로브 순서 뒤바뀜: Gateway는 200인데 provider가 준비되지 않은 추론 엔드포인트를 가리키면 UI는 열리고 대화만 비어 보입니다.
  3. 통합 메모리 독점: 가중치·Metal/ANE·Node 버퍼가 동시에 차면 CPU 그래프는 한산해도 체감만 느려집니다.
  4. 동거 I/O와 써멀: 장시간 추론이 팬과 열 제한을 고정하고, Xcode급 빌드와 에이전트가 한 호스트에 있으면 지터처럼 보입니다.
  5. 업그레이드 경쟁 상태: Gateway만 먼저 올리거나 반대로 모델만 먼저 바꾸면 저장된 base URL·토큰·실제 리스너가 갈라집니다. Docker 경로는 공식 Docker와 Control UI 글을 참고합니다.

포트와 책임: 변경 티켓에 붙일 표

리뷰 표에 그대로 넣어 «구술로 8000»이 세 번째 주에 다른 서비스에게 빼앗기는 일을 막습니다.

구성 요소 일반적인 기본값 OpenClaw 접점
Ollama 기본 HTTP 127.0.0.1:11434. LAN 공개는 명시적 바인드와 방화벽 설계가 필요합니다. provider baseURL은 OpenAI 호환 /v1로. 헬스 없는 맹목 리버스 프록시는 피합니다.
vLLM(로컬) 흔히 8000 또는 자체 포트. 여러 인스턴스는 포트와 GPU/스레드 풀을 나눕니다. Ollama와 같이 /v1/models와 최소 completion을 Gateway 연결 전에 실제로 통과시킵니다.
OpenClaw Gateway Control UI는 종종 18789. 실제 openclaw 설정을 따릅니다. 먼저 healthz/readyz, 그다음 provider. 세부는 Gateway·모델 분기입니다.

여섯 단계: 서명 가능한 기동·검증 순서

  1. 리소스 예산 한 줄: 추론 프로세스의 상한 메모리·동시 요청과 Gateway+Node 예비를 표에 적습니다. M4급에서는 OS와 디스크 캐시를 위해 RAM 10–20% 여유를 두는 편이 안전합니다(모델에 맞게 조정).
  2. 추론 먼저, provider는 나중: Ollama/vLLM 리스닝이 안정된 뒤 curl로 최소 chat/completions를 확인하고, 이어서 Gateway를 기동하거나 reload하여 «미준비»가 상태로 고정되지 않게 합니다.
  3. 포트와 루프백 정책 고정: 로컬 호출만 있으면 127.0.0.1 우선. 컨테이너가 호스트를 써야 하면 bridge와 담당자를 문서화합니다.
  4. 이중 프로브: 1층은 추론(HTTP+최소 생성), 2층은 Gateway healthz, 3층은 대화 E2E. 어느 층이든 빨간색이면 프로덕션 트래픽을 올리지 않습니다.
  5. 핫 변경 규율: 가중치·이미지 교체 시 대화를 드레인하고, 필요하면 Gateway 인그레스를 내리거나 읽기 전용으로 둡니다. 모델 교체 후 Gateway를 올리고 이중 프로브를 반복합니다.
  6. 롤백: 이전 가중치 경로와 이전 provider 블록을 보존합니다. 여러 항목이 한 번에 움직이면 «추론 → Gateway» 순으로 층별 롤백합니다. doctor 해석은 설치 후 doctor에서 Mac 호스트에 해당하는 절을 봅니다.
bash
# 최소 프로브 순서 예(호스트·포트 치환)
curl -sS "http://127.0.0.1:11434/api/tags" > /dev/null   # Ollama 생존
# curl -sS "http://127.0.0.1:8000/v1/models" > /dev/null  # vLLM
curl -fsS "http://127.0.0.1:18789/healthz"                 # Gateway
# 이어서 최단 대화 또는 문서에 적힌 openclaw doctor

온콜 문서에 넣을 세 가지 단단한 수치(실측으로 교체)

  • 첫 토큰 지연과 큐: 콜드 로드 후와 핫 상태의 P95를 나눕니다. 핫인데도 CPU가 낮은데 수 초를 넘기면 먼저 통합 메모리 압력과 스와핑을 보고, 동시성만 올리지 않습니다.
  • 동거 이중 부하: 대형 Xcode·모노레포 빌드와 24/7 에이전트가 싸우면 OOM이나 극도로 느린 토큰이 전형적입니다. 시간대·큐·전용 빌더가 모델 이름만 바꾸는 것보다 저렴합니다.
  • 키프얼라이브와 타임아웃: 긴 스트림에서 추론 구간과 클라이언트 구간 중 한쪽만 짧으면 중간 끊김처럼 보입니다. 쌍으로 바꾸고 변경 번호를 남깁니다.

노트북 «수동 운용»과 무관리 공유 호스트가 동거에 지는 이유

수면·깨우기, 가정용 uplink 흔들림, 예측 불가한 이웃 때문에 재현 가능한 기동·프로브가 확률이 됩니다. Ollama+Gateway 동거는 안정적인 열 경계와 예측 가능한 I/O가 필요합니다. 에이전트와 추론을 전용·24/7·메모리와 디스크를 계약에 쓸 수 있는 원격 환경으로 옮기는 편이 장기 튜닝보다 MTTR을 줄이기 쉽습니다. 본 Runbook을 프로덕션에 얹을 때 MACCOME 클라우드 Mac은 전용 Apple Silicon과 회계에 맞는 임대 형태로 리소스 표와 변경 관리를 다투게 하고, 개인 기기와 공유 호스트의 비재현성을 줄입니다.

첫 주에 하지 말 것

단일 completion이 검증되기 전에 Gateway 동시성만 두드리지 마십시오. 추론 포트가 다른 서비스에 잡혔는지 보기 전에 Gateway 버전만 올리지 마십시오. 두 번 깔끔하게 자르는 것이 열 페이지의 구전보다 새벽 전화를 줄입니다.

FAQ

오프라인 Ollama/vLLM 글과 어떻게 나눕니까?

그 글은 API 브리지·컨텍스트·무반응 분기입니다. 본 글은 동일 기계의 포트·프로브·리소스·기동 순서입니다. 오프라인 분기와 Gateway 분기를 함께 보십시오.

Gateway는 Docker, Ollama는 호스트이면 «동거»입니까?

논리적으론 한 기계입니다만 네트워크는 명시해야 합니다. host.docker.internal 또는 브리지 IP와 방화벽 검수까지 적습니다. 출발점은 Docker 프로덕션 배포와 공식 Docker 글입니다.