매트릭스

Matrix는 공식 matrix-js-sdk를 기반으로 구축된 다운로드 가능한 채널 Plugin(@openclaw/matrix)입니다. DM, 방, 스레드, 미디어, 반응, 투표, 위치 및 E2EE를 지원합니다.

설치

openclaw plugins install @openclaw/matrix

출처가 지정되지 않은 Plugin 명세는 먼저 ClawHub를 시도한 다음 npm으로 대체합니다. openclaw plugins install clawhub:@openclaw/matrix 또는 npm:@openclaw/matrix로 출처를 강제 지정할 수 있습니다. 로컬 체크아웃에서는 openclaw plugins install ./path/to/local/matrix-plugin을 사용합니다.

plugins install은 Plugin을 등록하고 활성화하므로 별도의 enable 단계가 필요하지 않습니다. 아래와 같이 구성하기 전까지 채널은 아무 작업도 수행하지 않습니다. 일반적인 설치 규칙은 Plugin을 참조하세요.

설정

1. 홈서버에 Matrix 계정을 만듭니다.
2. channels.matrix에 homeserver + accessToken 또는 homeserver + userId + password를 구성합니다.
3. Gateway를 다시 시작합니다.
4. 봇과 DM을 시작하거나 봇을 방에 초대합니다. 새 초대는 autoJoin이 허용하는 경우에만 수락됩니다.

대화형 설정

openclaw channels addopenclaw configure --section channels

마법사는 홈서버 URL, 인증 방법(토큰 또는 비밀번호), 사용자 ID(비밀번호 인증에만 해당), 선택적 기기 이름, E2EE 활성화 여부, 방 접근 권한 및 자동 참여 설정을 묻습니다. 일치하는 MATRIX_* 환경 변수가 이미 존재하고 계정에 저장된 인증 정보가 없으면 마법사에서 환경 변수 바로 가기를 제공합니다. openclaw channels resolve --channel matrix "Project Room"을 사용해 방 이름을 확인한 후 허용 목록을 저장하세요. 마법사에서 E2EE를 활성화하면 openclaw matrix encryption setup과 동일한 부트스트랩이 실행됩니다.

최소 구성

토큰 기반:

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

자동 참여

channels.matrix.autoJoin의 기본값은 "off"입니다. 수동으로 참여하기 전에는 새 초대를 통해 생성된 방이나 DM에 봇이 나타나지 않습니다. OpenClaw는 초대 시점에 해당 초대가 DM인지 그룹인지 구분할 수 없으므로 모든 초대에 먼저 autoJoin이 적용됩니다. dm.policy는 봇이 참여하고 방이 분류된 후에만 적용됩니다.

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

허용 목록 대상 형식

• DM(dm.allowFrom, groupAllowFrom, groups.<room>.users): @user:server를 사용합니다. 표시 이름은 기본적으로 무시됩니다(변경 가능하기 때문). 표시 이름 호환성이 명시적으로 필요한 경우에만 dangerouslyAllowNameMatching: true를 설정하세요.
• 방 허용 목록 키(groups, 레거시 별칭 rooms): !room:server 또는 #alias:server를 사용합니다. dangerouslyAllowNameMatching: true를 설정하지 않으면 일반 이름은 무시됩니다.
• 초대 허용 목록(autoJoinAllowlist): !room:server, #alias:server 또는 *를 사용합니다. 일반 이름은 항상 거부됩니다.

계정 ID 정규화

마법사는 친숙한 이름을 정규화된 계정 ID로 변환합니다(Ops Bot -> ops-bot). 계정 간 충돌을 방지하기 위해 범위가 지정된 환경 변수 이름에서는 문장 부호를 16진수 이스케이프합니다. -(0x2D)는 _X2D_가 되므로 ops-prod는 환경 변수 접두사 MATRIX_OPS_X2D_PROD_에 매핑됩니다.

캐시된 인증 정보

Matrix는 ~/.openclaw/credentials/matrix/ 아래에 인증 정보를 캐시합니다. 기본 계정은 credentials.json, 이름이 지정된 계정은 credentials-<account>.json을 사용합니다. 캐시된 인증 정보가 있으면 OpenClaw는 구성 파일에 accessToken이 없어도 Matrix가 구성된 것으로 간주합니다. 이는 설정, openclaw doctor, 채널 상태 검사에 적용됩니다.

환경 변수

동일한 구성 키가 설정되지 않은 경우 구성 키에 대응하는 환경 변수가 사용됩니다. 기본 계정은 접두사 없는 이름을 사용하며, 이름이 지정된 계정은 접미사 앞에 계정 토큰을 삽입합니다(정규화 참조).

ops 계정의 경우 이름은 MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN 등이 됩니다. MATRIX_HOMESERVER와 범위가 지정된 모든 *_HOMESERVER 변형은 작업 공간 .env에서 설정할 수 없습니다. 작업 공간 .env 파일을 참조하세요.

구성 예시

DM 페어링, 방 허용 목록, E2EE를 포함한 실용적인 기본 구성입니다.

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

스트리밍 미리보기

Matrix 답장 스트리밍은 선택적으로 활성화합니다. streaming은 OpenClaw가 작성 중인 어시스턴트 답변을 전달하는 방식을 제어하고, blockStreaming은 완료된 각 블록을 별도의 Matrix 메시지로 유지할지 제어합니다.

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

실시간 답변 미리보기는 유지하면서 중간 도구/진행률 줄을 숨기려면 객체 형식을 사용하세요.

{  channels: {    matrix: {      streaming: {        mode: "partial",        preview: {          toolProgress: false,        },      },    },  },}

전체 객체 형식은 { mode, preview, progress }를 허용합니다.

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // pick from configured or built-in labels (false to hide)          labels: ["Thinking", "Writing", "Searching"], // candidates for label: "auto"          maxLines: 8, // max rolling progress lines (default: 8)          maxLineChars: 120, // max chars per line before truncation (default: 120)          toolProgress: true, // show tool/progress activity (default: true)        },      },    },  },}

• progress.label: 사용자 지정 레이블이며, "auto" 또는 미설정 시 구성되었거나 기본 제공되는 레이블을 선택하고, false이면 숨깁니다.
• progress.labels: label이 "auto"이거나 설정되지 않은 경우에만 사용되는 후보입니다.
• progress.maxLines: 초안에 유지할 순환 진행률 줄의 최대 개수입니다. 이를 초과한 이전 줄은 제거됩니다.
• progress.maxLineChars: 잘리기 전까지 간결한 진행률 줄마다 허용되는 최대 문자 수입니다.
• progress.toolProgress: true(기본값)이면 실시간 도구/진행률 활동이 초안에 표시됩니다.

blockStreaming(기본값 false)은 streaming과 독립적입니다.

참고:

• 미리보기가 Matrix의 이벤트당 크기 제한을 초과하면 OpenClaw는 미리보기 스트리밍을 중단하고 최종 결과만 전달하는 방식으로 대체합니다.
• 미디어 답변은 항상 첨부 파일을 정상적으로 전송합니다. 오래된 미리보기를 안전하게 재사용할 수 없으면 OpenClaw는 최종 미디어 답변을 보내기 전에 해당 미리보기를 삭제 처리합니다.
• 미리보기 스트리밍이 활성화되어 있으면 도구 진행률 미리보기 업데이트가 기본적으로 켜집니다. 답변 텍스트의 미리보기 편집은 유지하되 도구 진행률은 일반 전달 경로로 보내려면 streaming.preview.toolProgress: false를 설정하세요.
• 미리보기 편집에는 추가 Matrix API 호출이 필요합니다. 가장 보수적인 요청 제한 프로필을 사용하려면 streaming: "off"를 유지하세요.

음성 메시지

수신되는 Matrix 음성 메모는 방의 멘션 게이트보다 먼저 전사됩니다. 따라서 requireMention: true인 방에서도 봇 이름을 말하는 음성 메모가 에이전트를 트리거할 수 있으며, 에이전트에는 오디오 첨부 파일 자리표시자만 전달되는 대신 전사문이 전달됩니다.

Matrix는 OpenAI gpt-4o-mini-transcribe와 같이 tools.media.audio 아래에 있는 공유 오디오 미디어 제공자를 사용합니다. 제공자 설정 및 제한은 미디어 도구 개요를 참조하세요.

• m.audio 이벤트와 audio/* MIME 유형의 m.file 이벤트가 대상입니다.
• 암호화된 방에서는 OpenClaw가 전사하기 전에 기존 Matrix 미디어 경로를 통해 첨부 파일을 복호화합니다.
• 전사문은 에이전트 프롬프트에서 기계 생성 및 신뢰할 수 없음으로 표시됩니다.
• 첨부 파일은 이미 전사된 것으로 표시되어 이후 미디어 도구가 다시 전사하지 않습니다.
• 오디오 전사를 전역적으로 비활성화하려면 tools.media.audio.enabled: false를 설정하세요.

승인 메타데이터

Matrix 네이티브 승인 프롬프트는 com.openclaw.approval 키 아래에 OpenClaw 전용 콘텐츠를 포함하는 일반 m.room.message 이벤트입니다. 기본 클라이언트에서도 텍스트 본문이 렌더링되며, OpenClaw를 인식하는 클라이언트는 구조화된 승인 ID, 종류, 상태, 결정 및 실행/Plugin 세부 정보를 읽을 수 있습니다.

프롬프트가 Matrix 이벤트 하나에 담기에는 너무 길면 OpenClaw는 표시되는 텍스트를 여러 조각으로 나누고 첫 번째 조각에만 com.openclaw.approval을 첨부합니다. 허용/거부 반응은 해당 첫 번째 이벤트에 연결되므로 긴 프롬프트도 단일 이벤트 프롬프트와 동일한 승인 대상을 유지합니다.

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

streaming: "quiet"은 블록이나 턴이 확정된 후에만 수신자에게 알립니다. 사용자별 푸시 규칙이 확정된 미리보기 마커와 일치해야 합니다. 전체 설정 방법은 조용한 미리보기를 위한 Matrix 푸시 규칙을 참조하세요.

봇 간 대화방

기본적으로 설정된 다른 OpenClaw 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는 특정 대화방 하나에 대해 계정 수준 설정을 재정의합니다.
• 수락된 설정 봇 메시지에는 공유 봇 루프 방지가 적용됩니다. channels.defaults.botLoopProtection을 설정한 다음, 계정별로 channels.matrix.botLoopProtection을 사용하거나 대화방별로 channels.matrix.groups.<room>.botLoopProtection을 사용해 재정의하세요.
• OpenClaw는 자기 응답 루프를 방지하기 위해 동일한 Matrix 사용자 ID에서 보낸 메시지를 계속 무시합니다.
• Matrix에는 기본 제공 봇 플래그가 없습니다. OpenClaw는 "봇이 작성함"을 "이 OpenClaw Gateway에 설정된 다른 Matrix 계정이 보냄"으로 간주합니다.

공유 대화방에서 봇 간 트래픽을 활성화할 때는 엄격한 대화방 허용 목록과 멘션 요구 사항을 사용하세요.

암호화 및 검증

암호화된(E2EE) 대화방에서 발신 이미지 이벤트는 thumbnail_file을 사용하므로 이미지 미리보기가 전체 첨부 파일과 함께 암호화됩니다. 암호화되지 않은 대화방은 일반 thumbnail_url을 사용합니다. 별도의 설정은 필요하지 않습니다. Plugin이 E2EE 상태를 자동으로 감지합니다.

모든 openclaw matrix 명령은 --verbose(전체 진단), --json(기계 판독 가능 출력), --account <id>(다중 계정 구성)를 지원합니다. 기본 출력은 간결합니다.

암호화 활성화

openclaw matrix encryption setup

비밀 저장소와 교차 서명을 부트스트랩하고, 필요한 경우 대화방 키 백업을 생성한 다음 상태와 다음 단계를 출력합니다. 유용한 플래그:

• --recovery-key <key> 부트스트랩 전에 복구 키를 적용합니다. 아래의 표준 입력 방식을 권장합니다.
• --force-reset-cross-signing 현재 교차 서명 ID를 폐기하고 새 ID를 생성합니다. 의도한 경우에만 사용하세요.

새 계정에서는 생성 시 E2EE를 활성화하세요.

openclaw matrix account add \  --homeserver https://matrix.example.org \  --access-token syt_xxx \  --enable-e2ee

--encryption은 --enable-e2ee의 별칭입니다. 이에 해당하는 수동 설정은 다음과 같습니다.

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

상태 및 신뢰 신호

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

verify status는 서로 독립적인 세 가지 신뢰 신호를 보고합니다. --verbose를 사용하면 모두 표시됩니다.

• Locally trusted: 이 클라이언트에서만 신뢰함
• Cross-signing verified: SDK가 교차 서명을 통한 검증을 보고함
• Signed by owner: 사용자의 자체 서명 키로 서명됨(진단 전용)

Verified by owner는 Cross-signing verified가 yes인 경우에만 yes입니다. 로컬 신뢰 또는 소유자 서명만으로는 충분하지 않습니다.

--allow-degraded-local-state는 먼저 Matrix 계정을 준비하지 않고 최선형 진단 결과를 반환합니다. 오프라인 상태이거나 일부만 설정된 상태를 점검할 때 유용합니다.

복구 키로 이 기기 검증

복구 키를 명령줄 인수로 전달하는 대신 표준 입력으로 파이프하세요.

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

이 명령은 세 가지 상태를 보고합니다.

• Recovery key accepted: Matrix가 비밀 저장소 또는 기기 신뢰에 사용할 키를 수락했습니다.
• Backup usable: 신뢰할 수 있는 복구 자료를 사용해 대화방 키 백업을 불러올 수 있습니다.
• Device verified by owner: 이 기기가 Matrix 교차 서명 ID의 완전한 신뢰를 확보했습니다.

복구 키로 백업 자료를 잠금 해제했더라도 완전한 ID 신뢰가 완료되지 않으면 0이 아닌 코드로 종료됩니다. 이 경우 다른 Matrix 클라이언트에서 자체 검증을 완료하세요.

openclaw matrix verify self

verify self는 Cross-signing verified: yes가 될 때까지 기다린 후 성공적으로 종료됩니다. 대기 시간을 조정하려면 --timeout-ms <ms>를 사용하세요.

리터럴 키 방식인 openclaw matrix verify device "<recovery-key>"도 작동하지만, 키가 셸 기록에 남습니다.

교차 서명 부트스트랩 또는 복구

openclaw matrix verify bootstrap

암호화된 계정을 위한 복구/설정 명령입니다. 다음 순서로 실행됩니다.

• 가능한 경우 기존 복구 키를 재사용해 비밀 저장소를 부트스트랩합니다.
• 교차 서명을 부트스트랩하고 누락된 공개 키를 업로드합니다.
• 현재 기기를 표시하고 교차 서명합니다.
• 서버 측 대화방 키 백업이 없으면 생성합니다.

홈서버가 교차 서명 키를 업로드할 때 UIA를 요구하면 OpenClaw는 먼저 인증 없음을 시도하고, 그다음 m.login.dummy, 마지막으로 m.login.password를 시도합니다. 마지막 방식에는 channels.matrix.password가 필요합니다.

유용한 플래그:

• --recovery-key-stdin(printf '%s\n' "$MATRIX_RECOVERY_KEY" | ...와 함께 사용) 또는 --recovery-key <key>
• --force-reset-cross-signing으로 현재 교차 서명 ID를 폐기합니다. 의도한 경우에만 사용해야 하며, 활성 복구 키가 저장되어 있거나 --recovery-key-stdin으로 제공되어야 합니다.

대화방 키 백업

openclaw matrix verify backup statusprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

backup status는 서버 측 백업의 존재 여부와 이 기기에서 해당 백업을 복호화할 수 있는지를 표시합니다. backup restore는 백업된 대화방 키를 로컬 암호화 저장소로 가져옵니다. 복구 키가 이미 디스크에 있으면 --recovery-key-stdin을 생략하세요.

손상된 백업을 새로운 기준 백업으로 교체하려면 다음 명령을 사용하세요. 복구할 수 없는 이전 기록의 손실을 감수하며, 현재 백업 비밀을 불러올 수 없는 경우 비밀 저장소도 다시 생성할 수 있습니다.

openclaw matrix verify backup reset --yes

이전 복구 키로 새 기준 백업을 의도적으로 더 이상 잠금 해제할 수 없게 해야 하는 경우에만 --rotate-recovery-key를 추가하세요.

검증 목록 조회, 요청 및 응답

openclaw matrix verify list

선택한 계정의 대기 중인 검증 요청을 나열합니다.

openclaw matrix verify request --own-useropenclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

이 계정에서 검증 요청을 보냅니다. --own-user는 자체 검증을 요청합니다. 같은 사용자의 다른 Matrix 클라이언트에서 메시지를 수락하세요. --user-id/--device-id/--room-id는 다른 사용자를 대상으로 지정합니다. --own-user는 다른 대상 지정 플래그와 함께 사용할 수 없습니다.

더 낮은 수준의 수명 주기 처리에서는 일반적으로 다른 클라이언트의 수신 요청을 추적하면서 다음 명령을 사용하여 특정 요청 <id>를 처리합니다. <id>는 verify list와 verify request에서 출력됩니다.

검증이 특정 DM 대화방에 연결된 경우 accept, start, sas, confirm-sas, mismatch-sas, cancel은 모두 DM 후속 처리 힌트로 --user-id와 --room-id를 지원합니다.

다중 계정 참고 사항

--account <id>를 지정하지 않으면 Matrix CLI 명령은 암시적 기본 계정을 사용합니다. 이름이 지정된 계정이 여러 개이고 channels.matrix.defaultAccount가 없으면 명령은 임의로 추측하지 않고 계정을 선택하도록 요청합니다. 이름이 지정된 계정에서 E2EE가 비활성화되어 있거나 사용할 수 없으면 오류에 해당 계정의 설정 키가 표시됩니다. 예: channels.matrix.accounts.assistant.encryption.

openclaw matrix account add \--account assistant \--homeserver https://matrix.example.org \--user-id '@assistant:example.org' \--password '<password>' \--device-name OpenClaw-Gateway

openclaw matrix account add \--account assistant \--homeserver https://matrix.example.org \--access-token '<token>'

openclaw matrix devices listopenclaw matrix devices prune-stale

프로필 관리

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

한 번의 호출에 두 옵션을 모두 전달하세요. Matrix는 mxc:// 아바타 URL을 직접 허용합니다. http:///https://를 전달하면 먼저 파일을 업로드하고 확인된 mxc:// URL을 channels.matrix.avatarUrl(또는 계정별 재정의)에 저장합니다.

스레드

Matrix는 자동 응답과 메시지 도구 전송 모두에서 네이티브 스레드를 지원합니다. 서로 독립적인 두 설정으로 동작을 제어합니다.

세션 라우팅 (sessionScope)

dm.sessionScope는 Matrix DM 방을 OpenClaw 세션에 매핑하는 방식을 결정합니다.

• "per-user"(기본값): 라우팅된 상대가 같은 모든 DM 방이 하나의 세션을 공유합니다.
• "per-room": 상대가 같더라도 각 Matrix DM 방에 자체 세션 키가 할당됩니다.

명시적 대화 바인딩은 항상 sessionScope보다 우선합니다. 바인딩된 방과 스레드는 선택한 대상 세션을 유지합니다.

응답 스레딩 (threadReplies)

threadReplies는 봇이 응답을 게시할 위치를 결정합니다.

• "off": 응답이 최상위에 게시됩니다. 수신된 스레드 메시지는 상위 세션에 유지됩니다.
• "inbound": 수신 메시지가 이미 스레드에 있었던 경우에만 해당 스레드 안에서 응답합니다.
• "always": 트리거 메시지를 루트로 하는 스레드 안에서 응답합니다. 해당 대화는 첫 번째 트리거부터 일치하는 스레드 범위 세션을 통해 라우팅됩니다.

dm.threadReplies는 DM에 대해서만 이를 재정의합니다. 예를 들어 방 스레드는 분리된 상태로 유지하면서 DM은 평면 구조로 유지할 수 있습니다.

스레드 상속 및 슬래시 명령

• 수신된 스레드 메시지에는 스레드 루트 메시지가 추가 에이전트 컨텍스트로 포함됩니다.
• 메시지 도구 전송은 같은 방(또는 같은 DM 사용자 대상)을 대상으로 할 때 명시적 threadId가 제공되지 않으면 현재 Matrix 스레드를 자동으로 상속합니다.
• DM 사용자 대상 재사용은 현재 세션 메타데이터가 같은 Matrix 계정의 동일한 DM 상대임을 입증하는 경우에만 적용됩니다. 그렇지 않으면 OpenClaw는 일반 사용자 범위 라우팅으로 대체합니다.
• /focus, /unfocus, /agents, /session idle, /session max-age, 스레드에 바인딩된 /acp spawn은 모두 Matrix 방과 DM에서 작동합니다.
• threadBindings.spawnSessions가 활성화된 경우 최상위 /focus는 새 Matrix 스레드를 생성하고 대상 세션에 바인딩합니다.
• 기존 Matrix 스레드 안에서 /focus 또는 /acp spawn --thread here를 실행하면 해당 스레드를 현재 위치에서 바인딩합니다.

OpenClaw가 동일한 공유 세션에서 다른 DM 방과 충돌하는 Matrix DM 방을 감지하면 /focus 우회 방법을 안내하고 dm.sessionScope 변경을 제안하는 일회성 m.notice를 게시합니다. 이 알림은 스레드 바인딩이 활성화된 경우에만 표시됩니다.

ACP 대화 바인딩

Matrix 방, DM, 기존 Matrix 스레드는 채팅 화면을 변경하지 않고도 지속적인 ACP 작업 공간이 될 수 있습니다.

운영자를 위한 빠른 절차:

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

--bind here는 하위 Matrix 스레드를 생성하지 않습니다. threadBindings.spawnSessions는 OpenClaw가 하위 스레드를 생성하거나 바인딩해야 하는 /acp spawn --thread auto|here를 제어합니다.

스레드 바인딩 구성

Matrix는 session.threadBindings의 전역 기본값을 상속하며 채널별 재정의를 지원합니다.

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions: 하위 에이전트 및 ACP 스레드 생성을 모두 제어합니다.
• threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions: 하위 에이전트 전용 또는 ACP 전용 생성을 위한 더 세부적인 재정의입니다.
• threadBindings.defaultSpawnContext

Matrix의 스레드 바인딩 세션 생성은 기본적으로 활성화되어 있습니다. 최상위 /focus와 /acp spawn --thread auto|here가 Matrix 스레드를 생성하거나 바인딩하지 못하게 하려면 threadBindings.spawnSessions: false로 설정하세요. 네이티브 하위 에이전트 스레드 생성 시 상위 대화 기록을 포크하지 않게 하려면 threadBindings.defaultSpawnContext: "isolated"로 설정하세요.

반응

Matrix는 발신 반응, 수신 반응 알림, 확인 반응을 지원합니다.

발신 반응 도구는 channels.matrix.actions.reactions로 제어됩니다.

• react는 Matrix 이벤트에 반응을 추가합니다.
• reactions는 Matrix 이벤트의 현재 반응 요약을 나열합니다.
• emoji=""는 해당 이벤트에 봇이 추가한 모든 반응을 제거합니다.
• remove: true는 봇이 추가한 반응 중 지정된 이모지 반응만 제거합니다.

결정 순서(먼저 정의된 값이 우선):

reactionNotifications: "own"은 봇이 작성한 Matrix 메시지를 대상으로 추가된 m.reaction 이벤트를 전달합니다. "off"는 반응 시스템 이벤트를 비활성화합니다. 반응 제거는 시스템 이벤트로 합성되지 않습니다. Matrix에서는 이를 독립적인 m.reaction 제거가 아닌 편집 삭제로 표시합니다.

기록 컨텍스트

• channels.matrix.historyLimit는 방 메시지가 에이전트를 트리거할 때 InboundHistory에 포함할 최근 방 메시지 수를 제어합니다. messages.groupChat.historyLimit로 대체되며, 둘 다 설정되지 않으면 실효 기본값은 0(비활성화)입니다.
• Matrix 방 기록은 방에만 적용됩니다. DM은 계속 일반 세션 기록을 사용합니다.
• 방 기록에는 대기 중인 메시지만 포함됩니다. OpenClaw는 아직 응답을 트리거하지 않은 방 메시지를 버퍼링한 다음 멘션이나 다른 트리거가 도착하면 해당 구간의 스냅샷을 생성합니다.
• 현재 트리거 메시지는 InboundHistory에 포함되지 않으며 해당 턴의 기본 수신 본문에 유지됩니다.
• 동일한 Matrix 이벤트의 재시도는 더 최신 방 메시지로 이동하지 않고 원래 기록 스냅샷을 재사용합니다.

컨텍스트 표시 범위

Matrix는 가져온 응답 텍스트, 스레드 루트, 대기 중인 기록과 같은 보조 방 컨텍스트에 대해 공유 contextVisibility 제어를 지원합니다.

• contextVisibility: "all"이 기본값입니다. 보조 컨텍스트가 수신된 그대로 유지됩니다.
• contextVisibility: "allowlist"는 활성 방/사용자 허용 목록 검사를 통과한 발신자의 보조 컨텍스트만 남깁니다.
• contextVisibility: "allowlist_quote"는 allowlist와 동일하게 동작하지만 명시적으로 인용된 응답 하나는 유지합니다.

이는 보조 컨텍스트의 표시 범위에만 영향을 주며, 수신 메시지 자체가 응답을 트리거할 수 있는지에는 영향을 주지 않습니다. 트리거 권한 부여는 계속 groupPolicy, groups, groupAllowFrom 및 DM 정책 설정에 따라 결정됩니다.

DM 및 방 정책

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

방은 계속 작동하게 유지하면서 DM을 완전히 비활성화하려면 dm.enabled: false로 설정하세요.

{  channels: {    matrix: {      dm: { enabled: false },      groupPolicy: "allowlist",      groupAllowFrom: ["@admin:example.org"],    },  },}

멘션 제어 및 허용 목록 동작은 그룹을 참조하세요.

Matrix DM 페어링 예시:

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

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

공유 DM 페어링 절차 및 저장소 구조는 페어링을 참조하세요.

직접 대화방 복구

다이렉트 메시지 상태가 불일치하면 OpenClaw의 오래된 m.direct 매핑이 현재 DM이 아닌 이전의 단독 대화방을 가리킬 수 있습니다. 상대에 대한 현재 매핑을 검사하세요.

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

복구하려면 다음을 실행하세요.

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

두 명령 모두 다중 계정 설정을 위한 --account <id>를 허용합니다. 복구 절차는 다음과 같습니다.

• 이미 m.direct에 매핑된 엄격한 1:1 DM을 우선합니다.
• 해당 사용자와 현재 참여 중인 엄격한 1:1 DM으로 대체합니다.
• 정상적인 DM이 없으면 새 직접 대화방을 생성하고 m.direct를 다시 작성합니다.

이 절차는 이전 대화방을 자동으로 삭제하지 않습니다. 정상적인 DM을 선택하고 매핑을 업데이트하여 이후 Matrix 전송, 확인 알림 및 기타 다이렉트 메시지 절차가 올바른 대화방을 대상으로 하게 합니다.

실행 승인

Matrix는 네이티브 승인 클라이언트로 작동할 수 있습니다. channels.matrix.execApprovals 아래에서 구성하세요. 계정별로 재정의하려면 channels.matrix.accounts.<account>.execApprovals를 사용하세요.

• enabled: Matrix 네이티브 프롬프트를 통해 승인을 전달합니다. 설정하지 않거나 "auto"로 설정하면 승인자 한 명 이상을 확인할 수 있는 즉시 자동으로 활성화됩니다. 명시적으로 비활성화하려면 false로 설정하세요.
• approvers: 실행 요청을 승인할 수 있는 Matrix 사용자 ID(@owner:example.org)입니다. channels.matrix.dm.allowFrom으로 대체됩니다.
• target: 프롬프트를 보낼 위치입니다. "dm"(기본값)은 승인자 DM으로 보내고, "channel"은 요청이 시작된 방 또는 DM으로 보내며, "both"는 양쪽 모두로 보냅니다.
• agentFilter / sessionFilter: Matrix 전달을 트리거할 에이전트/세션의 선택적 허용 목록입니다.

승인 종류에 따라 권한 부여 방식이 약간 다릅니다.

• 실행 승인은 execApprovals.approvers를 사용하며, 없으면 dm.allowFrom을 사용합니다.
• Plugin 승인은 dm.allowFrom을 통해서만 권한을 부여합니다.

두 종류 모두 Matrix 반응 바로가기와 메시지 업데이트를 공유합니다. 승인자는 기본 승인 메시지에서 다음 반응 바로가기를 볼 수 있습니다.

• ✅ 한 번 허용
• ❌ 거부
• ♾️ 항상 허용(유효한 실행 정책에서 허용하는 경우)

대체 슬래시 명령: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny.

확인된 승인자만 승인하거나 거부할 수 있습니다. 실행 승인을 채널로 전달하면 명령 텍스트가 포함됩니다. 신뢰할 수 있는 방에서만 channel 또는 both를 활성화하세요.

관련 문서: 실행 승인.

슬래시 명령

슬래시 명령(/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve 등)은 DM에서 직접 작동합니다. 방에서는 OpenClaw가 봇 자체의 Matrix 멘션이 접두사로 붙은 명령도 인식하므로, @bot:server /new는 사용자 지정 멘션 정규식 없이 명령 경로를 트리거합니다. 따라서 Element 및 유사한 클라이언트에서 사용자가 명령을 입력하기 전에 봇 이름을 탭 완성할 때 생성되는 방 형식의 @mention /command 게시물에도 봇이 응답할 수 있습니다.

권한 부여 규칙은 계속 적용됩니다. 명령 발신자는 일반 메시지와 동일한 DM 또는 방 허용 목록/소유자 정책을 충족해야 합니다.

다중 계정

{  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 값이 명명된 계정의 기본값으로 사용됩니다.
• groups.<room>.account를 사용하여 상속된 방 항목의 범위를 특정 계정으로 한정합니다. account가 없는 항목은 여러 계정에서 공유됩니다. 기본 계정이 최상위 수준에서 구성된 경우에도 account: "default"가 계속 작동합니다.

기본 계정 선택:

• 암시적 라우팅, 프로빙 및 CLI 명령에서 우선 사용할 명명된 계정을 선택하려면 defaultAccount를 설정합니다.
• 계정이 여러 개이고 그중 하나의 이름이 문자 그대로 default인 경우, defaultAccount를 설정하지 않아도 OpenClaw가 해당 계정을 암시적으로 사용합니다.
• 명명된 계정이 여러 개이고 기본 계정을 선택하지 않으면 CLI 명령이 계정을 임의로 추측하지 않습니다. defaultAccount를 설정하거나 --account <id>를 전달하세요.
• 최상위 channels.matrix.* 블록은 인증이 완료된 경우에만 암시적 default 계정으로 취급됩니다(homeserver + accessToken 또는 homeserver + userId + password). 캐시된 자격 증명으로 인증이 충족되면 명명된 계정은 homeserver + userId만으로도 검색할 수 있습니다.

승격:

• OpenClaw가 복구 또는 설정 중 단일 계정 구성을 다중 계정 구성으로 승격할 때 기존 명명된 계정이 있거나 defaultAccount가 이미 특정 계정을 가리키고 있으면 이를 유지합니다. Matrix 인증/부트스트랩 키만 승격된 계정으로 이동하며, 공유 전달 정책 키는 최상위 수준에 유지됩니다.

공유 다중 계정 패턴은 구성 참조를 확인하세요.

비공개/LAN 홈서버

기본적으로 OpenClaw는 SSRF 보호를 위해 계정별로 명시적으로 허용하지 않는 한 비공개/내부 Matrix 홈서버를 차단합니다.

홈서버가 localhost, LAN/Tailscale IP 또는 내부 호스트 이름에서 실행되는 경우 해당 계정에 network.dangerouslyAllowPrivateNetwork를 활성화하세요.

{  channels: {    matrix: {      homeserver: "http://matrix-synapse:8008",      network: {        dangerouslyAllowPrivateNetwork: 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과 같은 공개 평문 홈서버는 계속 차단됩니다. 가능하면 항상 https://를 사용하세요.

Matrix 트래픽 프록시 처리

Matrix 배포에 명시적인 아웃바운드 HTTP(S) 프록시가 필요한 경우 channels.matrix.proxy를 설정하세요.

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

명명된 계정은 channels.matrix.accounts.<id>.proxy를 사용하여 최상위 기본값을 재정의할 수 있습니다. OpenClaw는 런타임 Matrix 트래픽과 계정 상태 프로브에 동일한 프록시 설정을 사용합니다.

대상 해석

OpenClaw에서 방 또는 사용자 대상을 요구하는 모든 위치에 다음 Matrix 대상 형식을 사용할 수 있습니다.

• 사용자: @user:server, user:@user:server 또는 matrix:user:@user:server
• 방: !room:server, room:!room:server 또는 matrix:room:!room:server
• 별칭: #alias:server, channel:#alias:server 또는 matrix:channel:#alias:server

Matrix 방 ID는 대소문자를 구분합니다. 명시적 전달 대상, Cron 작업, 바인딩 또는 허용 목록을 구성할 때 Matrix의 방 ID 대소문자를 정확히 사용하세요. OpenClaw는 저장을 위해 내부 세션 키를 정규화하므로, 소문자로 된 해당 키는 Matrix 전달 ID의 신뢰할 수 있는 출처가 아닙니다.

실시간 디렉터리 조회에는 로그인한 Matrix 계정이 사용됩니다.

• 사용자 조회는 해당 홈서버의 Matrix 사용자 디렉터리를 쿼리합니다.
• 방 조회는 명시적 방 ID와 별칭을 직접 허용합니다. 참여한 방의 이름 조회는 최선형 방식이며, dangerouslyAllowNameMatching: true가 설정된 경우에만 런타임 방 허용 목록에 적용됩니다.
• 방 이름을 ID 또는 별칭으로 확인할 수 없으면 런타임 허용 목록 확인에서 무시됩니다.

구성 참조

허용 목록 형식의 사용자 필드(groupAllowFrom, dm.allowFrom, groups.<room>.users)에는 전체 Matrix 사용자 ID를 사용할 수 있으며, 이것이 가장 안전합니다. ID가 아닌 항목은 기본적으로 무시됩니다. dangerouslyAllowNameMatching: true가 설정되면 Matrix 디렉터리에서 표시 이름이 정확히 일치하는 항목을 시작 시 확인하며, 모니터가 실행 중일 때 허용 목록이 변경될 때마다 다시 확인합니다. 확인할 수 없는 항목은 런타임에 무시됩니다.

방 허용 목록 키(groups, 레거시 rooms)에는 방 ID 또는 별칭을 사용해야 합니다. 일반 방 이름 키는 기본적으로 무시되며, dangerouslyAllowNameMatching: true를 설정하면 참여한 방 이름을 대상으로 최선형 조회를 다시 활성화합니다.

계정 및 연결

• enabled: 채널을 활성화하거나 비활성화합니다.
• name: 계정의 선택적 표시 레이블입니다.
• defaultAccount: 여러 Matrix 계정이 구성된 경우 선호하는 계정 ID입니다.
• accounts: 이름이 지정된 계정별 재정의입니다. 최상위 channels.matrix 값은 기본값으로 상속됩니다.
• homeserver: 홈서버 URL입니다(예: https://matrix.example.org).
• network.dangerouslyAllowPrivateNetwork: 이 계정이 localhost, LAN/Tailscale IP 또는 내부 호스트 이름에 연결하도록 허용합니다.
• proxy: Matrix 트래픽에 사용할 선택적 HTTP(S) 프록시 URL입니다. 계정별 재정의를 지원합니다.
• userId: 전체 Matrix 사용자 ID입니다(@bot:example.org).
• accessToken: 토큰 기반 인증에 사용할 액세스 토큰입니다. env/file/exec 공급자 전반에서 일반 텍스트 및 SecretRef 값을 지원합니다(비밀 관리).
• password: 비밀번호 기반 로그인에 사용할 비밀번호입니다. 일반 텍스트 및 SecretRef 값을 지원합니다.
• deviceId: 명시적 Matrix 기기 ID입니다.
• deviceName: 비밀번호 로그인 시 사용되는 기기 표시 이름입니다.
• avatarUrl: 프로필 동기화 및 profile set 업데이트에 사용되는 저장된 자체 아바타 URL입니다.
• initialSyncLimit: 시작 동기화 중 가져오는 최대 이벤트 수입니다.

암호화

• encryption: E2EE를 활성화합니다. 기본값: false.
• startupVerification: "if-unverified"(E2EE가 켜져 있을 때의 기본값) 또는 "off"입니다. 이 기기가 확인되지 않은 경우 시작 시 자체 확인을 자동으로 요청합니다.
• startupVerificationCooldownHours: 다음 자동 시작 요청까지의 대기 시간입니다. 기본값: 24.

액세스 및 정책

• groupPolicy: "open", "allowlist" 또는 "disabled"입니다. 기본값: "allowlist".
• groupAllowFrom: 방 트래픽에 허용되는 사용자 ID 목록입니다.
• mentionPatterns: 방 멘션에 대한 범위 지정 정규식 패턴입니다. { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] } 형태의 객체입니다. 구성된 agents.list[].groupChat.mentionPatterns의 방별 적용 여부를 제어합니다.
• dm.enabled: false이면 모든 DM을 무시합니다. 기본값: true.
• dm.policy: "pairing"(기본값), "allowlist", "open" 또는 "disabled"입니다. 봇이 방에 참여하고 해당 방을 DM으로 분류한 후 적용되며, 초대 처리에는 영향을 주지 않습니다.
• dm.allowFrom: DM 트래픽에 허용되는 사용자 ID 목록입니다.
• dm.sessionScope: "per-user"(기본값) 또는 "per-room"입니다.
• dm.threadReplies: 답글 스레딩에 대한 DM 전용 재정의입니다("off", "inbound", "always").
• allowBots: 구성된 다른 Matrix 봇 계정의 메시지를 허용합니다(true 또는 "mentions").
• allowlistOnly: true이면 "disabled"를 제외한 모든 활성 DM 정책과 "open" 그룹 정책을 "allowlist"로 강제합니다. "disabled" 정책은 변경하지 않습니다.
• dangerouslyAllowNameMatching: true이면 사용자 허용 목록 항목에 대해 Matrix 표시 이름 디렉터리 조회를 허용하고, 방 허용 목록 키에 대해 참여한 방 이름 조회를 허용합니다. 전체 @user:server ID와 방 ID 또는 별칭을 사용하는 것이 좋습니다.
• autoJoin: "always", "allowlist" 또는 "off"입니다. 기본값: "off". DM 형식의 초대를 포함한 모든 Matrix 초대에 적용됩니다.
• autoJoinAllowlist: autoJoin이 "allowlist"일 때 허용되는 방/별칭입니다. 별칭 항목은 초대된 방이 주장하는 상태가 아니라 홈서버를 기준으로 확인됩니다.
• contextVisibility: 보조 컨텍스트 표시 범위입니다("all"이 기본값이며, "allowlist", "allowlist_quote"도 지원).

답글 동작

• replyToMode: "off"(기본값), "first", "all" 또는 "batched"입니다.
• threadReplies: "off"(명시적으로 설정하지 않으면 최상위 기본값은 "inbound"로 결정됨), "inbound" 또는 "always"입니다.
• threadBindings: 스레드에 바인딩된 세션 라우팅 및 수명 주기에 대한 채널별 재정의입니다.
• streaming: "off"(기본값), "partial", "quiet", "progress" 또는 객체 형식 { mode, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }입니다. true <-> "partial", false <-> "off".
• blockStreaming: true이면 완료된 어시스턴트 블록을 별도의 진행 메시지로 유지합니다. 기본값: false.
• markdown: 발신 텍스트를 위한 선택적 Markdown 렌더링 구성입니다.
• responsePrefix: 발신 답글 앞에 추가되는 선택적 문자열입니다.
• textChunkLimit: chunkMode: "length"일 때 문자를 기준으로 한 발신 청크 크기입니다. 기본값: 4000.
• chunkMode: "length"(기본값, 문자 수를 기준으로 분할) 또는 "newline"(줄 경계에서 분할)입니다.
• historyLimit: 방 메시지가 에이전트를 트리거할 때 InboundHistory로 포함되는 최근 방 메시지 수입니다. messages.groupChat.historyLimit로 대체되며, 실질적인 기본값은 0(비활성화)입니다.
• mediaMaxMb: 발신 전송 및 수신 처리에 적용되는 미디어 크기 상한(MB)입니다. 기본값: 20.

반응 설정

• ackReaction: 이 채널/계정에 대한 확인 반응 재정의입니다.
• ackReactionScope: 범위 재정의입니다("group-mentions"가 기본값이며, "group-all", "direct", "all", "none", "off"도 지원).
• reactionNotifications: 수신 반응 알림 모드입니다("own"이 기본값이며, "off"도 지원).

도구 및 방별 재정의

• actions: 작업별 도구 게이팅입니다(messages, reactions, pins, profile, memberInfo, channelInfo, verification).
• groups: 방별 정책 맵입니다. 세션 식별에는 확인 후의 안정적인 방 ID가 사용됩니다. (rooms는 레거시 별칭입니다.)
  • groups.<room>.account: 상속된 방 항목 하나를 특정 계정으로 제한합니다.
  • groups.<room>.enabled: 방별 토글입니다. false이면 해당 방은 맵에 없는 것처럼 무시됩니다.
  • groups.<room>.requireMention: 채널 수준 멘션 요구 사항에 대한 방별 재정의입니다.
  • groups.<room>.allowBots: 채널 수준 설정에 대한 방별 재정의입니다(true 또는 "mentions").
  • groups.<room>.botLoopProtection: 봇 간 루프 보호 예산에 대한 방별 재정의입니다.
  • groups.<room>.users: 방별 발신자 허용 목록입니다.
  • groups.<room>.tools: 방별 도구 허용/거부 재정의입니다.
  • groups.<room>.autoReply: 방별 멘션 게이팅 재정의입니다. true이면 해당 방의 멘션 요구 사항을 비활성화하고, false이면 다시 강제로 활성화합니다.
  • groups.<room>.skills: 방별 Skills 필터입니다.
  • groups.<room>.systemPrompt: 방별 시스템 프롬프트 조각입니다.

실행 승인 설정

• execApprovals.enabled: Matrix 네이티브 프롬프트를 통해 실행 승인을 전달합니다.
• execApprovals.approvers: 승인할 수 있는 Matrix 사용자 ID입니다. dm.allowFrom으로 대체됩니다.
• execApprovals.target: "dm"(기본값), "channel" 또는 "both"입니다.
• execApprovals.agentFilter / execApprovals.sessionFilter: 전달을 위한 선택적 에이전트/세션 허용 목록입니다.

관련 문서

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