2026년 OpenClaw Webhooks 인입(GitHub/GitLab CI): 공유 비밀·게이트웨이 라우팅·Rate limit, 독점 원격 Mac SSH 재현 배포와 401/413/타임아웃 FAQ
CI는 HTTP로 말합니다. GitHub Actions나 GitLab CI가 헤드리스 Mac 위의 OpenClaw 호환 게이트웨이를 깨우려면, 공유 비밀·리버스 프록시 경로·게이트웨이 스로틀·페이로드 크기 같은 지루한 부분이 프로덕션의 조용함과 페이저 폭주를 가릅니다. 이 런북은 인입 웹훅을 독점 실기에서 SSH로 재현 가능한 배포에 매핑하고, 401, 413, 타임아웃을 표로 정리합니다.
한눈에 보는 핵심
요지: 웹훅 URL은 능력(capability) URL로 취급하세요. 모든 요청을 인증하고, 페이로드는 작게 유지하며, 워커가 모델이나 디스크에 닿기 전에 게이트웨이에서 백프레셔를 걸도록 하세요.
- GitHub:
X-Hub-Signature-256으로 원문 본문의 HMAC-SHA256을 검증합니다. 비밀은 CI와 검증기에만 둡니다. - GitLab:
X-Gitlab-Token(또는 파이프라인 토큰 변수)을 보내고 없으면 거절합니다. URL 경로만으로 보안을 대체하지 마세요. - 게이트웨이: 외부 호스트명은 하나, 환경별 경로 접두사(
/hooks/prod/...), 명시적 Rate limit으로 파이프라인 폭주가 로컬 추론을 짓밟지 않게 합니다. - Mac 워커:
openclaw, Node, brew 포뮬러 버전을 고정하고, 설정은 git에 두며launchd로 재시작하고, CI가 치는 것과 동일한 HTTPS로 SSH에서 스모크 테스트합니다.
Apple 자격 증명과 CI가 헤드리스 러너에서 맞물리는 부분은 2026년 전용 원격 Mac CI: App Store Connect API(.p8)와 Fastlane — SSH 헤드리스 환경의 키 보관·파이프라인 주입 의사결정 매트릭스 + FAQ를, 버전 업 후 게이트웨이 타임아웃 정렬은 2026년 OpenClaw v2026.4.14 업그레이드 후 검증: gpt-5.4-pro 전방 호환, 게이트웨이 도구 설정 패치와 Ollama 타임아웃 수정을 독점 원격 Mac SSH에서 재현하는 체크리스트 + FAQ를 참고하세요.
1. 참조 아키텍처: CI → HTTPS → 게이트웨이 → 워커
2026년에 흔한 구성은 이렇습니다. GitHub Actions나 GitLab CI는 공유 인프라에서 돌고 당신의 HTTPS 엔드포인트를 호출합니다. 그 엔드포인트는 리버스 프록시나 엣지(Cloudflare, Tailscale Serve, 클라우드 LB)에서 TLS를 종료한 뒤 Mac의 127.0.0.1 리스너로 넘깁니다. OpenClaw 스타일 게이트웨이가 웹훅을 검증·JSON을 정규화하고, 모델·도구·셸 자동화를 부를 수 있는 프로세스로 넘깁니다.
공개 면을 프록시에 두면 인증서 회전, WAF 규칙, 경로별 Rate limit을 CI 재배포 없이 적용할 수 있습니다.
2. 공유 비밀: GitHub HMAC vs GitLab 토큰 헤더
2.1 GitHub (X-Hub-Signature-256)
GitHub는 웹훅 비밀로 원문 POST 본문에 서명합니다. 검증기는 동일한 바이트(예쁘게 찍은 JSON이 아님)를 해시하고 상수 시간 비교로 맞춥니다. 비밀은 저장소·조직 시크릿에 두고, Mac 쪽은 서비스 사용자만 읽을 수 있는 환경 파일에서 로드하세요. 홈 디렉터리 전체 공개는 피합니다.
2.2 GitLab (X-Gitlab-Token)
GitLab은 파이프라인·프로젝트 웹훅에 정적 토큰 헤더를 붙일 수 있습니다. 비밀번호처럼 다루고 주기적으로 회전하며, 가장 좁은 프로젝트에 스코프를 둡니다. .gitlab-ci.yml에서 curl로 트리거할 때는 마스킹된 CI 변수로 주입하고, Job 로그에 URL 전체가 찍히지 않게 하세요.
3. 게이트웨이 라우팅·경로 접두사·다중 환경 안전
명시적 경로 네임스페이스를 쓰세요: /hooks/ci/prod, /hooks/ci/staging. 각각 서로 다른 내부 포트나 Unix 소켓에 매핑해 스테이징 버그가 프로덕션 작업을 넣지 못하게 합니다. 엣지에서는 WAF·Rate limit 프로필을 다르게: 프로덕션은 버스트를 더 엄격히, 스테이징은 디버깅 재생을 더 허용합니다.
Mac에서 TLS를 직접 종료하는 경우(항상 권장은 아님)에도 환경별 리스너 설정 파일을 분리하세요. 쿼리 문자열 하나로 의미를 바꾸는 "설정 하나, 의미 둘"은 금지입니다.
4. Rate limit: CI 폭풍으로부터 게이트웨이 보호
CI는 실수로 팬아웃됩니다. 매트릭스 Job, 재시도, 수동 재실행이 분당 수십 건의 POST를 낼 수 있습니다. 리버스 프록시나 게이트웨이 수준에서 초당 요청·동시 연결 한도를 두어, 백로그가 로컬 큐 대신 HTTP 429와 Retry-After로 드러나게 하세요. 429 비율에 알림 임계값을 걸어 워크플로 설정 오류를 사용자보다 먼저 알아챕니다.
5. 독점 원격 Mac에서의 재현 가능 배포(SSH)
재현 가능성은 "내 맥에선 됨"과 "매주 화요일 새벽 3시에도 됨"의 차이입니다. 독점으로 쓰는 Mac에서는 다음을 고정합니다.
- 버전:
openclawCLI, 게이트웨이 패키지, Node 런타임을 핀하고 인프라 저장소 옆에 작은versions.lock에 기록합니다. - 설정: 리스너 주소·웹훅 경로·환경 변수를 git에 두고 SSH로
rsync또는 작은 Makefile 타깃으로 배포합니다. - 프로세스 모델:
launchdplist에StandardOutPath/StandardErrorPath를 두어 CI가 트리거한 실패가 감사 로그로 남게 합니다. - 스모크 테스트: CI Job(또는 수동 게이트)에서 웹훅과 동일한 공개 URL로 서명된 더미 페이로드를 POST합니다. TLS·경로·헤더가 어긋나면 머지 전에 잡습니다.
6. FAQ 매트릭스: 401, 413, 타임아웃
| 증상 | 가능 원인 | 우선 확인 |
|---|---|---|
401 Unauthorized |
HMAC·토큰 누락·불일치; HMAC에는 드물지만 JWT 엣지에서는 시계 어긋남. | X-Hub-Signature-256 / X-Gitlab-Token 존재 여부를 로그합니다(값은 절대 로그하지 않음). 원문 본문으로 HMAC을 재계산합니다. CI 변수와 Mac 쪽 비밀이 일치하는지 확인합니다. |
413 Payload Too Large |
CI가 과대 JSON을 보냄(아티팩트를 실수로 본문에 넣음) 또는 프록시 본문 한도가 GitLab/GitHub 기본보다 낮음. | 웹훅 본문에서 바이너리를 제거하고 URL만 보냅니다. 꼭 필요할 때만 nginx client_max_body_size 등을 올리고, 앱에도 상한을 둡니다. |
클라이언트 타임아웃 / 504 업스트림 |
워커가 모델 I/O에 막힘; CI HTTP 단계가 게이트웨이 처리보다 짧음; 프록시 유휴 타임아웃. | 웹훅 핸들러는 빠르게 202 Accepted를 돌려 비동기 처리합니다. GitHub --max-time·GitLab curl 타임아웃을 프록시 keep-alive에 맞춥니다. 게이트웨이 타임아웃 조정은 위에 링크한 업그레이드 후 FAQ를 참고하세요. |
웹훅 워커 거점으로 Mac mini가 잘 맞는 이유
웹훅 게이트웨이는 오래 살아 있는 서비스입니다. 수동 재시작 없이 주 단위로 버티고, CI 버스트를 견디며, 책상 위에서 조용해야 합니다. Apple Silicon Mac mini는 대기 전력이 매우 낮고(종종 수 와트 수준), 팬 소음이 적으며, 무인 launchd 작업과 잘 맞는 macOS 안정성을 제공합니다. SSH 자동화용 네이티브 Unix 사용자 공간, 프록시 보조용 Homebrew, Gatekeeper·SIP·FileVault로 이어지는 방어 깊이를 갖춰, 많은 범용 PC보다 무인 공격 표면이 작습니다.
민감한 훅을 위해 시끄러운 공유 러너를 빌리고 싶지 않다면 Mac mini M4는 실용적인 앵커입니다. 동시 검증에 충분한 성능, 예측 가능한 발열, 온라인을 유지할수록 총소유비용이 유리해집니다.
그 게이트웨이를 직접 제어하는 실기 위에 올릴 준비가 되었다면, 아래 SSHMac 홈에서 예상 웹훅 트래픽에 맞는 플랜을 고르세요.