OpenClaw Matrix 및 Element 연결 튜토리얼

소개

Matrix는 개방형 분산 인스턴트 메시징 프로토콜이며, Element는 가장 널리 사용되는 클라이언트입니다. OpenClaw를 Matrix 네트워크에 연결하면 모든 Matrix 클라이언트에서 AI 어시스턴트와 대화할 수 있으며, Matrix 프로토콜이 제공하는 프라이버시 보호와 분산화의 장점을 동시에 누릴 수 있습니다.

이 튜토리얼에서는 OpenClaw와 Matrix의 연동을 처음부터 안내해 드리겠습니다.

환경 준비

시작하기 전에 다음 조건이 충족되었는지 확인하십시오:

의존 항목	최소 버전	설명
Node.js	22+	OpenClaw 실행 환경
OpenClaw	최신 버전	`npm install -g openclaw@latest`
Matrix Homeserver	모든 버전	matrix.org 또는 자체 구축 Synapse
Element 클라이언트	모든 버전	테스트 및 일상 사용

아직 OpenClaw를 설치하지 않으셨다면 먼저 다음을 실행하십시오:

npm install -g openclaw@latest
openclaw onboard

1단계: Matrix Bot 계정 생성

OpenClaw 전용 Matrix 계정을 생성해야 합니다. Element 클라이언트를 사용하여 등록하는 것을 권장합니다.

matrix.org에서 등록

Element Web에 접속하여 "Create Account"를 클릭합니다
matrix.org를 Homeserver로 선택합니다 (또는 자체 구축한 Homeserver 주소를 사용)
사용자 이름을 입력합니다. openclaw-bot과 같은 이름을 권장합니다
강력한 비밀번호를 설정하고 등록을 완료합니다

자체 구축 Synapse에서 등록

자체 Synapse 서버를 운영하고 있다면 명령줄을 통해 등록할 수 있습니다:

# Synapse 서버에서 실행
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
# 안내에 따라 사용자 이름, 비밀번호를 입력하고 admin은 no를 선택합니다

2단계: Access Token 획득

OpenClaw는 Access Token을 통해 Matrix 계정을 인증해야 합니다. 두 가지 획득 방법이 있습니다.

방법 1: Element 클라이언트를 통해 획득

Bot 계정으로 Element에 로그인합니다
좌상단 프로필 아이콘을 클릭 → "All settings"
"Help & About" 탭으로 이동합니다
하단의 "Advanced" 영역을 펼칩니다
"Access token" 필드를 찾아 복사를 클릭합니다

방법 2: API를 통해 획득

curl -X POST "https://matrix.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@openclaw-bot:matrix.org",
    "password": "your-password-here"
  }'

반환 결과에 access_token 필드가 포함되어 있습니다:

{
  "user_id": "@openclaw-bot:matrix.org",
  "access_token": "syt_b3BlbmNsYXctYm90_xxxxxxxxxxxxx_xxxxxx",
  "device_id": "ABCDEFGHIJ"
}

이 Token을 안전하게 보관하고 타인에게 유출하지 마십시오.

3단계: OpenClaw 설정

OpenClaw 설정 파일 ~/.config/openclaw/openclaw.json5를 편집합니다:

{
  // 기타 설정...
  channels: {
    matrix: {
      enabled: true,
      // Matrix Homeserver 주소
      homeserverUrl: "https://matrix.org",
      // Bot의 전체 Matrix ID
      userId: "@openclaw-bot:matrix.org",
      // 이전 단계에서 획득한 Access Token
      accessToken: "syt_b3BlbmNsYXctYm90_xxxxxxxxxxxxx_xxxxxx",
      // 초대받은 채팅방에 자동 참여
      autoJoin: true,
      // 응답 모드: all은 모든 메시지에 응답, mention은 @로 호출 시에만 응답
      responseMode: "mention",
      // 허용된 채팅방 목록 (비어 있으면 모든 채팅방 허용)
      allowedRooms: [],
      // 표시 이름
      displayName: "OpenClaw AI",
      // 프로필 이미지 URL (선택 사항)
      avatarUrl: ""
    }
  }
}

설정 항목 상세 설명

설정 항목	타입	기본값	설명
`homeserverUrl`	string	필수	Homeserver의 전체 URL
`userId`	string	필수	Bot의 Matrix 사용자 ID
`accessToken`	string	필수	인증 토큰
`autoJoin`	boolean	`true`	채팅방 초대 자동 수락 여부
`responseMode`	string	`"mention"`	`all` 또는 `mention`
`allowedRooms`	array	`[]`	응답을 허용하는 채팅방 ID 목록
`displayName`	string	사용자 이름	Bot의 표시 이름

4단계: 시작 및 확인

설정을 저장한 후 OpenClaw를 재시작합니다:

openclaw restart

로그를 확인하여 Matrix 채널이 연결되었는지 확인합니다:

openclaw logs

다음과 유사한 출력을 확인할 수 있습니다:

[INFO] Matrix channel initializing...
[INFO] Connected to homeserver: https://matrix.org
[INFO] Logged in as @openclaw-bot:matrix.org
[INFO] Matrix channel ready, listening for messages

5단계: 채팅방 생성 및 Bot 초대

전용 채팅방 생성

Element에서 "+" 를 클릭하여 새 채팅방을 만듭니다
채팅방 이름을 "AI 어시스턴트" 등으로 입력합니다
필요에 따라 암호화 여부를 선택합니다 (아래 암호화 섹션 참조)
채팅방 생성 후 Bot 계정을 초대합니다

Bot 초대

채팅방에서 다음 명령어를 입력하여 Bot을 초대합니다:

/invite @openclaw-bot:matrix.org

autoJoin: true로 설정한 경우 Bot이 자동으로 초대를 수락하고 채팅방에 참여합니다.

대화 테스트

채팅방에서 메시지를 보내어 테스트합니다:

@openclaw-bot 안녕하세요, 자기소개를 해 주세요

responseMode를 all로 설정한 경우 @를 사용하지 않아도 응답이 트리거됩니다.

종단간 암호화 주의사항

Matrix의 종단간 암호화(E2EE)는 강력한 프라이버시 보호 기능이지만, Bot 통합 시 추가적인 주의가 필요합니다.

현재 제한 사항

OpenClaw의 Matrix 통합은 E2EE를 지원하지만 다음 사항을 고려해야 합니다:

디바이스 검증: 최초 시작 시 Bot의 디바이스 검증이 필요합니다. Element에서 수동으로 Bot의 디바이스를 검증하는 것을 권장합니다
키 백업: 키 백업을 활성화하는 것을 권장합니다. 그렇지 않으면 OpenClaw 재시작 후 이전 암호화된 메시지를 읽을 수 없을 수 있습니다
성능 오버헤드: E2EE는 메시지 처리 지연을 증가시킵니다

암호화 채팅방 지원 활성화

설정에 E2EE 관련 옵션을 추가합니다:

{
  channels: {
    matrix: {
      // ...기본 설정...
      encryption: {
        enabled: true,
        // 암호화 키 저장 경로
        storePath: "~/.openclaw/matrix-crypto-store",
        // 새 디바이스 자동 검증 여부
        autoVerify: false
      }
    }
  }
}

Bot 디바이스 검증

Element에서 디바이스 검증을 완료합니다:

Bot과의 개인 채팅을 엽니다
Bot 프로필 아이콘 클릭 → "Security"
"Manually verify by text" 또는 이모지 검증을 선택합니다
안내에 따라 검증 절차를 완료합니다

채팅방 접근 제한

보안을 위해 Bot이 특정 채팅방에서만 응답하도록 제한하는 것을 권장합니다:

{
  channels: {
    matrix: {
      // 이 채팅방에서만 메시지에 응답
      allowedRooms: [
        "!abcdefg:matrix.org",    // AI 어시스턴트 채팅방
        "!hijklmn:matrix.org"     // 팀 토론 채팅방
      ]
    }
  }
}

채팅방 ID를 얻는 방법: Element에서 채팅방 설정 → "Advanced" → "Internal room ID"를 복사합니다.

Bridge를 사용한 다른 플랫폼 연결

Matrix의 강력한 기능 중 하나는 Bridge를 통해 다른 플랫폼에 연결할 수 있다는 것입니다. OpenClaw와 함께 사용하면 하나의 Bot 계정으로 여러 플랫폼을 동시에 서비스할 수 있습니다.

주요 Bridge는 다음과 같습니다:

Bridge	연결 플랫폼	프로젝트 주소
mautrix-telegram	Telegram	github.com/mautrix/telegram
mautrix-whatsapp	WhatsApp	github.com/mautrix/whatsapp
mautrix-discord	Discord	github.com/mautrix/discord
mautrix-signal	Signal	github.com/mautrix/signal

Bridge를 통해 메시지가 Matrix와 대상 플랫폼 간에 자동으로 동기화되므로 OpenClaw는 Matrix에만 연결하면 됩니다.

자주 묻는 질문

Bot이 Homeserver에 연결할 수 없는 경우

# Homeserver에 접근 가능한지 확인
curl -s https://matrix.org/_matrix/client/versions

# Access Token이 유효한지 확인
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://matrix.org/_matrix/client/v3/account/whoami"

Bot이 메시지에 응답하지 않는 경우

responseMode 설정이 올바른지 확인합니다
allowedRooms에 현재 채팅방이 포함되어 있는지 확인합니다
OpenClaw 로그에서 오류 메시지를 확인합니다: openclaw logs

암호화된 채팅방의 메시지를 복호화할 수 없는 경우

encryption.enabled가 true로 설정되어 있는지 확인합니다
crypto-store 경로가 올바르고 쓰기 권한이 있는지 확인합니다
디바이스 검증 절차를 다시 수행합니다

마무리

이 튜토리얼을 통해 OpenClaw를 Matrix 네트워크에 성공적으로 연결하셨습니다. Matrix의 분산화 특성과 종단간 암호화 기능은 프라이버시를 중시하는 사용자에게 이상적인 선택입니다. OpenClaw의 AI 기능과 결합하면 Element 또는 Matrix와 호환되는 모든 클라이언트에서 스마트 어시스턴트 서비스를 이용할 수 있습니다.

다음 단계 권장 사항:

"OpenClaw 다중 채팅 채널 동시 연결 튜토리얼"을 참고하여 멀티 플랫폼 연동을 구현해 보십시오
ClawHub 스킬 마켓플레이스를 탐색하여 Bot에 더 많은 기능을 추가해 보십시오