Mattermost

狀態：可下載的 Plugin（機器人權杖 + WebSocket 事件）。支援頻道、群組和私訊。Mattermost 是可自行託管的團隊訊息平台；產品詳細資訊與下載請參閱官方網站 mattermost.com。

# 安裝

設定頻道前，請先安裝 Mattermost：

openclaw plugins install @openclaw/mattermost

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

詳細資訊：Plugin

# 快速設定

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

# 原生斜線命令

原生斜線命令採用選用啟用。啟用時，OpenClaw 會透過 Mattermost API 註冊 oc_* 斜線命令，並在 Gateway HTTP 伺服器上接收回呼 POST。

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

# 環境變數（預設帳號）

如果你偏好使用環境變數，請在 Gateway 主機上設定這些項目：

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

# 聊天模式

Mattermost 會自動回應私訊。頻道行為由 chatmode 控制：

設定範例：

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

注意事項：

• onchar 仍會回應明確的 @提及。
• 舊版設定會遵循 channels.mattermost.requireMention，但建議使用 chatmode。

# 執行緒與工作階段

使用 channels.mattermost.replyToMode 控制頻道和群組回覆要留在主要頻道，還是在觸發貼文下方開啟執行緒。

• off（預設）：只有在傳入貼文本來已在執行緒中時，才於執行緒中回覆。
• first：對於頂層頻道/群組貼文，在該貼文下方開啟執行緒，並將對話路由到執行緒範圍的工作階段。
• all：目前對 Mattermost 而言，行為與 first 相同。
• 私訊會忽略此設定，並維持非執行緒形式。

設定範例：

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

注意事項：

• 執行緒範圍的工作階段會使用觸發貼文 ID 作為執行緒根。
• first 和 all 目前等效，因為一旦 Mattermost 有執行緒根，後續區塊和媒體會繼續留在同一個執行緒中。

# 存取控制（DM）

• 預設：channels.mattermost.dmPolicy = "pairing"（未知寄件者會取得配對碼）。
• 透過以下方式核准：
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• 公開 DM：channels.mattermost.dmPolicy="open" 加上 channels.mattermost.allowFrom=["*"]。

# 頻道（群組）

• 預設：channels.mattermost.groupPolicy = "allowlist"（以提及作為門檻）。
• 使用 channels.mattermost.groupAllowFrom 將寄件者加入允許清單（建議使用使用者 ID）。
• 每個頻道的提及覆寫位於 channels.mattermost.groups.<channelId>.requireMention 下，或使用 channels.mattermost.groups["*"].requireMention 作為預設值。
• @username 比對是可變的，且只有在 channels.mattermost.dangerouslyAllowNameMatching: true 時才會啟用。
• 開放頻道：channels.mattermost.groupPolicy="open"（以提及作為門檻）。
• 執行階段注意事項：如果 channels.mattermost 完全缺失，執行階段會在群組檢查時退回使用 groupPolicy="allowlist"（即使已設定 channels.defaults.groupPolicy）。

範例：

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

# 外送傳遞目標

搭配 openclaw message send 或 Cron/Webhook 使用這些目標格式：

• channel:<id> 代表頻道
• user:<id> 代表 DM
• @username 代表 DM（透過 Mattermost API 解析）

# DM 頻道重試

當 OpenClaw 傳送至 Mattermost DM 目標，且需要先解析直接頻道時，預設會重試暫時性的直接頻道建立失敗。

使用 channels.mattermost.dmChannelRetry 可全域調整 Mattermost Plugin 的該行為，或使用 channels.mattermost.accounts.<id>.dmChannelRetry 針對單一帳戶調整。

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

注意事項：

• 這只套用於 DM 頻道建立（/api/v4/channels/direct），不是每個 Mattermost API 呼叫。
• 重試會套用於暫時性失敗，例如速率限制、5xx 回應，以及網路或逾時錯誤。
• 除 429 以外的 4xx 用戶端錯誤會被視為永久錯誤，不會重試。

# 預覽串流

Mattermost 會將思考、工具活動和部分回覆文字串流到單一草稿預覽貼文中，並在最終答案可安全傳送時就地完成。預覽會在同一個貼文 ID 上更新，而不是用逐區塊訊息洗版頻道。媒體/錯誤的最終訊息會取消待處理的預覽編輯，並使用一般傳遞，而不是送出一次性的預覽貼文。

透過 channels.mattermost.streaming 啟用：

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

# 回應（message 工具）

• 使用 message action=react 搭配 channel=mattermost。
• messageId 是 Mattermost 貼文 ID。
• emoji 接受像 thumbsup 或 :+1: 這類名稱（冒號可有可無）。
• 設定 remove=true（布林值）可移除回應。
• 新增/移除回應事件會作為系統事件轉送到路由的代理程式工作階段。

範例：

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：啟用/停用回應動作（預設為 true）。
• 每個帳戶覆寫：channels.mattermost.accounts.<id>.actions.reactions。

# 互動式按鈕（message 工具）

傳送帶有可點擊按鈕的訊息。使用者點擊按鈕時，代理程式會收到選取項目並可以回應。

透過將 inlineButtons 新增至頻道功能來啟用按鈕：

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

使用 message action=send 並帶上 buttons 參數。按鈕是 2D 陣列（按鈕列）：

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

按鈕欄位：

當使用者點擊按鈕時：

# 直接 API 整合（外部指令碼）

外部指令碼和 Webhook 可以透過 Mattermost REST API 直接發布按鈕，而不必經由 Agent 的 message 工具。可行時請使用 Plugin 的 buildButtonAttachments()；如果要發布原始 JSON，請遵循以下規則：

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
              },
            },
          },
        ],
      },
    ],
  },
}

HMAC 權杖產生

Gateway 使用 HMAC-SHA256 驗證按鈕點擊。外部指令碼必須產生符合 Gateway 驗證邏輯的權杖：

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}

# 目錄轉接器

Mattermost Plugin 包含一個目錄轉接器，可透過 Mattermost API 解析頻道和使用者名稱。這會在 openclaw message send 和 Cron/Webhook 投遞中啟用 #channel-name 與 @username 目標。

不需要設定，轉接器會使用帳號設定中的 Bot 權杖。

# 多帳號

Mattermost 支援在 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" },
      },
    },
  },
}

# 疑難排解

# 相關內容

• 頻道路由 - 訊息的工作階段路由
• 頻道總覽 - 所有支援的頻道
• 群組 - 群組聊天行為與提及閘控
• 配對 - DM 驗證與配對流程
• 安全性 - 存取模型與強化