2026 OpenClaw 게이트웨이 멱등 키와 요청 중복 제거(클라우드 Mac mini)

에이전트 게이트웨이는 최소 한 번 전달을 전제로 하며, 멱등 키가 없으면 결제와 파일 쓰기가 이중 실행되어 신뢰를 깨뜨립니다. 2026년 OpenClaw는 부작용 직전에 Redis 원자 선점과 리플레이 봉투를 둡니다. JSON Schema 게이트웨이 검증, nginx 롤링 드레인, 429와 Retry-After, 읽기 타임아웃 진단과 함께 아래 세부 설정을 적용하세요.

키 정규화

Idempotency-Key 헤더 또는 JSON idempotency_key를 단일 계약으로 삼습니다. base64url 디코딩 후 엔트로피가 16바이트 미만이면 거부해 열거 공격을 막습니다. 전선 길이는 128 ASCII 문자 상한으로 로그와 로드밸런서를 보호합니다. 정규화 뒤 SHA-256을 적용해 Redis 필드 이름으로 쓰면 프라이버시와 안정성을 동시에 얻습니다. (tenant_id, route_id, key_hash, schema_version) 튜플을 필수로 하고 스키마 업그레이드 시 의도적으로 오래된 리플레이를 무효화합니다.

Redis·Lua

첫 요청이 SET ... NX EX 172800에 성공한 워커만 상류를 호출합니다. 실패한 쪽은 봉투를 읽어 반환만 합니다. 야간 배치가 사흘까지 합법이면 259200초로 늘리고 메모리 알람을 조정합니다.

-- 의사 Lua
if redis.call('SET', key..':claim', pid, 'NX', 'EX', 172800) then
  return 'execute'
else
  return redis.call('GET', key..':envelope')
end

토폴로지 표

방식	이점	리스크	용도
프로세스 LRU	초저지연	분열 뇌	로컬 검증
Redis 클러스터	TTL·NX 성숙	핫 키	운영 표준
SQL 락	감사 친화	지연 증가	금융 규제
etcd 임대	메시 연동	운영 비용	mesh 보유 기업

TTL 172800/259200초

48시간은 결제 API 관행과 맞습니다. 72시간은 주말을 가로지르는 대사 작업에 여유를 줍니다. 만료 후에는 완전히 새 작업으로 취급하고 SDK는 사용자가 “새로 보내기”를 누를 때 키를 회전합니다. SLA 문구와 Redis EX를 일치시키고 감사 로그에 해시를 남깁니다.

리플레이 봉투

HTTP 상태, 재전송 가능한 헤더 부분집합, 본문 BLAKE3 또는 SHA-256을 저장합니다. 본문이 1 MiB를 넘기면 객체 스토리지로 넘기고 Redis에는 포인터만 둡니다. 스트리밍 응답은 청크 번호를 봉투에 넣어 부분 완료를 오인하지 않게 합니다. 체크섬 불일치 비율이 0.01%를 10분 넘기면 심각 사건으로 압축층·직렬화 버전을 의심합니다.

nginx 협업

TLS 종단에서 헤더를 정규화하고 내부 헤더에 해시 파생값을 실습니다. proxy_read_timeout은 게이트웨이 상류 예산보다 약간 길게 잡고 교착 진단 권장값과 맞춥니다. 드레인 중에도 Redis 엔드포인트를 고정해 늦게 플러시되는 클라이언트가 키를 잃지 않게 합니다.

체크리스트

1. 변경형 라우트를 조사해 requires_idempotency를 부여한다.
2. SDK는 기본 UUIDv4를 발급하고 22자 미만 수동 키를 거부한다.
3. 운영 Redis는 주 샤드 3개 이상, AOF는 everysec를 선택한다.
4. 통합 테스트에서 20병렬 중복을 보내 부작용 카운터가 한 번만 증가하는지 확인한다.
5. 드레인 중 50% 파드를 바꾸며 중복 트래픽을 흘리는 게임데이를 연다.
6. 오류 코드를 공개 표에 올리고 만료·본문 불일치·테넌트 불일치를 구분한다.
7. 대시보드에 리플레이 비율·클레임 p99·추방 키 수를 표시한다.

관측

idempo_replay_total이 35%를 30분 넘기면 클라이언트 루프를 의심합니다. 테넌트 라벨은 해시 버킷으로 카디널리티 폭발을 피합니다. Redis RTT와 추론 시간을 분리 기록해 캐시 퇴화를 모델 지연과 혼동하지 마세요. 주간으로 충돌률을 검토하고 이상 테넌트는 수동 큐로 넘깁니다.

과금 게이트웨이에서는 “멱등 적중”과 “실제 과금 이벤트”를 별도 카운터로 두어 마진을 과대 계상하지 않습니다. 고객 성공팀을 위해 7일 이동 평균 리플레이 적중률을 공개하면 연동 벤더 결함을 빨리 드러냅니다.

감사 대응을 위해 주간으로 Lua 스크립트 버전과 스키마 버전을 PDF 증빙으로 보내고, 장애 포스트모템에는 키 해시·라우트 ID·테넌트 버킷을 한 줄로 요약하세요.

분할

Redis 장애 시 실패 폐쇄 또는 실패 개방을 명시합니다. 결제 경로는 503과 백오프 지침이 안전하고 내부 샌드박스만 완화할 수 있습니다. 클라이언트 재시도는 최대 5회, 지터 백오프 상한 32초를 목표로 하고 Retry-After가 있으면 따릅니다. 자세한 내용은 429 글을 참고하세요.

FAQ

GET에도 키가 필요한가요?

보통 아니요. 부작용이 있는 작업을 GET에 실지 마세요.

라우트를 가로질러 재사용?

금지입니다. 저장 키에 라우트 ID를 포함하세요.

오프라인 큐는?

큐잉 시 키를 할당하고 플러시 때 재사용합니다.

Apple Silicon Mac mini는 저소음으로 상시 검증에 적합하며 launchd·키체인·경로 해석이 운영과 가깝습니다. macOS에서 Redis와 nginx를 함께 두고 OpenClaw 바이너리를 실제 유닛 파일로 돌리면 노트북 검증과의 간극이 줄어듭니다. MacHTML 클라우드 Mac은 하루 약 16.9달러로 빌려 고객 트래픽을 더럽히지 않고 중복 부하 시험을 할 수 있습니다.

같은 호스트에서 TLS 핸드셰이크 검증과 인증서 체인 차이도 돌릴 수 있어 SRE와 보안이 동일한 Apple Silicon 화면을 공유하며 멱등 롤아웃 설명 책임을 짧게 마칠 수 있습니다.