​

Matrix

​

번들 plugin

openclaw plugins install @openclaw/matrix

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

​

설정

1. Matrix plugin을 사용할 수 있는지 확인합니다.
   • 현재 패키지된 OpenClaw 릴리스에는 이미 번들로 포함되어 있습니다.
   • 이전/사용자 지정 설치에서는 위 명령으로 수동 추가할 수 있습니다.
2. 홈서버에서 Matrix 계정을 만듭니다.
3. channels.matrix를 다음 중 하나로 구성합니다:
   • homeserver + accessToken, 또는
   • homeserver + userId + password.
4. gateway를 재시작합니다.
5. 봇과 DM을 시작하거나 room에 초대합니다.
   • 새 Matrix 초대는 channels.matrix.autoJoin이 허용하는 경우에만 동작합니다.

openclaw channels add
openclaw configure --section channels

• homeserver URL
• 인증 방식: access token 또는 password
• 사용자 ID (password 인증만)
• 선택적 device 이름
• E2EE 활성화 여부
• room 접근과 초대 자동 참여를 구성할지 여부

• Matrix 인증 env var가 이미 존재하고 해당 계정에 config에 저장된 인증이 아직 없으면, 마법사는 인증을 env var에 유지하는 env 바로가기를 제안합니다.
• 계정 이름은 계정 ID로 정규화됩니다. 예를 들어 Ops Bot은 ops-bot이 됩니다.
• DM 허용 목록 항목은 @user:server를 직접 받을 수 있습니다. 표시 이름은 라이브 디렉터리 조회에서 정확히 하나의 일치 항목을 찾을 때만 동작합니다.
• Room 허용 목록 항목은 room ID와 alias를 직접 받을 수 있습니다. !room:server 또는 #alias:server를 권장하며, 해석되지 않은 이름은 허용 목록 해석 시 런타임에서 무시됩니다.
• 초대 자동 참여 허용 목록 모드에서는 안정적인 초대 대상만 사용하세요: !roomId:server, #alias:server, 또는 *. 일반 room 이름은 거부됩니다.
• 저장 전에 room 이름을 해석하려면 openclaw channels resolve --channel matrix "Project Room"를 사용하세요.

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}

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

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

• 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

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

• MATRIX_OPS_X2D_BOT_HOMESERVER
• MATRIX_OPS_X2D_BOT_ACCESS_TOKEN

​

구성 예제

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

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        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",
    },
  },
}

​

스트리밍 미리보기

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

• streaming: "off"가 기본값입니다. OpenClaw는 최종 답변을 기다렸다가 한 번만 전송합니다.
• streaming: "partial"은 현재 assistant 블록에 대해 편집 가능한 미리보기 메시지 하나를 일반 Matrix 텍스트 메시지로 생성합니다. 이는 Matrix의 기존 미리보기 우선 알림 동작을 유지하므로, 기본 클라이언트에서는 완성된 블록 대신 첫 번째 스트리밍 미리보기 텍스트에 대해 알림이 올 수 있습니다.
• streaming: "quiet"는 현재 assistant 블록에 대해 편집 가능한 조용한 미리보기 알림 하나를 생성합니다. 최종 확정된 미리보기 편집에 대한 수신자 푸시 규칙도 함께 구성하는 경우에만 이것을 사용하세요.
• blockStreaming: true는 별도의 Matrix 진행 상황 메시지를 활성화합니다. 미리보기 스트리밍이 활성화된 상태에서는 Matrix가 현재 블록의 라이브 초안을 유지하고 완료된 블록은 별도 메시지로 보존합니다.
• 미리보기 스트리밍이 켜져 있고 blockStreaming이 꺼져 있으면, Matrix는 라이브 초안을 제자리에서 편집하고 블록 또는 턴이 끝나면 같은 이벤트를 최종 확정합니다.
• 미리보기가 더 이상 하나의 Matrix 이벤트에 맞지 않으면 OpenClaw는 미리보기 스트리밍을 중단하고 일반 최종 전달로 대체합니다.
• 미디어 답변은 여전히 첨부 파일을 정상적으로 전송합니다. 오래된 미리보기를 더 이상 안전하게 재사용할 수 없으면 OpenClaw는 최종 미디어 답변을 보내기 전에 그것을 redact합니다.
• 미리보기 편집은 추가 Matrix API 호출 비용이 듭니다. 가장 보수적인 rate limit 동작을 원한다면 스트리밍을 꺼두세요.

• blockStreaming: true는 각 완료된 블록을 일반적인 알림 Matrix 메시지로 보냅니다.
• blockStreaming: false는 최종 완료된 답변만 일반적인 알림 Matrix 메시지로 보냅니다.

​

조용한 최종 확정 미리보기를 위한 자체 호스팅 푸시 규칙

• 수신자 사용자 = 알림을 받아야 하는 사람
• 봇 사용자 = 답변을 보내는 OpenClaw Matrix 계정
• 아래 API 호출에는 수신자 사용자의 access token을 사용
• 푸시 규칙의 sender는 봇 사용자의 전체 MXID와 일치시킴

1. OpenClaw가 조용한 미리보기를 사용하도록 구성합니다:

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

2. 수신자 계정이 이미 일반 Matrix 푸시 알림을 받고 있는지 확인합니다. 조용한 미리보기 규칙은 해당 사용자에게 이미 작동하는 pusher/device가 있을 때만 동작합니다.
3. 수신자 사용자의 access token을 가져옵니다.
   • 봇의 token이 아니라 수신 사용자 token을 사용하세요.
   • 기존 클라이언트 세션 token을 재사용하는 것이 보통 가장 쉽습니다.
   • 새 token을 발급해야 하면 표준 Matrix Client-Server API를 통해 로그인할 수 있습니다:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "@alice:example.org"
    },
    "password": "REDACTED"
  }'

4. 수신자 계정에 이미 pusher가 있는지 확인합니다:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

{
  "com.openclaw.finalized_preview": true
}

5. 이러한 알림을 받아야 하는 각 수신자 계정에 대해 override 푸시 규칙을 생성합니다:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

• https://matrix.example.org: homeserver 기본 URL
• $USER_ACCESS_TOKEN: 수신 사용자 access token
• openclaw-finalized-preview-botname: 이 수신 사용자에 대한 이 봇 전용 고유한 rule ID
• @bot:example.org: 수신 사용자 MXID가 아니라 OpenClaw Matrix 봇 MXID

• 푸시 규칙은 ruleId를 키로 사용합니다. 같은 rule ID에 대해 PUT을 다시 실행하면 해당 규칙 하나가 업데이트됩니다.
• 한 수신 사용자가 여러 OpenClaw Matrix 봇 계정에 대해 알림을 받아야 한다면, 각 sender 일치 항목마다 고유한 rule ID로 봇당 하나의 규칙을 생성하세요.
• 간단한 패턴은 openclaw-finalized-preview-<botname>이며, 예를 들어 openclaw-finalized-preview-ops 또는 openclaw-finalized-preview-support처럼 사용할 수 있습니다.

• 수신 사용자 token으로 인증
• sender를 OpenClaw 봇 MXID와 일치시킴

6. 규칙이 존재하는지 확인합니다:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

7. 스트리밍 답변을 테스트합니다. 조용한 모드에서는 room에 조용한 초안 미리보기가 표시되어야 하며, 블록이나 턴이 끝나면 제자리 최종 편집에 대해 한 번 알림이 와야 합니다.

curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

• 규칙은 봇 token이 아니라 수신 사용자 access token으로 생성하세요.
• 새 사용자 정의 override 규칙은 기본 억제 규칙보다 앞에 삽입되므로 추가 순서 지정 매개변수는 필요하지 않습니다.
• 이는 OpenClaw가 안전하게 제자리 확정할 수 있는 텍스트 전용 미리보기 편집에만 영향을 줍니다. 미디어 대체와 오래된 미리보기 대체는 여전히 일반 Matrix 전달을 사용합니다.
• GET /_matrix/client/v3/pushers에 pusher가 없으면, 해당 사용자는 아직 이 계정/device에 대해 작동하는 Matrix 푸시 전달을 갖고 있지 않습니다.

​

Synapse

• 최종 확정된 OpenClaw 미리보기 알림을 위해 특별한 homeserver.yaml 변경은 필요하지 않습니다.
• Synapse 배포가 이미 일반 Matrix 푸시 알림을 보내고 있다면, 사용자 token + 위 pushrules 호출이 주요 설정 단계입니다.
• Synapse를 reverse proxy 또는 worker 뒤에서 실행한다면 /_matrix/client/.../pushrules/가 Synapse에 올바르게 도달하는지 확인하세요.
• Synapse worker를 실행 중이라면 pusher가 정상인지 확인하세요. 푸시 전달은 메인 프로세스 또는 synapse.app.pusher / 구성된 pusher worker가 처리합니다.

​

Tuwunel

• 최종 확정 미리보기 마커 자체를 위한 Tuwunel 전용 config는 필요하지 않습니다.
• 해당 사용자에 대해 일반 Matrix 알림이 이미 작동한다면, 사용자 token + 위 pushrules 호출이 주요 설정 단계입니다.
• 사용자가 다른 device에서 활성 상태일 때 알림이 사라지는 것 같다면 suppress_push_when_active가 활성화되어 있는지 확인하세요. Tuwunel은 2025년 9월 12일 Tuwunel 1.4.2에서 이 옵션을 추가했으며, 하나의 device가 활성일 때 다른 device로의 푸시를 의도적으로 억제할 수 있습니다.

​

봇 간 room

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

• allowBots: true는 허용된 room과 DM에서 다른 구성된 Matrix 봇 계정의 메시지를 수락합니다.
• allowBots: "mentions"는 room에서는 이 봇을 눈에 띄게 언급할 때만 해당 메시지를 수락합니다. DM은 여전히 허용됩니다.
• groups.<room>.allowBots는 하나의 room에 대해 계정 수준 설정을 재정의합니다.
• OpenClaw는 자기 자신에게 답하는 루프를 피하기 위해 동일한 Matrix 사용자 ID의 메시지는 여전히 무시합니다.
• Matrix는 여기서 기본 bot 플래그를 노출하지 않으므로, OpenClaw는 “봇 작성”을 “이 OpenClaw gateway에 구성된 다른 Matrix 계정이 보낸 것”으로 취급합니다.

​

암호화 및 검증

{
  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

openclaw matrix verify bootstrap

openclaw matrix verify bootstrap --verbose

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

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

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

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

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

​

”검증됨”의 의미

• Locally trusted: 현재 클라이언트에서만 이 device를 신뢰함
• Cross-signing verified: SDK가 교차 서명을 통해 이 device를 검증된 것으로 보고함
• Signed by owner: 이 device가 자신의 self-signing key로 서명됨

​

bootstrap이 수행하는 작업

• 가능하면 기존 recovery key를 재사용하여 secret storage를 bootstrap
• 교차 서명을 bootstrap하고 누락된 공개 교차 서명 키 업로드
• 현재 device를 표시하고 교차 서명하려고 시도
• 서버 측 room-key 백업이 아직 없으면 새로 생성

​

새 백업 기준 상태

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

​

시작 동작

​

검증 알림

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

​

device 관리

openclaw matrix devices list

openclaw matrix devices prune-stale

​

crypto 저장소

​

프로필 관리

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

​

스레드

• dm.sessionScope: "per-user"(기본값)는 Matrix DM 라우팅을 발신자 범위로 유지하므로, 같은 상대방으로 해석되면 여러 DM room이 하나의 세션을 공유할 수 있습니다.
• dm.sessionScope: "per-room"은 정상적인 DM 인증 및 허용 목록 검사를 계속 사용하면서 각 Matrix DM room을 자체 세션 키로 격리합니다.
• 명시적인 Matrix 대화 바인딩은 여전히 dm.sessionScope보다 우선하므로, 바인딩된 room과 스레드는 선택된 대상 세션을 유지합니다.
• threadReplies: "off"는 답변을 최상위로 유지하고 들어오는 스레드 메시지를 부모 세션에 유지합니다.
• threadReplies: "inbound"는 들어온 메시지가 이미 해당 스레드에 있을 때만 스레드 안에서 답변합니다.
• threadReplies: "always"는 room 답변을 트리거 메시지를 루트로 하는 스레드에 유지하고, 첫 트리거 메시지부터 일치하는 스레드 범위 세션을 통해 해당 대화를 라우팅합니다.
• dm.threadReplies는 DM에 대해서만 최상위 설정을 재정의합니다. 예를 들어 room 스레드는 격리한 채 DM은 평면으로 유지할 수 있습니다.
• 들어오는 스레드 메시지에는 추가 agent 컨텍스트로 스레드 루트 메시지가 포함됩니다.
• message-tool 전송은 명시적인 threadId가 제공되지 않는 한 대상이 같은 room 또는 같은 DM 사용자 대상일 때 현재 Matrix 스레드를 자동 상속합니다.
• 동일 세션 DM 사용자 대상 재사용은 현재 세션 메타데이터가 같은 Matrix 계정의 동일한 DM 상대방임을 입증할 때만 시작되며, 그렇지 않으면 OpenClaw는 일반적인 사용자 범위 라우팅으로 되돌아갑니다.
• OpenClaw가 같은 공유 Matrix DM 세션에서 Matrix DM room이 다른 DM room과 충돌하는 것을 감지하면, thread 바인딩이 활성화되어 있고 dm.sessionScope 힌트가 있는 경우 해당 room에 /focus 탈출구를 안내하는 일회성 m.notice를 게시합니다.
• Matrix는 런타임 thread 바인딩을 지원합니다. /focus, /unfocus, /agents, /session idle, /session max-age, 그리고 스레드에 바인딩된 /acp spawn은 Matrix room과 DM에서 동작합니다.
• 최상위 Matrix room/DM의 /focus는 threadBindings.spawnSubagentSessions=true일 때 새 Matrix 스레드를 만들고 이를 대상 세션에 바인딩합니다.
• 기존 Matrix 스레드 내부에서 /focus 또는 /acp spawn --thread here를 실행하면 대신 현재 스레드를 바인딩합니다.

​

ACP 대화 바인딩

• 계속 사용할 Matrix DM, room 또는 기존 스레드 안에서 /acp spawn codex --bind here를 실행합니다.
• 최상위 Matrix DM 또는 room에서는 현재 DM/room이 채팅 표면으로 유지되고 향후 메시지는 생성된 ACP 세션으로 라우팅됩니다.
• 기존 Matrix 스레드 안에서는 --bind here가 현재 스레드를 제자리에서 바인딩합니다.
• /new와 /reset은 같은 바인딩된 ACP 세션을 제자리에서 재설정합니다.
• /acp close는 ACP 세션을 닫고 바인딩을 제거합니다.

• --bind here는 하위 Matrix 스레드를 만들지 않습니다.
• threadBindings.spawnAcpSessions는 OpenClaw가 하위 Matrix 스레드를 만들거나 바인딩해야 하는 /acp spawn --thread auto|here에만 필요합니다.

​

스레드 바인딩 구성

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSubagentSessions
• threadBindings.spawnAcpSessions

• 최상위 /focus가 새 Matrix 스레드를 만들고 바인딩하도록 허용하려면 threadBindings.spawnSubagentSessions: true를 설정하세요.
• /acp spawn --thread auto|here가 ACP 세션을 Matrix 스레드에 바인딩하도록 허용하려면 threadBindings.spawnAcpSessions: true를 설정하세요.

​

반응

• Outbound 반응 도구는 channels["matrix"].actions.reactions로 제어됩니다.
• react는 특정 Matrix 이벤트에 반응을 추가합니다.
• reactions는 특정 Matrix 이벤트의 현재 반응 요약을 나열합니다.
• emoji=""는 해당 이벤트에 대한 봇 계정 자신의 반응을 제거합니다.
• remove: true는 봇 계정의 지정한 이모지 반응만 제거합니다.

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• agent identity emoji 대체값

• 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 room 메시지가 agent를 트리거할 때 InboundHistory에 포함할 최근 room 메시지 수를 제어합니다. messages.groupChat.historyLimit으로 대체되며, 둘 다 설정되지 않으면 실제 기본값은 0입니다. 비활성화하려면 0으로 설정하세요.
• Matrix room 기록은 room 전용입니다. DM은 계속 일반 세션 기록을 사용합니다.
• Matrix room 기록은 pending 전용입니다. OpenClaw는 아직 답변을 트리거하지 않은 room 메시지를 버퍼링한 다음, 멘션이나 다른 트리거가 오면 해당 창을 스냅샷합니다.
• 현재 트리거 메시지는 InboundHistory에 포함되지 않습니다. 해당 턴의 기본 inbound 본문에 그대로 남습니다.
• 같은 Matrix 이벤트의 재시도는 새로운 room 메시지로 앞으로 이동하지 않고 원래 기록 스냅샷을 재사용합니다.

​

컨텍스트 가시성

• contextVisibility: "all"이 기본값입니다. 보조 컨텍스트는 받은 그대로 유지됩니다.
• contextVisibility: "allowlist"는 보조 컨텍스트를 활성 room/사용자 허용 목록 검사에서 허용된 발신자로 필터링합니다.
• contextVisibility: "allowlist_quote"는 allowlist처럼 동작하지만 하나의 명시적 인용 답장은 계속 유지합니다.

​

DM 및 room 정책

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

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

direct room 복구

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

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

• 이미 m.direct에 매핑된 엄격한 1:1 DM을 우선 선택
• 해당 사용자와 현재 참여 중인 엄격한 1:1 DM으로 대체
• 정상적인 DM이 없으면 새 direct room을 만들고 m.direct를 다시 작성

​

exec 승인

• channels.matrix.execApprovals.enabled
• channels.matrix.execApprovals.approvers (선택 사항, channels.matrix.dm.allowFrom으로 대체)
• channels.matrix.execApprovals.target (dm | channel | both, 기본값: dm)
• channels.matrix.execApprovals.agentFilter
• channels.matrix.execApprovals.sessionFilter

• channels.matrix.execApprovals.*는 Matrix 승인 프롬프트의 네이티브 DM/채널 fanout 모드를 제어합니다.
• Exec 승인은 execApprovals.approvers 또는 channels.matrix.dm.allowFrom의 exec 승인자 집합을 사용합니다.
• Plugin 승인은 Matrix DM 허용 목록 channels.matrix.dm.allowFrom을 사용합니다.
• Matrix 반응 바로가기와 메시지 업데이트는 exec 승인과 plugin 승인 모두에 적용됩니다.

• target: "dm"은 승인 프롬프트를 승인자 DM으로 전송
• target: "channel"은 프롬프트를 원래 Matrix room 또는 DM으로 다시 전송
• target: "both"는 승인자 DM과 원래 Matrix room 또는 DM 둘 다로 전송

• ✅ = 한 번 허용
• ❌ = 거부
• ♾️ = 해당 결정이 유효한 exec 정책에서 허용될 때 항상 허용

• channels.matrix.accounts.<account>.execApprovals

​

다중 계정

{
  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",
          },
        },
      },
    },
  },
}

​

비공개/LAN homeserver

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

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

​

Matrix 트래픽 프록시

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

​

대상 해석

• 사용자: @user:server, user:@user:server, 또는 matrix:user:@user:server
• Room: !room:server, room:!room:server, 또는 matrix:room:!room:server
• Alias: #alias:server, channel:#alias:server, 또는 matrix:channel:#alias:server

• 사용자 조회는 해당 homeserver의 Matrix 사용자 디렉터리를 조회합니다.
• Room 조회는 명시적인 room ID와 alias를 직접 허용한 뒤 해당 계정에 대해 참여 중인 room 이름 검색으로 대체됩니다.
• 참여 중인 room 이름 조회는 최선의 노력 방식입니다. room 이름을 ID 또는 alias로 해석할 수 없으면 허용 목록 해석 시 런타임에서 무시됩니다.

​

구성 참조

• enabled: 채널 활성화 또는 비활성화.
• name: 계정의 선택적 레이블.
• defaultAccount: 여러 Matrix 계정이 구성된 경우 선호되는 계정 ID.
• homeserver: homeserver URL, 예: https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: 이 Matrix 계정이 비공개/내부 homeserver에 연결되도록 허용합니다. homeserver가 localhost, LAN/Tailscale IP, 또는 matrix-synapse 같은 내부 호스트로 해석될 때 이를 활성화하세요.
• proxy: Matrix 트래픽용 선택적 HTTP(S) 프록시 URL. 이름 있는 계정은 자체 proxy로 최상위 기본값을 재정의할 수 있습니다.
• userId: 전체 Matrix 사용자 ID, 예: @bot:example.org.
• accessToken: token 기반 인증용 access token. 일반 텍스트 값과 SecretRef 값은 env/file/exec provider 전반에서 channels.matrix.accessToken 및 channels.matrix.accounts.<id>.accessToken에 대해 지원됩니다. Secrets Management를 참조하세요.
• password: password 기반 로그인용 password. 일반 텍스트 값과 SecretRef 값이 지원됩니다.
• deviceId: 명시적 Matrix device ID.
• deviceName: password 로그인용 device 표시 이름.
• avatarUrl: 프로필 동기화와 profile set 업데이트를 위한 저장된 self-avatar URL.
• initialSyncLimit: 시작 sync 중 가져오는 최대 이벤트 수.
• encryption: E2EE 활성화.
• allowlistOnly: true일 때 open room 정책을 allowlist로 승격하고, 활성 DM 정책 중 disabled를 제외한 모든 정책(pairing 및 open 포함)을 allowlist로 강제합니다. disabled 정책에는 영향을 주지 않습니다.
• allowBots: 다른 구성된 OpenClaw Matrix 계정의 메시지 허용(true 또는 "mentions").
• groupPolicy: open, allowlist, 또는 disabled.
• contextVisibility: 보조 room 컨텍스트 가시성 모드 (all, allowlist, allowlist_quote).
• groupAllowFrom: room 트래픽용 사용자 ID 허용 목록. 항목은 전체 Matrix 사용자 ID여야 하며, 해석되지 않은 이름은 런타임에서 무시됩니다.
• historyLimit: 그룹 기록 컨텍스트에 포함할 최대 room 메시지 수. messages.groupChat.historyLimit으로 대체되며, 둘 다 설정되지 않으면 실제 기본값은 0입니다. 비활성화하려면 0으로 설정하세요.
• replyToMode: off, first, all, 또는 batched.
• markdown: outbound Matrix 텍스트용 선택적 Markdown 렌더링 구성.
• streaming: off(기본값), "partial", "quiet", true, 또는 false. "partial"과 true는 일반 Matrix 텍스트 메시지로 미리보기 우선 초안 업데이트를 활성화합니다. "quiet"은 자체 호스팅 push-rule 설정을 위한 무알림 미리보기 알림을 사용합니다. false는 "off"와 같습니다.
• blockStreaming: true는 초안 미리보기 스트리밍이 활성화되어 있을 때 완료된 assistant 블록용 별도 진행 상황 메시지를 활성화합니다.
• threadReplies: off, inbound, 또는 always.
• threadBindings: 스레드 바인딩 세션 라우팅 및 수명 주기에 대한 채널별 재정의.
• startupVerification: 시작 시 자동 self-verification 요청 모드 (if-unverified, off).
• startupVerificationCooldownHours: 자동 시작 검증 요청을 다시 시도하기 전 cooldown.
• textChunkLimit: 문자 기준 outbound 메시지 청크 크기 (chunkMode가 length일 때 적용).
• chunkMode: length는 문자 수 기준으로 메시지를 분할하고, newline은 줄 경계에서 분할합니다.
• responsePrefix: 이 채널의 모든 outbound 답변 앞에 붙는 선택적 문자열.
• ackReaction: 이 채널/계정에 대한 선택적 ack 반응 재정의.
• ackReactionScope: 선택적 ack 반응 범위 재정의 (group-mentions, group-all, direct, all, none, off).
• reactionNotifications: inbound 반응 알림 모드 (own, off).
• mediaMaxMb: outbound 전송 및 inbound 미디어 처리용 미디어 크기 상한(MB).
• autoJoin: 초대 자동 참여 정책 (always, allowlist, off). 기본값: off. DM 스타일 초대를 포함한 모든 Matrix 초대에 적용됩니다.
• autoJoinAllowlist: autoJoin이 allowlist일 때 허용되는 room/alias. Alias 항목은 초대 처리 중 room ID로 해석되며, OpenClaw는 초대된 room이 주장하는 alias 상태를 신뢰하지 않습니다.
• dm: DM 정책 블록 (enabled, policy, allowFrom, sessionScope, threadReplies).
• dm.policy: OpenClaw가 room에 참여하고 이를 DM으로 분류한 후의 DM 접근을 제어합니다. 초대가 자동 참여되는지 여부는 변경하지 않습니다.
• dm.allowFrom: live directory lookup으로 이미 해석하지 않았다면 항목은 전체 Matrix 사용자 ID여야 합니다.
• dm.sessionScope: per-user(기본값) 또는 per-room. 같은 상대방이라도 각 Matrix DM room이 별도 컨텍스트를 유지하게 하려면 per-room을 사용하세요.
• dm.threadReplies: DM 전용 스레드 정책 재정의 (off, inbound, always). DMs에서 답변 배치와 세션 격리 모두에 대해 최상위 threadReplies 설정을 재정의합니다.
• execApprovals: Matrix 네이티브 exec 승인 전달 (enabled, approvers, target, agentFilter, sessionFilter).
• execApprovals.approvers: exec 요청을 승인할 수 있는 Matrix 사용자 ID. dm.allowFrom이 이미 승인자를 식별하는 경우 선택 사항입니다.
• execApprovals.target: dm | channel | both (기본값: dm).
• accounts: 이름 있는 계정별 재정의. 최상위 channels.matrix 값은 이 항목들의 기본값으로 동작합니다.
• groups: room별 정책 맵. room ID 또는 alias를 권장하며, 해석되지 않은 room 이름은 런타임에서 무시됩니다. 세션/그룹 ID는 해석 후 안정적인 room ID를 사용합니다.
• groups.<room>.account: 다중 계정 구성에서 하나의 상속된 room 항목을 특정 Matrix 계정으로 제한합니다.
• groups.<room>.allowBots: 구성된 봇 발신자에 대한 room 수준 재정의 (true 또는 "mentions").
• groups.<room>.users: room별 발신자 허용 목록.
• groups.<room>.tools: room별 도구 허용/거부 재정의.
• groups.<room>.autoReply: room 수준 멘션 게이팅 재정의. true는 해당 room의 멘션 요구 사항을 비활성화하고, false는 다시 강제 적용합니다.
• groups.<room>.skills: 선택적 room 수준 Skills 필터.
• groups.<room>.systemPrompt: 선택적 room 수준 system prompt 스니펫.
• rooms: groups의 레거시 alias.
• actions: 작업별 도구 게이팅 (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​

관련 항목

• Channels Overview — 지원되는 모든 채널
• Pairing — DM 인증 및 pairing 흐름
• Groups — 그룹 채팅 동작 및 멘션 게이팅
• Channel Routing — 메시지 세션 라우팅
• Security — 접근 모델 및 하드닝