OpenClaw gateway circuit breakers for flaky upstream tools: failure thresholds, half-open probes, metrics hooks, coordination with HTTP 429 Retry-After and token throttles, read-timeout diagnostics, health monitoring, and macOS rehearsal on cloud Mac mini

에이전트 게이트웨이는 모델, 벡터 저장소, 맞춤 HTTP 도구로 요청을 나눕니다. 상류가 흔들릴 때 단순 재시도는, 이미 병든 의존성으로 가는 트래픽을 곱절해 장애를 키웁니다. 2026년 운영 OpenClaw는 지수 백오프와 함께 서킷 브레이커를 써서 제한된 오류 예산을 넘으면 닫힘→열림으로 식히고, 반쯤 열린 상태에서 소량의 탐침으로 복구를 확인한 뒤 다시 전부 받아들입니다. 이 글은 실무 임계값, 반쯤 열림 박자, Prometheus에 내보낼 지표, 429와 Retry-After 협응, 테넌트별 토큰 예산, 읽기 타임아웃·걸림 진단과 합성 헬스 점검이 왜 “열려 있는데도 정상 같다”는 착시를 끊는지를 정리합니다. 429·Retry-After 처리, 토큰·스로틀, 읽기 타임아웃, 가용성 모니터링과 함께 읽으세요.

비용 측면에서, 전용 Mac mini(MacHTML 약 하루 16.9 US달러)로 게이트웨이 동작을 리허설하는 것은, 회복 중인 상류를 반쯤 열린 폭풍이 다시 두드리는 사고 대비에 비해 대개 저렴합니다.

서킷 없이 재시도하면 운영이 왜 무너지는가

재시도는 일시 오류를 가정합니다. 상류가 락 폭풍, 인증서 만료, 지역적 패킷 손실처럼 지속될 때는, 매 재시도가 가장 숨이 막히는 지점에만 부담을 더합니다. 하나의 제스처가 여섯 개 도구를 동시에 부를 수 있고, 도구마다 200ms 간격으로 세 번이면, 한 제스처에 18번의 실패 호가 쌓일 수 있습니다. 서킷 브레이커는 냉각이 끝날 때까지 이런 반복 실패를 빠른 국지 실패로 돌려 피해를 제한합니다.

OpenClaw는 동기 HTTP와 스트리밍 호출이 섞입니다. 브레이커는 의존성 단위로 두고 프로세스 전체만 쓰면 안 됩니다. 불안한 CRM 조회 API만 끊되, 동일 풀의 정상 도구(계산기)까지 잠가선 안 됩니다(소켓이 실제로 겹칠 때만). 키 이름은 공급자, 리전, 자격 증명 지문을 넣어 실수로 묶이지 않게 합니다.

닫힘, 열림, 반쯤 열림

닫힘: 모든 요청이 계측을 유지한 채 상류로 갑니다. 임계를 넘기면 열림: 이후 호출은 빨리 구조화된 “의존성을 쓸 수 없음” 오류로, 상위 플래너가 전략을 갈아탈 수 있게. 역사 p95 복구 시간에 기반한 휴지 후 반쯤 열림으로, 소량의 탐침만 흐릅니다. 연속된 성공이 닫힘을 되돌리고, 실패는 더 긴 쿨다운로 다시 열립니다.

enum BreakerState { Closed, Open, HalfOpen }

func (b *Breaker) Allow(now time.Time) bool {
  switch b.state {
  case Open:
    if now.Sub(b.openedAt) < b.cooldown { return false }
    b.state = HalfOpen
    b.probeBudget = 1
    return true
  case HalfOpen:
    return b.probeBudget > 0
  default:
    return true
  }
}

임계·슬라이딩 윈도

출발은 관측 트래픽, 블로그의 마법 수가 아닙니다. HTTP 도구엔 30초 창과, 비율을 보기 전에 최소 20회 시도를 기록합니다. 열 조건은 (A) 연속 5회 전송 실패, 또는 (B) 창 안에 샘플의 60%를 넘는 5xx. 연속은 전면 정지를 빨리, 비율은 국지적 악화를 잡습니다.

스트리밍 경로는 분류를 흐리지 마십시오. 토큰을 보낸 뒤의 중간 리셋은 과금 쟁점이어서, 브레이커 대상이 아닐 수 있습니다. “헤더가 끝내 도착하지 않은 경우”와 “40%쯤에서 끊긴 경우”를 별도 계수로 둡니다.

탐침·동시성

반쯤 열림이 가장 위험합니다. 탐침이 너무 많으면, 피하려던 떼 지름길이 다시 옵니다. 의존성마다 250ms에 비행 중 호출 1개, 지터는 50ms까지, 닫힘을 완전히 풀려면 서로 다른 워커의 연속된 두 번 성공을 요구합니다. 12개의 워커를 쓰면, 호스트가 각자 찌르지 않도록 Redis 작은 셀 또는 리더 선출로 직렬화하십시오.

Prometheus / SLO

최소: 의존성에 라벨이 붙은 breaker_state 게이지, breaker_transitions_total(from·to 라벨), 열린 동안의 즉시 거절 breaker_rejections_total, breaker_probe_latency_ms 히스토그램(25ms~2s 범위). 기존 요청 지연 히스토그램과 겹쳐, 전이 전에 지연이 올랐는지 봅니다. 라벨은 저카디널(이름, 리전, 환경)로 유지하십시오. 재시도·할당 정책이 연장만 시킨 흔적을 구분하려면 별도의 계열이나 사후검수 노트에 그 경로를 밝혀 둡니다.

보조: 실제 장애가 아닌, 할당량·Retry-After이 연장한 분을 나누는 계열.

# HELP breaker_state 0=closed 1=half_open 2=open
breaker_state{dep="crm_search"} 2
breaker_rejections_total{dep="crm_search"} 184

HTTP 429·Retry-After

상류가 429와 Retry-After: 120을 보내면, 그 식힘이 우선권을 가집니다. 국지 창이 먼저 반쯤 열림을 밀어 넣더라도, 120초 이상 열 냉각을 연장합니다. breaker_retry_after_skips_total 같은 별도 계기로, 이진 실패가 아닌, 할당량 휴지로 연장이 얼마나 자주 생겼는지 보이게 합니다. 세부: 가이드.

토큰·스로틀

토큰은 지출, 브레이커는 병. 신호는 교환되어야 합니다. 모델 A에서 열렸다면, A에 고정된 계획의 효율 쿼터를 깎고 B로 돌립니다. 보내기엔 애초에 실패할 뻔한 쿼터를 태우지 말고요. 끊긴 스트림 이중 과금 방지 문서에 구체적 배선이 나옵니다.

읽기 제한·걸림

긴 도구의 정당한 늦음이 얇은 읽기 한도 때문이라는 이유만으로, 단정 열지 마십시오. context deadline exceeded와 peer 리셋을 갈릅니다. 걸림 글. 반쯤 열림의 읽기 마감은, 본래 P99에 40% 안전을 더한 수준으로.

합성·게이지

합성 헬스는 고정된 캐너리 끝점을 얻습니다. 브레이커는 실제 사용 트래픽 믹스를 봅니다. 둘 다 갖는 편이 안전합니다. 드문 코드가 깨진 샤드에만 맞닿는 동안, 캐너리는 정상이어도, 브레이커는 끊깁니다. 반대로 짧은 스파이크는 캐너리는 통과하고 브레이커만 멈췄을 수 있습니다. 헬스 모니터와 서킷 게이지가 3분 넘게 엇갈리면 온콜을.

서킷·스로틀·큐

장치	주요 목적	쓰는 신호	사용자 효과
서킷	상류 보호	5xx, 연쇄	빠른 실패+다음 힌트
토큰 스로틀	예산	분·티어	저가 모델
요청 큐	부하 완화	대기열 깊이·지연	느려지지만, 즉시 5xx는 덜

macOS

launchctl로 통신 녹취를 초당 10 건, 5분 재전송하고, 이어 503을 주입합니다. Linux 컨테이너와 keepalive/타임아웃 규율이 조금씩 달라, macOS·클라우드 Mac에서 반쯤 열림 냉각이 “리눅스 전제”와 엇갈리지 않는지 확인이 필요합니다.

체크리스트

1. 각 상류·의존성에 고유 서킷 키를 두고, Prometheus·알람 라벨을 겹칩니다.
2. 게이지·카운터를 당겨, Grafana이 상태 전이를 15초 이내에 잡는지 봅니다.
3. 429 가이드에 맞춰 Retry-After을 파싱·반쯤 열림 자동을 켜기 전에, 배선을.
4. 탐침·생산 읽기의 마감이 본래 P99+40% 여윳값과 맞닿는지 합의합니다.
5. 둘 의존이 동시에 열리는 카오스, 서로 끼치지 않는지 확인합니다.
6. 에이전트가 쓰는 오류·코드표를, 사용자에게 그대로 터뜨리지 않는 선에서 문서에 박제합니다.
7. LaunchAgent·타이머를 본뜬, 주간으로 임대 Mac mini에 리허설 일정.
8. 냉각·토큰, 동시에 “굶”지 않는지(예산) 한 번씩.

Q&A

GraphQL+REST, 한 겹?

샤드가 다르면 쪼개, 한 겹은 국지 결함 가림.

탐침을 본 트래픽과 풀 공유?

User-Agent/헤더, SLO 제외.

웹소켓?

메시지. 첫 핑·타임아웃, 와이파이 로밍, 떨림.

탄성 있는 게이트웨이는 알고리즘뿐 아니라, 반복해서 연습하는 팀이 만듭니다. MacHTML에서 Mac mini를 하루 약 16.9 US달러에 빌리면, LaunchAgent 기반 잘못 주입·반쯤 열림 타이밍·스크랩·부하, 그리고 실제 macOS망 느낌을, 본전 반영 전에 같이 끌고 갈 수 있습니다.