​

Matrix (eklenti)

​

Gerekli eklenti

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

Kurulum

1. Matrix eklentisini yükleyin:
   • npm’den: openclaw plugins install @openclaw/matrix
   • Yerel checkout’tan: openclaw plugins install ./extensions/matrix
2. Bir homeserver üzerinde bir Matrix hesabı oluşturun:
   • Barındırma seçeneklerine göz atın: https://matrix.org/ecosystem/hosting/
   • Ya da kendiniz barındırın.
3. Bot hesabı için bir erişim belirteci alın:
   • Homeserver’ınızda curl ile Matrix giriş API’sini kullanın:
   curl --request POST \
     --url https://matrix.example.org/_matrix/client/v3/login \
     --header 'Content-Type: application/json' \
     --data '{
     "type": "m.login.password",
     "identifier": {
       "type": "m.id.user",
       "user": "your-user-name"
     },
     "password": "your-password"
   }'
   
   • matrix.example.org yerine homeserver URL’nizi yazın.
   • Ya da channels.matrix.userId + channels.matrix.password ayarlayın: OpenClaw aynı giriş uç noktasını çağırır, erişim belirtecini ~/.openclaw/credentials/matrix/credentials.json içinde saklar ve bir sonraki başlatmada yeniden kullanır.
4. Kimlik bilgilerini yapılandırın:
   • Ortam: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (veya MATRIX_USER_ID + MATRIX_PASSWORD)
   • Ya da yapılandırma: channels.matrix.*
   • Her ikisi de ayarlıysa yapılandırma önceliklidir.
   • Erişim belirteciyle: kullanıcı kimliği /whoami üzerinden otomatik olarak alınır.
   • Ayarlandığında channels.matrix.userId tam Matrix kimliği olmalıdır (örnek: @bot:example.org).
5. Gateway’i yeniden başlatın (ya da ilk kurulumu tamamlayın).
6. Herhangi bir Matrix istemcisinden botla DM başlatın veya onu bir odaya davet edin (Element, Beeper vb.; bkz. https://matrix.org/ecosystem/clients/). Beeper E2EE gerektirir, bu nedenle channels.matrix.encryption: true ayarlayın ve cihazı doğrulayın.

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

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

​

Şifreleme (E2EE)

• Kripto modülü yüklenirse, şifreli odalar otomatik olarak çözümlenir.
• Şifreli odalara gönderimde giden medya şifrelenir.
• İlk bağlantıda OpenClaw, diğer oturumlarınızdan cihaz doğrulaması ister.
• Anahtar paylaşımını etkinleştirmek için başka bir Matrix istemcisinde (Element vb.) cihazı doğrulayın. to enable key sharing.
• Kripto modülü yüklenemezse E2EE devre dışı bırakılır ve şifreli odalar çözümlenmez; OpenClaw bir uyarı günlüğe yazar.
• Eksik kripto modülü hataları görürseniz (örneğin @matrix-org/matrix-sdk-crypto-nodejs-*), @matrix-org/matrix-sdk-crypto-nodejs için derleme betiklerine izin verin ve pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs çalıştırın veya ikiliyi node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js ile alın.

​

Çoklu hesap

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

• Eşzamanlı modül içe aktarımlarında yarış durumlarını önlemek için hesap başlatma işlemi sıralı olarak gerçekleştirilir.
• Ortam değişkenleri (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, vb.) yalnızca varsayılan hesap için geçerlidir.
• Temel kanal ayarları (DM politikası, grup politikası, mention kısıtlaması vb.) hesap başına geçersiz kılınmadıkça tüm hesaplara uygulanır.
• Her hesabı farklı bir agente yönlendirmek için bindings[].match.accountId kullanın.
• Kripto durumu hesap + access token başına saklanır (hesap başına ayrı anahtar depoları).

​

Yönlendirme modeli

• Yanıtlar her zaman Matrix’e geri gider.
• DM’ler ajanın ana oturumunu paylaşır; odalar grup oturumlarına eşlenir.

​

Erişim denetimi (DM’ler)

• Varsayılan: channels.matrix.dm.policy = "pairing". Bilinmeyen göndericiler bir eşleştirme kodu alır.
• Onaylama yolları:
  • openclaw pairing list matrix
  • openclaw pairing approve matrix <CODE>
• Herkese açık DM’ler: channels.matrix.dm.policy="open" artı channels.matrix.dm.allowFrom=["*"].
• channels.matrix.dm.allowFrom tam Matrix kullanıcı kimliklerini kabul eder (örnek: @user:server). Sihirbaz, dizin aramasında tek ve tam eşleşme bulunduğunda görünen adları kullanıcı kimliklerine çözer.
• Görünen adları veya yalın localpart’ları kullanmayın (örnek: "Alice" veya "alice"). Bunlar belirsizdir ve allowlist eşleştirmesinde yok sayılır. Tam @user:server kimliklerini kullanın.

​

Odalar (gruplar)

• Varsayılan: channels.matrix.groupPolicy = "allowlist" (bahis/mention ile kapılı). Ayarlanmadığında varsayılanı geçersiz kılmak için channels.defaults.groupPolicy kullanın.
• Odaları channels.matrix.groups ile izin listesine alın (oda kimlikleri veya takma adlar; dizin aramasında tek ve tam eşleşme bulunduğunda adlar kimliklere çözülür):

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

• requireMention: false o odada otomatik yanıtı etkinleştirir.
• groups."*" odalar genelinde mention kapılama için varsayılanları ayarlayabilir.
• groupAllowFrom odalarda botu tetikleyebilecek göndericileri kısıtlar (tam Matrix kullanıcı kimlikleri).
• Oda başına users izin listeleri, belirli bir oda içinde göndericileri daha da kısıtlayabilir (tam Matrix kullanıcı kimliklerini kullanın).
• Yapılandırma sihirbazı, oda izin listelerini ister (oda kimlikleri, takma adlar veya adlar) ve adları yalnızca tam ve benzersiz eşleşmede çözer.
• Başlangıçta OpenClaw, izin listelerindeki oda/kullanıcı adlarını kimliklere çözer ve eşlemeyi günlüğe yazar; çözülemeyen girdiler izin listesi eşleştirmesinde yok sayılır.
• Davetler varsayılan olarak otomatik kabul edilir; channels.matrix.autoJoin ve channels.matrix.autoJoinAllowlist ile kontrol edin.
• Hiç odaya izin vermek için channels.matrix.groupPolicy: "disabled" ayarlayın (veya boş bir izin listesi bırakın).
• Eski anahtar: channels.matrix.rooms (groups ile aynı yapı).

​

Thread’ler

• Yanıt thread’leri desteklenir.
• channels.matrix.threadReplies yanıtların thread içinde kalıp kalmayacağını kontrol eder:
  • off, inbound (varsayılan), always
• channels.matrix.replyToMode, thread içinde yanıtlanmadığında reply-to meta verisini kontrol eder:
  • off (varsayılan), first, all

​

Capabilities

​

Sorun Giderme

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw pairing list matrix

• Giriş yapıldı ancak oda mesajları yok sayılıyor: oda groupPolicy veya oda izin listesi tarafından engellenmiş.
• DM’ler yok sayılıyor: channels.matrix.dm.policy="pairing" durumundayken gönderici onay bekliyor.
• Şifreli odalar başarısız: kripto desteği veya şifreleme ayarları uyumsuz.

​

Yapılandırma başvurusu (Matrix)

• channels.matrix.enabled: kanal başlatmayı etkinleştir/devre dışı bırak.
• channels.matrix.homeserver: homeserver URL’si.
• channels.matrix.userId: Matrix kullanıcı kimliği (erişim belirteciyle isteğe bağlı).
• channels.matrix.accessToken: erişim belirteci.
• channels.matrix.password: giriş için parola (belirteç saklanır).
• channels.matrix.deviceName: cihaz görünen adı.
• channels.matrix.encryption: E2EE’yi etkinleştir (varsayılan: false).
• channels.matrix.initialSyncLimit: başlangıç senkronizasyon sınırı.
• channels.matrix.threadReplies: off | inbound | always (varsayılan: inbound).
• channels.matrix.textChunkLimit: giden metin parça boyutu (karakter).
• channels.matrix.chunkMode: length (varsayılan) veya uzunluk parçalamasından önce boş satırlarda (paragraf sınırları) bölmek için newline.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (varsayılan: eşleştirme).
• channels.matrix.dm.allowFrom: DM izin listesi (tam Matrix kullanıcı kimlikleri). open için "*" gerekir. Sihirbaz mümkün olduğunda adları kimliklere çözer.
• channels.matrix.groupPolicy: allowlist | open | disabled (varsayılan: izin listesi).
• channels.matrix.groupAllowFrom: grup mesajları için izinli göndericiler (tam Matrix kullanıcı kimlikleri).
• channels.matrix.allowlistOnly: DM’ler + odalar için izin listesi kurallarını zorla.
• channels.matrix.groups: grup izin listesi + oda başına ayar eşlemesi.
• channels.matrix.rooms: eski grup izin listesi/yapılandırması.
• channels.matrix.replyToMode: thread’ler/etiketler için reply-to modu.
• channels.matrix.mediaMaxMb: gelen/giden medya sınırı (MB).
• channels.matrix.autoJoin: davet işleme (always | allowlist | off, varsayılan: her zaman).
• channels.matrix.autoJoinAllowlist: otomatik katılım için izin verilen oda kimlikleri/takma adları.
• channels.matrix.accounts: hesap kimliğine göre anahtarlanmış çoklu hesap yapılandırması (her hesap üst düzey ayarları devralır).
• channels.matrix.actions: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).