Matrix (플러그인)

Matrix는 개방형 분산 메시징 프로토콜입니다. OpenClaw는 임의의 홈서버에서 Matrix 사용자로 연결하므로, 봇용 Matrix 계정이 필요합니다. 로그인하면 봇에 직접 DM을 보내거나 방(Matrix “그룹”)에 초대할 수 있습니다. Beeper도 유효한 클라이언트 옵션이지만 E2EE 활성화가 필요합니다.

상태: 플러그인(@vector-im/matrix-bot-sdk)을 통해 지원됩니다. 다이렉트 메시지, 방, 스레드, 미디어, 리액션, 투표(발송 + poll-start를 텍스트로), 위치, E2EE(크립토 모듈 포함)가 지원됩니다.

플러그인 필요

Matrix는 플러그인으로 제공되며 기본 코어에 포함되지 않습니다.

CLI로 설치 (npm 레지스트리):

openclaw plugins install @openclaw/matrix

로컬 체크아웃 (git 저장소에서 실행 시):

openclaw plugins install ./extensions/matrix

설정/온보딩 중 Matrix를 선택하고 git 체크아웃이 감지되면, OpenClaw가 로컬 설치 경로를 자동으로 제안합니다.

자세한 내용: Plugins

설정

  1. Matrix 플러그인을 설치합니다:

    • npm에서: openclaw plugins install @openclaw/matrix
    • 로컬 체크아웃에서: openclaw plugins install ./extensions/matrix

  2. 홈서버에서 Matrix 계정을 생성합니다:

  3. 봇 계정의 액세스 토큰을 발급받습니다:

    • 홈서버에서 curl을 사용하여 Matrix 로그인 API를 호출합니다:
    curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "your-user-name"
  },
  "password": "your-password"
}'
    • matrix.example.org를 실제 홈서버 URL로 바꾸세요.
    • 또는 channels.matrix.userId + channels.matrix.password를 설정합니다: OpenClaw가 동일한 로그인 엔드포인트를 호출하고 액세스 토큰을 ~/.openclaw/credentials/matrix/credentials.json에 저장하여 다음 시작 시 재사용합니다.

  4. 자격 증명을 설정합니다:

    • 환경 변수: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (또는 MATRIX_USER_ID + MATRIX_PASSWORD)
    • 또는 설정: channels.matrix.*
    • 둘 다 설정된 경우 설정이 우선합니다.
    • 액세스 토큰 사용 시: 사용자 ID는 /whoami를 통해 자동으로 가져옵니다.
    • 설정 시 channels.matrix.userId는 전체 Matrix ID여야 합니다(예: @bot:example.org).

  5. 게이트웨이를 재시작합니다(또는 온보딩을 완료합니다).

  6. Matrix 클라이언트(Element, Beeper 등; https://matrix.org/ecosystem/clients/ 참조)에서 봇에 DM을 보내거나 방에 초대합니다. Beeper는 E2EE가 필요하므로 channels.matrix.encryption: true를 설정하고 디바이스를 인증하세요.

최소 설정 (액세스 토큰, 사용자 ID 자동 가져오기):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}

E2EE 설정 (종단 간 암호화 활성화):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

암호화 (E2EE)

종단 간 암호화는 Rust 크립토 SDK를 통해 지원됩니다.

channels.matrix.encryption: true로 활성화합니다:

  • 크립토 모듈이 로드되면 암호화된 방이 자동으로 복호화됩니다.
  • 암호화된 방으로 전송 시 아웃바운드 미디어가 암호화됩니다.
  • 첫 연결 시 OpenClaw가 다른 세션에 디바이스 인증을 요청합니다.
  • 다른 Matrix 클라이언트(Element 등)에서 디바이스를 인증하여 키 공유를 활성화하세요.
  • 크립토 모듈을 로드할 수 없으면 E2EE가 비활성화되고 암호화된 방이 복호화되지 않습니다. OpenClaw가 경고를 로그에 기록합니다.
  • 크립토 모듈 누락 오류(예: @matrix-org/matrix-sdk-crypto-nodejs-*)가 발생하면, @matrix-org/matrix-sdk-crypto-nodejs의 빌드 스크립트를 허용하고 pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs를 실행하거나 node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js로 바이너리를 가져오세요.

크립토 상태는 계정 + 액세스 토큰별로 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/에 저장됩니다(SQLite 데이터베이스). 동기화 상태는 동일 경로의 bot-storage.json에 있습니다. 액세스 토큰(디바이스)이 변경되면 새 저장소가 생성되고 암호화된 방에서 봇을 다시 인증해야 합니다.

디바이스 인증: E2EE가 활성화되면 봇이 시작 시 다른 세션에 인증을 요청합니다. Element(또는 다른 클라이언트)를 열고 인증 요청을 승인하여 신뢰를 설정합니다. 인증되면 봇이 암호화된 방에서 메시지를 복호화할 수 있습니다.

다중 계정

다중 계정 지원: channels.matrix.accounts에 계정별 자격 증명과 선택적 name을 사용합니다. 공유 패턴은 gateway/configuration을 참조하세요.

각 계정은 임의의 홈서버에서 별도의 Matrix 사용자로 실행됩니다. 계정별 설정은 최상위 channels.matrix 설정을 상속하며 모든 옵션(DM 정책, 그룹, 암호화 등)을 재정의할 수 있습니다.

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

참고:

  • 계정 시작은 동시 모듈 가져오기로 인한 경쟁 조건을 방지하기 위해 직렬화됩니다.
  • 환경 변수(MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN 등)는 기본 계정에만 적용됩니다.
  • 기본 채널 설정(DM 정책, 그룹 정책, 멘션 게이팅 등)은 계정별로 재정의하지 않는 한 모든 계정에 적용됩니다.
  • bindings[].match.accountId를 사용하여 각 계정을 다른 에이전트로 라우팅합니다.
  • 크립토 상태는 계정 + 액세스 토큰별로 저장됩니다(계정별 별도 키 저장소).

라우팅 모델

  • 응답은 항상 Matrix로 돌아갑니다.
  • DM은 에이전트의 메인 세션을 공유하며, 방은 그룹 세션에 매핑됩니다.

접근 제어 (DM)

  • 기본값: channels.matrix.dm.policy = "pairing". 알 수 없는 발신자는 페어링 코드를 받습니다.
  • 승인 방법:
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • 공개 DM: channels.matrix.dm.policy="open" + channels.matrix.dm.allowFrom=["*"].
  • channels.matrix.dm.allowFrom은 전체 Matrix 사용자 ID를 받습니다(예: @user:server). 마법사는 디렉토리 검색에서 정확히 하나만 매칭되면 표시 이름을 사용자 ID로 변환합니다.
  • 표시 이름이나 순수 로컬파트를 사용하지 마세요(예: "Alice" 또는 "alice"). 모호하여 허용 목록 매칭에서 무시됩니다. 전체 @user:server ID를 사용하세요.

방 (그룹)

  • 기본값: channels.matrix.groupPolicy = "allowlist" (멘션 게이팅). channels.defaults.groupPolicy를 사용하여 미설정 시 기본값을 재정의합니다.
  • 런타임 참고: channels.matrix가 완전히 없으면 런타임이 방 확인에 groupPolicy="allowlist"로 폴백합니다(channels.defaults.groupPolicy가 설정되어 있더라도).
  • channels.matrix.groups로 방을 허용 목록에 추가합니다(방 ID 또는 별칭; 디렉토리 검색에서 정확히 하나만 매칭되면 이름이 ID로 변환됩니다):
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}
  • requireMention: false는 해당 방에서 자동 응답을 활성화합니다.
  • groups."*"로 방 전체의 멘션 게이팅 기본값을 설정할 수 있습니다.
  • groupAllowFrom은 방에서 봇을 트리거할 수 있는 발신자를 제한합니다(전체 Matrix 사용자 ID).
  • 방별 users 허용 목록으로 특정 방 내 발신자를 추가로 제한할 수 있습니다(전체 Matrix 사용자 ID 사용).
  • 설정 마법사는 방 허용 목록(방 ID, 별칭 또는 이름)을 프롬프트하며, 정확히 고유하게 매칭되는 경우에만 이름을 변환합니다.
  • 시작 시 OpenClaw가 허용 목록의 방/사용자 이름을 ID로 변환하고 매핑을 로그에 기록합니다. 변환되지 않은 항목은 허용 목록 매칭에서 무시됩니다.
  • 초대는 기본적으로 자동 참가됩니다. channels.matrix.autoJoin과 channels.matrix.autoJoinAllowlist로 제어합니다.
  • 방을 허용하지 않으려면 channels.matrix.groupPolicy: "disabled"를 설정하거나 빈 허용 목록을 유지합니다.
  • 레거시 키: channels.matrix.rooms (groups와 동일한 형태).

스레드

  • 답장 스레딩이 지원됩니다.
  • channels.matrix.threadReplies는 답장이 스레드에 유지되는지 제어합니다:
    • off, inbound (기본값), always
  • channels.matrix.replyToMode는 스레드로 답장하지 않을 때의 reply-to 메타데이터를 제어합니다:
    • off (기본값), first, all

기능

기능상태
다이렉트 메시지지원됨
방지원됨
스레드지원됨
미디어지원됨
E2EE지원됨 (크립토 모듈 필요)
리액션지원됨 (도구를 통한 발송/읽기)
투표발송 지원; 인바운드 poll start는 텍스트로 변환됨 (responses/ends 무시)
위치지원됨 (geo URI; 고도 무시)
네이티브 명령지원됨

문제 해결

먼저 다음 순서로 실행합니다:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

필요 시 DM 페어링 상태를 확인합니다:

openclaw pairing list matrix

일반적인 실패 원인:

  • 로그인되었지만 방 메시지가 무시됨: groupPolicy 또는 방 허용 목록에 의해 차단됨.
  • DM이 무시됨: channels.matrix.dm.policy="pairing"일 때 발신자가 승인 대기 중.
  • 암호화된 방이 실패: 크립토 지원 또는 암호화 설정 불일치.

진단 흐름: /channels/troubleshooting.

설정 레퍼런스 (Matrix)

전체 설정: Configuration

제공자 옵션:

  • channels.matrix.enabled: 채널 시작 활성화/비활성화.
  • channels.matrix.homeserver: 홈서버 URL.
  • channels.matrix.userId: Matrix 사용자 ID (액세스 토큰 사용 시 선택).
  • channels.matrix.accessToken: 액세스 토큰.
  • channels.matrix.password: 로그인 비밀번호 (토큰이 저장됨).
  • channels.matrix.deviceName: 디바이스 표시 이름.
  • channels.matrix.encryption: E2EE 활성화 (기본값: false).
  • channels.matrix.initialSyncLimit: 초기 동기화 제한.
  • channels.matrix.threadReplies: off | inbound | always (기본값: inbound).
  • channels.matrix.textChunkLimit: 아웃바운드 텍스트 청크 크기 (문자).
  • channels.matrix.chunkMode: length (기본값) 또는 newline로 빈 줄(단락 경계)에서 먼저 분할.
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (기본값: pairing).
  • channels.matrix.dm.allowFrom: DM 허용 목록 (전체 Matrix 사용자 ID). open은 "*" 필요. 마법사가 가능한 경우 이름을 ID로 변환.
  • channels.matrix.groupPolicy: allowlist | open | disabled (기본값: allowlist).
  • channels.matrix.groupAllowFrom: 그룹 메시지의 허용된 발신자 (전체 Matrix 사용자 ID).
  • channels.matrix.allowlistOnly: DM + 방에 허용 목록 규칙 강제.
  • channels.matrix.groups: 그룹 허용 목록 + 방별 설정 맵.
  • channels.matrix.rooms: 레거시 그룹 허용 목록/설정.
  • channels.matrix.replyToMode: 스레드/태그의 reply-to 모드.
  • channels.matrix.mediaMaxMb: 인바운드/아웃바운드 미디어 용량 (MB).
  • channels.matrix.autoJoin: 초대 처리 (always | allowlist | off, 기본값: always).
  • channels.matrix.autoJoinAllowlist: 자동 참가 허용 방 ID/별칭.
  • channels.matrix.accounts: 계정 ID별 다중 계정 설정 (각 계정은 최상위 설정 상속).
  • channels.matrix.actions: 액션별 도구 게이팅 (reactions/messages/pins/memberInfo/channelInfo).
arrow_back
이전
Line
다음
Mattermost
arrow_forward