Matriks

Matrix adalah plugin saluran yang dapat diunduh (@openclaw/matrix) dan dibuat berdasarkan matrix-js-sdk resmi. Plugin ini mendukung DM, ruang, utas, media, reaksi, jajak pendapat, lokasi, dan E2EE.

Instalasi

openclaw plugins install @openclaw/matrix

Spesifikasi plugin tanpa awalan akan mencoba ClawHub terlebih dahulu, lalu menggunakan npm sebagai alternatif. Paksa sumber dengan openclaw plugins install clawhub:@openclaw/matrix atau npm:@openclaw/matrix. Dari checkout lokal: openclaw plugins install ./path/to/local/matrix-plugin.

plugins install mendaftarkan dan mengaktifkan plugin; tidak diperlukan langkah enable terpisah. Saluran tetap tidak melakukan apa pun hingga dikonfigurasi di bawah ini. Lihat Plugin untuk aturan instalasi umum.

Penyiapan

1. Buat akun Matrix di homeserver Anda.
2. Konfigurasikan channels.matrix dengan homeserver + accessToken, atau homeserver + userId + password.
3. Mulai ulang Gateway.
4. Mulai DM dengan bot, atau undang bot ke ruang. Undangan baru hanya diterima jika diizinkan oleh autoJoin.

Penyiapan interaktif

openclaw channels addopenclaw configure --section channels

Wisaya meminta URL homeserver, metode autentikasi (token atau kata sandi), ID pengguna (hanya untuk autentikasi kata sandi), nama perangkat opsional, apakah E2EE akan diaktifkan, serta akses ruang/gabung otomatis. Jika variabel lingkungan MATRIX_* yang sesuai sudah tersedia dan akun belum memiliki autentikasi tersimpan, wisaya menawarkan pintasan variabel lingkungan. Selesaikan nama ruang sebelum menyimpan daftar izin dengan openclaw channels resolve --channel matrix "Project Room". Mengaktifkan E2EE dalam wisaya menjalankan bootstrap yang sama dengan openclaw matrix encryption setup.

Konfigurasi minimal

Berbasis token:

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

Berbasis kata sandi (token disimpan dalam cache setelah login pertama):

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

Gabung otomatis

Nilai bawaan channels.matrix.autoJoin adalah "off": bot tidak akan muncul di ruang atau DM baru dari undangan baru hingga Anda bergabung secara manual. OpenClaw tidak dapat menentukan pada saat undangan diterima apakah undangan tersebut merupakan DM atau grup, sehingga setiap undangan diproses terlebih dahulu melalui autoJoin; dm.policy baru berlaku kemudian, setelah bot bergabung dan ruang diklasifikasikan.

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

Format target daftar izin

• DM (dm.allowFrom, groupAllowFrom, groups.<room>.users): gunakan @user:server. Nama tampilan diabaikan secara bawaan (karena dapat berubah); tetapkan dangerouslyAllowNameMatching: true hanya untuk kompatibilitas nama tampilan secara eksplisit.
• Kunci daftar izin ruang (groups, alias lama rooms): gunakan !room:server atau #alias:server. Nama biasa diabaikan kecuali dangerouslyAllowNameMatching: true.
• Daftar izin undangan (autoJoinAllowlist): gunakan !room:server, #alias:server, atau *. Nama biasa selalu ditolak.

Normalisasi ID akun

Wisaya mengubah nama yang mudah dibaca menjadi ID akun yang dinormalisasi (Ops Bot -> ops-bot). Tanda baca di-escape dalam bentuk heksadesimal pada nama variabel lingkungan bercakupan agar akun tidak bertabrakan: - (0x2D) menjadi _X2D_, sehingga ops-prod dipetakan ke awalan lingkungan MATRIX_OPS_X2D_PROD_.

Kredensial tersimpan dalam cache

Matrix menyimpan kredensial dalam cache di ~/.openclaw/credentials/matrix/: credentials.json untuk akun bawaan, credentials-<account>.json untuk akun bernama. Jika kredensial tersimpan dalam cache tersedia, OpenClaw menganggap Matrix telah dikonfigurasi meskipun tidak ada accessToken dalam berkas konfigurasi—ini mencakup penyiapan, openclaw doctor, dan pemeriksaan status saluran.

Variabel lingkungan

Variabel lingkungan yang didukung oleh kunci konfigurasi digunakan ketika kunci konfigurasi yang setara belum ditetapkan. Akun bawaan menggunakan nama tanpa awalan; akun bernama menyisipkan token akun sebelum sufiks (lihat normalisasi).

Untuk akun ops, nama menjadi MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN, dan seterusnya. MATRIX_HOMESERVER (dan varian bercakupan *_HOMESERVER apa pun) tidak dapat ditetapkan dari .env ruang kerja; lihat Berkas .env ruang kerja.

Contoh konfigurasi

Konfigurasi dasar praktis dengan pemasangan DM, daftar izin ruang, dan 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",    },  },}

Pratinjau streaming

Streaming balasan Matrix bersifat opsional. streaming mengontrol cara OpenClaw mengirimkan balasan asisten yang sedang berlangsung; blockStreaming mengontrol apakah setiap blok yang selesai dipertahankan sebagai pesan Matrix tersendiri.

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

Untuk mempertahankan pratinjau jawaban langsung tetapi menyembunyikan baris sementara alat/progres, gunakan bentuk objek:

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

Bentuk objek lengkap menerima { mode, preview, progress }:

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // pilih dari label yang dikonfigurasi atau label bawaan (false untuk menyembunyikan)          labels: ["Thinking", "Writing", "Searching"], // kandidat untuk label: "auto"          maxLines: 8, // jumlah maksimum baris progres bergulir (bawaan: 8)          maxLineChars: 120, // jumlah maksimum karakter per baris sebelum dipotong (bawaan: 120)          toolProgress: true, // tampilkan aktivitas alat/progres (bawaan: true)        },      },    },  },}

• progress.label: label khusus, "auto"/tidak ditetapkan untuk memilih label yang dikonfigurasi atau label bawaan, atau false untuk menyembunyikannya.
• progress.labels: kandidat yang hanya digunakan ketika label adalah "auto" atau tidak ditetapkan.
• progress.maxLines: jumlah maksimum baris progres bergulir yang dipertahankan dalam draf; baris yang lebih lama dari batas ini akan dipangkas.
• progress.maxLineChars: jumlah maksimum karakter per baris progres ringkas sebelum dipotong.
• progress.toolProgress: ketika true (bawaan), aktivitas alat/progres langsung muncul dalam draf.

blockStreaming (bawaan false) tidak bergantung pada streaming:

Catatan:

• Jika ukuran pratinjau melampaui batas ukuran per peristiwa Matrix, OpenClaw menghentikan streaming pratinjau dan beralih ke pengiriman hasil akhir saja.
• Balasan media selalu mengirim lampiran secara normal; jika pratinjau lama tidak dapat digunakan kembali dengan aman, OpenClaw menyuntingnya sebelum mengirim balasan media final.
• Pembaruan pratinjau progres alat diaktifkan secara bawaan ketika streaming pratinjau aktif. Tetapkan streaming.preview.toolProgress: false untuk mempertahankan edit pratinjau bagi teks jawaban, tetapi membiarkan progres alat menggunakan jalur pengiriman normal.
• Edit pratinjau memerlukan panggilan API Matrix tambahan. Biarkan streaming: "off" untuk profil batas laju yang paling konservatif.

Pesan suara

Catatan suara Matrix yang masuk ditranskripsikan sebelum gerbang penyebutan ruang, sehingga catatan suara yang menyebut nama bot dapat memicu agen dalam ruang dengan requireMention: true, dan agen menerima transkrip, bukan sekadar placeholder lampiran audio.

Matrix menggunakan penyedia media audio bersama di bawah tools.media.audio, seperti OpenAI gpt-4o-mini-transcribe. Lihat Ikhtisar alat media untuk penyiapan dan batas penyedia.

• Peristiwa m.audio dan peristiwa m.file dengan tipe MIME audio/* memenuhi syarat.
• Dalam ruang terenkripsi, OpenClaw mendekripsi lampiran melalui jalur media Matrix yang sudah ada sebelum transkripsi.
• Transkrip ditandai sebagai hasil buatan mesin dan tidak tepercaya dalam prompt agen.
• Lampiran ditandai sebagai telah ditranskripsikan agar alat media hilir tidak mentranskripsikannya lagi.
• Tetapkan tools.media.audio.enabled: false untuk menonaktifkan transkripsi audio secara global.

Metadata persetujuan

Prompt persetujuan asli Matrix merupakan peristiwa m.room.message biasa dengan konten khusus OpenClaw di bawah kunci com.openclaw.approval. Klien standar tetap merender isi teks; klien yang memahami OpenClaw dapat membaca ID persetujuan terstruktur, jenis, status, keputusan, serta detail eksekusi/plugin.

Jika prompt terlalu panjang untuk satu peristiwa Matrix, OpenClaw membagi teks yang terlihat menjadi beberapa bagian dan hanya melampirkan com.openclaw.approval pada bagian pertama. Reaksi izinkan/tolak terikat ke peristiwa pertama tersebut, sehingga prompt panjang mempertahankan target persetujuan yang sama seperti prompt satu peristiwa.

Aturan push yang dihosting sendiri untuk pratinjau final yang senyap

streaming: "quiet" hanya memberi tahu penerima setelah blok atau giliran difinalisasi—aturan push per pengguna harus cocok dengan penanda pratinjau final. Lihat Aturan push Matrix untuk pratinjau senyap untuk panduan lengkapnya.

Ruang antarbot

Secara default, pesan Matrix dari akun Matrix OpenClaw lain yang dikonfigurasi akan diabaikan. Gunakan allowBots untuk secara sengaja mengizinkan lalu lintas antaragen:

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

• allowBots: true menerima pesan dari akun bot Matrix lain yang dikonfigurasi di ruang dan DM yang diizinkan.
• allowBots: "mentions" hanya menerima pesan tersebut ketika pesan secara terlihat menyebut bot ini di ruang; DM tetap diizinkan tanpa syarat tersebut.
• groups.<room>.allowBots menggantikan pengaturan tingkat akun untuk satu ruang.
• Pesan bot terkonfigurasi yang diterima menggunakan perlindungan perulangan bot bersama. Konfigurasikan channels.defaults.botLoopProtection, lalu ganti per akun dengan channels.matrix.botLoopProtection atau per ruang dengan channels.matrix.groups.<room>.botLoopProtection.
• OpenClaw tetap mengabaikan pesan dari ID pengguna Matrix yang sama untuk menghindari perulangan balasan ke diri sendiri.
• Matrix tidak memiliki penanda bot bawaan; OpenClaw menganggap "ditulis oleh bot" sebagai "dikirim oleh akun Matrix lain yang dikonfigurasi pada Gateway OpenClaw ini".

Gunakan daftar ruang yang diizinkan secara ketat dan persyaratan penyebutan saat mengaktifkan lalu lintas antarbot di ruang bersama.

Enkripsi dan verifikasi

Di ruang terenkripsi (E2EE), peristiwa gambar keluar menggunakan thumbnail_file agar pratinjau gambar dienkripsi bersama lampiran lengkap; ruang yang tidak terenkripsi menggunakan thumbnail_url biasa. Tidak diperlukan konfigurasi—Plugin mendeteksi status E2EE secara otomatis.

Semua perintah openclaw matrix menerima --verbose (diagnostik lengkap), --json (keluaran yang dapat dibaca mesin), dan --account <id> (penyiapan multiakun). Secara default, keluarannya ringkas.

Mengaktifkan enkripsi

openclaw matrix encryption setup

Melakukan bootstrap penyimpanan rahasia dan penandatanganan silang, membuat cadangan kunci ruang jika diperlukan, lalu mencetak status dan langkah berikutnya. Flag yang berguna:

• --recovery-key <key> menerapkan kunci pemulihan sebelum bootstrap (utamakan bentuk stdin di bawah)
• --force-reset-cross-signing membuang identitas penandatanganan silang saat ini dan membuat yang baru (hanya untuk penggunaan yang disengaja)

Untuk akun baru, aktifkan E2EE saat akun dibuat:

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

--encryption adalah alias untuk --enable-e2ee. Konfigurasi manual yang setara:

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

Status dan sinyal kepercayaan

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

verify status melaporkan tiga sinyal kepercayaan yang independen (--verbose menampilkan semuanya):

• Dipercaya secara lokal: hanya dipercaya oleh klien ini
• Diverifikasi melalui penandatanganan silang: SDK melaporkan verifikasi melalui penandatanganan silang
• Ditandatangani oleh pemilik: ditandatangani oleh kunci penandatanganan mandiri Anda sendiri (hanya untuk diagnostik)

Diverifikasi oleh pemilik bernilai ya hanya ketika Diverifikasi melalui penandatanganan silang bernilai ya; kepercayaan lokal atau tanda tangan pemilik saja tidak cukup.

--allow-degraded-local-state mengembalikan diagnostik upaya terbaik tanpa terlebih dahulu menyiapkan akun Matrix; berguna untuk pemeriksaan luring atau konfigurasi parsial.

Memverifikasi perangkat ini dengan kunci pemulihan

Salurkan kunci pemulihan melalui stdin alih-alih meneruskannya melalui baris perintah:

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

Perintah tersebut melaporkan tiga status:

• Kunci pemulihan diterima: Matrix menerima kunci untuk penyimpanan rahasia atau kepercayaan perangkat.
• Cadangan dapat digunakan: cadangan kunci ruang dapat dimuat dengan materi pemulihan tepercaya.
• Perangkat diverifikasi oleh pemilik: perangkat ini memiliki kepercayaan penuh terhadap identitas penandatanganan silang Matrix.

Perintah keluar dengan status bukan nol ketika kepercayaan identitas penuh belum lengkap, meskipun kunci pemulihan telah membuka materi cadangan. Dalam kasus tersebut, selesaikan verifikasi mandiri dari klien Matrix lain:

openclaw matrix verify self

verify self menunggu hingga Diverifikasi melalui penandatanganan silang: ya sebelum berhasil keluar. Gunakan --timeout-ms <ms> untuk menyesuaikan waktu tunggu.

Bentuk kunci literal openclaw matrix verify device "<recovery-key>" juga berfungsi, tetapi kunci akan tersimpan dalam riwayat shell.

Melakukan bootstrap atau memperbaiki penandatanganan silang

openclaw matrix verify bootstrap

Perintah perbaikan/penyiapan untuk akun terenkripsi. Secara berurutan, perintah ini:

• melakukan bootstrap penyimpanan rahasia, menggunakan kembali kunci pemulihan yang ada jika memungkinkan
• melakukan bootstrap penandatanganan silang dan mengunggah kunci publik yang belum ada
• menandai dan menandatangani silang perangkat saat ini
• membuat cadangan kunci ruang di sisi server jika belum ada

Jika homeserver memerlukan UIA untuk mengunggah kunci penandatanganan silang, OpenClaw mencoba tanpa autentikasi terlebih dahulu, lalu m.login.dummy, kemudian m.login.password (memerlukan channels.matrix.password).

Flag yang berguna:

• --recovery-key-stdin (pasangkan dengan printf '%s\n' "$MATRIX_RECOVERY_KEY" | ...) atau --recovery-key <key>
• --force-reset-cross-signing untuk membuang identitas penandatanganan silang saat ini (hanya jika disengaja; memerlukan kunci pemulihan aktif yang disimpan atau diberikan melalui --recovery-key-stdin)

Cadangan kunci ruang

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

backup status menunjukkan apakah cadangan di sisi server tersedia dan apakah perangkat ini dapat mendekripsinya. backup restore mengimpor kunci ruang yang dicadangkan ke penyimpanan kriptografi lokal; hilangkan --recovery-key-stdin jika kunci pemulihan sudah tersimpan di disk.

Untuk mengganti cadangan yang rusak dengan garis dasar baru (menerima hilangnya riwayat lama yang tidak dapat dipulihkan; juga dapat membuat ulang penyimpanan rahasia jika rahasia cadangan saat ini tidak dapat dimuat):

openclaw matrix verify backup reset --yes

Tambahkan --rotate-recovery-key hanya ketika kunci pemulihan sebelumnya memang harus berhenti membuka garis dasar cadangan baru.

Mencantumkan, meminta, dan menanggapi verifikasi

openclaw matrix verify list

Mencantumkan permintaan verifikasi yang tertunda untuk akun yang dipilih.

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

Mengirim permintaan verifikasi dari akun ini. --own-user meminta verifikasi mandiri (terima perintah konfirmasi di klien Matrix lain milik pengguna yang sama); --user-id/--device-id/--room-id menargetkan orang lain. --own-user tidak dapat digabungkan dengan flag penargetan lainnya.

Untuk penanganan siklus hidup tingkat rendah—biasanya saat membayangi permintaan masuk dari klien lain—perintah berikut bertindak pada permintaan tertentu <id> (dicetak oleh verify list dan verify request):

accept, start, sas, confirm-sas, mismatch-sas, dan cancel semuanya menerima --user-id dan --room-id sebagai petunjuk tindak lanjut DM ketika verifikasi dikaitkan dengan ruang pesan langsung tertentu.

Catatan multiakun

Tanpa --account <id>, perintah CLI Matrix menggunakan akun default implisit. Jika terdapat beberapa akun bernama dan tidak ada channels.matrix.defaultAccount, perintah tidak akan menebak dan meminta Anda memilih. Ketika E2EE dinonaktifkan atau tidak tersedia untuk akun bernama, pesan kesalahan menunjuk ke kunci konfigurasi akun tersebut, misalnya 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

Pengelolaan profil

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

Berikan kedua opsi dalam satu pemanggilan. Matrix menerima URL avatar mxc:// secara langsung; memberikan http:///https:// akan mengunggah berkas terlebih dahulu dan menyimpan URL mxc:// yang telah dihasilkan ke channels.matrix.avatarUrl (atau penggantian khusus akun).

Utas

Matrix mendukung utas native untuk balasan otomatis maupun pengiriman melalui alat pesan. Dua pengaturan independen mengendalikan perilakunya:

Perutean sesi (sessionScope)

dm.sessionScope menentukan cara ruang DM Matrix dipetakan ke sesi OpenClaw:

• "per-user" (bawaan): semua ruang DM dengan rekan yang dirutekan sama berbagi satu sesi.
• "per-room": setiap ruang DM Matrix mendapatkan kunci sesinya sendiri, bahkan untuk rekan yang sama.

Pengikatan percakapan eksplisit selalu lebih diprioritaskan daripada sessionScope; ruang dan utas yang terikat tetap menggunakan sesi target yang dipilih.

Pengutasan balasan (threadReplies)

threadReplies menentukan tempat bot mengirim balasannya:

• "off": balasan berada di tingkat teratas. Pesan masuk dalam utas tetap berada di sesi induk.
• "inbound": membalas di dalam utas hanya jika pesan masuk sudah berada di utas tersebut.
• "always": membalas di dalam utas yang berakar pada pesan pemicu; percakapan tersebut dirutekan melalui sesi dengan cakupan utas yang sesuai sejak pemicu pertama dan seterusnya.

dm.threadReplies menggantikan pengaturan ini khusus untuk DM—misalnya, mempertahankan isolasi utas ruang sambil menjaga DM tetap tanpa utas.

Pewarisan utas dan perintah garis miring

• Pesan masuk dalam utas menyertakan pesan root utas sebagai konteks agen tambahan.
• Pengiriman melalui alat pesan secara otomatis mewarisi utas Matrix saat ini ketika menargetkan ruang yang sama (atau target pengguna DM yang sama), kecuali threadId eksplisit diberikan.
• Penggunaan kembali target pengguna DM hanya berlaku ketika metadata sesi saat ini membuktikan rekan DM yang sama pada akun Matrix yang sama; jika tidak, OpenClaw kembali menggunakan perutean normal dengan cakupan pengguna.
• /focus, /unfocus, /agents, /session idle, /session max-age, dan /acp spawn yang terikat utas semuanya berfungsi di ruang dan DM Matrix.
• /focus tingkat teratas membuat utas Matrix baru dan mengikatnya ke sesi target ketika threadBindings.spawnSessions diaktifkan.
• Menjalankan /focus atau /acp spawn --thread here di dalam utas Matrix yang sudah ada akan mengikat utas tersebut di tempatnya.

Ketika OpenClaw mendeteksi ruang DM Matrix bertabrakan dengan ruang DM lain pada sesi bersama yang sama, OpenClaw mengirim m.notice satu kali yang mengarahkan ke jalan keluar /focus dan menyarankan perubahan dm.sessionScope. Pemberitahuan tersebut hanya muncul ketika pengikatan utas diaktifkan.

Pengikatan percakapan ACP

Ruang Matrix, DM, dan utas Matrix yang sudah ada dapat menjadi ruang kerja ACP persisten tanpa mengubah permukaan obrolan.

Alur cepat operator:

• Jalankan /acp spawn codex --bind here di dalam DM, ruang, atau utas Matrix yang sudah ada dan ingin terus digunakan.
• Dalam DM atau ruang tingkat teratas, DM/ruang saat ini tetap menjadi permukaan obrolan dan pesan berikutnya dirutekan ke sesi ACP yang dibuat.
• Di dalam utas yang sudah ada, --bind here mengikat utas saat ini di tempatnya.
• /new dan /reset mengatur ulang sesi ACP terikat yang sama di tempatnya.
• /acp close menutup sesi ACP dan menghapus pengikatannya.

--bind here tidak membuat utas turunan Matrix. threadBindings.spawnSessions mengendalikan /acp spawn --thread auto|here, ketika OpenClaw perlu membuat atau mengikat utas turunan.

Konfigurasi pengikatan utas

Matrix mewarisi bawaan global dari session.threadBindings dan mendukung penggantian khusus kanal:

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions: mengendalikan pembuatan utas subagen maupun ACP.
• threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions: penggantian yang lebih spesifik untuk pembuatan khusus subagen atau khusus ACP.
• threadBindings.defaultSpawnContext

Pembuatan sesi terikat utas Matrix diaktifkan secara bawaan. Atur threadBindings.spawnSessions: false untuk mencegah /focus tingkat teratas dan /acp spawn --thread auto|here membuat/mengikat utas Matrix. Atur threadBindings.defaultSpawnContext: "isolated" ketika pembuatan utas subagen native tidak boleh mencabangkan transkrip induk.

Reaksi

Matrix mendukung reaksi keluar, pemberitahuan reaksi masuk, dan reaksi tanda terima.

Peralatan reaksi keluar dikendalikan oleh channels.matrix.actions.reactions:

• react menambahkan reaksi ke peristiwa Matrix.
• reactions mencantumkan ringkasan reaksi saat ini untuk peristiwa Matrix.
• emoji="" menghapus reaksi milik bot pada peristiwa tersebut.
• remove: true hanya menghapus reaksi emoji yang ditentukan dari bot.

Urutan resolusi (nilai pertama yang ditentukan akan digunakan):

reactionNotifications: "own" meneruskan peristiwa m.reaction yang ditambahkan ketika menargetkan pesan Matrix yang ditulis bot; "off" menonaktifkan peristiwa sistem reaksi. Penghapusan reaksi tidak disintesis menjadi peristiwa sistem—Matrix menampilkannya sebagai redaksi, bukan sebagai penghapusan m.reaction mandiri.

Konteks riwayat

• channels.matrix.historyLimit mengendalikan jumlah pesan ruang terbaru yang disertakan sebagai InboundHistory ketika pesan ruang memicu agen. Beralih ke messages.groupChat.historyLimit sebagai cadangan; nilai bawaan efektif 0 jika keduanya tidak diatur (dinonaktifkan).
• Riwayat ruang Matrix hanya berlaku untuk ruang; DM tetap menggunakan riwayat sesi normal.
• Riwayat ruang hanya mencakup pesan tertunda: OpenClaw menyangga pesan ruang yang belum memicu balasan, lalu mengambil cuplikan jendela tersebut ketika penyebutan atau pemicu lain tiba.
• Pesan pemicu saat ini tidak disertakan dalam InboundHistory; pesan tersebut tetap berada dalam isi pesan masuk utama untuk giliran itu.
• Percobaan ulang peristiwa Matrix yang sama menggunakan kembali cuplikan riwayat asli alih-alih bergeser maju ke pesan ruang yang lebih baru.

Visibilitas konteks

Matrix mendukung kontrol contextVisibility bersama untuk konteks ruang tambahan seperti teks balasan yang diambil, root utas, dan riwayat tertunda.

• contextVisibility: "all" adalah bawaan. Konteks tambahan dipertahankan sebagaimana diterima.
• contextVisibility: "allowlist" menyaring konteks tambahan agar hanya mencakup pengirim yang diizinkan oleh pemeriksaan daftar izin ruang/pengguna aktif.
• contextVisibility: "allowlist_quote" berperilaku seperti allowlist, tetapi tetap mempertahankan satu balasan yang dikutip secara eksplisit.

Pengaturan ini hanya memengaruhi visibilitas konteks tambahan, bukan apakah pesan masuk itu sendiri dapat memicu balasan. Otorisasi pemicu tetap berasal dari groupPolicy, groups, groupAllowFrom, dan pengaturan kebijakan DM.

Kebijakan DM dan ruang

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

Untuk sepenuhnya membisukan DM sambil mempertahankan fungsi ruang, atur dm.enabled: false:

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

Lihat Grup untuk perilaku pengendalian berdasarkan penyebutan dan daftar izin.

Contoh pemasangan untuk DM Matrix:

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

Jika pengguna Matrix yang belum disetujui terus mengirim pesan sebelum persetujuan, OpenClaw menggunakan kembali kode pemasangan tertunda yang sama dan dapat mengirim balasan pengingat setelah masa tunggu singkat alih-alih membuat kode baru.

Lihat Pemasangan untuk alur pemasangan DM bersama dan tata letak penyimpanannya.

Perbaikan ruang langsung

Jika status pesan langsung menyimpang, OpenClaw dapat memiliki pemetaan m.direct usang yang menunjuk ke ruang tunggal lama, bukan DM aktif. Periksa pemetaan saat ini untuk seorang rekan:

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

Perbaiki:

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

Kedua perintah menerima --account <id> untuk penyiapan multi-akun. Alur perbaikan:

• memprioritaskan DM 1:1 ketat yang sudah dipetakan dalam m.direct
• beralih sebagai cadangan ke DM 1:1 ketat mana pun yang saat ini telah digabungkan dengan pengguna tersebut
• membuat ruang langsung baru dan menulis ulang m.direct jika tidak ada DM yang sehat

Alur ini tidak menghapus ruang lama secara otomatis. Alur ini memilih DM yang sehat dan memperbarui pemetaan agar pengiriman Matrix, pemberitahuan verifikasi, dan alur pesan langsung lainnya di masa mendatang menargetkan ruang yang tepat.

Persetujuan eksekusi

Matrix dapat bertindak sebagai klien persetujuan native. Konfigurasikan di bawah channels.matrix.execApprovals (atau channels.matrix.accounts.<account>.execApprovals untuk penggantian khusus akun):

• enabled: mengirimkan persetujuan melalui permintaan native Matrix. Jika tidak diatur atau bernilai "auto", akan aktif otomatis setelah setidaknya satu pemberi persetujuan dapat ditentukan; atur false untuk menonaktifkannya secara eksplisit.
• approvers: ID pengguna Matrix (@owner:example.org) yang diizinkan menyetujui permintaan eksekusi. Beralih ke channels.matrix.dm.allowFrom sebagai cadangan.
• target: tempat permintaan dikirim. "dm" (bawaan) mengirim ke DM pemberi persetujuan; "channel" mengirim ke ruang atau DM asal; "both" mengirim ke keduanya.
• agentFilter / sessionFilter: daftar izin opsional untuk menentukan agen/sesi yang memicu pengiriman Matrix.

Otorisasi sedikit berbeda menurut jenis persetujuan:

• Persetujuan eksekusi menggunakan execApprovals.approvers, dengan dm.allowFrom sebagai cadangan.
• Persetujuan Plugin memberikan otorisasi hanya melalui dm.allowFrom.

Kedua jenis menggunakan pintasan reaksi dan pembaruan pesan Matrix yang sama. Pemberi persetujuan melihat pintasan reaksi pada pesan persetujuan utama:

• ✅ izinkan sekali
• ❌ tolak
• ♾️ selalu izinkan (ketika kebijakan eksekusi efektif mengizinkannya)

Perintah garis miring cadangan: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny.

Hanya pemberi persetujuan yang berhasil ditentukan yang dapat menyetujui atau menolak. Pengiriman kanal untuk persetujuan eksekusi menyertakan teks perintah—hanya aktifkan channel atau both di ruang tepercaya.

Terkait: Persetujuan eksekusi.

Perintah garis miring

Perintah garis miring (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve, dan sebagainya) berfungsi langsung di DM. Di ruang, OpenClaw juga mengenali perintah yang diawali dengan penyebutan Matrix milik bot, sehingga @bot:server /new memicu jalur perintah tanpa regex penyebutan khusus—hal ini membuat bot tetap responsif terhadap kiriman bergaya ruang @mention /command yang dihasilkan Element dan klien serupa ketika pengguna melengkapi nama bot dengan tombol tab sebelum mengetik perintah.

Aturan otorisasi tetap berlaku: pengirim perintah harus memenuhi kebijakan daftar izin/pemilik DM atau ruang yang sama seperti pesan biasa.

Multi-akun

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

Pewarisan:

• Nilai channels.matrix tingkat teratas bertindak sebagai nilai default untuk akun bernama, kecuali akun tersebut menggantinya.
• Batasi entri ruang yang diwariskan ke akun tertentu dengan groups.<room>.account. Entri tanpa account digunakan bersama di seluruh akun; account: "default" tetap berfungsi ketika akun default dikonfigurasi di tingkat teratas.

Pemilihan akun default:

• Atur defaultAccount untuk memilih akun bernama yang diutamakan oleh perutean implisit, pemeriksaan, dan perintah CLI.
• Jika Anda memiliki beberapa akun dan salah satunya secara harfiah bernama default, OpenClaw menggunakannya secara implisit meskipun defaultAccount tidak diatur.
• Dengan beberapa akun bernama dan tanpa akun default yang dipilih, perintah CLI tidak akan menebak—atur defaultAccount atau teruskan --account <id>.
• Blok channels.matrix.* tingkat teratas hanya diperlakukan sebagai akun default implisit ketika autentikasinya lengkap (homeserver + accessToken, atau homeserver + userId + password). Akun bernama tetap dapat ditemukan dari homeserver + userId setelah kredensial yang tersimpan dalam cache mencakup autentikasi.

Promosi:

• Ketika OpenClaw mempromosikan konfigurasi akun tunggal menjadi multiakun selama perbaikan atau penyiapan, OpenClaw mempertahankan akun bernama yang ada jika tersedia atau jika defaultAccount sudah mengarah ke akun tersebut. Hanya kunci autentikasi/bootstrap Matrix yang dipindahkan ke akun hasil promosi; kunci kebijakan pengiriman bersama tetap berada di tingkat teratas.

Lihat referensi konfigurasi untuk pola multiakun bersama.

Homeserver privat/LAN

Secara default, OpenClaw memblokir homeserver Matrix privat/internal untuk perlindungan SSRF, kecuali Anda mengaktifkannya untuk setiap akun.

Jika homeserver Anda berjalan di localhost, IP LAN/Tailscale, atau nama host internal, aktifkan network.dangerouslyAllowPrivateNetwork untuk akun tersebut:

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

Contoh penyiapan CLI:

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

Keikutsertaan ini hanya mengizinkan target privat/internal yang tepercaya. Homeserver publik tanpa enkripsi seperti http://matrix.example.org:8008 tetap diblokir. Utamakan https:// jika memungkinkan.

Memproksikan lalu lintas Matrix

Jika deployment Matrix Anda memerlukan proksi HTTP(S) keluar yang eksplisit, atur channels.matrix.proxy:

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

Akun bernama dapat mengganti nilai default tingkat teratas dengan channels.matrix.accounts.<id>.proxy. OpenClaw menggunakan pengaturan proksi yang sama untuk lalu lintas Matrix saat runtime dan pemeriksaan status akun.

Resolusi target

Matrix menerima bentuk target berikut di mana pun OpenClaw meminta target ruang atau pengguna:

• Pengguna: @user:server, user:@user:server, atau matrix:user:@user:server
• Ruang: !room:server, room:!room:server, atau matrix:room:!room:server
• Alias: #alias:server, channel:#alias:server, atau matrix:channel:#alias:server

ID ruang Matrix peka huruf besar-kecil. Gunakan kapitalisasi ID ruang yang persis sama dengan di Matrix saat mengonfigurasi target pengiriman eksplisit, tugas cron, pengikatan, atau daftar izin. OpenClaw mempertahankan kunci sesi internal dalam bentuk kanonis untuk penyimpanan, sehingga kunci berhuruf kecil tersebut bukan sumber yang dapat diandalkan untuk ID pengiriman Matrix.

Pencarian direktori langsung menggunakan akun Matrix yang sedang masuk:

• Pencarian pengguna mengueri direktori pengguna Matrix pada homeserver tersebut.
• Pencarian ruang menerima ID dan alias ruang eksplisit secara langsung. Pencarian nama ruang yang telah diikuti bersifat upaya terbaik dan hanya berlaku untuk daftar izin ruang saat runtime jika dangerouslyAllowNameMatching: true ditetapkan.
• Jika nama ruang tidak dapat diuraikan menjadi ID atau alias, nama tersebut diabaikan oleh resolusi daftar izin saat runtime.

Referensi konfigurasi

Kolom pengguna bergaya daftar izin (groupAllowFrom, dm.allowFrom, groups.<room>.users) menerima ID pengguna Matrix lengkap (paling aman). Entri non-ID diabaikan secara default. Jika dangerouslyAllowNameMatching: true ditetapkan, kecocokan persis nama tampilan dalam direktori Matrix diuraikan saat proses dimulai dan setiap kali daftar izin berubah selagi pemantau berjalan; entri yang tidak dapat diuraikan diabaikan saat runtime.

Kunci daftar izin ruang (groups, rooms lama) sebaiknya berupa ID atau alias ruang. Kunci yang hanya berupa nama ruang diabaikan secara default; dangerouslyAllowNameMatching: true memulihkan pencarian upaya terbaik terhadap nama ruang yang telah diikuti.

Akun dan koneksi

• enabled: aktifkan atau nonaktifkan kanal.
• name: label tampilan opsional untuk akun.
• defaultAccount: ID akun pilihan saat beberapa akun Matrix dikonfigurasi.
• accounts: penggantian bernama per akun. Nilai channels.matrix tingkat atas diwarisi sebagai nilai default.
• homeserver: URL homeserver, misalnya https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: izinkan akun ini terhubung ke localhost, IP LAN/Tailscale, atau nama host internal.
• proxy: URL proksi HTTP(S) opsional untuk lalu lintas Matrix. Mendukung penggantian per akun.
• userId: ID pengguna Matrix lengkap (@bot:example.org).
• accessToken: token akses untuk autentikasi berbasis token. Nilai teks biasa dan SecretRef didukung di seluruh penyedia env/file/exec (Pengelolaan Rahasia).
• password: kata sandi untuk masuk berbasis kata sandi. Nilai teks biasa dan SecretRef didukung.
• deviceId: ID perangkat Matrix eksplisit.
• deviceName: nama tampilan perangkat yang digunakan saat masuk dengan kata sandi.
• avatarUrl: URL avatar diri yang disimpan untuk sinkronisasi profil dan pembaruan profile set.
• initialSyncLimit: jumlah maksimum peristiwa yang diambil selama sinkronisasi awal.

Enkripsi

• encryption: aktifkan E2EE. Default: false.
• startupVerification: "if-unverified" (default saat E2EE aktif) atau "off". Secara otomatis meminta verifikasi mandiri saat proses dimulai jika perangkat ini belum terverifikasi.
• startupVerificationCooldownHours: masa tunggu sebelum permintaan otomatis berikutnya saat proses dimulai. Default: 24.

Akses dan kebijakan

• groupPolicy: "open", "allowlist", atau "disabled". Default: "allowlist".
• groupAllowFrom: daftar izin ID pengguna untuk lalu lintas ruang.
• mentionPatterns: pola regex tercakup untuk penyebutan di ruang. Objek dengan { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }. Mengendalikan apakah agents.list[].groupChat.mentionPatterns yang dikonfigurasi berlaku per ruang.
• dm.enabled: jika false, abaikan semua DM. Default: true.
• dm.policy: "pairing" (default), "allowlist", "open", atau "disabled". Berlaku setelah bot bergabung dan mengklasifikasikan ruang sebagai DM; tidak memengaruhi penanganan undangan.
• dm.allowFrom: daftar izin ID pengguna untuk lalu lintas DM.
• dm.sessionScope: "per-user" (default) atau "per-room".
• dm.threadReplies: penggantian khusus DM untuk penguntaian balasan ("off", "inbound", "always").
• allowBots: terima pesan dari akun bot Matrix lain yang dikonfigurasi (true atau "mentions").
• allowlistOnly: jika true, memaksa semua kebijakan DM aktif (kecuali "disabled") dan kebijakan grup "open" menjadi "allowlist". Tidak mengubah kebijakan "disabled".
• dangerouslyAllowNameMatching: jika true, mengizinkan pencarian direktori berdasarkan nama tampilan Matrix untuk entri daftar izin pengguna dan pencarian nama ruang yang telah diikuti untuk kunci daftar izin ruang. Utamakan ID @user:server lengkap serta ID atau alias ruang.
• autoJoin: "always", "allowlist", atau "off". Default: "off". Berlaku untuk setiap undangan Matrix, termasuk undangan bergaya DM.
• autoJoinAllowlist: ruang/alias yang diizinkan saat autoJoin bernilai "allowlist". Entri alias diuraikan terhadap homeserver, bukan terhadap status yang diklaim oleh ruang pengundang.
• contextVisibility: visibilitas konteks tambahan ("all" default, "allowlist", "allowlist_quote").

Perilaku balasan

• replyToMode: "off" (default), "first", "all", atau "batched".
• threadReplies: "off" (default tingkat atas diuraikan menjadi "inbound" kecuali ditetapkan secara eksplisit), "inbound", atau "always".
• threadBindings: penggantian per kanal untuk perutean dan siklus hidup sesi yang terikat ke utas.
• streaming: "off" (default), "partial", "quiet", "progress", atau bentuk objek { mode, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }. true <-> "partial", false <-> "off".
• blockStreaming: jika true, blok asisten yang telah selesai dipertahankan sebagai pesan kemajuan terpisah. Default: false.
• markdown: konfigurasi perenderan Markdown opsional untuk teks keluar.
• responsePrefix: string opsional yang ditambahkan di awal balasan keluar.
• textChunkLimit: ukuran potongan keluar dalam karakter saat chunkMode: "length". Default: 4000.
• chunkMode: "length" (default, membagi berdasarkan jumlah karakter) atau "newline" (membagi pada batas baris).
• historyLimit: jumlah pesan ruang terbaru yang disertakan sebagai InboundHistory ketika pesan ruang memicu agen. Menggunakan messages.groupChat.historyLimit sebagai cadangan; default efektif 0 (dinonaktifkan).
• mediaMaxMb: batas ukuran media dalam MB untuk pengiriman keluar dan pemrosesan masuk. Default: 20.

Pengaturan reaksi

• ackReaction: penggantian reaksi pengakuan untuk kanal/akun ini.
• ackReactionScope: penggantian cakupan ("group-mentions" default, "group-all", "direct", "all", "none", "off").
• reactionNotifications: mode notifikasi reaksi masuk ("own" default, "off").

Peralatan dan penggantian per ruang

• actions: pembatasan alat per tindakan (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
• groups: peta kebijakan per ruang. Identitas sesi menggunakan ID ruang stabil setelah resolusi. (rooms adalah alias lama.)
  • groups.<room>.account: batasi satu entri ruang yang diwarisi ke akun tertentu.
  • groups.<room>.enabled: pengalih per ruang. Jika false, ruang diabaikan seolah-olah tidak ada dalam peta.
  • groups.<room>.requireMention: penggantian per ruang untuk persyaratan penyebutan tingkat kanal.
  • groups.<room>.allowBots: penggantian per ruang untuk pengaturan tingkat kanal (true atau "mentions").
  • groups.<room>.botLoopProtection: penggantian per ruang untuk anggaran perlindungan perulangan antarbot.
  • groups.<room>.users: daftar izin pengirim per ruang.
  • groups.<room>.tools: penggantian izin/tolak alat per ruang.
  • groups.<room>.autoReply: penggantian penyaringan berdasarkan penyebutan per ruang. true menonaktifkan persyaratan penyebutan untuk ruang tersebut; false memaksanya aktif kembali.
  • groups.<room>.skills: filter Skills per ruang.
  • groups.<room>.systemPrompt: cuplikan prompt sistem per ruang.

Pengaturan persetujuan eksekusi

• execApprovals.enabled: kirim persetujuan eksekusi melalui prompt asli Matrix.
• execApprovals.approvers: ID pengguna Matrix yang diizinkan untuk menyetujui. Menggunakan dm.allowFrom sebagai cadangan.
• execApprovals.target: "dm" (default), "channel", atau "both".
• execApprovals.agentFilter / execApprovals.sessionFilter: daftar izin agen/sesi opsional untuk pengiriman.

Terkait

• Ikhtisar Kanal - semua kanal yang didukung
• Pemasangan - alur autentikasi dan pemasangan DM
• Grup - perilaku obrolan grup dan penyaringan berdasarkan penyebutan
• Perutean Kanal - perutean sesi untuk pesan
• Keamanan - model akses dan pengerasan