2026 OpenClaw Matrix 채널: matrix-js-sdk 플러그인, 최소 구성, Mac 클라우드 검증
Matrix는 단일 Webhook이 아니다. 장기 동기화·토큰·E2EE가 Slack/Discord와 다르다. 본 문서는 matrix-js-sdk 경로, ClawHub 스타일 플러그인 전제, Homeserver부터 방 권한까지의 순서, Mac 클라우드에서의 프로세스·출구/DNS, 수신 없음/전송 실패/불안정 연결 표를 정리한다. Docker DNS 문서와 함께 읽으면 추상도 오류를 크게 줄인다.
1. 문제
동기 루프가 멈추면 몇 시간 동안 조용하다. 개인 토큰으로 봇을 돌리면 감사와 로테이션이 깨진다. E2EE 방에서는 장치 신뢰가 없으면 플러그인 결함처럼 보인다. Webhook형과 달리 Matrix는 멤버십과 방 ACL이 곧바로 배달 가능 여부에 영향을 준다. 모델은 정상인데 Matrix만 빨간색일 때는 모델이 아니라 동기 대기열과 방 권한을 먼저 본다.
TLS 가로채기 환경에서는 로그에 TLS 오류가 흩어지므로, 인증서 저장소와 프록시 예외를 맞추기 전에는 SDK를 바꿔도 재현된다. 연합을 쓴다면 방화벽에서 연합 포트 정책을 먼저 확정하고, Mac 클라우드의 고정 출구 IP가 홈서버 허용 목록에 있는지 확인한다.
2. 전제
플러그인과 레지스트리로 기능을 모으고, Matrix는 공식 SDK로 브라우저 확장 의존을 줄인다. Node 지원 범위를 맞추고 비대화형으로 버전을 고정한다. 변경 전 ~/.openclaw를 백업한다. 기업 프록시에서는 HTTPS_PROXY와 NO_PROXY를 OpenClaw와 동일 환경에 둔다. 맥 클라우드에서는 launchd와 로그 로테이션을 먼저 정한다. 스테이징에서 모델 연결과 Matrix 동기화를 별도 메트릭으로 두면 야간 무음 장애 원인을 나누기 쉽다.
플러그인 업데이트 시 Peer 경고를 무시하지 말고, SecretRef나 채널 Breaking이 있는 메이저 업그레이드 글과 동시에 넣지 않도록 유지보수 창을 분리한다.
운영 관점에서 Matrix는 메시지 한 통마다 상태가 쌓이므로 로그 볼륨이 Webhook보다 커질 수 있다. 디스크 알림 임계값을 낮게 잡고, 로그 보존 일수를 GDPR·사내 정책과 맞춘다. Mac 클라우드 인스턴스를 수평 확장할 때는 동일 토큰을 복제하지 말고 봇 사용자를 분리해 레이스를 피한다.
3. 표
| 항목 | Matrix SDK | Webhook |
|---|---|---|
| 연결 | 장기 동기화 | 요청/구독 |
| 자격 | 토큰+장치 | URL/OAuth |
| 운영 | 재연결·지연 | 429 |
4. 5단계
네트워크와 신원을 먼저 증명한 뒤 프롬프트를 다룬다. 각 단계마다 성공 기준을 한 줄로 적어두면 온콜이 문서만 보고도 되돌릴 수 있다.
- 플러그인 고정 버전 설치
- Homeserver https URL
- 봇 토큰을 시크릿에
- 최소 방에서 텍스트 전송 확인
openclaw doctor와 로그, launchd 재시작 정책
curl로 Homeserver 헬스 엔드포인트를 비교해 네트워크 경로 차이를 한 줄로 기록한다.5. 지표
- 동기 지연 상한을 E2E로 기록
- 동일 출구 IP의 429는 에이전트 분리·지터
- 디스크 가득 방지 로그 로테이션
- 스테이징 24시간 번인 후 프로덕션
- 토큰 만료는 Matrix만 조용히 죽이므로 Runbook에 명시
- 낮은 메모리 플랜에서는 동기 배치와 추론이 경쟁할 수 있음
- 여러 Homeserver를 쓰면 토큰·방 ID를 섞지 않는다
- 릴리스 노트에서 채널 플러그인 변경을 주말 배포 전에 확인
- 동일 맥락의 Docker Exit 137·DNS 글과 교차 검증하면 추상도를 낮출 수 있다
- 채널별로 로그 라벨을 나누면 Slack Webhook 오류와 Matrix 동기 오류가 혼선되지 않는다
- 주말 배포 전에는 변경 범위를 한 플러그인으로 제한하고 롤백 담당자를 명시한다
- 모델 장애와 채널 장애를 동시에 의심하지 말고 메트릭으로 먼저 분리한다
- 알림 채널(페이지듀티)과 Matrix 운영 채널을 분리하면 노이즈가 눈에 띄게 줄어든다.
- 운영자 교대 시 봇 토큰 위치를 한 줄로 문서화한다
6. FAQ
Slack 병행? 자격 증명과 로그 라벨을 분리하고 한 번에 한 채널만 변경한다. 라우팅 규칙이 겹치면 한 채널에서 온 이벤트가 다른 채널 워크플로를 덮어쓸 수 있으므로, 스테이징에서 라우팅 매트릭스를 표로 남긴다.
| 증상 | 먼저 | 다음 |
|---|---|---|
| 수신 없음 | 참여·동기 | FW/프록시/TLS |
| 전송 실패 | ACL·속도 | 모델 규칙 |
| 불안정 | 재시작·RAM·디스크 | 서버 점검 |
롤백: 아카이브를 복원하고 Matrix 끈 뒤 다른 채널이 살아 있는지 확인한다.
대시보드에는 동기 지연과 모델 지연을 다른 계열로 둔다. 야간 배치로 대량 전송할 때는 속도 제한을 피하기 위해 지터를 넣는다. 스테이징과 프로덕션의 OPENCLAW_* 접두사를 분리하면 설정 누출을 줄인다. 여러 Homeserver를 실험할 때 토큰과 방 ID를 섞지 않는다.
Windows나 과도한 컨테이너 추상은 네트워크와 권한 비용이 든다. Apple 도구와 SSH 운용에 익숙한 팀에는 Mac 클라우드에 OpenClaw와 다중 채널을 두는 편이 장기적으로 안정적이다. 본문에서 다룬 doctor·로그·프록시 순서와 VPSMAC의 5분 배포 가이드를 같은 Runbook에 묶으면 온콜이 가벼워진다. 신규 온보딩 시 봇 계정·방 초대 권한을 개인 계정과 분리하는 체크리스트를 두고, 장애 포스트모템에는 동기 지연 P99와 모델 지연 P99를 함께 남겨 다음 분기 용량에 반영한다.