예약 작업·인바운드 웹훅·CI 콜백과 멱등성
소규모 팀은 이미 OpenClaw Gateway를 돌리지만 Slack형 IM 없이도 예약 점검, 인바운드 웹훅, CI 결론으로 자동화를 돌려야 할 때가 많습니다. 이 글에서는 세 가지 트리거 범주, 인증과 멱등성 매트릭스, 온콜 위키에 붙여 넣을 수 있는 여섯 단계 런북을 정의합니다. 말미에는 프로덕션에서 흔히 쓰는 수치 기준과 호스팅형 Mac 노드가 운영 부담을 줄이는 조건을 정리합니다.
채팅 채널에는 누가 어떤 스레드에서 말했는지에 대한 암묵적 맥락이 있습니다. 순수 HTTP와 cron 흐름은 처음부터 계약을 박아 두지 않으면 그것이 사라집니다. 출시 전에 다음 실패 모드를 검토하세요.
중복 전달이 부작용을 두 배로 만듦: CI 플랫폼과 웹훅 릴레이는 타임아웃 시 재시도하는 경우가 많습니다. 멱등성 키와 중복 제거 창이 없으면 같은 작업 성공이 두 번 실행될 수 있습니다.
인증이 약함: 비밀 URL은 로그와 프록시를 통해 새어 나갑니다. 최소한 헤더 시크릿, HMAC 또는 mTLS로 옮기세요.
cron이 유지보수와 충돌: 상시 가동 노드를 패치하는 동안 cron이 돌면 핸들러가 반쯤 초기화된 상태로 실행될 수 있습니다.
리전 간 순서에 대한 환상: 먼저 수신했다고 먼저 발생한 것은 아닙니다. 이벤트 시각과 단조 시퀀스를 실어 나르세요.
관측성이 빈약함: 요청 ID, 상류 작업 ID, 멱등성 지문이 없으면 티켓을 로그에 매핑할 수 없습니다.
트리거를 제품 요구사항처럼 다루세요. 지연 민감도, 일관성 필요성, 허용 드리프트가 cron, 웹훅, CI 콜백 중 무엇인지를 결정합니다.
| 트리거 | 전형적 용도 | 강점 | 주요 위험 |
|---|---|---|---|
| 예약 비트 | 헬스 스윕, 일일 요약, 임시 파일 정리 | 예측 가능한 부하, 단순 운영 | 실제 이벤트와 분리됨. 유지보수 중에는 일시 중지 |
| 인바운드 웹훅 | 티켓 훅, 승인, 모니터링 HTTP 익스포터 | 비즈니스 이벤트에 거의 실시간으로 맞춤 | 중복, 위조 발신자, TLS와 프록시 복잡도 |
| CI 종단 콜백 | 빌드 후 서명, 릴리스 게이트 | 아티팩트와의 결합이 강함 | 불투명한 플랫폼 재시도. 페이로드 버전 드리프트 |
실무 페어링
한 번만 일어나야 하는 부작용에는 웹훅 또는 CI 콜백과 멱등 저장소를 쓰세요. 읽기 전용 집계에는 cron을 남깁니다. Gateway가 공인 인터넷을 향할 때는 TLS 종단과 에지에서 리스너를 좁히고, 설치 및 Gateway 문제 해결 체크리스트로 기준 점검을 따르세요.
순서대로 실행한 뒤 검증하고 트래픽을 넓히세요. 시크릿 이름은 볼트 정책에 맞게 바꿉니다.
계약을 고정: JSON 필드 event_time, source, job_id, idempotency_key, payload_version을 요구하고 버전 없는 알 수 없는 페이로드는 거부합니다.
에지에서 인증: 리버스 프록시에서 Authorization 베어러 또는 HMAC을 검증하고 IP 허용 목록을 둡니다. Gateway는 내부 홉만 신뢰합니다.
멱등 저장소 추가: idempotency_key를 기본 키로 TTL(CI의 경우 보통 24~72시간). 중복 POST는 같은 비즈니스 응답을 돌려줍니다.
유지보수 중 cron 게이트: 플래그 파일 또는 키-값 게이트. 유지보수 활성 시 조기 종료와 하트비트 로그를 남깁니다.
관측성 삼중선 연결: 진입마다 request_id를 만들어 응답 헤더로 돌리고, job_id와 해시된 멱등성 키를 로그에 남깁니다.
재시도에 카오스 주입: 동일 POST 세 번, 30초 상류 단절 후 복구하여 부작용 이중화가 없고 페이징이 올바른지 확인합니다.
curl -sS -X POST "https://gateway.example.internal/hooks/ci" \
-H "Authorization: Bearer ${HOOK_SECRET}" \
-H "X-Idempotency-Key: ${CI_JOB_ID}-${CI_CONCLUSION}" \
-H "X-Request-Id: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"payload_version":1,"job_id":"'"${CI_JOB_ID}"'","conclusion":"success"}'
내부 전용과 공개 진입의 위협 모델이 다릅니다. 리뷰어를 빠르게 맞추려면 표를 공유하세요.
| 패턴 | 적합 | 반드시 설정 |
|---|---|---|
| 공유 시크릿과 TLS | 사설망 또는 제로 트러스트 터널 | 시크릿 로테이션. 응답에 시크릿을 되돌리지 않기 |
| HMAC 서명 | 공개 웹훅, 상류 다수 | 타임스탬프 창 대략 ±300초. 상수 시간 비교 |
| mTLS | 엔터프라이즈 CI에서 컨트롤 플레인 | 짧은 수명 리프 인증서 로테이션과 폐기 |
멱등성 키 형태. {source}:{stable_id} 형태를 선호하세요. 밀리초만 쓰면 재시도에 즉시 중복 제거가 깨집니다.
생 시크릿은 로그에 남기지 마세요. 해시되거나 접두사가 붙은 식별자만 저장하고, 로깅 벤더를 두 번째 폭발 반경으로 만들지 마세요.
아래 범위는 흔한 프로덕션 관행을 요약합니다. SLA에 맞게 조정하고 벤더 보장과 혼동하지 마세요.
스케줄러와 노트북을 자체 호스팅하는 것은 수면, 불안정한 가정용 네트워크, OS 업그레이드가 cron과 웹훅을 반쯤 성공 상태로 만들 때까지입니다. Gateway와 진입을 VpsMesh 상시 가동 Mac Mini 클라우드 노드에 두면 아웃바운드 IP, 유지보수 창, 하드웨어 격리가 안정되어 비 IM 자동화를 취미 스크립트에서 온콜 친화 루프로 끌어올릴 수 있습니다.
진입을 좁히고 멱등하며 관측 가능하면 그렇습니다. 먼저 설치 및 닥터 체크리스트로 Gateway를 안정화한 뒤 웹훅을 엽니다.
중복과 발신자 증명 부재입니다. 공유 시크릿 또는 HMAC, 에지 IP 제한, 멱등 히트 시 동일 의미의 응답을 추가하세요. 안정적인 아웃바운드가 필요하면 요금 페이지에서 노드를 비교하세요.
유지보수를 cron 피크와 어긋나게 하고, 시계를 엄격히 맞추며, 리전 간 콜백 타임아웃을 넓히세요. 원격 Mac 안내는 고객센터에 있습니다.