OpenClaw Matrix 2026｜Linux VPS·Homeserver·토큰·다중 룸

Matrix는 연합형 룸과 단일 Client-Server API로 채팅 백엔드를 제공합니다. Linux 클라우드 VPS에 OpenClaw Gateway를 두고 HS와 붙이면 상시 CPU·TLS·팀·봇 단위 룸 분리를 저비용으로 가져가기 쉽습니다. 노출면은 2026 OpenClaw Linux 클라우드 VPS 최소 공격 표면: 방화벽 템플릿, Gateway 루프백 바인딩·SSH 터널 관리 vs 공개 HTTPS 리버스 프록시 결정 매트릭스·단계별 FAQ와 맞추세요. 여기서는 플러그인 활성화, Homeserver URL·토큰, 다중 룸 라우팅 재현과 동기 멈춤 L0–L3 FAQ만 압축합니다.

443

HTTPS 클라 API

!room

룸 ID 우선

L0–L3

동기 계층 점검

Matrix 플러그인 활성화(재현 베이스라인)

게이트웨이 설정에서 Matrix 통합을 켜고 프로세스 기동 시 플러그인이 로드되는지 확인합니다(셸 프로필에만 의존 금지). systemd 등으로 재시작한 뒤 로그에 플러그인 등록이 보이는지 토큰 작업 전에 확인합니다.

점검 순서(이름은 배포판에 맞게 조정)

# 1) 문서와 게이트웨이 버전 일치
openclaw version   # 또는 동등 명령

# 2) HS로 나가는 HTTPS(SNI·신뢰 저장소)
curl -sS -o /dev/null -w "%{http_code}\n" https://matrix.example.org/_matrix/client/versions

# 3) 재시작 후 로그에 플러그인 라인
sudo systemctl restart openclaw-gateway
journalctl -u openclaw-gateway -b --no-pager | tail -n 80

시각·DNS

NTP를 켜 두세요. 시간 어긋남은 TLS를 깨고 토큰이 무효처럼 보이게 합니다. HS가 사내 전용이면 게이트웨이 리졸버도 런북에 적습니다.

Homeserver URL·사용자 ID·액세스 토큰

베이스 URL은 보통 https://<host> 한 줄로 Client-Server 루트에 맞춥니다. 봇 MXID(@bot:domain)도 도메인과 일치시키고, 장수명 액세스 토큰은 Git 대신 비밀 저장소로만 넣습니다. 로테이션 후에는 게이트웨이를 재시작해 옛 세션을 비웁니다.

환경 변수 예시(실제 키 이름은 릴리스마다 다를 수 있음)

export MATRIX_HS_URL="https://matrix.example.org"
export MATRIX_USER_ID="@openclaw-bot:example.org"
export MATRIX_ACCESS_TOKEN="syt_..."   # 셸 기록에 남기지 말 것
export MATRIX_DEVICE_ID="OPENCLAW_VPS_01"  # 고정 디바이스명은 감사에 유리

E2EE 룸

E2EE가 필요하면 봇 모델(브리지용 비암호 vs 디바이스 키)을 먼저 확인하세요. 오류는 403보다 「참여만 된 채 무응답」으로 자주 보입니다. 비암호 검증 룸으로 먼저 통과시키세요.

여러 룸을 라우팅할 때의 포인트

별칭(#team:domain)보다 룸 ID(!abcdef:domain)을 우선합니다. 허용 목록에 ID를 박고 룸마다 정책 프로필을 매핑하세요. 클라이언트 트래픽과 공개 HTTPS·콜백 경로는 분리 설계합니다. TLS·업스트림·SSH 분리 패턴은 2026 OpenClaw Linux 클라우드 VPS에서 내부망·로컬 Ollama 연동: Gateway 업스트림, TLS 분리, SSH 터널과 NO_PROXY 매트릭스——재현 절차와 502·타임아웃 계층별 FAQ를 참고하면 됩니다.

라우팅	어울리는 경우	주의
단일 운영 룸	소규모 팀	나중에 스레드로 분할
허용 목록	VPS 한 대로 팀 분리	별칭 바뀌어도 룸 ID 유지
접두사 디스패치	여러 봇 공존	슬래시 명령 충돌 주의

런북 한 페이지

런북 한 줄 요약: HS URL·봇 MXID·검증 룸 ID·토큰 담당·마지막 성공 curl …/_matrix/client/versions.

계층별 FAQ: 동기와 「묵묵부답」처럼 보이는 장애

L0–L3 표현을 다른 Linux 채널 글과 맞추면 장애 티켓이 정렬됩니다.

L0 — Homeserver까지 HTTP 경로가 없음

VPS에서 HS로 curl -v. 실패 시 DNS·신뢰 저장소·기업 CA·아웃바운드 FW입니다.

L1 — Client API가 401·403

토큰·MXID·IP 허용 목록을 의심합니다. Authorization: Bearer 형식과 실제 룸 초대를 확인합니다.

L2 — 동기 루프나 큰 캐치업 지연

since 갭이 크면 멈춘 것처럼 보입니다. CPU·HS 레이트·타임라인 필터를 보고 저장된 동기 토큰으로 재개합니다.

L3 — 「참여했는데 응답이 없음」

파워 레벨·모더레이션·E2EE 신뢰·디바이스 ID 충돌을 봅니다. 스냅샷 VM에서는 디바이스 ID를 로테이션합니다.