Mattermost

狀態：可下載的外掛（機器人權杖 + WebSocket 事件）。支援頻道、私人頻道、群組私訊和私訊。Mattermost 是可自行託管的團隊訊息平台（mattermost.com）。

安裝

openclaw plugins install @openclaw/mattermost

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

詳細資訊：外掛

快速設定

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

openclaw channels add --channel mattermost --bot-token <token> --http-url https://chat.example.com

原生斜線命令

原生斜線命令須選擇加入。啟用後，OpenClaw 會在機器人所屬的每個團隊註冊 oc_* 斜線命令，並在閘道 HTTP 伺服器上接收回呼 POST。

{  channels: {    mattermost: {      commands: {        native: true,        nativeSkills: true,        callbackPath: "/api/channels/mattermost/command",        // 當 Mattermost 無法直接連線至閘道時使用（反向 Proxy／公開 URL）。        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",      },    },  },}

已註冊的命令：/oc_status、/oc_model、/oc_models、/oc_new、/oc_help、/oc_think、/oc_reasoning、/oc_verbose、/oc_queue。使用 nativeSkills: true 時，技能命令也會註冊為 /oc_<skill>。

環境變數（預設帳號）

若偏好使用環境變數，請在閘道主機上設定以下項目：

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

聊天模式

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

設定範例：

{  channels: {    mattermost: {      chatmode: "onchar",      oncharPrefixes: [">", "!"], // 預設值    },  },}

注意事項：

• onchar 仍會回應明確的 @提及。
• 仍支援 channels.mattermost.requireMention，但建議使用 chatmode。各頻道的 groups.<channelId>.requireMention 設定優先於兩者。
• 機器人在頻道討論串中傳送可見回覆後，該討論串中的後續訊息不必再次 @提及或加上 onchar 前綴便會獲得回應，讓多輪討論串對話得以持續。參與狀態會從機器人上次在該討論串回覆起保留 7 天，並在閘道重新啟動後持續保留。機器人僅觀察而未回覆的討論串不受影響；若要再次要求明確提及，請建立新的頂層訊息。
• 將 channels.mattermost.implicitMentions.threadParticipation: false 設為停止讓已參與討論串的後續訊息略過提及限制。帳號覆寫使用 channels.mattermost.accounts.<id>.implicitMentions。Mattermost 目前不會產生 replyToBot 或 quotedBot 事實，因此這些旗標在此處沒有作用。

討論串與工作階段

使用 channels.mattermost.replyToMode 控制頻道和群組回覆要留在主頻道，還是在觸發貼文下建立討論串。

• off（預設）：僅在傳入貼文本來就在討論串中時，才於討論串回覆。
• first：對於頂層頻道／群組貼文，在該貼文下建立討論串，並將對話路由至討論串範圍的工作階段。
• 目前在 Mattermost 中，all 和 batched 的行為與 first 相同，因為 Mattermost 一旦有討論串根貼文，後續區塊和媒體就會繼續留在同一討論串中。
• 即使設定了 replyToMode，私訊仍預設為 off。

使用 channels.mattermost.replyToModeByChatType 覆寫 direct、group 或 channel 聊天的模式。設定 direct，讓私訊選擇加入討論串：

• off（預設）：私訊不使用討論串，並留在單一持續更新的工作階段中。
• first、all 或 batched：每則頂層私訊都會建立 Mattermost 討論串，並由全新、獨立的工作階段支援。

{  channels: {    mattermost: {      replyToMode: "all",      replyToModeByChatType: {        direct: "first",      },    },  },}

注意事項：

• 討論串範圍的工作階段會使用觸發貼文 ID 作為討論串根。
• first 和 all 目前等同，因為 Mattermost 一旦有討論串根貼文，後續區塊和媒體就會繼續留在同一討論串中。
• 各聊天類型的覆寫優先於 replyToMode。若沒有 direct 覆寫，現有部署會維持平面、非討論串式的私訊。

存取控制（私訊）

• 預設值：channels.mattermost.dmPolicy = "pairing"（未知傳送者會收到配對碼）。其他值：allowlist、open、disabled。
• 核准方式：
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• 公開私訊：channels.mattermost.dmPolicy="open" 加上 channels.mattermost.allowFrom=["*"]（設定結構描述會強制要求萬用字元）。
• channels.mattermost.allowFrom 接受使用者 ID（建議）和 accessGroup:<name> 項目。請參閱存取群組。

頻道（群組）

• 預設值：channels.mattermost.groupPolicy = "allowlist"（須提及）。
• 使用 channels.mattermost.groupAllowFrom 將傳送者加入允許清單（建議使用使用者 ID）。
• channels.mattermost.groupAllowFrom 接受 accessGroup:<name> 項目。請參閱存取群組。
• 各頻道的提及覆寫位於 channels.mattermost.groups.<channelId>.requireMention 下，或使用 channels.mattermost.groups["*"].requireMention 設定預設值。
• @username 比對是可變動的，且僅在 channels.mattermost.dangerouslyAllowNameMatching: true 時啟用。
• 開放頻道：channels.mattermost.groupPolicy="open"（須提及）。
• 解析順序：channels.mattermost.groupPolicy，接著是 channels.defaults.groupPolicy，再來是 "allowlist"。
• 執行階段注意事項：若完全缺少 channels.mattermost 區段，執行階段會針對群組檢查採取封閉式失敗並使用 groupPolicy="allowlist"（即使已設定 channels.defaults.groupPolicy），同時記錄一次性警告。

範例：

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

對外傳遞目標

將下列目標格式搭配 openclaw message send 或排程／網路鉤子使用：

對外傳送每則訊息最多支援一個附件；請將多個檔案分成多次傳送。

私訊頻道重試

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

使用 channels.mattermost.dmChannelRetry 為 Mattermost 外掛全域調整此行為，或使用 channels.mattermost.accounts.<id>.dmChannelRetry 為單一帳號調整。預設值：

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

注意事項：

• 這僅適用於私訊頻道建立（/api/v4/channels/direct），而非每個 Mattermost API 呼叫。
• 重試會使用含隨機抖動的指數退避，並套用於速率限制、5xx 回應，以及網路或逾時錯誤等暫時性失敗。
• 除了 429 之外的 4xx 用戶端錯誤會被視為永久性錯誤，不會重試。

預覽串流

Mattermost 會將思考、工具活動和部分回覆文字串流至預覽草稿貼文，並在最終答案可安全傳送時就地完成該貼文。在 partial 模式下，預覽會更新相同的貼文 ID，而不會以每個區塊一則訊息的方式洗版頻道。在 block 模式下，預覽會在已完成文字與工具活動區塊之間輪替，因此較早的區塊會保留為各自的貼文，而不會被下一個區塊覆寫。媒體或錯誤的最終回覆會取消待處理的預覽編輯，並改用一般傳遞，而不會送出一次性的預覽貼文。

預覽串流在 partial 模式下預設開啟。透過 channels.mattermost.streaming.mode 設定（舊版純量／布林值 streaming 會由 openclaw doctor --fix 遷移）：

{  channels: {    mattermost: {      streaming: { mode: "partial" }, // 關閉 | 部分 | 區塊 | 進度    },  },}

表情回應（訊息工具）

• 搭配 channel=mattermost 使用 message action=react。
• messageId 是 Mattermost 貼文 ID。
• emoji 接受如 thumbsup 或 :+1: 的名稱（冒號可省略）。
• 將 remove=true（布林值）設為移除表情回應。
• 新增／移除表情回應事件會以系統事件轉送至已路由的代理程式工作階段，並套用與訊息相同的私訊／群組政策檢查。

範例：

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

設定：

• channels.mattermost.actions.reactions：啟用／停用表情回應動作（預設為 true）。
• 每個帳號的覆寫設定：channels.mattermost.accounts.<id>.actions.reactions。

互動式按鈕（訊息工具）

傳送含可點擊按鈕的訊息。當使用者點擊按鈕時，代理程式會收到選取結果並可回應。

按鈕來自語意化的 presentation 承載資料（用於一般代理程式回覆及 message action=send）。OpenClaw 會將值按鈕呈現為 Mattermost 互動式按鈕、讓 URL 按鈕顯示於訊息文字中，並將選取選單降級為可讀文字。

message action=send channel=mattermost target=channel:<channelId> presentation={"blocks":[{"type":"buttons","buttons":[{"label":"是","value":"yes"},{"label":"否","value":"no"}]}]}

呈現按鈕欄位：

若要在代理程式系統提示詞中宣告按鈕支援，請將 inlineButtons 新增至頻道功能：

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

當使用者點擊按鈕時：

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

外部指令碼和網路鉤子可以透過 Mattermost REST API 直接發布按鈕，而不必經由代理程式的 message 工具。建議優先使用 OpenClaw 的 message 工具。若為直接整合，請從 @openclaw/mattermost/api.js 匯入 buildButtonAttachments；若發布原始 JSON，請遵循以下規則：

承載資料結構：

{  channel_id: "<channelId>",  message: "選擇一個選項：",  props: {    attachments: [      {        actions: [          {            id: "mybutton01", // 僅限英數字元，請參閱下方            type: "button", // 必填，否則點擊會被無聲忽略            name: "核准", // 顯示標籤            style: "primary", // 選填："default"、"primary"、"danger"            integration: {              url: "https://gateway.example.com/mattermost/interactions/default",              context: {                action_id: "mybutton01", // 必須與按鈕 ID 相符                action: "approve",                // ...任何自訂欄位...                _token: "<hmac>", // 請參閱下方 HMAC 章節              },            },          },        ],      },    ],  },}

HMAC 權杖產生

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

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 外掛包含一個目錄配接器，可透過 Mattermost API 解析頻道與使用者名稱。這可讓 #channel-name 與 @username 目標用於 openclaw message send 及排程／網路鉤子遞送。

不需要任何設定——配接器會使用帳號設定中的機器人權杖。

多帳號

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

帳號值會覆寫頂層欄位；未指定帳號時，channels.mattermost.defaultAccount 會選擇要使用的帳號。

疑難排解

相關內容

• 頻道路由——訊息的工作階段路由
• 頻道概覽——所有支援的頻道
• 群組——群組聊天行為與提及限制
• 配對——私訊驗證與配對流程
• 安全性——存取模型與強化措施