> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openclaw.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Matrix

# Matrix (플러그인)

Matrix는 개방형, 분산형 메시징 프로토콜입니다. OpenClaw는 모든 홈 서버에서 Matrix **사용자**로 연결됩니다. 따라서 봇을 위해 Matrix 계정이 필요합니다. 한 번 로그인되면, 봇에게 직접 다이렉트 메시지를 보내거나 방 (Matrix "그룹")에 초대할 수 있습니다. Beeper도 유효한 클라이언트 옵션이지만, E2EE를 활성화해야 합니다.

상태: 플러그인(@vector-im/matrix-bot-sdk)을 통해 지원됩니다. 다이렉트 메시지, 방, 스레드, 미디어, 반응, 투표 (텍스트로서의 전송 + 시작), 위치, 그리고 E2EE(암호화 지원 포함).

## 플러그인 필요

Matrix는 플러그인으로 제공되며 코어 설치와 함께 번들로 제공되지 않습니다.

CLI를 통한 설치 (npm 레지스트리):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/matrix
```

로컬 체크아웃 (git repo에서 실행 중일 때):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install ./extensions/matrix
```

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

자세한 내용: [플러그인](/ko-KR/tools/plugin)

## 설정

1. Matrix 플러그인을 설치합니다:
   * npm에서: `openclaw plugins install @openclaw/matrix`
   * 로컬 체크아웃에서: `openclaw plugins install ./extensions/matrix`

2. 홈 서버에서 Matrix 계정을 만듭니다:
   * [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/)에서 호스팅 옵션 탐색
   * 또는 직접 호스팅합니다.

3. 봇 계정을 위한 액세스 토큰을 얻습니다:

   * 홈 서버에서 `curl`을 사용하여 Matrix 로그인 API 사용:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   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/](https://matrix.org/ecosystem/clients/) 참조). Beeper는 E2EE를 필요로 하므로, `channels.matrix.encryption: true`를 설정하고 디바이스를 검증하세요.

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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](/ko-KR/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts)에서 확인하십시오.

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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로 돌아갑니다.
* 다이렉트 메시지는 에이전트의 주 세션을 공유합니다; 방은 그룹 세션으로 매핑됩니다.

## 엑세스 제어 (다이렉트 메시지)

* 기본: `channels.matrix.dm.policy = "pairing"`. 알 수 없는 발신자는 페어링 코드를 받습니다.
* 승인 방법:
  * `openclaw pairing list matrix`
  * `openclaw pairing approve matrix <CODE>`
* 공개 다이렉트 메시지: `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`가 완전히 없는 경우, `channels.defaults.groupPolicy`가 설정되어 있더라도 런타임은 방 확인에 `groupPolicy="allowlist"`로 폴백합니다.
* `channels.matrix.groups`로 방을 허용 목록에 추가하십시오 (방 ID 또는 별칭; 이름은 디렉토리 검색에서 단일 정확한 매치를 찾을 때 ID로 변환됨):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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).
* 방 내 특정 발신자를 제한하기 위해 per-room `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`는 스레드에서 답글을 보내지 않을 때 답글 메타데이터를 제어합니다:
  * `off` (기본값), `first`, `all`

## 기능

| 기능       | 상태                                       |
| -------- | ---------------------------------------- |
| 다이렉트 메시지 | ✅ 지원                                     |
| 방        | ✅ 지원                                     |
| 스레드      | ✅ 지원                                     |
| 미디어      | ✅ 지원                                     |
| E2EE     | ✅ 지원 (암호화 모듈 필요)                         |
| 반응       | ✅ 지원 (도구를 통해 전송/읽기)                      |
| 투표       | ✅ 전송 지원; 수신 투표 시작은 텍스트로 변환됨 (응답/종료는 무시됨) |
| 위치       | ✅ 지원 (geo URI; 고도 무시됨)                   |
| 네이티브 명령어 | ✅ 지원                                     |

## 문제 해결

이 사다리를 먼저 실행하십시오:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```

필요한 경우 DM 페어링 상태 확인:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw pairing list matrix
```

일반적인 실패:

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

분류 흐름: [/channels/troubleshooting](/ko-KR/channels/troubleshooting)에서 확인하십시오.

## 구성 참조 (Matrix)

전체 구성: [구성](/ko-KR/gateway/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`: 다이렉트 메시지 허용 목록 (전체 Matrix 사용자 ID). `open`은 `"*"`을 필요로 합니다. 마법사가 가능한 경우 이름을 ID로 변환합니다.
* `channels.matrix.groupPolicy`: `allowlist | open | disabled` (기본값: allowlist).
* `channels.matrix.groupAllowFrom`: 그룹 메시지에 대한 허용된 발신자 (전체 Matrix 사용자 ID).
* `channels.matrix.allowlistOnly`: 다이렉트 메시지 + 방에 대해 허용 목록 규칙 강제.
* `channels.matrix.groups`: 그룹 허용 목록 + 방별 설정 맵.
* `channels.matrix.rooms`: 레거시 그룹 허용 목록/구성.
* `channels.matrix.replyToMode`: 스레드/태그에 대한 답글 모드.
* `channels.matrix.mediaMaxMb`: 인바운드/아웃바운드 미디어 용량 (MB).
* `channels.matrix.autoJoin`: 초대 처리 (`always | allowlist | off`, 기본값: always).
* `channels.matrix.autoJoinAllowlist`: 자동 참가를 위한 허용된 방 ID/별칭.
* `channels.matrix.accounts`: 계정 ID로 키된 멀티 계정 구성 (각 계정은 기본 설정을 상속).
* `channels.matrix.actions`: 작업별 도구 게이팅 (반응/메시지/핀/멤버 정보/채널 정보).