OpenClaw

OpenClaw Matrix 채널

분산형
보통

OpenClaw를 Matrix(오픈 연합 통신 프로토콜)에 연결합니다. 이 통합을 통해 AI 어시스턴트는 모든 홈서버(matrix.org, Element 또는 자체 호스팅)의 Matrix 룸 및 다이렉트 메시지에 참여할 수 있습니다. OpenClaw는 Matrix Client-Server API를 통해 연결하며 Rust crypto SDK를 통한 선택적 종단 간 암호화(E2EE)를 지원합니다. Matrix 채널은 플러그인으로 제공되며 연합, 스레드, 리액션 및 리치 미디어를 지원합니다.

기본 정보
난이도보통
카테고리분산형
지원 기능 수5 / 6

Matrix 지원 기능

텍스트 메시지

지원

미디어 및 파일

지원

리액션

지원

스레드

지원

음성 메시지

미지원

그룹 채팅

지원

Matrix 사전 요구사항

  • 모든 홈서버(matrix.org, Element 또는 자체 호스팅)의 활성 Matrix 계정
  • Matrix 플러그인 설치: openclaw plugins install @openclaw/matrix
  • 실행 및 구성된 OpenClaw Gateway
  • 서버에 Node.js 18+ 설치됨

Matrix 빠른 설정

1

Matrix 플러그인 설치

Matrix 채널은 별도의 플러그인으로 제공됩니다. 'openclaw plugins install @openclaw/matrix'로 설치합니다. 플러그인은 npm 레지스트리에서 다운로드되어 자동으로 활성화됩니다.

2

Matrix 자격 증명 얻기

액세스 토큰 또는 사용자명/비밀번호가 필요합니다. 액세스 토큰의 경우: curl을 사용하여 홈서버의 로그인 엔드포인트를 호출하고 토큰을 복사합니다. 사용자명/비밀번호의 경우: Gateway가 자동으로 로그인하고 토큰을 ~/.openclaw/credentials/matrix/credentials.json에 저장합니다.

3

Matrix 채널 구성 추가

홈서버 URL과 자격 증명이 포함된 Matrix 채널 구성을 ~/.openclaw/openclaw.json에 추가합니다. 환경 변수 MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_PASSWORD도 사용할 수 있습니다.

4

Gateway 시작 및 테스트

'openclaw gateway'를 실행하여 서비스를 시작합니다. 다른 계정에서 Matrix 봇 사용자에게 다이렉트 메시지를 보냅니다. 기본 페어링 정책을 사용하는 경우 터미널에서 'openclaw pairing approve matrix <code>'를 통해 발신자를 승인합니다.

Matrix 구성 예시

config.json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "accessToken": "your_access_token_here",
      "dmPolicy": "pairing"
    }
  }
}

Matrix 상세 문서

아키텍처 개요

OpenClaw는 Client-Server API를 통해 Matrix에 연결하여 표준 Matrix 클라이언트 역할을 합니다. 아키텍처는 이벤트 기반입니다: 봇은 긴 폴링 동기화 요청을 통해 이벤트(메시지, 리액션, 멤버 변경)를 수신하고 AI로 처리한 다음 API를 통해 응답을 보냅니다. Matrix는 연합형이므로 봇은 봇 계정이 등록된 홈서버뿐만 아니라 글로벌 Matrix 네트워크의 모든 홈서버 사용자와 통신할 수 있습니다. 이는 WhatsApp이나 Telegram과 같은 중앙 집중식 플랫폼과 근본적으로 다릅니다. 흐름: 사용자가 Matrix에서 메시지 전송 → 홈서버가 동기화를 통해 Gateway로 라우팅 → OpenClaw가 AI로 처리 → 이벤트 전송 API를 통해 응답 → 메시지가 연합을 통해 전달.
연합을 통해 matrix.org의 봇은 모든 Matrix 홈서버(예: element.io, Mozilla의 홈서버 또는 자체 호스팅 인스턴스)의 사용자와 채팅할 수 있습니다.
Matrix 플러그인은 기본적으로 긴 폴링을 사용합니다. Webhook이나 공개 URL이 필요 없습니다 — Gateway가 홈서버에 대한 아웃바운드 연결을 설정합니다.

인증 방법

OpenClaw는 Matrix에 대한 두 가지 인증 방법을 지원합니다: 1. **액세스 토큰(권장)** — curl 또는 Matrix 클라이언트를 사용하여 홈서버의 로그인 API를 호출하여 토큰을 얻습니다. 구성에서 channels.matrix.accessToken을 설정합니다. 시스템은 /whoami 엔드포인트를 통해 사용자 ID를 자동으로 가져옵니다. 2. **사용자명/비밀번호** — channels.matrix.userId 및 channels.matrix.password를 설정합니다. OpenClaw는 로그인 엔드포인트를 자동으로 호출하고 액세스 토큰을 ~/.openclaw/credentials/matrix/credentials.json에 저장합니다. 환경 변수는 구성 파일보다 우선합니다: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_PASSWORD.
openclaw.json
# 액세스 토큰 방식
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx..."
    }
  }
}

# 사용자명/비밀번호 방식
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your_password"
    }
  }
}
액세스 토큰이나 비밀번호를 버전 관리에 커밋하지 마십시오. 프로덕션 배포에는 환경 변수를 사용하십시오. 토큰이 손상된 경우 Matrix 클라이언트를 통해 모든 기기에서 로그아웃하여 모든 토큰을 무효화한 다음 새 토큰을 생성하십시오.

DM 정책

DM(다이렉트 메시지) 정책은 AI 어시스턴트와 상호 작용할 수 있는 사용자를 제어합니다. OpenClaw는 4가지 정책을 지원합니다: • pairing(기본값) — 알 수 없는 사용자는 첫 번째 연락 시 페어링 코드를 받습니다. 'openclaw pairing approve matrix <CODE>'를 통해 승인하여 액세스 권한을 부여합니다. 승인되면 사용자는 자유롭게 채팅할 수 있습니다. • allowlist — channels.matrix.dm.allowFrom에 명시적으로 나열된 Matrix 사용자 ID만 봇에 메시지를 보낼 수 있습니다. 다른 사용자는 자동으로 무시됩니다. • open — 봇에 메시지를 보내는 모든 사용자가 응답을 받습니다. allowFrom: ["*"]가 필요합니다. 주의해서 사용하십시오. • disabled — DM 처리가 완전히 꺼집니다. 허용 목록은 @user:server 형식의 전체 Matrix 사용자 ID(예: @alice:matrix.org)를 허용합니다.
openclaw.json
{
  "channels": {
    "matrix": {
      "dmPolicy": "allowlist",
      "dm": {
        "allowFrom": ["@alice:matrix.org", "@bob:example.org"]
      }
    }
  }
}

그룹 채팅(룸) 지원

Matrix 그룹 대화는 "룸"이라고 합니다. 기본적으로 OpenClaw는 룸에 대해 허용 목록 정책을 사용하며 멘션 기반 활성화가 필요합니다. 봇이 참여하는 룸과 응답 방법을 구성할 수 있습니다. 룸은 룸 ID(!roomId:server) 또는 룸 별칭(#alias:server)으로 식별됩니다. 자동 참여 동작, 멘션 요구 사항 및 룸별 사용자 허용 목록과 같은 룸별 설정을 구성할 수 있습니다.
openclaw.json
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!abc123:matrix.org": {
          "allow": true,
          "requireMention": false,
          "users": ["@alice:matrix.org"]
        },
        "#team-chat:example.org": {
          "allow": true
        }
      },
      "autoJoin": "allowlist"
    }
  }
}
autoJoin을 'always'로 설정하면 모든 룸 초대를 자동으로 수락하고, 'allowlist'는 구성된 룸만 참여하며, 'off'는 초대를 무시합니다.
requireMention: false를 사용하면 봇을 멘션하지 않고도 자동 응답이 활성화됩니다. 트래픽이 많은 룸에서는 주의해서 사용하십시오.

종단 간 암호화(E2EE)

Matrix는 Olm 및 Megolm 프로토콜을 통해 종단 간 암호화(E2EE)를 지원합니다. Rust crypto SDK를 통해 암호화를 활성화하면 OpenClaw가 암호화된 룸에 참여할 수 있습니다. 활성화되면 시스템은 암호화된 메시지를 자동으로 해독하고, 보호된 룸에서 아웃바운드 미디어를 암호화하며, 암호화 상태를 ~/.openclaw/matrix/accounts/(SQLite)에 저장합니다. 첫 번째 연결 시 기기 확인이 필요합니다 — Element 또는 다른 Matrix 클라이언트에서 확인 요청을 승인하여 키 공유를 활성화합니다. 암호화 모듈 로드에 실패하면 E2EE가 비활성화되고 암호화된 룸에 액세스할 수 없습니다.
openclaw.json
{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}
액세스 토큰을 변경하면 기기 재확인이 필요합니다. 암호화된 메시지 기록에 대한 액세스를 잃지 않도록 암호화 상태 디렉터리(~/.openclaw/matrix/accounts/)의 백업을 유지하십시오.

연합 및 홈서버 선택

Matrix는 연합 프로토콜입니다 — 단일 중앙 서버가 없습니다. 모든 홈서버에 봇을 등록할 수 있습니다: • **matrix.org** — Matrix Foundation이 운영하는 대표 홈서버. 개방형 등록, 높은 신뢰성이지만 높은 트래픽으로 인해 느릴 수 있습니다. • **Element Matrix Services** — element.io에서 전문적으로 호스팅되는 홈서버, 프리미엄 기능 및 지원 포함. • **자체 호스팅** — 자체 홈서버를 실행하여 최대 제어 및 개인 정보 보호를 달성합니다. Synapse가 가장 성숙하고 활발하게 개발되고 있는 옵션입니다. Dendrite (Go)와 Conduit (Rust)는 소규모 배포에 적합한 가벼운 대안이지만, 현재 유지보수 또는 제한적 개발 모드로 전환되었습니다. 봇이 어디에 등록되어 있든 연합 덕분에 모든 홈서버의 사용자와 통신할 수 있습니다.
프로덕션 배포의 경우 더 나은 제어 및 성능을 위해 자체 호스팅 홈서버 또는 Element Matrix Services 사용을 고려하십시오.
연합은 투명하게 작동합니다 — 사용자는 봇이 어느 홈서버에 있는지 알 필요가 없습니다.

스레드 및 응답 모드

Matrix는 m.thread 관계 유형을 통해 스레드 대화를 지원합니다. OpenClaw는 스레드에 참여하고 응답 처리 방법을 제어할 수 있습니다. threadReplies 설정은 스레드 동작을 제어합니다: 'off'는 스레드 지원을 비활성화하고, 'inbound'는 스레드 컨텍스트만 읽으며, 'always'는 읽기와 스레드 응답 생성을 모두 수행합니다. replyToMode 설정은 응답 관계에 대한 메타데이터 첨부를 제어합니다.
openclaw.json
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "reference"
    }
  }
}

미디어 처리 및 파일 업로드

Matrix는 이미지, 동영상, 오디오 및 문서를 포함한 리치 미디어를 지원합니다. OpenClaw는 미디어 업로드를 자동으로 처리합니다 — 파일은 홈서버의 미디어 저장소에 업로드되고 메시지 이벤트에서 참조됩니다. mediaMaxMb 설정을 통해 최대 파일 크기를 구성할 수 있습니다. 기본 인바운드 미디어는 50MB이며 아웃바운드 전송 시 큰 이미지는 자동으로 JPEG 최적화 및 크기 조정이 수행됩니다.
openclaw.json
{
  "channels": {
    "matrix": {
      "mediaMaxMb": 50
    }
  }
}
미디어 업로드는 홈서버에 저장됩니다. matrix.org와 같은 공개 홈서버를 사용하는 경우 스토리지 제한 및 서비스 약관에 유의하십시오.

리액션 및 리치 기능

OpenClaw는 Matrix 리액션(메시지에 대한 이모지 응답), 투표, 위치 공유(geo URI 형식) 및 기타 리치 기능을 지원합니다. 활성화하면 도구를 통해 리액션을 보내고 읽을 수 있습니다. actions 구성을 통해 특정 작업을 제어하여 AI 에이전트가 수행할 수 있는 작업(리액션, 메시지, 고정, 멤버/채널 정보)을 제한할 수 있습니다.
openclaw.json
{
  "channels": {
    "matrix": {
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": false
      }
    }
  }
}

자체 호스팅 AI에 Matrix를 선택하는 이유

Matrix는 자체 호스팅 AI 어시스턴트에 탁월한 선택입니다: • **진정으로 개방적** — 개방형 사양, 벤더 종속 없음, 여러 클라이언트 및 서버 구현. • **연합형** — 단일 제어 지점 또는 장애 지점이 없습니다. 봇은 글로벌 Matrix 네트워크 전체에서 통신할 수 있습니다. • **개인 정보 중심** — E2EE 지원, 자체 호스팅 옵션, 중앙 집중식 데이터 수집 없음. • **기능 풍부** — 스레드, 리액션, 미디어, 투표 및 확장 가능한 이벤트 유형. • **전화번호 불필요** — WhatsApp이나 Signal과 달리 Matrix 등록에는 전화번호가 필요하지 않습니다. 절충점은 복잡성입니다: Matrix의 연합 모델과 E2EE 설정은 중앙 집중식 플랫폼보다 더 복잡할 수 있습니다. 개인 정보를 중시하는 사용자와 팀에게는 이러한 절충점이 가치가 있습니다.

Matrix 구성 참조

enabled
Type: booleanDefault: true

Matrix 채널 활성화 또는 비활성화

homeserver
Type: stringDefault: "https://matrix.org"

Matrix 홈서버 URL(예: https://matrix.org, https://element.io)

accessToken
Type: stringDefault: ""

인증용 Matrix 액세스 토큰(권장 방법)

userId
Type: stringDefault: ""

Matrix 사용자 ID(예: @bot:matrix.org) — 비밀번호 인증과 함께 사용

password
Type: stringDefault: ""

Matrix 계정 비밀번호 — userId와 함께 로그인에 사용

encryption
Type: booleanDefault: false

Rust crypto SDK를 통한 종단 간 암호화 활성화

dmPolicy
Type: stringDefault: "pairing"

DM 액세스 정책: pairing, allowlist, open 또는 disabled

dm.allowFrom
Type: arrayDefault: []

DM이 허용되는 Matrix 사용자 ID(예: [@alice:matrix.org])

groupPolicy
Type: stringDefault: "allowlist"

룸 정책: allowlist 또는 disabled

groups
Type: objectDefault: {}

룸별 구성(룸 ID 또는 별칭을 키로 사용)

groups.<roomId>.allow
Type: booleanDefault: false

봇이 이 룸에 참여하도록 허용

groups.<roomId>.requireMention
Type: booleanDefault: true

이 룸에서 응답을 트리거하려면 봇 멘션 필요

groups.<roomId>.users
Type: arrayDefault: []

룸별 사용자 허용 목록(Matrix 사용자 ID)

autoJoin
Type: stringDefault: "allowlist"

룸 초대 자동 참여: always, allowlist 또는 off

textChunkLimit
Type: numberDefault: 4096

아웃바운드 메시지당 최대 문자 수

chunkMode
Type: stringDefault: "length"

긴 응답 분할 방법: length(하드 제한) 또는 newline(단락 경계)

threadReplies
Type: stringDefault: "inbound"

스레드 동작: off, inbound(읽기 전용) 또는 always(읽기 + 생성)

replyToMode
Type: stringDefault: "reference"

응답 메타데이터 첨부 모드

mediaMaxMb
Type: numberDefault: 50

최대 미디어 파일 크기(메가바이트)

actions.reactions
Type: booleanDefault: true

에이전트가 리액션을 보내고 읽을 수 있도록 허용

actions.messages
Type: booleanDefault: true

에이전트가 메시지를 읽고 보내고 편집하고 삭제할 수 있도록 허용

actions.pins
Type: booleanDefault: true

에이전트가 메시지를 고정하거나 고정 해제할 수 있도록 허용

actions.memberInfo
Type: booleanDefault: true

에이전트가 룸 멤버 정보를 조회할 수 있도록 허용

actions.channelInfo
Type: booleanDefault: true

에이전트가 룸/채널 정보를 검색할 수 있도록 허용

Matrix 자주 묻는 질문

Matrix 문제 해결

봇이 메시지를 받지 못함

DM 정책이 메시지를 차단하거나 봇이 룸에 없음

channels.matrix.dmPolicy 및 dm.allowFrom 설정을 확인하십시오. 룸의 경우 룸이 groups 허용 목록에 있고 봇이 초대되어 참여했는지 확인하십시오.
E2EE 암호화된 룸에 메시지가 표시되지 않음

기기가 확인되지 않았거나 암호화 모듈 로드 실패

Element 또는 다른 Matrix 클라이언트에서 봇의 기기를 확인하십시오. 암호화 모듈 로드 오류에 대한 로그를 확인하십시오. channels.matrix.encryption이 true로 설정되어 있는지 확인하십시오.
액세스 토큰이 유효하지 않거나 만료됨

홈서버에서 토큰이 취소되거나 무효화됨

다시 로그인하여 새 액세스 토큰을 생성하십시오. 사용자명/비밀번호를 사용하는 경우 ~/.openclaw/credentials/matrix/credentials.json을 삭제하고 Gateway를 다시 시작하십시오.
봇이 룸에 참여했지만 응답하지 않음

룸이 허용 목록에 없거나 requireMention이 활성화됨

allow: true로 룸을 channels.matrix.groups에 추가하십시오. requireMention이 true인 경우 사용자는 응답을 받으려면 봇을 멘션해야 합니다.
다른 홈서버와의 연합 오류

홈서버 연결 또는 연합 문제

federationtester.matrix.org에서 홈서버의 연합 상태를 확인하십시오. 자체 호스팅인 경우 DNS SRV 레코드 및 SSL 인증서를 확인하십시오.
플러그인 설치 실패

npm 레지스트리 액세스 또는 Node.js 버전 비호환성

Node.js 18+가 설치되어 있는지 확인하십시오. 자세한 오류 로그를 보려면 'openclaw plugins install @openclaw/matrix --verbose'를 시도하십시오. npm 레지스트리에 대한 네트워크 연결을 확인하십시오.
전체 문서 보기모든 채널로 돌아가기

관련 채널

Nostr

Advanced

OpenClaw 분산형 NIP-04 DM 통합

설정 가이드

Tlon

Advanced

OpenClaw Urbit 메신저 통합

설정 가이드