Matrix 연동
기준일: 2026-07-26
난이도: 고급
공식 기준: Matrix
개요
Hermes Matrix 어댑터는 homeserver 봇 계정으로 룸·DM에 참여합니다. 셀프호스트 Synapse/Dendrite 및 공용 서버를 지원하며, E2EE·룸 allowlist·보안 강화를 다룹니다.
핵심 개념
| 항목 | 내용 |
|---|---|
| 인증 | User ID (@bot:server) + Access Token |
| Homeserver | MATRIX_HOMESERVER URL |
| E2EE | 장치 키·올바름 검증 — macOS 등은 Proxy Mode 문서 참고 |
| 룸 제한 | allowed_rooms |
| 보안 | 토큰 권한 최소화, 비공개 배포 hardening |
상세
설정 단계
- 봇 계정 생성 (공용 클라이언트 또는 관리 API)
- Access Token 발급 (로그인 후 토큰; 유출 = 계정 탈취)
- 본인 Matrix User ID를 allowlist에 추가
hermes gateway setup또는.env
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:example.org
MATRIX_ACCESS_TOKEN=syt_...
MATRIX_ALLOWED_USERS=@you:example.org
# MATRIX_HOME_ROOM=!roomid:example.org
hermes gateway
동작
- DM/룸 메시지 → 세션 키 정책에 따라 컨텍스트 분리
- 명령은 플랫폼 슬래시·텍스트 명령 매핑 (원문 Commands in Matrix)
- Home Room: cron·프로액티브 알림
E2EE
암호화 룸에서는 장치 신뢰·키 백업이 중요합니다. 네이티브 E2EE 제약이 있는 환경(문서의 macOS Proxy Mode 등)은 공식 Proxy Mode 절을 따르세요.
Private hardening
- 등록 비공개, rate limit, federation 제한
- 봇 계정 별도, admin 권한 금지
- 토큰 로테이션
Room allowlist
# 개념: allowed_rooms 에 room ID 목록
# 비어 있으면 정책 기본값 — 원문 표 확인
트러블슈팅
| 문제 | 확인 |
|---|---|
| 로그인/동기화 실패 | homeserver URL, 토큰 만료 |
| 암호화 메시지 해독 실패 | 장치 키, 재로그인, proxy mode |
| 룸 무응답 | invite, 초대, power level |
| 테스트 | 원문 Synapse integration tests 경로 |
보안
Access token = 비밀번호. allowlist 없이 공개 룸 배치 금지. 민 작업은 E2EE + 검증된 장치.
체크리스트
- 공식 원문과 명령·설정 키를 대조했다
- 로컬/
config.yaml/.env에서 재현 경로를 확인했다 - 권한·allowlist·시크릿 노출을 점검했다
- 실패 시 롤백·비활성화 방법을 알고 있다
다음 단계
- 공식 문서: Matrix
- 메시징 게이트웨이
- Hermes Agent 소개
기준일: 2026-07-26 — 공식 문서 동기화 코퍼스