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 無法直接連上閘道時使用（反向代理／公開 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 後，Skill 命令也會註冊為 /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：對於頂層頻道／群組貼文，在該貼文下方建立討論串，並將對話路由至討論串範圍的工作階段。
• all 和 batched：目前在 Mattermost 中的行為與 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" }, // off | partial | block | progress    },  },}

表情回應（訊息工具）

• 搭配 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":"Yes","value":"yes"},{"label":"No","value":"no"}]}]}

呈現按鈕欄位：

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

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

當使用者點擊按鈕時：

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

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

承載資料結構：

{  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                action: "approve",                // ... any custom fields ...                _token: "<hmac>", // see HMAC section below              },            },          },        ],      },    ],  },}

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 解析頻道與使用者名稱。這讓 openclaw message send 與排程／網路鉤子傳送能使用 #channel-name 和 @username 目標。

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

多帳號

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 會選擇要使用的帳號。

疑難排解

相關內容

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