​

Mattermost

​

Paketlenmiş eklenti

openclaw plugins install @openclaw/mattermost

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

​

Hızlı kurulum

1. Mattermost eklentisinin kullanılabilir olduğundan emin olun.
   • Güncel paketlenmiş OpenClaw sürümleri bunu zaten içerir.
   • Daha eski/özel kurulumlar bunu yukarıdaki komutlarla elle ekleyebilir.
2. Bir Mattermost bot hesabı oluşturun ve bot token değerini kopyalayın.
3. Mattermost temel URL’sini kopyalayın (örneğin https://chat.example.com).
4. OpenClaw’ı yapılandırın ve ağ geçidini başlatın.

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

​

Yerel slash komutları

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Mattermost ağ geçidine doğrudan ulaşamadığında kullanın (ters proxy/genel URL).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

• native: "auto" Mattermost için varsayılan olarak devre dışıdır. Etkinleştirmek için native: true ayarlayın.
• callbackUrl atlanırsa OpenClaw bunu ağ geçidi ana makinesi/portunun ve callbackPath değerinin birleşiminden türetir.
• Çoklu hesap kurulumlarında commands, üst düzeyde veya channels.mattermost.accounts.<id>.commands altında ayarlanabilir (hesap değerleri üst düzey alanları geçersiz kılar).
• Komut geri çağırımları, OpenClaw’ın oc_* komutlarını kaydederken Mattermost’un döndürdüğü komut başına token’larla doğrulanır.
• Slash geri çağırımları; kayıt başarısız olduysa, başlangıç kısmi kaldıysa veya geri çağırım token’ı kayıtlı komutlardan biriyle eşleşmiyorsa kapalı başarısız olur.
• Erişilebilirlik gereksinimi: geri çağırım uç noktasına Mattermost sunucusundan erişilebilmelidir.
  • Mattermost, OpenClaw ile aynı ana makinede/ağ ad alanında çalışmıyorsa callbackUrl için localhost ayarlamayın.
  • Bu URL, /api/channels/mattermost/command yolunu OpenClaw’a ters proxy ile yönlendirmiyorsa callbackUrl için Mattermost temel URL’nizi ayarlamayın.
  • Hızlı bir kontrol olarak curl https://<gateway-host>/api/channels/mattermost/command çalıştırabilirsiniz; bir GET isteği 404 değil, OpenClaw’dan 405 Method Not Allowed döndürmelidir.
• Mattermost çıkış allowlist gereksinimi:
  • Geri çağırımınız private/tailnet/internal adresleri hedefliyorsa, geri çağırım ana makinesini/alan adını içerecek şekilde Mattermost ServiceSettings.AllowedUntrustedInternalConnections ayarını yapın.
  • Tam URL değil, ana makine/alan adı girdileri kullanın.
    • İyi: gateway.tailnet-name.ts.net
    • Kötü: https://gateway.tailnet-name.ts.net

​

Ortam değişkenleri (varsayılan hesap)

• MATTERMOST_BOT_TOKEN=...
• MATTERMOST_URL=https://chat.example.com

​

Sohbet kipleri

• oncall (varsayılan): kanallarda yalnızca @mention yapıldığında yanıt verir.
• onmessage: her kanal mesajına yanıt verir.
• onchar: bir mesaj tetikleyici önekle başladığında yanıt verir.

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"],
    },
  },
}

• onchar, açık @mention’lara yine de yanıt verir.
• channels.mattermost.requireMention eski yapılandırmalarda dikkate alınır ancak chatmode tercih edilir.

​

Threading ve oturumlar

• off (varsayılan): yalnızca gelen gönderi zaten bir thread içindeyse bir thread içinde yanıt verir.
• first: üst düzey kanal/grup gönderileri için bu gönderinin altında bir thread başlatır ve konuşmayı thread kapsamlı bir oturuma yönlendirir.
• all: bugün Mattermost için first ile aynı davranışı gösterir.
• Doğrudan mesajlar bu ayarı yok sayar ve thread kullanılmadan kalır.

{
  channels: {
    mattermost: {
      replyToMode: "all",
    },
  },
}

• Thread kapsamlı oturumlar, tetikleyici gönderi kimliğini thread kökü olarak kullanır.
• first ve all şu anda eşdeğerdir çünkü Mattermost bir thread köküne sahip olduğunda devam parçaları ve medya aynı thread içinde sürer.

​

Erişim denetimi (DM’ler)

• Varsayılan: channels.mattermost.dmPolicy = "pairing" (bilinmeyen göndericiler bir eşleştirme kodu alır).
• Onaylama:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• Herkese açık DM’ler: channels.mattermost.dmPolicy="open" ve channels.mattermost.allowFrom=["*"].

​

Kanallar (gruplar)

• Varsayılan: channels.mattermost.groupPolicy = "allowlist" (mention geçitli).
• channels.mattermost.groupAllowFrom ile göndericileri allowlist’e ekleyin (kullanıcı kimlikleri önerilir).
• Kanal başına mention geçersiz kılmaları channels.mattermost.groups.<channelId>.requireMention altında veya varsayılan için channels.mattermost.groups["*"].requireMention altında bulunur.
• @username eşleştirmesi değişkendir ve yalnızca channels.mattermost.dangerouslyAllowNameMatching: true olduğunda etkindir.
• Açık kanallar: channels.mattermost.groupPolicy="open" (mention geçitli).
• Çalışma zamanı notu: channels.mattermost tamamen yoksa, çalışma zamanı grup kontrolleri için groupPolicy="allowlist" varsayımına döner (channels.defaults.groupPolicy ayarlı olsa bile).

{
  channels: {
    mattermost: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
    },
  },
}

​

Giden teslimat hedefleri

• Bir kanal için channel:<id>
• Bir DM için user:<id>
• Bir DM için @username (Mattermost API üzerinden çözülür)

• Kimlik bir kullanıcı olarak varsa (GET /api/v4/users/<id> başarılı olursa), OpenClaw /api/v4/channels/direct üzerinden doğrudan kanalı çözümleyerek bir DM gönderir.
• Aksi halde kimlik bir kanal kimliği olarak değerlendirilir.

​

DM kanal yeniden denemesi

{
  channels: {
    mattermost: {
      dmChannelRetry: {
        maxRetries: 3,
        initialDelayMs: 1000,
        maxDelayMs: 10000,
        timeoutMs: 30000,
      },
    },
  },
}

• Bu yalnızca DM kanal oluşturma işlemi (/api/v4/channels/direct) için geçerlidir, her Mattermost API çağrısı için değil.
• Yeniden denemeler; hız sınırları, 5xx yanıtları ve ağ veya zaman aşımı hataları gibi geçici hatalara uygulanır.
• 429 dışındaki 4xx istemci hataları kalıcı kabul edilir ve yeniden denenmez.

​

Tepkiler (mesaj aracı)

• channel=mattermost ile message action=react kullanın.
• messageId, Mattermost gönderi kimliğidir.
• emoji, thumbsup veya :+1: gibi adları kabul eder (iki nokta üst üste işaretleri isteğe bağlıdır).
• Bir tepkiyi kaldırmak için remove=true (boolean) ayarlayın.
• Tepki ekleme/kaldırma olayları, yönlendirilen aracı oturumuna sistem olayları olarak iletilir.

message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true

• channels.mattermost.actions.reactions: tepki eylemlerini etkinleştirir/devre dışı bırakır (varsayılan true).
• Hesap başına geçersiz kılma: channels.mattermost.accounts.<id>.actions.reactions.

​

Etkileşimli düğmeler (mesaj aracı)

{
  channels: {
    mattermost: {
      capabilities: ["inlineButtons"],
    },
  },
}

message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]

• text (gerekli): görüntülenecek etiket.
• callback_data (gerekli): tıklama sırasında geri gönderilen değer (eylem kimliği olarak kullanılır).
• style (isteğe bağlı): "default", "primary" veya "danger".

1. Tüm düğmeler bir onay satırıyla değiştirilir (örneğin, ”✓ Yes @user tarafından seçildi”).
2. Aracı seçimi gelen mesaj olarak alır ve yanıt verir.

• Düğme geri çağırımları HMAC-SHA256 doğrulaması kullanır (otomatik, yapılandırma gerekmez).
• Mattermost, API yanıtlarından callback verilerini çıkarır (güvenlik özelliği), bu nedenle tıklamada tüm düğmeler kaldırılır — kısmi kaldırma mümkün değildir.
• Tire veya alt çizgi içeren eylem kimlikleri otomatik olarak temizlenir (Mattermost yönlendirme sınırlaması).

• channels.mattermost.capabilities: yetenek dizgesi dizisi. Aracı sistem isteminde düğmeler aracı açıklamasını etkinleştirmek için "inlineButtons" ekleyin.
• channels.mattermost.interactions.callbackBaseUrl: düğme geri çağırımları için isteğe bağlı harici temel URL (örneğin https://gateway.example.com). Mattermost ağ geçidine doğrudan bağlandığı ana makineden erişemediğinde bunu kullanın.
• Çoklu hesap kurulumlarında aynı alanı channels.mattermost.accounts.<id>.interactions.callbackBaseUrl altında da ayarlayabilirsiniz.
• interactions.callbackBaseUrl atlanırsa OpenClaw geri çağırım URL’sini gateway.customBindHost + gateway.port değerlerinden türetir, ardından http://localhost:<port> değerine döner.
• Erişilebilirlik kuralı: düğme geri çağırım URL’sine Mattermost sunucusundan erişilebilmelidir. localhost yalnızca Mattermost ve OpenClaw aynı ana makinede/ağ ad alanında çalışıyorsa işe yarar.
• Geri çağırım hedefiniz private/tailnet/internal ise, onun ana makinesini/alan adını Mattermost ServiceSettings.AllowedUntrustedInternalConnections ayarına ekleyin.

​

Doğrudan API entegrasyonu (harici betikler)

{
  channel_id: "<channelId>",
  message: "Bir seçenek belirleyin:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // yalnızca alfanümerik — aşağıya bakın
            type: "button", // gerekli, aksi halde tıklamalar sessizce yok sayılır
            name: "Approve", // görüntülenecek etiket
            style: "primary", // isteğe bağlı: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // düğme kimliğiyle eşleşmelidir (ad araması için)
                action: "approve",
                // ... herhangi bir özel alan ...
                _token: "<hmac>", // aşağıdaki HMAC bölümüne bakın
              },
            },
          },
        ],
      },
    ],
  },
}

1. Attachment’lar üst düzey attachments içinde değil, props.attachments içinde olmalıdır (aksi halde sessizce yok sayılır).
2. Her eylem type: "button" içermelidir — bu olmadan tıklamalar sessizce yutulur.
3. Her eylem bir id alanına ihtiyaç duyar — Mattermost kimlik olmadan eylemleri yok sayar.
4. Eylem id değeri yalnızca alfanümerik olmalıdır ([a-zA-Z0-9]). Tire ve alt çizgi Mattermost’un sunucu tarafı eylem yönlendirmesini bozar (404 döndürür). Kullanmadan önce bunları çıkarın.
5. context.action_id, düğmenin id değeriyle eşleşmelidir; böylece onay mesajında ham kimlik yerine düğme adı görünür (örneğin “Approve”).
6. context.action_id gereklidir — etkileşim işleyicisi bu olmadan 400 döndürür.

1. Gizli anahtarı bot token’dan türetin: HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)
2. _token hariç tüm alanlarla bağlam nesnesini oluşturun.
3. Sıralanmış anahtarlar ve boşluksuz olacak şekilde serileştirin (ağ geçidi sıralanmış anahtarlarla JSON.stringify kullanır; bu da sıkıştırılmış çıktı üretir).
4. İmzalama: HMAC-SHA256(key=secret, data=serializedContext)
5. Ortaya çıkan hex özetini bağlam içine _token olarak ekleyin.

import hmac, hashlib, json

secret = hmac.new(
    b"openclaw-mattermost-interactions",
    bot_token.encode(), hashlib.sha256
).hexdigest()

ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

context = {**ctx, "_token": token}

• Python’un json.dumps işlevi varsayılan olarak boşluk ekler ({"key": "val"}). JavaScript’in sıkıştırılmış çıktısıyla ({"key":"val"}) eşleşmesi için separators=(",", ":") kullanın.
• Her zaman tüm bağlam alanlarını (_token hariç) imzalayın. Ağ geçidi _token alanını çıkarır, sonra kalan her şeyi imzalar. Bir alt kümenin imzalanması sessiz doğrulama hatasına yol açar.
• sort_keys=True kullanın — ağ geçidi imzalamadan önce anahtarları sıralar ve Mattermost payload’u saklarken bağlam alanlarının sırasını değiştirebilir.
• Gizli anahtarı rastgele baytlardan değil, bot token’dan türetin (belirlenimli). Gizli anahtar, düğmeleri oluşturan işlemle doğrulayan ağ geçidinde aynı olmalıdır.

​

Dizin bağdaştırıcısı

​

Çoklu hesap

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

​

Sorun giderme

• Kanallarda yanıt yok: botun kanalda olduğundan emin olun ve onu mention yapın (oncall), bir tetikleyici önek kullanın (onchar) veya chatmode: "onmessage" ayarlayın.
• Kimlik doğrulama hataları: bot token’ı, temel URL’yi ve hesabın etkin olup olmadığını kontrol edin.
• Çoklu hesap sorunları: ortam değişkenleri yalnızca default hesabı için geçerlidir.
• Yerel slash komutları Unauthorized: invalid command token. döndürüyor: OpenClaw geri çağırım token’ını kabul etmedi. Tipik nedenler:
  • slash komutu kaydı başarısız oldu veya başlangıçta yalnızca kısmen tamamlandı
  • geri çağırım yanlış ağ geçidine/hesaba gidiyor
  • Mattermost hâlâ önceki bir geri çağırım hedefine işaret eden eski komutlara sahip
  • ağ geçidi, slash komutlarını yeniden etkinleştirmeden yeniden başlatıldı
• Yerel slash komutları çalışmayı bırakırsa şu günlük girdilerini kontrol edin: mattermost: failed to register slash commands veya mattermost: native slash commands enabled but no commands could be registered.
• callbackUrl atlanırsa ve günlüklerde geri çağırımın http://127.0.0.1:18789/... olarak çözümlendiğine dair uyarı varsa, bu URL muhtemelen yalnızca Mattermost, OpenClaw ile aynı ana makinede/ağ ad alanında çalıştığında erişilebilirdir. Bunun yerine açıkça dışarıdan erişilebilir bir commands.callbackUrl ayarlayın.
• Düğmeler beyaz kutular olarak görünüyor: aracı bozuk düğme verileri gönderiyor olabilir. Her düğmede hem text hem de callback_data alanlarının bulunduğunu kontrol edin.
• Düğmeler görüntüleniyor ama tıklamalar hiçbir şey yapmıyor: Mattermost sunucu yapılandırmasında AllowedUntrustedInternalConnections değerinin 127.0.0.1 localhost içerdiğini ve ServiceSettings içinde EnablePostActionIntegration değerinin true olduğunu doğrulayın.
• Düğmeler tıklamada 404 döndürüyor: düğme id değeri muhtemelen tire veya alt çizgi içeriyor. Mattermost’un eylem yönlendiricisi alfanümerik olmayan kimliklerde bozulur. Yalnızca [a-zA-Z0-9] kullanın.
• Ağ geçidi günlüklerinde invalid _token: HMAC uyuşmazlığı. Tüm bağlam alanlarını (bir alt küme değil) imzaladığınızı, sıralanmış anahtarlar kullandığınızı ve sıkıştırılmış JSON (boşluksuz) kullandığınızı kontrol edin. Yukarıdaki HMAC bölümüne bakın.
• Ağ geçidi günlüklerinde missing _token in context: _token alanı düğmenin bağlamında yok. Entegrasyon payload’unu oluştururken bunun dahil edildiğinden emin olun.
• Onayda düğme adı yerine ham kimlik görünüyor: context.action_id, düğmenin id değeriyle eşleşmiyor. Her ikisini de aynı temizlenmiş değere ayarlayın.
• Aracı düğmelerden haberdar değil: Mattermost kanal yapılandırmasına capabilities: ["inlineButtons"] ekleyin.

​

İlgili

• Kanallara Genel Bakış — desteklenen tüm kanallar
• Eşleştirme — DM kimlik doğrulaması ve eşleştirme akışı
• Gruplar — grup sohbeti davranışı ve mention geçitleme
• Kanal Yönlendirme — mesajlar için oturum yönlendirme
• Güvenlik — erişim modeli ve sertleştirme