2026 OpenClaw MeshMac 실전: 원격 Mac·Matrix Webhook으로 공유 빌드 상태 브로드캐스트
MeshMac 다중 노드 풀에서는 어느 Mac이 빌드하든 팀은 Matrix 한 방에서 같은 타임라인을 봐야 합니다. 아래는 OpenClaw 게이트웨이·토큰, 웹훅·앱 서비스 단계, 서명·최소 권한, CI 매핑 표, 수신 실패 FAQ까지 최소 재현 순서입니다(약 800–1500자 분량 본문).
다중 노드 협업 알림을 Matrix 한 방으로 모으기
노드마다 다른 봇·다른 방에 쏘면 온콜이 끊깁니다. 단일 인그레스 게이트웨이만 Matrix에 쓰고, CI·OpenClaw 상태는 그 앞에서 정규화하세요. 공유 큐·동기화 패턴은 다중 노드 배포·태스크 큐·상태 동기화 글과 맞추면, 빌드가 어느 원격 Mac에서 돌아도 관측자는 동일한 협업 타임라인을 봅니다.
범용 웹훅 하드닝·페이로드 검증은 OpenClaw Webhook·공유 빌드 알림과 동일한 원칙(검증 → 인증 → 큐)을 적용한 뒤, 본 글에서는 Matrix 전용 접속·토큰·룸 스코프만 추가하면 됩니다.
게이트웨이 설치와 토큰
Synapse와 CI 송신이 안정적으로 닿는 호스트(전용 VM·소형 인그레스 Mac 포함)에 OpenClaw 게이트웨이를 띄웁니다. OPENCLAW_CONFIG_ROOT를 고정하고 설정은 읽기 전용 마운트로 두세요. Matrix용 빌드 봇 사용자를 만들어 팀 방에 한 번만 초대한 뒤, 액세스 토큰은 게이트웨이 프로세스 사용자에게만 읽히게 저장합니다. 워커 노드에는 Matrix 시크릿을 넣지 않습니다.
- 홈서버 URL은 검증된 TLS와 일치해야 하며 자가 서명이면 핀 고정을 문서화합니다.
- 룸 ID는 별칭만이 아니라 전체 ID 문자열을 설정에 넣습니다.
- 상관 ID는 CI → 게이트웨이 → Matrix 본문에 같이 실어 로그를 이어 붙입니다.
토큰 로테이션 주기·바인딩은 IM 알림·토큰 로테이션 가이드와 같은 운영 리듬을 쓰면 다중 노드 전환 시에도 알림이 끊기지 않습니다.
Matrix 웹훅·앱 서비스 구성 단계
- 노출: 리버스 프록시 뒤에서
/hooks/matrix/build-status등 단일 HTTPS 경로를 연다. - 등록: 통합 관리자 또는 Synapse의
app_service_config_files로 YAML 경로를 지정한다. - 앱 서비스 YAML:
id·url·as_token·hs_token과sender_localpart·네임스페이스를 채운다. - 검증: Synapse 리로드 후 서명된 샘플 POST로
m.room.message가 방에 찍히는지 본다. - 다중 노드 가시성: 토픽 또는 메시지 푸터에
mesh_node_id를 고정 필드로 적어 SSH 없이도 어느 Mac이 보고했는지 구분한다.
메시지 서명 또는 최소 권한 검증
모든 수신 POST는 게이트웨이에서만 검증합니다. HMAC-SHA256은 원문 바이트 기준으로 서명을 재계산하고 상수 시간 비교로 맞춥니다. 제공자가 서명을 못 쓰면 베어러 시크릿에 더해 CI 고정 송신 IP 허용 목록을 두고, 타임스탬프가 5분을 넘기면 거절합니다.
Matrix 측은 한 방에 메시지 보내기만 허용된 토큰을 쓰고 초대·관리 권한은 제외합니다. Authorization 헤더는 로그에 남기지 않으며, 각 원격 Mac 러너가 아니라 오직 인그레스 한 곳에서만 Homeserver API를 호출하게 유지합니다.
CI 상태 필드 매핑 표
GitHub Actions·GitLab CI 등 페이로드를 게이트웨이 내부 키로 한 번 정규화한 뒤 Matrix 마크다운 또는 plain 텍스트로 렌더링합니다.
| CI 소스 필드 | 게이트웨이 키 | Matrix 메시지 용도 |
|---|---|---|
| workflow / pipeline 이름 | workflow | 첫 줄 굵게: 어떤 자동화가 발화했는지 |
| status / conclusion | state | queued·running·succeeded·failed 등 팀 합의 이모지와 매핑 |
| head ref / branch | branch | 릴리스 브랜치와 피처 브랜치 가시성 |
| head sha / commit id | commit | 짧은 7자 + 실행 URL 링크 |
| html_url / web_url | run_url | 클릭 가능한 로그·아티팩트로 심층 디버깅 |
| runner name / 커스텀 라벨 | mesh_node_id | 풀 내 다중 노드 구분용 푸터(협업 알림의 핵심) |
메시지가 안 올 때·수신 실패 FAQ
- CI는 200인데 방에 이벤트가 없음
- 봇 멤버십·브리지 로그의 빈 본문·템플릿의 null conclusion을 확인하고, 최소 워크플로로 재시도하세요.
- 앱 서비스 서명 오류
- Synapse의 hs_token과 디스크 YAML을 diff하고, 비밀 문자열 끝 개행을 제거한 뒤 홈서버 호스트에서 curl로 수신기 TLS를 검증합니다.
- 일부 노드만 알림이 옴
- 러너가 공유 게이트웨이 URL을 우회했을 가능성이 큽니다. 환경 변수로 웹훅 URL을 통일하고 송신을 승인된 인그레스로만 제한하세요.
- 한 실행에 타임라인이 여러 줄
- 실행 ID+상태 키로 멱등성을 두고 Redis·SQLite 등에 72시간 보관 후에만 Matrix 텍스트를 내면 중복이 사라집니다.
요약
Matrix 알림은 게이트웨이 한 줄기로만 보내고, HTTP 호출자를 검증한 뒤 CI 필드를 한 번 정규화하세요. mesh_node_id로 다중 노드 협업 맥락을 잃지 않습니다. 다음으로 홈, 블로그, 도움말 센터에서 원격 Mac 절차를 이어 보세요.