Mattermost

Status: Plugin yang dapat diunduh (token bot + peristiwa WebSocket). Saluran, grup, dan DM didukung. Mattermost adalah platform pesan tim yang dapat di-host sendiri; lihat situs resmi di mattermost.com untuk detail produk dan unduhan.

# Instalasi

Instal Mattermost sebelum mengonfigurasi saluran:

openclaw plugins install @openclaw/mattermost

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

Detail: Plugin

# Pengaturan cepat

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

# Perintah slash native

Perintah slash native bersifat opt-in. Saat diaktifkan, OpenClaw mendaftarkan perintah slash oc_* melalui API Mattermost dan menerima POST callback di server HTTP Gateway.

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Use when Mattermost cannot reach the gateway directly (reverse proxy/public URL).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

# Variabel lingkungan (akun default)

Atur ini di host Gateway jika Anda lebih suka env vars:

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

# Mode chat

Mattermost merespons DM secara otomatis. Perilaku saluran dikontrol oleh chatmode:

Contoh konfigurasi:

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

Catatan:

• onchar tetap merespons @mention eksplisit.
• channels.mattermost.requireMention tetap dihormati untuk konfigurasi lama, tetapi chatmode lebih disarankan.

# Threading dan sesi

Gunakan channels.mattermost.replyToMode untuk mengontrol apakah balasan saluran dan grup tetap berada di saluran utama atau memulai thread di bawah posting pemicu.

• off (default): hanya membalas di thread saat posting masuk sudah berada di dalam thread.
• first: untuk posting saluran/grup tingkat atas, mulai thread di bawah posting tersebut dan arahkan percakapan ke sesi dengan cakupan thread.
• all: perilaku yang sama seperti first untuk Mattermost saat ini.
• Pesan langsung mengabaikan pengaturan ini dan tetap tidak ber-thread.

Contoh konfigurasi:

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

Catatan:

• Sesi dengan cakupan thread menggunakan id posting pemicu sebagai root thread.
• first dan all saat ini setara karena setelah Mattermost memiliki root thread, potongan lanjutan dan media berlanjut di thread yang sama.

# Kontrol akses (DM)

• Default: channels.mattermost.dmPolicy = "pairing" (pengirim tidak dikenal mendapatkan kode pairing).
• Setujui melalui:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• DM publik: channels.mattermost.dmPolicy="open" ditambah channels.mattermost.allowFrom=["*"].

# Saluran (grup)

• Default: channels.mattermost.groupPolicy = "allowlist" (dibatasi mention).
• Izinkan pengirim dengan channels.mattermost.groupAllowFrom (ID pengguna disarankan).
• Override mention per saluran berada di bawah channels.mattermost.groups.<channelId>.requireMention atau channels.mattermost.groups["*"].requireMention untuk default.
• Pencocokan @username dapat berubah dan hanya diaktifkan saat channels.mattermost.dangerouslyAllowNameMatching: true.
• Saluran terbuka: channels.mattermost.groupPolicy="open" (dibatasi mention).
• Catatan runtime: jika channels.mattermost sepenuhnya tidak ada, runtime kembali ke groupPolicy="allowlist" untuk pemeriksaan grup (meskipun channels.defaults.groupPolicy diatur).

Contoh:

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

# Target untuk pengiriman keluar

Gunakan format target ini dengan openclaw message send atau cron/webhook:

• channel:<id> untuk saluran
• user:<id> untuk DM
• @username untuk DM (diselesaikan melalui API Mattermost)

# Percobaan ulang saluran DM

Saat OpenClaw mengirim ke target DM Mattermost dan perlu menyelesaikan saluran langsung terlebih dahulu, secara default OpenClaw mencoba ulang kegagalan pembuatan saluran langsung yang bersifat sementara.

Gunakan channels.mattermost.dmChannelRetry untuk menyesuaikan perilaku tersebut secara global untuk Plugin Mattermost, atau channels.mattermost.accounts.<id>.dmChannelRetry untuk satu akun.

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

Catatan:

• Ini hanya berlaku untuk pembuatan saluran DM (/api/v4/channels/direct), bukan setiap panggilan API Mattermost.
• Percobaan ulang berlaku untuk kegagalan sementara seperti pembatasan laju, respons 5xx, serta kesalahan jaringan atau timeout.
• Kesalahan klien 4xx selain 429 diperlakukan sebagai permanen dan tidak dicoba ulang.

# Streaming pratinjau

Mattermost mengalirkan pemikiran, aktivitas alat, dan teks balasan parsial ke dalam satu posting pratinjau draf yang diselesaikan di tempat saat jawaban akhir aman untuk dikirim. Pratinjau diperbarui pada id posting yang sama, bukan membanjiri saluran dengan pesan per potongan. Final media/kesalahan membatalkan edit pratinjau tertunda dan menggunakan pengiriman normal alih-alih mengirim posting pratinjau sementara.

Aktifkan melalui channels.mattermost.streaming:

{
  channels: {
    mattermost: {
      streaming: "partial", // off | partial | block | progress
    },
  },
}

# Reaksi (alat pesan)

• Gunakan message action=react dengan channel=mattermost.
• messageId adalah id posting Mattermost.
• emoji menerima nama seperti thumbsup atau :+1: (titik dua opsional).
• Atur remove=true (boolean) untuk menghapus reaksi.
• Peristiwa tambah/hapus reaksi diteruskan sebagai peristiwa sistem ke sesi agen yang dirutekan.

Contoh:

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

Konfigurasi:

• channels.mattermost.actions.reactions: aktifkan/nonaktifkan tindakan reaksi (default true).
• Override per akun: channels.mattermost.accounts.<id>.actions.reactions.

# Tombol interaktif (alat pesan)

Kirim pesan dengan tombol yang dapat diklik. Saat pengguna mengklik tombol, agen menerima pilihan dan dapat merespons.

Aktifkan tombol dengan menambahkan inlineButtons ke kapabilitas saluran:

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

Gunakan message action=send dengan parameter buttons. Tombol adalah array 2D (baris tombol):

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

Bidang tombol:

Saat pengguna mengklik tombol:

# Integrasi API langsung (skrip eksternal)

Skrip eksternal dan Webhook dapat memposting tombol langsung melalui REST API Mattermost alih-alih melalui alat message milik agen. Gunakan buildButtonAttachments() dari Plugin jika memungkinkan; jika memposting JSON mentah, ikuti aturan ini:

Struktur payload:

{
  channel_id: "<channelId>",
  message: "Choose an option:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // alphanumeric only - see below
            type: "button", // required, or clicks are silently ignored
            name: "Approve", // display label
            style: "primary", // optional: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // must match button id (for name lookup)
                action: "approve",
                // ... any custom fields ...
                _token: "<hmac>", // see HMAC section below
              },
            },
          },
        ],
      },
    ],
  },
}

Pembuatan token HMAC

Gateway memverifikasi klik tombol dengan HMAC-SHA256. Skrip eksternal harus membuat token yang cocok dengan logika verifikasi Gateway:

Contoh Python:

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}

# Adapter direktori

Plugin Mattermost menyertakan adapter direktori yang menyelesaikan nama kanal dan pengguna melalui API Mattermost. Ini mengaktifkan target #channel-name dan @username dalam pengiriman openclaw message send serta cron/webhook.

Tidak diperlukan konfigurasi - adapter menggunakan token bot dari konfigurasi akun.

# Multi-akun

Mattermost mendukung beberapa akun di bawah channels.mattermost.accounts:

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

# Pemecahan masalah

# Terkait

• Perutean Kanal - perutean sesi untuk pesan
• Ringkasan Kanal - semua kanal yang didukung
• Grup - perilaku chat grup dan gating penyebutan
• Pairing - autentikasi DM dan alur pairing
• Keamanan - model akses dan hardening