메인 콘텐츠로 건너뛰기

​
Matrix (plugin)

Matrix는 개방형 분산 메시징 프로토콜입니다. OpenClaw는 어떤 homeserver에서든 Matrix user로 연결되므로, bot용 Matrix account가 필요합니다. 로그인 후에는 bot에게 DM을 보내거나 room(Matrix의 “group”)에 초대할 수 있습니다. Beeper도 유효한 client 옵션이지만 E2EE가 켜져 있어야 합니다. 상태: plugin(@vector-im/matrix-bot-sdk)으로 지원됩니다. direct messages, rooms, threads, media, reactions, polls(send + poll-start as text), location, E2EE(crypto support 포함)를 지원합니다.

​
Plugin 필요

Matrix는 plugin으로 제공되며 core install에 번들되어 있지 않습니다. CLI 설치(npm registry): 
openclaw plugins install @openclaw/matrix
로컬 checkout: 
openclaw plugins install ./extensions/matrix
configure/onboarding 중 Matrix를 선택했고 git checkout이 감지되면, OpenClaw는 로컬 install path를 자동으로 제안합니다. 자세한 내용: Plugins

​
설정

  1. Matrix plugin을 설치합니다.
    • npm: openclaw plugins install @openclaw/matrix
    • 로컬 checkout: openclaw plugins install ./extensions/matrix
  2. homeserver에 Matrix account를 만듭니다.
  3. bot account용 access token을 얻습니다.
    • home server에서 Matrix login API를 curl로 호출:
    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는 자신의 homeserver URL로 바꾸세요.
    • 또는 channels.matrix.userId + channels.matrix.password를 설정하세요. OpenClaw는 같은 login endpoint를 호출하고 access token을 ~/.openclaw/credentials/matrix/credentials.json에 저장한 뒤 다음 시작에 재사용합니다.
  4. credential을 설정합니다.
    • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (또는 MATRIX_USER_ID + MATRIX_PASSWORD)
    • 또는 config: channels.matrix.*
    • 둘 다 설정되면 config가 우선합니다.
    • access token 사용 시 user ID는 /whoami로 자동 조회됩니다.
    • channels.matrix.userId를 직접 넣는다면 전체 Matrix ID여야 합니다 (예: @bot:example.org).
  5. gateway를 재시작합니다(또는 onboarding을 마칩니다).
  6. Matrix client(Element, Beeper 등)에서 bot과 DM을 시작하거나 room에 초대합니다. Beeper는 E2EE가 필요하므로 channels.matrix.encryption: true를 설정하고 device를 검증하세요.
최소 구성(access token, user ID 자동 조회): 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}
E2EE 구성(end-to-end encryption 활성화): 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

​
Encryption (E2EE)

종단간 암호화는 Rust crypto SDK를 통해 지원됩니다. channels.matrix.encryption: true로 활성화합니다.
  • crypto module이 로드되면 encrypted room이 자동으로 복호화됩니다.
  • encrypted room에 보낼 outbound media도 암호화됩니다.
  • 첫 연결 시 OpenClaw는 다른 session들에 device verification 요청을 보냅니다.
  • key sharing을 활성화하려면 다른 Matrix client(Element 등)에서 device를 검증하세요.
  • crypto module을 로드할 수 없으면 E2EE는 비활성화되고 encrypted room은 복호화되지 않습니다. OpenClaw는 warning을 기록합니다.
  • crypto module 누락 오류(예: @matrix-org/matrix-sdk-crypto-nodejs-*)가 보이면 @matrix-org/matrix-sdk-crypto-nodejs의 build script를 허용하고 pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs를 실행하거나, node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js로 바이너리를 가져오세요.
Crypto state는 account + access token별로 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ 아래(SQLite DB)에 저장됩니다. sync state는 그 옆의 bot-storage.json에 있습니다. access token(device)이 바뀌면 새 store가 생성되며 encrypted room용 bot 검증도 다시 해야 합니다. Device verification: E2EE가 활성화되면 bot은 시작 시 다른 session으로 verification request를 보냅니다. Element(또는 다른 client)를 열어 verification request를 승인하면 trust가 설정되고, 이후 encrypted room 메시지를 복호화할 수 있습니다.

​
Multi-account

multi-account는 channels.matrix.accounts로 구성합니다. 계정별 credential과 선택적 name을 둘 수 있습니다. 공통 패턴은 gateway/configuration 를 참고하세요. 각 account는 어떤 homeserver에서든 별도의 Matrix user로 실행됩니다. 계정별 config는 최상위 channels.matrix 설정을 상속하며, 필요한 옵션(DM policy, groups, encryption 등)을 override할 수 있습니다. 
{
  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"] },
        },
      },
    },
  },
}
참고:
  • concurrent module import의 race condition을 피하려고 account startup은 serialize됩니다.
  • env var(MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN 등)는 default account에만 적용됩니다.
  • 기본 채널 설정(DM policy, group policy, mention gating 등)은 account별 override가 없다면 모든 account에 적용됩니다.
  • bindings[].match.accountId로 각 account를 서로 다른 agent에 라우팅할 수 있습니다.
  • crypto state는 account + access token별로 따로 저장됩니다.

​
Routing model

  • reply는 항상 Matrix로 돌아갑니다.
  • DM은 agent의 main session을 공유하고, room은 group session에 매핑됩니다.

​
접근 제어(DMs)

  • 기본값: channels.matrix.dm.policy = "pairing". 알 수 없는 sender는 pairing code를 받습니다.
  • 승인:
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • 공개 DM: channels.matrix.dm.policy="open" + channels.matrix.dm.allowFrom=["*"]
  • channels.matrix.dm.allowFrom은 전체 Matrix user ID만 받습니다 (예: @user:server). wizard는 directory search가 단 하나의 정확한 match를 찾으면 display name을 user ID로 해석합니다.
  • display name이나 bare localpart(예: "Alice", "alice")는 사용하지 마세요. 모호해서 allowlist matching에서 무시됩니다. 전체 @user:server 형식을 쓰세요.

​
Rooms (groups)

  • 기본값: channels.matrix.groupPolicy = "allowlist" (mention-gated). 설정이 비어 있으면 기본값을 바꾸기 위해 channels.defaults.groupPolicy를 사용할 수 있습니다.
  • runtime 참고: channels.matrix가 완전히 없으면 room check는 channels.defaults.groupPolicy가 설정되어 있어도 groupPolicy="allowlist"로 fallback합니다.
  • room allowlist는 channels.matrix.groups로 설정합니다(room ID 또는 alias; directory search가 하나의 정확한 match를 찾을 때만 이름을 ID로 해석).
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}
  • requireMention: false면 그 room에서 auto-reply가 활성화됩니다.
  • groups."*"는 room 전반의 mention gating 기본값을 설정할 수 있습니다.
  • groupAllowFrom은 room에서 bot을 트리거할 수 있는 sender를 제한합니다 (전체 Matrix user ID).
  • room별 users allowlist는 특정 room 안의 sender를 추가로 제한할 수 있습니다 (전체 Matrix user ID 사용).
  • configure wizard는 room allowlist(room ID, alias, name)를 묻고, 정확하고 유일하게 일치하는 경우에만 name을 해석합니다.
  • 시작 시 OpenClaw는 allowlist의 room/user name을 ID로 해석하고 mapping을 로그에 남깁니다. 해석되지 않은 항목은 allowlist matching에서 무시됩니다.
  • 초대는 기본적으로 auto-join됩니다. channels.matrix.autoJoin과 channels.matrix.autoJoinAllowlist로 제어합니다.
  • 어떤 room도 허용하지 않으려면 channels.matrix.groupPolicy: "disabled"를 사용하세요 (또는 빈 allowlist 유지).
  • 레거시 key: channels.matrix.rooms (groups와 동일한 형태)

​
Threads

  • reply threading을 지원합니다.
  • channels.matrix.threadReplies는 reply가 thread에 남을지 제어합니다.
    • off, inbound(기본), always
  • channels.matrix.replyToMode는 thread reply가 아닐 때 reply-to metadata를 제어합니다.
    • off(기본), first, all

​
Capabilities

FeatureStatus
Direct messagesSupported
RoomsSupported
ThreadsSupported
MediaSupported
E2EESupported (crypto module required)
ReactionsSupported (send/read via tools)
PollsSend supported; inbound poll starts are converted to text (responses/ends ignored)
LocationSupported (geo URI; altitude ignored)
Native commandsSupported

​
문제 해결

먼저 이 순서를 실행하세요. 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
그다음 필요하면 DM pairing 상태를 확인합니다. 
openclaw pairing list matrix
흔한 문제:
  • 로그인은 됐지만 room message를 무시함: groupPolicy 또는 room allowlist에 막혀 있음
  • DM을 무시함: channels.matrix.dm.policy="pairing" 상태에서 sender 승인 대기
  • encrypted room이 실패함: crypto support 또는 encryption setting 불일치
장애 진단 흐름: /channels/troubleshooting

​
Configuration reference (Matrix)

전체 구성: Configuration Provider option:
  • channels.matrix.enabled: 채널 시작 활성화/비활성화
  • channels.matrix.homeserver: homeserver URL
  • channels.matrix.userId: Matrix user ID(access token이 있으면 선택)
  • channels.matrix.accessToken: access token
  • channels.matrix.password: login password(token 저장됨)
  • channels.matrix.deviceName: device display name
  • channels.matrix.encryption: E2EE 활성화(기본값 false)
  • channels.matrix.initialSyncLimit: initial sync limit
  • channels.matrix.threadReplies: off | inbound | always (기본값 inbound)
  • channels.matrix.textChunkLimit: outbound text chunk size(chars)
  • channels.matrix.chunkMode: length(기본) 또는 newline
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (기본 pairing)
  • channels.matrix.dm.allowFrom: DM allowlist(전체 Matrix user IDs). open에는 "*" 필요. wizard는 가능할 때 name을 ID로 해석합니다.
  • channels.matrix.groupPolicy: allowlist | open | disabled (기본 allowlist)
  • channels.matrix.groupAllowFrom: group message용 allowlisted sender(전체 Matrix IDs)
  • channels.matrix.allowlistOnly: DM + room에 allowlist 규칙 강제
  • channels.matrix.groups: group allowlist + room별 설정 map
  • channels.matrix.rooms: 레거시 group allowlist/config
  • channels.matrix.replyToMode: thread/tag용 reply-to mode
  • channels.matrix.mediaMaxMb: inbound/outbound media cap(MB)
  • channels.matrix.autoJoin: invite handling (always | allowlist | off, 기본 always)
  • channels.matrix.autoJoinAllowlist: auto-join 허용 room ID/alias
  • channels.matrix.accounts: account ID별 multi-account 구성 (각 account는 top-level setting 상속)
  • channels.matrix.actions: action별 tool gating (reactions/messages/pins/memberInfo/channelInfo)