2026년 OpenClaw: 다중 Provider 장애 조기 전환과 429/5xx 지수 백오프 — 게이트웨이 라우팅, 타임아웃 분할과 독점 원격 Mac SSH 재현 가능 트러블슈팅 체크리스트 + FAQ

한눈에 보는 핵심

요지: Provider는 계약이 아니라 불안정한 버스입니다. 게이트웨이가 경로를 고르고, 건강도를 재며, Mac의 파일 디스크립터나 큐가 막히기 전에 부하를 덜어내야 합니다.

• 라우팅: 바깥 API는 안정적으로 유지하고, 논리 모델명 → 실제 Provider ID 매핑은 한곳에만 둡니다. 페일오버 때 클라이언트 재배포가 필요 없게 합니다.
• 429: 서버 힌트를 따릅니다. Retry-After(초 또는 HTTP-date)를 파싱하고, 그 위에 전체 지터(full jitter)를 얹으며, 키당 동시성 상한을 겁니다.
• 5xx: 짧은 시도와 지수 백오프, 회로 차단(circuit breaker)을 함께 씁니다. 같은 죽은 업스트림에 열 번 물지 말고 보조 Provider로 빨리 넘깁니다.
• 타임아웃: 연결·TLS·첫 바이트(TTFB)·엔드투엔드 도구 예산을 나눕니다. 거대한 단일 타임아웃은 어느 홉이 멈췄는지 가립니다.
• SSH Mac: 버전을 고정하고, 요청마다 correlation ID를 로그에 남기며, CI가 쓸 것과 동일한 curl을 재생합니다. 독점 단일 머신이면 경합이 읽기 쉽습니다.

1. 다중 Provider 토폴로지: 게이트웨이 하나, 업스트림 여럿

탄력 있는 구성은 Mac 위에 하나의 리스너(또는 HA를 위해 밀접한 한 쌍)를 둡니다. IDE 확장·CLI 에이전트·자동화는 여러분의 호스트명으로만 말합니다. 게이트웨이 안의 라우터 표가 요청마다 어느 업스트림이 응답할지 정합니다: 주 클라우드 API, 보조 벤더, 로컬 Ollama, 또는 저비용 트리아지 모델.

스킬·셸 스크립트 곳곳에 Provider URL을 흩뿌리지 마세요. 엔드포인트나 모델 문자열이 바뀔 때 설정 한 번 리로드로 끝내야 합니다.

2. 건강 신호: 언제 페일오버할까(하지 말아야 할 때)

2.1 강한 신호

• 키 순환 뒤의 401/403 — 맹목적으로 넘기지 말고 자격 증명을 먼저 고칩니다.
• 할당량 의미가 분명한 429 — 실패한 요청만이 아니라 해당 키 전체를 느리게 합니다.
• 연쇄 5xx나 연결 리셋 — 짧은 지수 재시도 후 회로를 열고 대체 업스트림으로 보냅니다.

2.2 약한 신호

• 상태는 200인데 p95 TTFB만 오름 — 붕괴 직전일 때가 많습니다. 일찍 부하를 덜어냅니다.
• 스트림이 도구 중간에 끊김 — 청크 경계를 로그에 남기고 업스트림 점검 창과 비교합니다.

3. 백오프 설계: 429 대 5xx

429(Too Many Requests): 기다리라는 뜻입니다. API 키마다 토큰 버킷을 두고 Retry-After를 파싱합니다. 헤더가 없으면 보수적인 기본 지연(예: 1–2초)에서 시작해 [0, d] 전체 지터를 더해 프로세스 간 떼 지르기(thundering herd)를 막습니다.

5xx·네트워크 오류: 작은 재시도 예산(예: 2–4회)과 지수 백오프·지터를 씁니다. 회로 차단과 짝을 이룹니다: 창 W 안에 N번 실패하면 M분 동안 신규 트래픽을 보조 Provider로 보내고, 한 번의 프로브만 다시 보냅니다.

계층마다 재시도를 곱하지 마세요. CLI·게이트웨이·리버스 프록시가 모두 재시도하면 자기 DDoS가 됩니다. 재시도 주인은 한 층으로 정하고, 아래층은 구조화된 오류로 빨리 실패하게 합니다.

4. 2026년 트래픽 스파이크에서도 버티는 게이트웨이 라우팅

• 필요할 때만 스티키: 대화 기억은 저장소에 두고, 우연히 한 업스트림 파드에 의존하지 않게 합니다.
• 카나리 가중치: 새 Provider에 5%만 실어 본 뒤 설정에서 primary 포인터를 바꿉니다.
• 결정적 저하: 프리미엄이 모두 빨간색일 때 "최소 동작 모델" 경로를 정의합니다. 30분 걸리는 hang보다 짧고 정직한 응답이 낫습니다.

5. 타임아웃 분할: 어느 홉이 범인인지

모든 타임아웃을 한 손잡이에 몰면 어느 홉에서 멈췄는지 영원히 가려져 오진합니다. 측정 가능한 단위로 나눠 설정합니다.

• 연결 + TLS(정상 경로에서는 보통 수 초).
• 헤더 송신 후 첫 바이트(TTFB), 스트리밍 채팅 완성에 특히 중요합니다.
• 엔드투엔드 사용자 예산 — Mac에서의 도구 실행과 디스크 I/O까지 포함합니다.
• 청크 사이 유휴 — 클라이언트가 침묵을 실패로 볼 때 필요합니다.

네 구간 모두에 동일 correlation ID를 남깁니다. SSH 위에서도 운영 경로와 같은 터널로 curl -w '%{time_connect} %{time_starttransfer} %{time_total}\n'을 재생합니다.

6. 재현 체크리스트: SSH로 붙는 독점 원격 Mac

1. 버전 고정: openclaw·게이트웨이 패키지·Node 버전을 plist나 compose 옆에 커밋되는 파일에 기록합니다.
2. 설정을 Git에: Provider 표, 타임아웃, 재시도 상한 — 서버에만 손으로 남는 prod 전용 diff는 금지합니다.
3. launchd 로그: stdout/stderr 경로와 로테이션; 지원되면 JSON 로그에 correlation ID를 넣습니다.
4. 결함 주입: 노트북에서 Mac의 /etc/hosts로 primary 호스트명을 잠시 막거나, 할당량 0인 테스트 키로 429를 강제해 페일오버 지표가 기대대로 움직이는지 확인합니다.
5. 리플레이 스크립트: 짧은 채팅·긴 컨텍스트·도구 집약 세 가지 요청을 저장해 매 업그레이드 후 실행합니다.

7. FAQ — 증상 → 먼저 볼 것

게이트웨이·도구까지 한 대에 올릴 때 Mac mini가 유리한 이유

라우팅·백오프·로그 상관은 결국 안정적인 단일 호스트에서 가장 읽기 쉽습니다. Apple Silicon 통합 메모리는 동시 스트림과 작은 모델 사이드카를 한 칩에서 감당하고, macOS는 장시간 무인 가동에 익숙하며, Gatekeeper·SIP·FileVault는 상용 Windows 워크스테이션 대비 악성코드 표면적을 줄입니다. Mac mini M4급은 대기 전력이 매우 낮아 게이트웨이를 24/7로 켜 두어도 전기 부담이 작습니다.

OpenClaw 스타일 스택에서 Provider 폭풍을 견디려면 재현 가능한 SSH 런북과 저전력·저소음 하드웨어가 같이 가야 합니다. 팀이 동일 체크리스트를 복제할 준비가 됐다면, 2026년 기준으로도 Mac mini M4는 여전히 균형이 좋은 시작점입니다. 요금과 구성은 홈에서 바로 비교해 보세요.