2026년 OpenClaw Webhook·Hooks 원격 물리 Mac 게이트웨이 구성: 토큰 인증·역프록시 경로·CI 트리거 재현 Runbook(401/404 분석+FAQ)
GitHub·채팅 브리지·내부 버스에서 OpenClaw를 트리거하는 플랫폼 팀은 CI는 초록인데 프로덕션 웹훅만 401/404로 무너지는 상황을 자주 봅니다. 이 글은 Bearer 토큰과 전달 헤더 정렬, nginx/Caddy 경로 접두를 OpenClaw 실제 등록 경로와 일치, GitHub Actions로 엣지와 동일 계약 재생까지 2026년에 바로 쓸 복붙 런북과 증상 매트릭스·7단계 검증·인용 수치·FAQ를 담았습니다.
1. 원격 Mac 게이트웨이에서 웹훅이 조용히 실패하는 이유
물리 Mac은 실제 Unix 소켓, 예측 가능한 launchd 수명, 리전 CI까지 지터가 낮아 훌륭한 웹훅 대상이지만, 실패 모드는 흔히 "OpenClaw가 죽었다"가 아닙니다. 계약 어긋남입니다—SaaS가 치는 URL, 프록시가 다시 쓰는 경로, 검증기가 읽는 헤더 집합이 서로 독립적으로 드리프트합니다.
- 헤더 제거: 역프록시는 명시적으로 전달하지 않으면
Authorization이나 사용자 정의X-*헤더를 버리는 경우가 많습니다. CI는 인증된 것처럼 보이지만 업스트림은 토큰을 못 봅니다. - 이중 접두: OpenClaw를
/agents/openclaw뒤에 두었는데 핸들러는 접두 없이/hooks/...만 등록한 경우—엣지 없이 localhost만 curl하면 사라지는 404입니다. - 시크릿 산재: GitHub Secrets에서만 토큰을 돌렸거나 그 반대로 macOS 쪽 검증기만 갱신하면 파이프라인 샤드에 따라 간헐적 401이 납니다. 안정적인 게이트웨이 프로세스 스토리는 2026년 OpenClaw Gateway 7×24 끊김과 데몬 트러블슈팅: install-daemon, launchd와 openclaw health 재현 가능 런북과 짝을 이루어 보세요.
2. 토큰·경로 의사결정 매트릭스
설계 리뷰와 프록시·OpenClaw 업그레이드 직후에 아래 표를 씁니다. "취약" 열에 해당하면 담당자 이름과 롤백 티켓 템플릿을 붙이세요.
| 차원 | 취약 패턴 | 프로덕션 목표 |
|---|---|---|
| 토큰 전달 | 접근 로그에 남는 쿼리 ?token= |
Authorization: Bearer 또는 HMAC 서명 헤더를 끝까지 전달 |
| 경로 매핑 | 명시적 strip/rewrite 없이 location /만 프록시 |
공개 경로 → 프록시 규칙 → OpenClaw 라우트 표를 문서화한 삼단 |
| TLS 엣지 | "VPN이니까" 평문 HTTP 웹훅 | Caddy/nginx에서 TLS 종료; 내부 버스는 선택적 mTLS |
| CI 트리거 | 유지보수자 노트북의 애드혹 curl |
프로덕션과 동일 JSON 봉투를 보내는 버전 관리 워크플로 |
| 관측 가능성 | OpenClaw 로그만 있고 프록시 액세스 로그 없음 | 엣지와 앱에서 request_id를 최소 60초 보존으로 상관 |
게이트웨이 바이너리·채널을 아직 올리는 중이면 플랫폼 설치 순서부터 2026년 OpenClaw 완전 설치 가이드: Mac / Windows / Linux 전 플랫폼 배포로 밟은 뒤, 인그레스를 이 글로 강화하세요.
3. 7단계 재현 가능 런북
원격 Mac에서 관리자 SSH로 순서대로 실행합니다. 웹훅 인시던트는 경로·헤더 한 끗 차이로 갈립니다—트랜스크립트를 남기세요.
- 계약 고정: 메서드, 전체 공개 URL, JSON 스키마, 대소문자 포함 필수 헤더를 적습니다. 동일 블록을 내부 위키와 GitHub 워크플로 주석 헤더에 붙입니다.
- 업스트림 로컬 증명: Mac에서
curl -fsS -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:<port>/<문서화된-경로>로 최소 본문을 보냅니다. DNS·TLS 전에 HTTP 2xx를 기대합니다. - 프록시 정렬: nginx 또는 Caddy에서 TLS를 종료하고 공개 경로를 OpenClaw가 등록한 업스트림 경로에 맞춥니다.
strip_prefix나rewrite를 쓰면 성공·실패 호 각각$request_uri와 업스트림 URI를 로그에 남깁니다. - 인증 헤더 전달:
Authorization과 벤더 서명 헤더를 명시적으로 통과시킵니다. 기본 "안전" 프록시 설정이 이를 빼는 경우가 많아 미스터리 401의 1순위 원인입니다. - GitHub Actions 연결:
workflow_dispatch와 릴리스 태그에서 돌 잡을 추가하고, 시크릿OPENCLAW_WEBHOOK_URL·OPENCLAW_WEBHOOK_TOKEN을 읽어 비-2xx면 잡을 실패시킵니다. 프로덕션이 쓰는 JSON 형태와 맞춥니다. - 401/404 훈련: 잘못된 토큰(401 기대)과 경로 한 단 더(404 기대)를 한 번씩 보내 프록시·앱 로그에서 알림 규칙을 검증합니다.
- 롤백 번들: 변경 전 프록시 유닛 파일, TLS 인증서 경로, 이전
location블록을 스냅샷합니다. 분기마다 15분 안에 복구 리허설을 합니다.
4. 인용 가능한 임계값
- 합성 웹훅 SLO: Mac이 대화형 부하로 유휴일 때 CI에서 엔드투엔드 POST→2xx p95 2.5 s 이내; 5분 동안 연속 3회 프로브 실패 시 페이지.
- 로테이션 창: 토큰 교체 후 검증기+CI 시크릿을 단일 30분 변경 창 안에서 갱신하고 티켓 종료 전 합성 잡을 재생합니다.
- 로그 상관 예산: 엣지와 애플리케이션 요청 식별자를 최소 7일 보관—주말 릴리스를 디스크 전체 스냅샷 없이 디버깅하기에 충분합니다.
- IPv6 규율: DNS에 AAAA가 있으면 IPv6 가능 러너에서 Actions를 테스트하거나 IPv4를 명시적으로 고정합니다. 혼합 패밀리 가상호스트는 "내 curl에선 됨" 404의 단골입니다.
5. FAQ
Mac에서 curl은 되는데 웹훅 URL은 HTTP 401이 나옵니다. 왜인가요?
localhost curl에는 Bearer가 있지만 로드밸런서 경로는 Authorization을 버리거나 다른 자격 증명을 요구하는 가상호스트로 보낼 수 있습니다. 프록시 액세스 로그에서 헤더 존재(해시)를 diff하고 OpenClaw 검증기가 기대하는 헤더 이름과 일치하는지 확인하세요.
같은 호스트명으로 수동 curl은 되는데 GitHub Actions는 404입니다. 왜인가요?
경로와 DNS 패밀리 불일치가 흔합니다. Actions는 /api/hooks/openclaw를 치는데 엣지는 /hooks/openclaw만 선언했거나, IPv6가 기본 서버 블록으로 갑니다. TLS 종료 지점에서 $request_uri를 로그하고 동작하는 curl과 바이트 단위로 비교하세요.
웹훅 토큰은 GitHub Secrets에만 두면 되나요?
CI는 발신 자격 증명을 시크릿에 둡니다. Mac은 Keychain, launchd 환경, 또는 권한 0600의 root 소유 파일로 검증기를 둡니다. 둘 다 커밋하지 말고 동일 유지보수 창에서 함께 로테이션하세요.
macOS나 OpenClaw 업그레이드 후 합성 웹훅은 얼마나 자주 재생해야 하나요?
게이트웨이·프록시·OS 업그레이드 직후 30분 안에 CI 프로브와 공개 URL 수동 curl을 실행합니다. 훅 등록 테이블과 동적 임포트는 작은 semver에서도 바뀔 수 있어 스키마 마이그레이션처럼 다루세요.
6. 이 자동화 엣지에 Mac mini가 맞는 이유
웹훅·훅 워커는 다른 엣지 데몬과 같이 진짜 POSIX 스택, 예측 가능한 launchd 감독, 런북과 맞는 TLS 도구를 원합니다. macOS는 WSL이나 컨테이너 네트워킹 깜짝 이슈 없이 그걸 제공하고—Homebrew, curl, Caddy·nginx가 스크립트 가정과 같이 동작합니다.
Apple Silicon Mac mini는 유휴 전력 약 4 W·무소음 냉각으로 CI 트래픽을 받아야 하는 게이트웨이에 적합합니다. Gatekeeper·SIP·FileVault는 TLS 우선 웹훅 설계와 잘 겹치고, 데스크톱 OS를 다공성으로 바꾸지 않습니다.
중첩 VM 대신 위에서 검증한 명령 그대로 통제 가능한 하드웨어에서 돌리려면 Mac mini M4가 웹훅 전체 경로를 소유하기 가장 균형 잡힌 선택입니다. ZoneMac 노드 둘러보기로 전용 Apple 실리콘에서 OpenClaw 훅을 실행해 보세요.
전용 Mac mini에서 웹훅 실행
OpenClaw 게이트웨이·서명 빌드·CI 인접 훅용 물리 macOS 노드—이 런북이 전제로 하는 TLS·launchd 스택과 동일합니다.