​

Matrix

​

번들 plugin

openclaw plugins install @openclaw/matrix

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

​

설정

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

openclaw channels add
openclaw configure --section channels

• homeserver URL
• 인증 방식: 액세스 토큰 또는 비밀번호
• 비밀번호 인증을 선택한 경우에만 user ID
• 선택적 device 이름
• E2EE 활성화 여부
• 지금 Matrix room 접근을 구성할지 여부

• 선택한 계정에 대해 Matrix 인증 env var가 이미 존재하고, 해당 계정의 인증이 아직 config에 저장되지 않은 경우, 마법사는 env 바로가기를 제안하고 해당 계정에 enabled: true만 기록합니다.
• 다른 Matrix 계정을 대화형으로 추가하면, 입력한 계정 이름이 config와 env var에 사용되는 account ID로 정규화됩니다. 예를 들어 Ops Bot은 ops-bot이 됩니다.
• DM 허용 목록 프롬프트는 전체 @user:server 값을 즉시 받을 수 있습니다. 표시 이름은 실시간 디렉터리 조회에서 정확히 하나의 일치 항목을 찾은 경우에만 작동하며, 그렇지 않으면 마법사가 전체 Matrix ID로 다시 시도하라고 요청합니다.
• Room 허용 목록 프롬프트는 room ID와 alias를 직접 받을 수 있습니다. 참가 중인 room 이름도 실시간으로 확인할 수 있지만, 확인되지 않은 이름은 설정 중 입력된 그대로만 유지되며 이후 런타임 허용 목록 해석에서는 무시됩니다. !room:server 또는 #alias:server를 권장합니다.
• 런타임 room/세션 식별은 안정적인 Matrix room ID를 사용합니다. room에 선언된 alias는 조회 입력으로만 사용되며, 장기 세션 키나 안정적인 그룹 식별자로는 사용되지 않습니다.
• 저장 전에 room 이름을 해석하려면 openclaw channels resolve --channel matrix "Project Room"를 사용하세요.

{
  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",
        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 블록에 대해 수정 가능한 미리보기 메시지 하나를 생성합니다.
• blockStreaming: true는 별도의 Matrix 진행 메시지를 활성화합니다. streaming: "partial"과 함께 사용하면 Matrix는 현재 블록의 실시간 초안을 유지하고 완료된 블록은 별도 메시지로 보존합니다.
• streaming: "partial"이고 blockStreaming이 꺼져 있으면, Matrix는 실시간 초안만 수정하고 해당 블록 또는 턴이 끝나면 완료된 답장을 한 번 전송합니다.
• 미리보기가 더 이상 하나의 Matrix 이벤트에 맞지 않으면, OpenClaw는 미리보기 스트리밍을 중단하고 일반 최종 전달로 대체합니다.
• 미디어 답장은 여전히 첨부파일을 일반 방식으로 전송합니다. 오래된 미리보기를 더 이상 안전하게 재사용할 수 없으면 OpenClaw는 최종 미디어 답장을 보내기 전에 이를 redaction 처리합니다.
• 미리보기 수정에는 추가 Matrix API 호출 비용이 듭니다. 가장 보수적인 속도 제한 동작을 원하면 스트리밍을 끄세요.

​

암호화 및 검증

​

봇 간 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 user ID의 메시지는 계속 무시합니다.
• 여기서 Matrix는 기본적인 bot 플래그를 제공하지 않습니다. OpenClaw는 “봇이 작성한”을 “이 OpenClaw 게이트웨이에서 구성된 다른 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이 하는 일

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

​

새 백업 기준선

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

​

시작 동작

• OpenClaw는 가능하면 동일한 Matrix 계정, 액세스 토큰, device ID를 자동으로 재사용합니다.
• 실행 가능한 Matrix 마이그레이션 변경이 수행되기 전에 OpenClaw는 ~/Backups/openclaw-migrations/ 아래에 복구 스냅샷을 생성하거나 재사용합니다.
• 여러 Matrix 계정을 사용하는 경우, 이전 flat-store 레이아웃에서 업그레이드하기 전에 channels.matrix.defaultAccount를 설정하여 어떤 계정이 해당 공유 레거시 상태를 받아야 하는지 OpenClaw가 알 수 있게 하세요.
• 이전 plugin이 Matrix room-key 백업 복호화 키를 로컬에 저장했다면, 시작 시 또는 openclaw doctor --fix 실행 시 이를 새 복구 키 흐름으로 자동 가져옵니다.
• 마이그레이션 준비 후 Matrix 액세스 토큰이 변경된 경우, 시작 시 자동 백업 복원을 포기하기 전에 보류 중인 레거시 복원 상태가 있는 형제 토큰 해시 저장소 루트를 검색합니다.
• 동일 계정, homeserver, user에 대해 나중에 Matrix 액세스 토큰이 변경되면, OpenClaw는 빈 Matrix 상태 디렉터리에서 시작하는 대신 가장 완전한 기존 토큰 해시 저장소 루트를 우선 재사용합니다.
• 다음 게이트웨이 시작 시 백업된 room key가 새 crypto 저장소로 자동 복원됩니다.
• 이전 plugin에 백업되지 않은 로컬 전용 room key가 있었다면, OpenClaw는 이를 명확히 경고합니다. 해당 key는 이전 rust crypto 저장소에서 자동 내보내기할 수 없으므로 일부 이전 암호화 기록은 수동 복구 전까지 계속 사용할 수 없을 수 있습니다.
• 전체 업그레이드 흐름, 제한 사항, 복구 명령, 일반적인 마이그레이션 메시지는 Matrix migration을 참조하세요.

​

Node crypto 저장소 모델

• SDK가 기대하는 IndexedDB API shim으로 fake-indexeddb 사용
• initRustCrypto 전에 crypto-idb-snapshot.json에서 Rust crypto IndexedDB 내용을 복원
• 초기화 후와 런타임 중에 업데이트된 IndexedDB 내용을 다시 crypto-idb-snapshot.json에 저장
• gateway 런타임 영속성과 CLI 유지관리 작업이 같은 스냅샷 파일에서 경쟁하지 않도록 advisory 파일 잠금을 사용해 crypto-idb-snapshot.json에 대한 스냅샷 복원과 저장을 직렬화

• 영속적인 Matrix key material에 대한 SecretRef 지원을 추가하여 복구 키와 관련 저장소 암호화 secret을 로컬 파일뿐 아니라 OpenClaw secrets provider에서도 가져올 수 있도록 함

​

프로필 관리

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

​

자동 검증 알림

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

​

device 위생

openclaw matrix devices list

openclaw matrix devices prune-stale

​

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를 다시 써서 그것을 가리키게 함

​

Threads

• threadReplies: "off"는 답장을 최상위 수준으로 유지하고 수신 thread 메시지를 부모 세션에 유지합니다.
• threadReplies: "inbound"는 수신 메시지가 이미 해당 thread에 있을 때만 thread 내부에서 답장합니다.
• threadReplies: "always"는 room 답장을 트리거 메시지를 루트로 하는 thread에 유지하고, 첫 트리거 메시지부터 일치하는 thread 범위 세션을 통해 해당 대화를 라우팅합니다.
• dm.threadReplies는 DM에 대해서만 최상위 설정을 재정의합니다. 예를 들어 room thread는 분리하면서 DM은 평면으로 유지할 수 있습니다.
• 수신 thread 메시지에는 추가 에이전트 컨텍스트로 thread 루트 메시지가 포함됩니다.
• 이제 message-tool 전송은 대상이 같은 room이거나 같은 DM 사용자 대상인 경우, 명시적인 threadId가 제공되지 않으면 현재 Matrix thread를 자동 상속합니다.
• Matrix는 런타임 thread 바인딩을 지원합니다. 이제 /focus, /unfocus, /agents, /session idle, /session max-age, thread에 바인딩된 /acp spawn이 Matrix room과 DM에서 작동합니다.
• threadBindings.spawnSubagentSessions=true일 때 최상위 Matrix room/DM의 /focus는 새 Matrix thread를 만들고 이를 대상 세션에 바인딩합니다.
• 기존 Matrix thread 안에서 /focus 또는 /acp spawn --thread here를 실행하면 현재 thread가 대신 바인딩됩니다.

​

ACP 대화 바인딩

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

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

​

Thread 바인딩 구성

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

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

​

Reactions

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

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• 에이전트 ID 이모지 대체값

• 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"는 reaction 시스템 이벤트를 비활성화합니다.
• Matrix는 제거를 독립적인 m.reaction 제거가 아니라 redaction으로 표시하므로, reaction 제거는 아직 시스템 이벤트로 합성되지 않습니다.

​

기록 컨텍스트

• channels.matrix.historyLimit는 Matrix room 메시지가 에이전트를 트리거할 때 InboundHistory로 포함할 최근 room 메시지 수를 제어합니다.
• 기본값은 messages.groupChat.historyLimit를 따릅니다. 비활성화하려면 0으로 설정하세요.
• Matrix room 기록은 room 전용입니다. DM은 계속 일반 세션 기록을 사용합니다.
• Matrix room 기록은 pending-only입니다. OpenClaw는 아직 답장을 트리거하지 않은 room 메시지를 버퍼링한 뒤, 멘션이나 다른 트리거가 들어오면 그 구간을 스냅샷으로 저장합니다.
• 현재 트리거 메시지는 InboundHistory에 포함되지 않으며, 해당 턴의 메인 수신 본문에 남아 있습니다.
• 동일한 Matrix 이벤트를 재시도할 때는 새 room 메시지로 앞으로 이동하지 않고 원래 기록 스냅샷을 재사용합니다.

​

컨텍스트 가시성

• contextVisibility: "all"이 기본값입니다. 보조 컨텍스트는 받은 그대로 유지됩니다.
• contextVisibility: "allowlist"는 활성 room/user 허용 목록 검사에서 허용된 발신자만 보조 컨텍스트에 남깁니다.
• 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>

​

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.*는 exec 승인에 대해서만 기본 DM/채널 라우팅을 제어합니다.
• plugin 승인은 계속 공통 same-chat /approve와 구성된 approvals.plugin 전달을 사용합니다.
• Matrix는 승인자를 안전하게 추론할 수 있을 때 plugin 승인 권한 부여를 위해 channels.matrix.dm.allowFrom을 재사용할 수 있지만, 별도의 기본 plugin 승인 DM/채널 fanout 경로를 제공하지는 않습니다.

• target: "dm"은 승인 프롬프트를 승인자 DM으로 보냅니다
• target: "channel"은 프롬프트를 원래 Matrix room 또는 DM으로 다시 보냅니다
• target: "both"는 승인자 DM과 원래 Matrix room 또는 DM 모두로 보냅니다

• 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",
      allowPrivateNetwork: 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 이름 조회는 best-effort입니다. room 이름을 ID나 alias로 해석할 수 없으면 런타임 허용 목록 해석에서 무시됩니다.

​

구성 참조

• enabled: 채널 활성화 또는 비활성화.
• name: 계정의 선택적 레이블.
• defaultAccount: 여러 Matrix 계정이 구성된 경우 선호되는 account ID.
• homeserver: homeserver URL(예: https://matrix.example.org).
• allowPrivateNetwork: 이 Matrix 계정이 private/internal homeserver에 연결되도록 허용합니다. homeserver가 localhost, LAN/Tailscale IP 또는 matrix-synapse 같은 내부 호스트로 해석되는 경우 활성화하세요.
• proxy: Matrix 트래픽용 선택적 HTTP(S) 프록시 URL. 이름 있는 계정은 자체 proxy로 최상위 기본값을 재정의할 수 있습니다.
• userId: 전체 Matrix user ID(예: @bot:example.org).
• accessToken: 토큰 기반 인증용 액세스 토큰. 일반 텍스트 값과 SecretRef 값은 env/file/exec provider 전반에서 channels.matrix.accessToken과 channels.matrix.accounts.<id>.accessToken에 지원됩니다. Secrets Management를 참조하세요.
• password: 비밀번호 기반 로그인용 비밀번호. 일반 텍스트 값과 SecretRef 값이 지원됩니다.
• deviceId: 명시적 Matrix device ID.
• deviceName: 비밀번호 로그인용 device 표시 이름.
• avatarUrl: 프로필 동기화 및 set-profile 업데이트용으로 저장된 self-avatar URL.
• initialSyncLimit: 시작 시 sync 이벤트 제한.
• encryption: E2EE 활성화.
• allowlistOnly: DM과 room에 대해 허용 목록 전용 동작 강제.
• allowBots: 다른 구성된 OpenClaw Matrix 계정의 메시지를 허용(true 또는 "mentions").
• groupPolicy: open, allowlist, 또는 disabled.
• contextVisibility: 보조 room 컨텍스트 가시성 모드(all, allowlist, allowlist_quote).
• groupAllowFrom: room 트래픽용 user ID 허용 목록.
• groupAllowFrom 항목은 전체 Matrix user ID여야 합니다. 해석되지 않은 이름은 런타임에 무시됩니다.
• historyLimit: 그룹 기록 컨텍스트로 포함할 최대 room 메시지 수. 기본값은 messages.groupChat.historyLimit를 따릅니다. 비활성화하려면 0으로 설정하세요.
• replyToMode: off, first, 또는 all.
• markdown: 발신 Matrix 텍스트용 선택적 Markdown 렌더링 구성.
• streaming: off(기본값), partial, true, 또는 false. partial과 true는 제자리 수정 업데이트가 가능한 단일 메시지 초안 미리보기를 활성화합니다.
• blockStreaming: true는 초안 미리보기 스트리밍이 활성화된 동안 완료된 assistant 블록에 대해 별도 진행 메시지를 활성화합니다.
• threadReplies: off, inbound, 또는 always.
• threadBindings: thread 바인딩 세션 라우팅 및 수명 주기에 대한 채널별 재정의.
• startupVerification: 시작 시 자동 self-verification 요청 모드(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 전용 thread 정책 재정의(off, inbound, always). DM에서 답장 배치와 세션 분리 모두에 대해 최상위 threadReplies 설정을 재정의합니다.
• execApprovals: Matrix 기본 exec 승인 전달(enabled, approvers, target, agentFilter, sessionFilter).
• execApprovals.approvers: exec 요청을 승인할 수 있는 Matrix user ID. dm.allowFrom이 이미 승인자를 식별하는 경우 선택 사항입니다.
• execApprovals.target: dm | channel | both (기본값: dm).
• accounts: 이름 있는 계정별 재정의. 최상위 channels.matrix 값이 이 항목의 기본값으로 동작합니다.
• groups: room별 정책 맵. room ID 또는 alias를 권장하며, 해석되지 않은 room 이름은 런타임에 무시됩니다. 세션/그룹 ID는 해석 후 안정적인 room ID를 사용하고, 사람이 읽는 레이블은 계속 room 이름에서 가져옵니다.
• 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 수준 시스템 프롬프트 스니펫.
• rooms: groups의 레거시 별칭.
• actions: 작업별 도구 게이팅(messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​

관련

• 채널 개요 — 지원되는 모든 채널
• 페어링 — DM 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 — 메시지용 세션 라우팅
• 보안 — 접근 모델 및 보안 강화