OpenClaw 게이트웨이 데드레터 큐와 안전한 도구 재실행(2026): 포이즌 메시지, 스키마 드리프트, 멱등 배수, 메트릭, 로그 감사, 클라우드 Mac mini에서의 macOS 리허설

에이전트 HTTP 도구로 뻗는 게이트웨이는 인라인 지수 백오프만으로는 못 고치는 실패를 반드시 만납니다. 하룻밤 사이 어긋난 파트너 계약, 게이트웨이 JSON 스키마와 상류 마이크로서비스 구현의 불일치, 길게 이어지는 상류 장애입니다. 이런 종착류 실패를 핫 패스에 가두면 모델 스트림 지연, 메모리 압력, 트레이스 스팬 고착이 연쇄합니다. 성숙한 2026년 OpenClaw 운영은 이를 데드레터 큐(DLQ)로 격리해 사람 또는 정책 게이트 아래에서 검사·수정·재실행합니다. 본문은 DLQ로 가는 조건, 파티션과 보존, 재실행이 멱등 키와 중복 제거와 어떻게 맞물리는지, 서킷 브레이커가 배수를 어떻게 멈추는지, Prometheus 메트릭으로 건강을 어떻게 증명하는지, 마스킹 로그와 로테이션으로 감사 가능성을 지키는 방법을 정리합니다.

비용 프레이밍부터 말하면 잘못된 이중 재실행이 고객 청구를 두 번 움직이거나 공유 CRM을 망가뜨리는 사고보다, MacHTML 전용 Mac mini(대략 하루 16.9달러)에서 DLQ 정책을 주간 리허에 올리는 편이 싸다는 각도가 있습니다. 브로커·게이트웨이·스크레이프 사이드카를 한 실리콘에서 돌리며 디스크 쿼터와 newsyslog까지 현실적으로 봅니다.

재시도 옆에 DLQ가 필요한 이유

재시도는 짧은 시간 안에 나아질 일시 장애를 가정합니다. 도구 통합은 그 가정을 매일 깨뜨립니다. 상대 OpenAPI가 밤중에 필드명을 바꿔 422를 내거나, 벡터 검색이 샤드 재배치로 열 두 분 동안 500을 뱉습니다. 이를 워커 풀에 가두면 지연이 모델로 전파되고 사용자 체감 정체가 늘며, 각 대기 호출이 버퍼와 스팬을 쥔 채 놓지 않습니다.

DLQ는 종착 실패를 저속 레인으로 옮겨 운영자가 배치로 페이로드를 보고 스키마를 맞추고 테넌트를 격리합니다. 2026년 여러 팀이 쓰는 실무 규칙 예시는 멱등 읽기에 대해 인라인 재시도를 세 번·총 2.5초 안으로 제한하고, 오류 클래스가 알 수 없거나 상류가 비재시도를 명시하면 DLQ로 보내는 것입니다. 멱등 키 없는 쓰기는 무한 재시도 금지이며, 플래너에 구조화 오류를 즉시 돌리거나 정책상 사람 승인이 필요하면 DLQ로 보내는 둘 중 하나입니다.

OpenClaw의 부채꼴 전개는 문제를 키웁니다. 한 계획 단계가 여섯 도구를 동시에 칠 수 있으므로 도구별 DLQ 파티션을 나누지 않으면, 포이즌 CRM 검색이 같은 Redis 뒤의 건강한 계산기 도구 배수까지 막을 수 있습니다.

포이즌과 스키마 실패

포이즌은 코드나 데이터를 바꾸지 않는 한 영원히 성공하지 않는 페이로드입니다. 게이트웨이 JSON 스키마 검증 실패, 출구 정책에 막힌 URL, 카나리에서 사라진 기능 이름 참조가 전형적입니다. 이들은 즉시 비재시도로 분류하고 기계가 읽을 수 있는 failure_class(예: SCHEMA_REJECT, EGRESS_DENY)를 붙이며 원래 트레이스 ID를 달아 DLQ에 넣어 지원이 티켓과 대조하게 합니다.

스키마 드리프트는 특별 취급이 필요합니다. 각 인큐에 tool_contract_version: 20260425.3처럼 버전을 박아 재실행 담당이 실패가 14:00 UTC 수정 이전인지 이후인지 판단하게 합니다. 주간으로 계약 버전을 올리는 팀이라면 파티션당 보존 십사 일·용량 500MB 전후가 흔합니다. 창을 넘기면 자동 만료와 묘비 메트릭으로 GDPR류 삭제 증적과 미처리 만료 건수를 동시에 남깁니다.

부분 포이즌 배치(백 건 중 다섯 건만 검증 실패)는 배치 전체 거절 대신 행 단위 DLQ로 쪼개 나머지 구십다섯 건의 처리량을 지킵니다.

운영자가 기대하는 봉투

원시 도구 인자와 별도로 DLQ 메시지는 봉투를 갖습니다. 새벽 호출을 버티는 최소한은 tenant_id, request_id, idempotency_key 또는 명시적 null, tool_name, tool_version, first_seen_at, last_error_code, retry_count, failure_class, 그리고 4KB 상한의 마스킹된 HTTP 헤더 사본입니다. 본문이 256KB를 넘으면 압축 객체 저장소 포인터를 달아 브로커를 무겁게 만들지 않습니다.

{
  "dlq_version": 1,
  "request_id": "req_9f2c…",
  "idempotency_key": "idem_7a91…",
  "tool": {"name": "crm_search", "contract": "20260425.3"},
  "failure_class": "UPSTREAM_TIMEOUT",
  "retry_count": 3,
  "last_http_status": 504,
  "first_seen_at": "2026-04-25T01:12:04Z",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

비밀은 본문에 직접 쓰지 말고 금고 경로 참조로 바꿉니다. OAuth 갱신 산출물이 실렸던 호출이라면 vault://tenant/42/oauth처럼 두어 디스크 스냅샷 유출이 곧바로 자격 증명 사고가 되지 않게 합니다.

재실행 안전과 멱등 계약

멱등 없는 재실행은 청구 메일 두 통의 온상입니다. 재실행은 원래 멱등 키를 TTL 안에서 재사용하거나—금융 도구는 대개 24~72시간—의도된 두 번째 시도임이 하류에 전달되는 supersedes_request_id가 달린 새 키를 발급합니다. Redis TTL과 충돌 안전 저장 패턴은 멱등 글에 맡깁니다.

수동 배수는 상류 의존성당 초당 한 건에서 시작해 오 분간 오류율이 0.5% 아래면 단계적으로 올립니다. 당직 두 명이 동시에 속도를 두 배로 만들지 않게 운영자별 동시 실행 상한도 둡니다. 변경 도구는 봉투에 이인 승인 플래그를 요구하고, CI에서 쏘는 자동 재실행은 전용 서비스 계정으로 분리하며 키는 삼십 일마다 돌리고 행동 메트릭은 사람 배수와 카디널리티를 나눕니다.

브레이커와 배수 조율

상류 서킷이 열린 채 DLQ를 배수하는 일은 회복 중인 상대에게 다시 포이즌을 뿌리는 행위입니다. 실무는 브레이커 게이지를 보고 서킷 브레이커 안내의 반열림 성공 프로브 박자에 맞춘 뒤 배수 잡을 켜고, 다시 열리면 자동 정지가 기본형입니다. 상태 DRAIN_PAUSED_BREAKER_OPEN 전환으로 Slack을 치고 dlq_drain_paused_total을 올리는 단순 기계도 통합니다.

429와 Retry-After가 붙으면 클라이언트 트래픽과 같이 DLQ 배수도 헤더 냉각을 존중하고 워커 떼 지름길을 피하려 최대 250ms 지터를 더합니다.

Prometheus와 지연 SLO

최소한 도구 파티션별 dlq_depth 게이지, dlq_ingress_total{failure_class}, dlq_replay_success_total, dlq_replay_failure_total, 첫 실패부터 성공 재실행까지 dlq_age_seconds 히스토그램, 컴플라이언스 보고용 dlq_expired_total을 냅니다. 대시보드는 Prometheus 글에서 만든 것에 바로 꽂습니다.

SLO 예: DLQ 메시지의 95%가 사십팔 시간 안에 성공 재실행이나 명시적 운영 처분. 단일 테넌트에서 십오 분 창 dlq_depth가 만을 넘기면 페이지합니다. 대개 상류 정지가 클라이언트 오류로 위장한 신호입니다.

로그, 개인정보 마스킹, 감사

재실행은 비즈니스 로직을 다시 돌립니다. 운영자 신원, 시각, 구·신 멱등 키, 마스킹된 인자 차이 로그를 남깁니다. 작은 Mac mini 실기에서 디스크가 넘치지 않게 마스킹과 logrotate 패턴을 맞추고 폭주 배수가 JSON 기가바이트를 뱉어도 버티게 합니다.

macOS에서는 게이트웨이 로그를 50MB·칠 세대 newsyslog가 흔합니다. DLQ 보존과 회전 주기를 맞춰 브로커에서 만료된 뒤에도 파일로 상관할 수 있게 합니다.

비교: 재시도 큐·DLQ·아웃박스

관점	핫 재시도 큐	DLQ	트랜잭션 아웃박스
지연 예산	밀리초	분~일	DB 커밋에 묶임
사람 검토	드묾	전제	선택
순서 보장	키 단위 베스트 에포트	파티션 내 FIFO	단일 라이터로 강함
어울리는 곳	일시 5xx 묶음	포이즌, 긴 정지, 정책 홀드	자사 DB에 정확히 한 번 부작용

번호 매긴 운영 절차

1. 깊이 급증이 스크레이프 오탐이 아닌지 브로커 UI와 dlq_depth를 대조한다.
2. 다섯 건을 샘플하고 failure_class가 같으면 티켓은 하나로 묶는다.
3. 서킷 상태와 오류 예산을 확인한 뒤 배수를 켠다.
4. 초당 한 건으로 시작해 dlq_replay_failure_total을 본다.
5. 끝나면 메트릭을 스냅해 사고 기록에 붙인다.

자주 묻는 질문

DLQ와 핫 재시도가 같은 Redis 뭉치여도 되나

하드웨어는 공유해도 키 공간과 메모리 정책은 나눠 DLQ 역압이 핫 재시도 메타를 쫓아내지 않게 합니다.

멱등 키 수명은

기대하는 최장 법적 분쟁 창에 맞춥니다. B2B에선 도구 72시간, 청구 연동 30일 병행이 보입니다.

에이전트가 무인 재실행해도 되나

읽기 전용에 멱등이 증명됐을 때만 제한적으로. 그 외엔 운영 의도가 필요해 자율 루프를 피합니다.

믿을 만한 DLQ는 큐 기교만이 아니라 관측 가능성과 macOS에 가까운 리허설이 한 덩어리입니다. MacHTML에서 빌린 Mac mini(대략 하루 16.9달러)는 네이티브 macOS와 조용한 실리콘, Apple Silicon 여유를 함께 주어 본전에 가기 전 배수 스크립트, LaunchAgent, 마스킹 로그를 한꺼번에 검증하기 좋습니다.