OpenClaw Matrix 플러그인 설정: 5분 만에 메시징 연동하기

새로운 채팅 플랫폼을 연동할 때마다 복잡한 설정 과정 때문에 머리 아픈 적 많으시죠? 특히 Matrix처럼 강력하지만 세부 설정이 많은 프로토콜은 더 까다롭게 느껴질 수 있어요. OpenClaw의 Matrix 플러그인을 사용하면 DM부터 E2EE(종단간 암호화)까지 필요한 기능을 깔끔하게 구현할 수 있습니다.

필요한 플러그인

Matrix는 플러그인 형태이며 OpenClaw 코어에 기본으로 포함되어 있지 않아요.

npm에서 설치하려면 다음 명령어를 사용하세요:

openclaw plugins install @openclaw/matrix

로컬 체크아웃에서 설치하는 방법은 다음과 같아요:

openclaw plugins install ./path/to/local/matrix-plugin

플러그인 동작 방식과 설치 규칙에 대한 자세한 내용은 Plugins 문서를 참고해 주세요.

설정

1. 플러그인을 설치합니다.
2. homeserver에 Matrix 계정을 생성합니다.
3. channels.matrix를 다음 중 하나로 설정합니다:
   • homeserver + accessToken
   • homeserver + userId + password
4. Gateway를 재시작합니다.
5. 봇과 DM을 시작하거나 봇을 room에 초대합니다.

대화형 설정 경로는 다음과 같아요:

openclaw channels add
openclaw configure --section channels

Matrix 위저드에서 실제로 묻는 항목들은 다음과 같습니다:

• homeserver URL
• 인증 방식: access token 또는 password
• password 인증을 선택한 경우에만 user ID 입력
• 선택 사항인 device name
• E2EE 활성화 여부
• 지금 Matrix room access를 설정할지 여부

위저드 동작 시 주의할 점이에요:

• 선택한 계정에 대한 Matrix 인증 환경 변수가 이미 존재하고, 해당 계정의 인증 정보가 설정 파일에 저장되어 있지 않다면, 위저드는 환경 변수 숏컷을 제안하고 해당 계정에 대해 enabled: true만 기록합니다.
• 다른 Matrix 계정을 대화형으로 추가할 때, 입력한 계정 이름은 설정 및 환경 변수에 사용되는 계정 ID로 정규화됩니다. 예를 들어, Ops Bot은 ops-bot이 됩니다.
• DM allowlist 프롬프트는 전체 @user:server 값을 즉시 수락합니다. 표시 이름(Display name)은 실시간 디렉토리 조회에서 정확히 일치하는 항목이 하나만 있을 때만 작동하며, 그렇지 않으면 위저드에서 전체 Matrix ID로 다시 시도하라고 요청합니다.
• Room allowlist 프롬프트는 room ID와 alias를 직접 수락합니다. 참여 중인 room 이름을 실시간으로 확인할 수도 있지만, 확인되지 않은 이름은 설정 시 입력한 대로만 유지되고 나중에 런타임 allowlist 확인 시 무시됩니다. !room:server 또는 #alias:server 형식을 사용하는 것이 좋습니다.
• 런타임 room/세션 식별에는 고정된 Matrix room ID를 사용합니다. room에 선언된 alias는 조회용 입력값으로만 사용되며, 장기적인 세션 키나 고정된 그룹 식별자로 사용되지 않습니다.
• 저장하기 전에 room 이름을 확인하려면 openclaw channels resolve --channel matrix "Project Room" 명령어를 사용하세요.

최소한의 token 기반 설정 예시입니다:

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

password 기반 설정 예시입니다 (로그인 후 token이 캐시됩니다):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

Matrix는 캐시된 인증 정보를 ~/.openclaw/credentials/matrix/에 저장합니다. 기본 계정은 credentials.json을 사용하고, 이름이 지정된 계정은 credentials-<account>.json을 사용해요.

환경 변수 대응 항목은 다음과 같습니다 (설정 키가 지정되지 않은 경우 사용됩니다):

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

기본 계정이 아닌 경우, 계정 범위가 지정된 환경 변수를 사용하세요:

• MATRIX_<ACCOUNT_ID>_HOMESERVER
• MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
• MATRIX_<ACCOUNT_ID>_USER_ID
• MATRIX_<ACCOUNT_ID>_PASSWORD
• MATRIX_<ACCOUNT_ID>_DEVICE_ID
• MATRIX_<ACCOUNT_ID>_DEVICE_NAME

ops 계정에 대한 예시입니다:

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

정규화된 계정 ID ops-bot의 경우 다음과 같이 사용합니다:

• MATRIX_OPS_BOT_HOMESERVER
• MATRIX_OPS_BOT_ACCESS_TOKEN

대화형 위저드는 이러한 인증 환경 변수가 이미 존재하고 선택한 계정에 Matrix 인증 정보가 설정 파일에 저장되어 있지 않은 경우에만 환경 변수 숏컷을 제안합니다.

설정 예시

DM pairing, room allowlist, E2EE가 활성화된 실용적인 기본 설정이에요:

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}

스트리밍 미리보기

Matrix 답변 스트리밍은 선택 사항(opt-in)입니다.

OpenClaw가 단일 초안 답변을 보내고, 모델이 텍스트를 생성하는 동안 해당 초안을 실시간으로 수정하며, 답변이 완료되면 최종 확정하도록 하려면 channels.matrix.streaming을 "partial"로 설정하세요:

{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

• streaming: "off"가 기본값입니다. OpenClaw는 최종 답변이 나올 때까지 기다렸다가 한 번에 보냅니다.
• streaming: "partial"은 여러 개의 부분 메시지를 보내는 대신 수정 가능한 하나의 미리보기 메시지를 생성합니다.
• 미리보기가 더 이상 하나의 Matrix event에 들어가지 않을 정도로 길어지면, OpenClaw는 미리보기 스트리밍을 중단하고 일반적인 최종 전송 방식으로 전환합니다.
• 미디어 답변은 여전히 첨부 파일을 정상적으로 전송합니다. 오래된 미리보기를 더 이상 안전하게 재사용할 수 없는 경우, OpenClaw는 최종 미디어 답변을 보내기 전에 해당 미리보기를 삭제(redact)합니다.
• 미리보기 수정은 추가적인 Matrix API 호출 비용이 발생합니다. 가장 보수적인 rate-limit 동작을 원한다면 스트리밍을 꺼두는 것이 좋습니다.

AI Setup Assistant

다음 단계

• 플러그인 기본 가이드
• Gateway 설정 상세
• E2EE 보안 가이드

암호화 및 인증

암호화(E2EE)가 활성화된 룸에서는 thumbnail_file을 사용해서 이미지 미리보기도 전체 첨부 파일과 함께 암호화돼요. 암호화되지 않은 룸은 기존처럼 thumbnail_url을 사용하고요. 별도의 설정은 필요 없어요. 플러그인이 E2EE 상태를 자동으로 감지하거든요.

Bot to bot rooms

기본적으로 설정된 다른 OpenClaw Matrix 계정에서 오는 Matrix 메시지는 무시돼요.

에이전트 간의 Matrix 트래픽을 의도적으로 허용하고 싶다면 allowBots를 사용하세요.

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

• allowBots: true: 허용된 룸과 DM에서 설정된 다른 Matrix 봇 계정의 메시지를 수락해요.
• allowBots: "mentions": 룸에서 이 봇을 명시적으로 멘션했을 때만 메시지를 수락해요. DM은 항상 허용돼요.
• groups.<room>.allowBots: 특정 룸에 대해 계정 수준 설정을 덮어써요.
• OpenClaw는 자기 자신에게 답장하는 루프를 방지하기 위해 동일한 Matrix user ID가 보낸 메시지는 여전히 무시해요.
• Matrix는 여기서 네이티브 봇 플래그를 노출하지 않아요. OpenClaw는 “이 OpenClaw Gateway에 설정된 다른 Matrix 계정이 보낸 메시지”를 “봇이 작성한 것”으로 간주해요.

공유 룸에서 봇 간 트래픽을 활성화할 때는 엄격한 룸 허용 목록(allowlists)과 멘션 요구 사항을 사용하는 것이 좋아요.

암호화 활성화하기:

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

인증 상태 확인하기:

openclaw matrix verify status

상세 상태 확인 (전체 진단):

openclaw matrix verify status --verbose

기계 읽기 가능한 출력에 저장된 복구 키 포함하기:

openclaw matrix verify status --include-recovery-key --json

교차 서명(cross-signing) 및 인증 상태 부트스트랩:

openclaw matrix verify bootstrap

다중 계정 지원: 계정별 자격 증명과 선택 사항인 name을 포함한 channels.matrix.accounts를 사용하세요. 공유 패턴에 대해서는 Configuration reference를 참고해 주세요.

상세 부트스트랩 진단:

openclaw matrix verify bootstrap --verbose

부트스트랩 전 교차 서명 ID 강제 초기화:

openclaw matrix verify bootstrap --force-reset-cross-signing

복구 키로 이 디바이스 인증하기:

openclaw matrix verify device "<your-recovery-key>"

상세 디바이스 인증 세부 정보:

openclaw matrix verify device "<your-recovery-key>" --verbose

룸 키(room-key) 백업 상태 확인:

openclaw matrix verify backup status

상세 백업 상태 진단:

openclaw matrix verify backup status --verbose

서버 백업에서 룸 키 복구하기:

openclaw matrix verify backup restore

상세 복구 진단:

openclaw matrix verify backup restore --verbose

현재 서버 백업을 삭제하고 새로운 백업 기준점 생성하기:

openclaw matrix verify backup reset --yes

모든 verify 명령어는 기본적으로 간결하게 표시되며(내부 SDK 로그 포함), --verbose를 사용할 때만 상세 진단 내용을 보여줘요. 스크립트를 짤 때는 --json을 사용해서 전체 내용을 기계가 읽을 수 있는 형식으로 출력하세요.

다중 계정 설정에서 Matrix CLI 명령어는 --account <id>를 전달하지 않으면 암시적인 Matrix 기본 계정을 사용해요. 이름이 지정된 계정을 여러 개 설정했다면, channels.matrix.defaultAccount를 먼저 설정하세요. 그렇지 않으면 CLI 작업이 중단되고 계정을 명시적으로 선택하라는 요청을 받게 돼요. 특정 계정을 대상으로 인증이나 디바이스 작업을 수행하고 싶을 때는 항상 --account를 사용하세요.

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

이름이 지정된 계정에서 암호화가 비활성화되었거나 사용할 수 없는 경우, Matrix 경고와 인증 오류는 해당 계정의 설정 키(예: channels.matrix.accounts.assistant.encryption)를 가리키게 돼요.

”인증됨(verified)“의 의미

OpenClaw는 이 Matrix 디바이스가 여러분 자신의 교차 서명 ID에 의해 인증된 경우에만 인증된 것으로 간주해요. 실제로 openclaw matrix verify status --verbose를 실행하면 세 가지 신뢰 신호를 확인할 수 있어요.

• Locally trusted: 현재 클라이언트에서만 이 디바이스를 신뢰함
• Cross-signing verified: SDK가 교차 서명을 통해 디바이스가 인증되었음을 보고함
• Signed by owner: 디바이스가 여러분 자신의 자체 서명 키(self-signing key)로 서명됨

Verified by owner는 교차 서명 인증이나 소유자 서명이 있을 때만 yes가 돼요. 로컬 신뢰만으로는 OpenClaw가 디바이스를 완전히 인증된 것으로 처리하기에 충분하지 않아요.

부트스트랩(bootstrap)이 하는 일

openclaw matrix verify bootstrap은 암호화된 Matrix 계정을 수리하고 설정하는 명령어예요. 다음 작업들을 순서대로 수행해요.

• 보안 저장소(secret storage)를 부트스트랩하고, 가능한 경우 기존 복구 키를 재사용해요.
• 교차 서명을 부트스트랩하고 누락된 공개 교차 서명 키를 업로드해요.
• 현재 디바이스를 표시하고 교차 서명을 시도해요.
• 서버 측 룸 키 백업이 아직 없다면 새로 생성해요.

홈서버에서 교차 서명 키를 업로드하기 위해 대화형 인증이 필요한 경우, OpenClaw는 먼저 인증 없이 시도한 다음 m.login.dummy로, 그 후 channels.matrix.password가 설정되어 있다면 m.login.password로 시도해요.

현재의 교차 서명 ID를 버리고 새 ID를 만들고 싶을 때만 --force-reset-cross-signing을 사용하세요.

의도적으로 현재 룸 키 백업을 버리고 향후 메시지를 위해 새로운 백업 기준점을 시작하려면 openclaw matrix verify backup reset --yes를 사용하세요. 이 작업을 하면 복구 불가능한 이전 암호화 히스토리를 더 이상 사용할 수 없게 된다는 점을 꼭 기억해 주세요.

새로운 백업 기준점

향후 암호화된 메시지가 계속 작동하게 유지하면서 복구 불가능한 이전 히스토리를 잃어도 괜찮다면, 다음 명령어들을 순서대로 실행하세요.

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

특정 Matrix 계정을 대상으로 하려면 각 명령어에 --account <id>를 추가하세요.

시작 시 동작 (Startup behavior)

encryption: true일 때, Matrix는 startupVerification의 기본값을 "if-unverified"로 설정해요. 시작할 때 이 디바이스가 아직 인증되지 않았다면, Matrix는 다른 Matrix 클라이언트에서 자기 인증(self-verification)을 요청해요. 이미 요청이 대기 중인 경우에는 중복 요청을 건너뛰고, 재시작 후 다시 시도하기 전에 로컬 쿨다운 시간을 적용해요. 기본적으로 실패한 요청은 성공적으로 생성된 요청보다 더 빨리 재시도돼요. 자동 시작 요청을 비활성화하려면 startupVerification: "off"로 설정하거나, 재시도 간격을 조정하고 싶다면 startupVerificationCooldownHours를 튜닝하세요.

시작 시 보수적인 암호화 부트스트랩 과정도 자동으로 수행돼요. 이 과정은 먼저 현재 보안 저장소와 교차 서명 ID를 재사용하려고 시도하며, 명시적인 부트스트랩 수리 흐름을 실행하지 않는 한 교차 서명을 초기화하지 않아요.

시작 시 부트스트랩 상태가 깨진 것을 발견하고 channels.matrix.password가 설정되어 있다면, OpenClaw는 더 엄격한 수리 경로를 시도할 수 있어요. 현재 디바이스가 이미 소유자 서명(owner-signed)이 되어 있다면, OpenClaw는 이를 자동으로 초기화하는 대신 해당 ID를 보존해요.

이전 공개 Matrix 플러그인에서 업그레이드하는 경우:

• OpenClaw는 가능한 경우 동일한 Matrix 계정, 액세스 토큰, 디바이스 ID를 자동으로 재사용해요.
• 실행 가능한 Matrix 마이그레이션 변경 사항이 작동하기 전에, OpenClaw는 ~/Backups/openclaw-migrations/ 아래에 복구 스냅샷을 생성하거나 재사용해요.
• 여러 Matrix 계정을 사용하는 경우, 이전의 단일 저장소 레이아웃에서 업그레이드하기 전에 channels.matrix.defaultAccount를 설정해서 어떤 계정이 기존 레거시 상태를 이어받을지 OpenClaw에 알려주세요.
• 이전 플러그인이 Matrix 룸 키 백업 복호화 키를 로컬에 저장했다면, 시작 시 또는 openclaw doctor --fix 실행 시 새로운 복구 키 흐름으로 자동으로 가져와요.
• 마이그레이션 준비 후 Matrix 액세스 토큰이 변경된 경우, 이제 시작 시 자동 백업 복구를 포기하기 전에 대기 중인 레거시 복구 상태가 있는지 형제 토큰 해시 저장소 루트를 스캔해요.
• 나중에 동일한 계정, 홈서버, 사용자에 대해 Matrix 액세스 토큰이 변경되면, OpenClaw는 빈 Matrix 상태 디렉토리에서 시작하는 대신 가장 완전한 기존 토큰 해시 저장소 루트를 재사용하는 것을 선호해요.
• 다음 Gateway 시작 시, 백업된 룸 키가 새로운 암호화 저장소로 자동으로 복구돼요.
• 이전 플러그인에 백업되지 않은 로컬 전용 룸 키가 있었다면 OpenClaw가 명확하게 경고를 표시할 거예요. 해당 키들은 이전 Rust 암호화 저장소에서 자동으로 내보낼 수 없으므로, 수동으로 복구하기 전까지 일부 오래된 암호화 히스토리를 사용하지 못할 수 있어요.
• 전체 업그레이드 흐름, 제한 사항, 복구 명령어 및 일반적인 마이그레이션 메시지는 Matrix migration을 참고하세요.

암호화된 런타임 상태는 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ 아래의 계정별, 사용자별 토큰 해시 루트로 정리돼요. 이 디렉토리에는 동기화 저장소(bot-storage.json), 암호화 저장소(crypto/), 복구 키 파일(recovery-key.json), IndexedDB 스냅샷(crypto-idb-snapshot.json), 스레드 바인딩(thread-bindings.json), 그리고 시작 인증 상태(startup-verification.json)가 포함돼요. 토큰은 바뀌어도 계정 정체성이 동일하다면, OpenClaw는 해당 계정/홈서버/사용자 조합에 대해 가장 좋은 기존 루트를 재사용하여 이전 동기화 상태, 암호화 상태, 스레드 바인딩 및 시작 인증 상태를 계속 볼 수 있게 해요.

Node crypto store model

이 플러그인의 Matrix E2EE는 Node에서 공식 matrix-js-sdk Rust 암호화 경로를 사용해요. 이 경로는 암호화 상태가 재시작 후에도 유지되도록 IndexedDB 기반의 영속성을 요구해요.

OpenClaw는 현재 Node에서 다음과 같은 방식으로 이를 제공하고 있어요.

• SDK가 요구하는 IndexedDB API 심(shim)으로 fake-indexeddb를 사용해요.
• initRustCrypto 전에 crypto-idb-snapshot.json에서 Rust 암호화 IndexedDB 내용을 복구해요.
• 초기화 후 및 런타임 중에 업데이트된 IndexedDB 내용을 다시 crypto-idb-snapshot.json에 저장해요.

이것은 호환성과 저장소를 위한 구조일 뿐, 커스텀 암호화 구현이 아니에요. 스냅샷 파일은 민감한 런타임 상태이므로 제한적인 파일 권한으로 저장돼요. OpenClaw의 보안 모델에서 Gateway 호스트와 로컬 OpenClaw 상태 디렉토리는 이미 신뢰할 수 있는 운영자 경계 내에 있으므로, 이는 별도의 원격 신뢰 경계라기보다는 주로 운영상의 내구성에 관한 문제예요.

계획된 개선 사항:

• 복구 키 및 관련 저장소 암호화 비밀을 로컬 파일뿐만 아니라 OpenClaw 비밀 제공자(secrets providers)로부터 가져올 수 있도록 영구 Matrix 키 자료에 대한 SecretRef 지원을 추가할 예정이에요.

프로필 관리

선택한 계정의 Matrix 프로필을 다음 명령어로 업데이트하세요.

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

특정 Matrix 계정을 대상으로 하려면 --account <id>를 추가하세요.

Matrix는 mxc:// 아바타 URL을 직접 수락해요. http:// 또는 https:// 아바타 URL을 전달하면, OpenClaw가 이를 Matrix에 먼저 업로드하고 확인된 mxc:// URL을 channels.matrix.avatarUrl(또는 선택한 계정 오버라이드)에 다시 저장해요.

자동 인증 알림

이제 Matrix 인증 수명 주기 알림이 엄격한 DM 인증 룸에 m.notice 메시지로 직접 게시돼요. 여기에는 다음 내용이 포함돼요.

• 인증 요청 알림
• 인증 준비 완료 알림 (명시적인 “이모지로 인증” 안내 포함)
• 인증 시작 및 완료 알림
• 사용 가능한 경우 SAS 세부 정보 (이모지 및 숫자)

다른 Matrix 클라이언트로부터 들어오는 인증 요청은 OpenClaw가 추적하고 자동으로 수락해요. 자기 인증 흐름의 경우, OpenClaw는 이모지 인증이 가능해지면 자동으로 SAS 흐름을 시작하고 자신의 측을 확인해요. 다른 Matrix 사용자나 디바이스로부터의 인증 요청에 대해서는 OpenClaw가 요청을 자동 수락한 다음 SAS 흐름이 정상적으로 진행되기를 기다려요. 여러분은 여전히 Matrix 클라이언트에서 이모지나 숫자로 된 SAS를 비교하고 “일치함”을 확인해서 인증을 완료해야 해요.

OpenClaw는 자기가 시작한 중복 흐름을 맹목적으로 자동 수락하지 않아요. 시작 시 자기 인증 요청이 이미 대기 중이라면 새로운 요청 생성을 건너뛰어요.

인증 프로토콜/시스템 알림은 에이전트 채팅 파이프라인으로 전달되지 않으므로 NO_REPLY를 생성하지 않아요.

디바이스 위생 (Device hygiene)

오래된 OpenClaw 관리 Matrix 디바이스가 계정에 쌓이면 암호화된 룸의 신뢰 상태를 파악하기 어려워질 수 있어요. 다음 명령어로 목록을 확인하세요.

openclaw matrix devices list

오래된 OpenClaw 관리 디바이스를 제거하려면 다음을 사용하세요.

openclaw matrix devices prune-stale

Direct Room Repair

DM 상태가 동기화되지 않으면 OpenClaw에 실제 DM 대신 오래된 1인용 룸을 가리키는 유효하지 않은 m.direct 매핑이 남을 수 있어요. 다음 명령어로 특정 사용자에 대한 현재 매핑을 조사하세요.

openclaw matrix direct inspect --user-id @alice:example.org

다음 명령어로 수리할 수 있어요.

openclaw matrix direct repair --user-id @alice:example.org

수리 기능은 플러그인 내부의 Matrix 전용 로직을 유지해요.

• 이미 m.direct에 매핑된 엄격한 1:1 DM을 선호해요.
• 그렇지 않으면 해당 사용자와 현재 참여 중인 다른 엄격한 1:1 DM으로 대체해요.
• 정상적인 DM이 존재하지 않으면 새로운 다이렉트 룸을 만들고 m.direct가 이를 가리키도록 다시 써요.

수리 흐름은 오래된 룸을 자동으로 삭제하지 않아요. 정상적인 DM을 선택하고 매핑을 업데이트해서 새로운 Matrix 메시지 전송, 인증 알림 및 기타 DM 흐름이 다시 올바른 룸을 대상으로 하도록 만들 뿐이에요.

스레드

Matrix는 자동 답장과 메시지 도구 전송 모두에서 네이티브 Matrix 스레드를 지원해요.

• threadReplies: "off": 답장을 최상위 수준으로 유지하고, 들어오는 스레드 메시지를 부모 세션에 유지해요.
• threadReplies: "inbound": 들어오는 메시지가 이미 해당 스레드에 있는 경우에만 스레드 내부에서 답장해요.
• threadReplies: "always": 룸 답장을 트리거 메시지에 뿌리를 둔 스레드에 유지하고, 첫 번째 트리거 메시지부터 해당 스레드 범위의 세션을 통해 대화를 라우팅해요.
• dm.threadReplies: DM에 대해서만 최상위 설정을 덮어써요. 예를 들어, DM은 평면적으로 유지하면서 룸 스레드는 격리할 수 있어요.
• 들어오는 스레드 메시지에는 에이전트 컨텍스트로 스레드 루트 메시지가 추가로 포함돼요.
• 메시지 도구 전송 시, 대상이 동일한 룸이거나 동일한 DM 사용자라면 명시적인 threadId가 제공되지 않는 한 현재 Matrix 스레드를 자동으로 상속해요.
• Matrix에 대한 런타임 스레드 바인딩이 지원돼요. /focus, /unfocus, /agents, /session idle, /session max-age, 그리고 스레드 바인딩된 /acp spawn이 이제 Matrix 룸과 DM에서 작동해요.
• threadBindings.spawnSubagentSessions=true일 때 최상위 Matrix 룸/DM에서 /focus를 실행하면 새로운 Matrix 스레드를 생성하고 이를 대상 세션에 바인딩해요.
• 기존 Matrix 스레드 내부에서 /focus 또는 /acp spawn --thread here를 실행하면 현재 스레드를 대신 바인딩해요.

AI Setup Assistant

ACP 대화 바인딩

Matrix 룸, DM, 그리고 기존 Matrix 스레드를 채팅 화면을 바꾸지 않고도 지속 가능한 ACP 워크스페이스로 전환할 수 있어요.

빠른 오퍼레이터 흐름은 다음과 같아요:

• 계속 사용하려는 Matrix DM, 룸 또는 기존 스레드 안에서 /acp spawn codex --bind here를 실행하세요.
• 상위 레벨의 Matrix DM이나 룸에서는 현재 DM/룸이 채팅 화면으로 유지되고, 이후 메시지는 생성된 ACP 세션으로 라우팅돼요.
• 기존 Matrix 스레드 내부에서 --bind here를 사용하면 해당 스레드가 그 자리에서 바인딩돼요.
• /new와 /reset은 바인딩된 동일한 ACP 세션을 그 자리에서 초기화해요.
• /acp close는 ACP 세션을 닫고 바인딩을 제거해요.

참고 사항:

• --bind here는 자식 Matrix 스레드를 생성하지 않아요.
• threadBindings.spawnAcpSessions는 OpenClaw가 자식 Matrix 스레드를 생성하거나 바인딩해야 하는 /acp spawn --thread auto|here의 경우에만 필요해요.

리액션

Matrix는 아웃바운드 리액션 액션, 인바운드 리액션 알림, 그리고 인바운드 ack 리액션을 지원해요.

• 아웃바운드 리액션 툴링은 channels["matrix"].actions.reactions에 의해 제어돼요.
• react는 특정 Matrix 이벤트에 리액션을 추가해요.
• reactions는 특정 Matrix 이벤트에 대한 현재 리액션 요약을 나열해요.
• emoji=""는 해당 이벤트에서 봇 계정의 자체 리액션을 제거해요.
• remove: true는 봇 계정에서 지정된 이모지 리액션만 제거해요.

Ack 리액션은 표준 OpenClaw 결정 순서를 따라요:

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• 에이전트 아이덴티티 이모지 fallback

Ack 리액션 범위(scope)는 다음 순서로 결정돼요:

• channels["matrix"].accounts.<accountId>.ackReactionScope
• channels["matrix"].ackReactionScope
• messages.ackReactionScope

리액션 알림 모드는 다음 순서로 결정돼요:

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• 기본값: own

현재 동작 방식은 다음과 같아요:

• reactionNotifications: "own"은 봇이 작성한 Matrix 메시지를 대상으로 할 때 추가된 m.reaction 이벤트를 전달해요.
• reactionNotifications: "off"는 리액션 시스템 이벤트를 비활성화해요.
• 리액션 제거는 아직 시스템 이벤트로 합성되지 않아요. Matrix는 이를 독립적인 m.reaction 제거가 아닌 redaction으로 표시하기 때문이에요.

히스토리 컨텍스트

• channels.matrix.historyLimit은 Matrix 룸 메시지가 에이전트를 트리거할 때 InboundHistory로 포함될 최근 룸 메시지 수를 제어해요.
• 이 설정이 없으면 messages.groupChat.historyLimit으로 대체돼요. 비활성화하려면 0으로 설정하세요.
• Matrix 룸 히스토리는 룸 전용이에요. DM은 계속해서 일반 세션 히스토리를 사용해요.
• Matrix 룸 히스토리는 보류(pending) 전용이에요. OpenClaw는 아직 답장을 트리거하지 않은 룸 메시지를 버퍼링한 다음, 멘션이나 다른 트리거가 도착하면 해당 윈도우를 스냅샷으로 찍어요.
• 현재 트리거 메시지는 InboundHistory에 포함되지 않고, 해당 턴의 메인 인바운드 본문에 유지돼요.
• 동일한 Matrix 이벤트의 재시도는 최신 룸 메시지로 이동하는 대신 원래의 히스토리 스냅샷을 재사용해요.
• 가져온 룸 컨텍스트(답장 및 스레드 컨텍스트 조회 포함)는 발신자 허용 목록(groupAllowFrom)에 의해 필터링되므로, 허용 목록에 없는 메시지는 에이전트 컨텍스트에서 제외돼요.

DM 및 룸 정책 예시

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

멘션 게이팅 및 허용 목록 동작에 대해서는 Groups를 참조하세요.

Matrix DM 페어링 예시는 다음과 같아요:

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

승인되지 않은 Matrix 사용자가 승인 전에 계속 메시지를 보내는 경우, OpenClaw는 동일한 대기 중인 페어링 코드를 재사용하며, 새 코드를 생성하는 대신 짧은 쿨다운 후에 다시 알림 답장을 보낼 수 있어요.

공유 DM 페어링 흐름 및 스토리지 레이아웃에 대해서는 Pairing을 참조하세요.

여러 개의 Matrix 계정을 관리하다 보면 설정이 꼬여서 고생할 때가 많죠. 알림용 계정과 개인용 계정을 분리해서 깔끔하게 운영하고 싶은 개발자분들을 위해 다중 계정 설정 방법을 준비했습니다.

다중 계정 예시 (Multi-account example)

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

channels.matrix의 최상위 값은 이름을 지정한 계정에서 따로 덮어쓰지 않는 한 기본값으로 작동해요. 상속된 room 항목을 특정 Matrix 계정으로 제한하려면 groups.<room>.account (또는 이전 방식인 rooms.<room>.account)를 사용하면 됩니다.

account 설정이 없는 항목은 모든 Matrix 계정에서 공유되고, 최상위 channels.matrix.*에 기본 계정이 직접 설정되어 있다면 account: "default" 항목도 그대로 잘 작동해요.

단순히 인증 정보 일부를 공유한다고 해서 별도의 암시적 기본 계정이 자동으로 생성되지는 않아요. OpenClaw는 최상위 default 계정에 새로운 인증 정보(homeserver와 accessToken, 또는 homeserver와 userId 및 password)가 있을 때만 해당 계정을 생성합니다. 이름을 지정한 계정은 나중에 캐시된 자격 증명으로 인증이 가능할 때 homeserver와 userId만으로도 계속 찾을 수 있어요.

암시적 라우팅이나 probing, CLI 작업을 할 때 OpenClaw가 특정 Matrix 계정을 우선적으로 사용하게 하려면 defaultAccount를 설정하세요. 여러 개의 이름을 가진 계정을 구성했다면, defaultAccount를 설정하거나 암시적 계정 선택이 필요한 CLI 명령어를 실행할 때 --account <id>를 전달해야 해요.

특정 명령어에서만 이 선택을 바꾸고 싶다면 openclaw matrix verify ...나 openclaw matrix devices ...를 실행할 때 --account <id>를 넘겨주면 됩니다.

프라이빗/LAN 홈서버 (Private/LAN homeservers)

기본적으로 OpenClaw는 SSRF 보호를 위해 프라이빗/내부 Matrix 홈서버를 차단해요. 사용하려면 계정별로 직접 허용 설정을 해줘야 합니다.

홈서버가 localhost, LAN/Tailscale IP 또는 내부 호스트네임에서 실행 중이라면, 해당 Matrix 계정에 allowPrivateNetwork 설정을 활성화하세요.

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: true,
      accessToken: "syt_internal_xxx",
    },
  },
}

CLI 설정 예시는 다음과 같아요.

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

이 설정은 신뢰할 수 있는 프라이빗/내부 대상만 허용해요. http://matrix.example.org:8008 같은 공개된 cleartext 홈서버는 여전히 차단됩니다. 가능하다면 항상 https://를 사용하는 게 좋아요.

AI Setup Assistant

다음 단계

• Matrix 채널 설정 가이드
• OpenClaw 보안 정책

Matrix 트래픽 Proxy 설정

Matrix 배포 시 명시적인 아웃바운드 HTTP(S) Proxy가 필요하다면 channels.matrix.proxy를 설정해 보세요.

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

개별 계정(Named accounts)에서는 channels.matrix.accounts.<id>.proxy를 사용해 상위 기본 설정을 덮어쓸 수 있어요. OpenClaw는 런타임 Matrix 트래픽과 계정 상태 확인(account status probes)에 동일한 Proxy 설정을 사용해요.

대상 확인

OpenClaw에서 Room이나 User 대상을 입력할 때, Matrix는 다음과 같은 형식을 지원해요.

• Users: @user:server, user:@user:server, 또는 matrix:user:@user:server
• Rooms: !room:server, room:!room:server, 또는 matrix:room:!room:server
• Aliases: #alias:server, channel:#alias:server, 또는 matrix:channel:#alias:server

실시간 디렉토리 조회는 로그인된 Matrix 계정을 사용해요.

• User 조회는 해당 Homeserver의 Matrix User 디렉토리를 검색해요.
• Room 조회는 명시적인 Room ID와 Alias를 직접 허용하며, 그 외에는 해당 계정이 참여 중인 Room 이름을 검색해요.
• 참여 중인 Room 이름 조회는 최선을 다해 시도하는 방식(best-effort)이에요. 만약 Room 이름을 ID나 Alias로 변환할 수 없다면, 런타임 허용 목록(allowlist) 확인 시 해당 항목은 무시돼요.

설정 레퍼런스

• enabled: 채널 활성화 여부를 설정해요.
• name: 계정에 사용할 선택적 라벨이에요.
• defaultAccount: 여러 Matrix 계정이 설정된 경우 우선적으로 사용할 계정 ID예요.
• homeserver: homeserver URL이에요. 예: https://matrix.example.org.
• allowPrivateNetwork: Matrix 계정이 프라이빗/내부 homeserver에 연결할 수 있게 허용해요. homeserver 주소가 localhost, LAN/Tailscale IP 또는 matrix-synapse 같은 내부 호스트인 경우 이 옵션을 활성화하세요.
• proxy: Matrix 트래픽을 위한 선택적 HTTP(S) proxy URL이에요. 개별 계정 설정에서 최상위 기본값을 고유한 proxy 설정으로 덮어쓸 수 있어요.
• userId: 전체 Matrix user ID예요. 예: @bot:example.org.
• accessToken: 토큰 기반 인증을 위한 access token이에요. env/file/exec 프로바이더 전반에서 channels.matrix.accessToken 및 channels.matrix.accounts.<id>.accessToken에 대해 일반 텍스트와 SecretRef 값을 모두 지원해요. 자세한 내용은 Secrets Management를 참고하세요.
• password: 비밀번호 기반 로그인을 위한 비밀번호예요. 일반 텍스트와 SecretRef 값을 지원해요.
• deviceId: 명시적인 Matrix device ID예요.
• deviceName: 비밀번호 로그인 시 사용할 디바이스 표시 이름이에요.
• avatarUrl: 프로필 동기화 및 set-profile 업데이트를 위해 저장된 아바타 URL이에요.
• initialSyncLimit: 시작 시 동기화할 이벤트 제한 수예요.
• encryption: E2EE를 활성화해요.
• allowlistOnly: DM과 room에 대해 allowlist 전용 동작을 강제해요.
• groupPolicy: open, allowlist, 또는 disabled 중 하나를 선택해요.
• groupAllowFrom: room 트래픽을 허용할 user ID allowlist예요.
• groupAllowFrom 항목은 전체 Matrix user ID여야 해요. 확인되지 않은 이름은 런타임에서 무시돼요.
• historyLimit: 그룹 히스토리 컨텍스트에 포함할 최대 room 메시지 수예요. 설정하지 않으면 messages.groupChat.historyLimit을 따르며, 비활성화하려면 0으로 설정하세요.
• replyToMode: off, first, 또는 all 중 하나를 선택해요.
• streaming: off(기본값) 또는 partial이에요. partial은 실시간 편집 업데이트가 포함된 단일 메시지 초안 미리보기를 활성화해요.
• threadReplies: off, inbound, 또는 always 중 하나를 선택해요.
• threadBindings: 스레드 기반 세션 라우팅 및 수명 주기에 대한 채널별 설정이에요.
• startupVerification: 시작 시 자동 자체 인증 요청 모드예요 (if-unverified, off).
• startupVerificationCooldownHours: 자동 시작 인증 요청을 재시도하기 전의 대기 시간(시간 단위)이에요.
• textChunkLimit: 발신 메시지의 청크 크기예요.
• chunkMode: length 또는 newline 중 하나를 선택해요.
• responsePrefix: 발신 답장에 추가할 선택적 메시지 접두사예요.
• ackReaction: 이 채널/계정에 대한 선택적 ack reaction 설정이에요.
• ackReactionScope: 선택적 ack reaction 범위 설정이에요 (group-mentions, group-all, direct, all, none, off).
• reactionNotifications: 수신 reaction 알림 모드예요 (own, off).
• mediaMaxMb: Matrix 미디어 처리를 위한 최대 용량(MB)이에요. 발신 및 수신 미디어 처리 모두에 적용돼요.
• autoJoin: 초대 자동 수락 정책이에요 (always, allowlist, off). 기본값은 off예요.
• autoJoinAllowlist: autoJoin이 allowlist일 때 허용할 room/alias 목록이에요. alias는 초대 처리 중에 room ID로 변환되며, OpenClaw는 초대된 room에서 주장하는 alias 상태를 신뢰하지 않아요.
• dm: DM 정책 블록이에요 (enabled, policy, allowFrom, threadReplies).
• dm.allowFrom 항목은 실시간 디렉토리 조회를 통해 이미 확인된 경우가 아니라면 전체 Matrix user ID를 사용해야 해요.
• dm.threadReplies: DM 전용 스레드 정책 설정이에요 (off, inbound, always). DM 내의 답장 위치와 세션 격리 모두에 대해 최상위 threadReplies 설정을 덮어써요.
• accounts: 계정별 개별 설정이에요. 최상위 channels.matrix 값이 기본값으로 사용돼요.
• groups: room별 정책 맵이에요. room ID나 alias 사용을 권장하며, 확인되지 않은 이름은 런타임에서 무시돼요. 세션/그룹 식별은 변환된 room ID를 사용하지만, 표시 이름은 room 이름을 사용해요.
• rooms: groups의 이전 이름(alias)이에요.
• actions: 액션별 도구 제한 설정이에요 (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

관련 문서

• Channels Overview — 지원되는 모든 채널
• Pairing — DM 인증 및 페어링 흐름
• Groups — 그룹 채팅 동작 및 멘션 제어
• Channel Routing — 메시지 세션 라우팅
• Security — 액세스 모델 및 보안 강화

AI Setup Assistant

다음 단계

• Channels Overview
• Pairing
• Groups
• Channel Routing
• Security