2026 OpenClaw Webhook 실전: MeshMac 다중 노드 공유 빌드 트리거·상태 알림
Git·CI에서 SSH 없이 OpenClaw를 켜려는 팀용입니다. MeshMac 다중 노드에서 웹훅으로 검증·토큰·공유 빌드 큐·상태 알림(채널 무관)을 잇는 순서·대조표·HTTP 점검표를 800–1500자 분량으로 정리했습니다.
다중 노드에서 웹훅이 흔히 실패하는 이유
- 검증 없는 JSON은 잘못된 페이로드가 큐를 오염시키거나 파서 예외만 남기고 원인 추적이 어렵습니다.
- 약한 인증은 URL 유출 시 스푸핑·재전송으로 빌드 팜이 노출됩니다. Bearer·HMAC 중 하나는 필수입니다.
- 수신 노드에만 디스패치하면 공유 큐를 우회해 부하가 한 대에 몰리고, 다른 노드는 상태를 모릅니다.
웹훅은 중앙 태스크 큐 패턴과 맞추세요. 다중 노드 배포·태스크 큐·상태 동기화와 흐름을 맞추면 노드 간 작업·상태가 같아집니다.
검증·인증·OpenClaw 트리거·알림 대조표
열은 각각 거름·신원·큐 적재·알림 통로를 뜻합니다.
| 층 | 목표 | 범용 구현 예 |
|---|---|---|
| 페이로드 검증 | 잘못된 형태 조기 차단 | JSON Schema·DTO; event·repository·ref·커밋 SHA·멱등 키 필수 |
| 토큰·서명 | 호출자 신원 증명 | Authorization Bearer 시크릿, 또는 원문 바디 HMAC-SHA256·상수 시간 비교 |
| OpenClaw 트리거 | 어느 노드에서든 공유 빌드 | 정규화 → 단일 태스크 레코드 → Redis/SQS/팀 API 등 중앙 큐에 push, 노드는 poll·claim |
| 상태 브로드캐스트 | 노드 간·외부 가시성 | 아웃바운드 HTTPS 웹훅, NATS·Kafka, Slack 호환 인커밍 훅; 항상 node id·build id 포함 |
설정 단계
TLS 종단·단일 큐 소비 전제. 메시 개요는 Mac 메시 OpenClaw 다중 노드 협업 참고.
1
HTTPS 라우트 하나를 공개합니다(예:
/hooks/openclaw/build). 요청마다 상관 ID를 로그·응답 JSON에 넣어 재시도 추적이 되게 합니다.
2
부수 효과 전 검증. JSON 파싱·타입·문자열 길이 상한을 적용하고, 알 수 없는
event는 400으로 거절합니다. 검증 통과 전에는 절대 큐에 넣지 않습니다.
3
시크릿 검증. Bearer는 접두어를 제거한 뒤 금고 값과 상수 시간 비교합니다. HMAC은 원시 바이트로 서명을 재계산해
crypto.timingSafeEqual 등으로 맞춥니다.
4
OpenClaw 태스크 적재. 웹훅을 단일 태스크 유형(예:
shared_build)으로 매핑하고 멱등 키·커밋·라벨을 포함합니다. 재시도 의미는 태스크 큐·실패 재시도 글과 맞춥니다.
5
상태 알림. 적재 직후
queued를 어댑터로 보내고, OpenClaw 상태가 바뀔 때 running·succeeded·failed를 반복합니다. 코어는 한 인터페이스로 두고 Slack·Teams·두 번째 웹훅만 교체합니다.
6
빠른 응답. 태스크가 큐에 내구 저장되면
202로 승인합니다. 무거운 검증·팬아웃은 비동기로 넘겨 GitHub·GitLab 등 30초 내 타임아웃을 피합니다.런북에 적기 좋은 기본값
- 업스트림 HTTP 타임아웃: 많은 제공자가 10–30초 부근에서 끊습니다. 핸들러는 5초 이내로 끝내고 장기 작업은 큐로 넘깁니다.
- 멱등 키 보관: 재전송 대비 24–72시간 이상 저장해 중복 빌드를 막습니다.
- 아웃바운드 알림: 클라이언트 타임아웃 3–5초, 지수 백오프로 3회 이상 재시도해 일시적 DNS 장애에도 신호가 사라지지 않게 합니다.
흔한 HTTP 상태 코드·점검
송신측·프록시는 코드를 문자 그대로 해석합니다. 아래 표로 장애 대응 시간을 줄이세요.
| 코드 | 가능 원인 | 점검 항목 |
|---|---|---|
| 400 | 깨진 JSON·스키마 실패 | 바디 로그, 필수 필드, charset·Content-Type |
| 401 | Bearer 누락·불일치 | Authorization 형식, 시크릿 로테이션, 모든 레플리카의 금고 마운트 |
| 403 | 인증은 됐으나 출처 불허 | IP 허용 목록, 조직 허용 목록, 환경(host) 불일치 |
| 404 | 경로 오류·오래된 LB 규칙 | Ingress 경로, trailing slash, 카나리 vs 프로덕션 호스트 |
| 413 | 페이로드 과대 | Nginx·CDN 바디 크기 한도, 대형 diff 제거 |
| 429 | 속도 제한 | 소스별 throttle, burst, Retry-After·백오프 헤더 |
| 500 | 핸들러 미처리 예외 | 앱 로그, 의존성 버전, 큐 클라이언트 오류 |
| 502 / 503 | 업스트림·의존성 불가 | 훅 서비스에서 큐 도달성, Redis TLS, 파드 readiness |
요약
웹훅은 얇고 신뢰할 수 있는 경계로 두세요: 검증 → 인증 → 큐에 한 번만 → 범용 어댑터로 알림. 큐와 알림 엔드포인트만 일관되면 MeshMac 노드 수를 늘려도 패턴은 동일합니다. 전용 Mac에서 OpenClaw를 돌릴 준비가 되면 홈에서 플랜을 비교하고, 블로그에서 클러스터 글을 이어 읽으며, 도움말 센터에서 SSH·VNC 접속 절차를 확인하세요.