將 OpenClaw 連接到 Mattermost：5 分鐘完成設定指南

需要安裝 Plugin

Mattermost 是以 Plugin 形式提供的，並沒有包含在核心安裝包裡。

透過 CLI 安裝（npm registry）：

openclaw plugins install @openclaw/mattermost

本地檢出（如果你是從 git repo 執行）：

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

如果你在設定過程中選擇 Mattermost 且系統偵測到 git 檢出，OpenClaw 會自動提供本地安裝路徑。

詳細資訊：Plugins

快速設定

安裝 Mattermost plugin。
建立一個 Mattermost 機器人帳號並複製 bot token。
複製 Mattermost 的 base URL（例如：https://chat.example.com）。
設定 OpenClaw 並啟動 Gateway。

最簡設定：

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

原生 Slash 指令

原生 Slash 指令是選用的。啟用後，OpenClaw 會透過 Mattermost API 註冊 oc_* 指令，並在 Gateway 的 HTTP 伺服器接收 callback 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",
      },
    },
  },
}

注意事項：

對於 Mattermost，native: "auto" 預設為停用。請設定 native: true 來啟用。
如果省略 callbackUrl，OpenClaw 會根據 Gateway 的 host/port + callbackPath 自動推導一個。
在多帳號設定中，commands 可以設定在頂層或 channels.mattermost.accounts.<id>.commands 下（帳號設定會覆蓋頂層欄位）。
指令 callback 會透過各別指令的 token 進行驗證，若驗證失敗則會拒絕請求。
連通性要求：Mattermost 伺服器必須能夠連線到 callback 端點。
- 除非 Mattermost 與 OpenClaw 運行在同一個主機或網路命名空間，否則不要將 callbackUrl 設為 localhost。
- 除非你的 Mattermost base URL 會將 /api/channels/mattermost/command 反向代理到 OpenClaw，否則不要將 callbackUrl 設為該 URL。
- 你可以快速檢查：執行 curl https://<gateway-host>/api/channels/mattermost/command；GET 請求應該從 OpenClaw 收到 405 Method Not Allowed，而不是 404。
Mattermost 出站白名單要求：
- 如果你的 callback 目標是私有/tailnet/內部位址，請設定 Mattermost 的 ServiceSettings.AllowedUntrustedInternalConnections 以包含該 callback 的 host/domain。
- 請使用 host/domain 條目，而非完整 URL。
  - 正確：gateway.tailnet-name.ts.net
  - 錯誤：https://gateway.tailnet-name.ts.net

環境變數（預設帳號）

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

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

環境變數僅適用於預設帳號 (default)。其他帳號必須使用設定檔中的數值。

聊天模式

Mattermost 會自動回覆私訊 (DM)。頻道的行為是由 chatmode 控制的：

oncall (預設)：只有在頻道中被 @mention 時才會回覆。
onmessage：回覆頻道中的每一則訊息。
onchar：當訊息以特定前綴開頭時回覆。

設定範例：

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

注意：

onchar 仍然會回應明確的 @mention。
為了相容舊版設定，系統仍會參考 channels.mattermost.requireMention，但建議優先使用 chatmode。

討論串與 Session

使用 channels.mattermost.replyToMode 來控制頻道和群組的回覆是要留在主頻道，還是要在觸發貼文下開啟一個討論串 (thread)。

off (預設)：只有當傳入的貼文已經在討論串中時，才在討論串中回覆。
first：對於頂層的頻道/群組貼文，在該貼文下開啟討論串，並將對話引導至討論串範圍的 Session。
all：目前在 Mattermost 中的行為與 first 相同。
私訊 (Direct messages) 會忽略此設定，且不會使用討論串。

設定範例：

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

注意：

討論串範圍的 Session 使用觸發貼文的 ID 作為討論串根節點。
first 和 all 目前是等效的，因為一旦 Mattermost 有了討論串根節點，後續的內容和媒體都會在同一個討論串中繼續。

存取控制 (DMs)

預設值：channels.mattermost.dmPolicy = "pairing"（未知的傳送者會收到配對碼）。
審核方式：
- openclaw pairing list mattermost
- openclaw pairing approve mattermost <CODE>
公開私訊：channels.mattermost.dmPolicy="open" 加上 channels.mattermost.allowFrom=["*"]。

頻道 (群組)

預設值：channels.mattermost.groupPolicy = "allowlist"（受 mention 限制）。
使用 channels.mattermost.groupAllowFrom 來設定允許名單（建議使用使用者 ID）。
@username 匹配是可變的，只有在 channels.mattermost.dangerouslyAllowNameMatching: true 時才會啟用。
公開頻道：channels.mattermost.groupPolicy="open"（受 mention 限制）。
運行時說明：如果完全缺少 channels.mattermost 設定，系統在進行群組檢查時會回退到 groupPolicy="allowlist"（即使設定了 channels.defaults.groupPolicy 也是如此）。

外部傳送的目標

你可以透過 openclaw message send、cron 或 webhooks 使用以下目標格式：

channel:<id> 用於頻道
user:<id> 用於私訊 (DM)
@username 用於私訊 (DM)（透過 Mattermost API 解析）

單純的 ID（例如 64ifufp...）在 Mattermost 中是模糊的（可能是使用者 ID 或頻道 ID）。

OpenClaw 會以使用者優先的方式解析它們：

如果該 ID 對應到某個使用者（GET /api/v4/users/<id> 成功），OpenClaw 會透過 /api/v4/channels/direct 解析出直接頻道並傳送私訊 (DM)。
否則，該 ID 會被視為頻道 ID。

如果你需要確定的行為，建議一律使用明確的前綴（user:<id> / channel:<id>）。

DM 頻道重試機制

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

你可以使用 channels.mattermost.dmChannelRetry 來調整 Mattermost plugin 的全域行為，或是針對單一帳號使用 channels.mattermost.accounts.<id>.dmChannelRetry。

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

注意事項：

這僅適用於私訊頻道建立 (/api/v4/channels/direct)，而非所有的 Mattermost API 呼叫。
重試適用於暫時性失敗，例如速率限制 (rate limits)、5xx 回應，以及網路或逾時錯誤。
除了 429 以外的 4xx 用戶端錯誤會被視為永久性錯誤，不會進行重試。

Reactions (訊息工具)

使用 message action=react 搭配 channel=mattermost。
messageId 是 Mattermost 的貼文 ID。
emoji 接受像 thumbsup 或 :+1: 這樣的名稱（冒號是選填的）。
設定 remove=true (boolean) 來移除表情回應。
表情回應的增加或移除事件會作為系統事件，轉發到路由後的 agent session。

範例：

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。

互動式按鈕 (訊息工具)

傳送帶有可點擊按鈕的訊息。當使用者點擊按鈕時，agent 會收到選擇並進行回應。

在 channel capabilities 中加入 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"}]]

按鈕欄位：

text (必填) 與 callback_data (必填)：分別為顯示標籤，以及點擊時傳回的值（作為 action ID 使用）。
style (選填)：可選 "default"、"primary" 或 "danger"。

當使用者點擊按鈕時：

所有按鈕都會被替換為確認文字（例如：「✓ Yes selected by @user」）。
agent 會收到該選擇作為傳入訊息並進行回應。

注意：

按鈕回呼 (callback) 使用 HMAC-SHA256 驗證（自動完成，不需要額外設定）。
Mattermost 會從其 API 回應中移除 callback 資料（這是一項安全性設計），因此所有按鈕在點擊後都會被移除 —— 無法僅移除部分按鈕。
包含連字號或底線的 Action ID 會自動進行清理（這是為了繞過 Mattermost 的路由限制）。

設定：

channels.mattermost.capabilities：capability 字串陣列。加入 "inlineButtons" 可以在 agent 的系統提示詞中啟用按鈕工具說明。
channels.mattermost.interactions.callbackBaseUrl：選填的外部按鈕回呼基礎 URL（例如 https://gateway.example.com）。當 Mattermost 無法直接透過 bind host 連接到 Gateway 時，請使用此設定。
在多帳號設定中，你也可以在 channels.mattermost.accounts.<id>.interactions.callbackBaseUrl 下設定相同欄位。
如果省略 interactions.callbackBaseUrl，OpenClaw 會從 gateway.customBindHost + gateway.port 推導出回呼 URL，最後則退而求其次使用 http://localhost:<port>。
連通性規則：Mattermost 伺服器必須能夠連線到按鈕回呼 URL。只有當 Mattermost 和 OpenClaw 執行在同一個主機或網路命名空間時，localhost 才會生效。
如果你的回呼目標是私有網路、tailnet 或內部網路，請將其主機/網域加入 Mattermost 的 ServiceSettings.AllowedUntrustedInternalConnections。

直接 API 整合 (外部腳本)

外部腳本和 webhook 可以直接透過 Mattermost REST API 發佈按鈕，而不必經過 agent 的 message 工具。盡可能使用 extension 提供的 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
              },
            },
          },
        ],
      },
    ],
  },
}

關鍵規則：

Attachments 必須放在 props.attachments，而不是頂層的 attachments（否則會被靜默忽略）。
每個 action 都需要 type: "button" —— 少了它，點擊動作會被靜默吞掉。
每個 action 都需要 id 欄位 —— Mattermost 會忽略沒有 ID 的 action。
Action id 必須僅限英數字 ([a-zA-Z0-9])。連字號和底線會破壞 Mattermost 的伺服器端 action 路由（導致回傳 404）。請在使用前將其移除。
context.action_id 必須與按鈕的 id 一致，這樣確認訊息才會顯示按鈕名稱（例如 “Approve”）而不是原始 ID。
context.action_id 是必填項 —— 如果少了它，互動處理器會回傳 400。

HMAC token 產生方式：

Gateway 會使用 HMAC-SHA256 驗證按鈕點擊。外部腳本產生的 token 必須符合 Gateway 的驗證邏輯：

從 bot token 衍生 secret：HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)
建立包含所有欄位的 context 物件，但排除 _token。
使用排序過的 key 且不含空格進行序列化（Gateway 使用 JSON.stringify 並排序 key，會產生緊湊的輸出）。
簽署：HMAC-SHA256(key=secret, data=serializedContext)
將產生的十六進位摘要作為 _token 加入 context 中。

Python 範例：

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}

常見的 HMAC 陷阱：

Python 的 json.dumps 預設會加入空格 ({"key": "val"})。請務必使用 separators=(",", ":") 來匹配 JavaScript 的緊湊輸出 ({"key":"val"})。
務必簽署所有 context 欄位（不含 _token）。Gateway 會移除 _token 後簽署剩餘的所有內容。只簽署部分欄位會導致驗證失敗。
使用 sort_keys=True —— Gateway 在簽署前會先排序 key，而且 Mattermost 在儲存 payload 時可能會重新排列 context 欄位。
從 bot token 衍生 secret（這是固定結果），不要使用隨機位元組。建立按鈕的程序與驗證的 Gateway 之間，使用的 secret 必須一致。

Directory 適配器

Mattermost plugin 內建了一個 Directory 適配器，它會透過 Mattermost API 來幫你解析頻道和使用者名稱。有了它，你在使用 openclaw message send 或者設定 cron/webhook 派送時，就可以直接用 #channel-name 和 @username 當作發送目標，非常方便。

這部分完全不需要額外設定，適配器會直接抓取你帳號設定裡的 bot token 來使用。

多帳號支援

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

疑難排解

頻道內沒有回應：確保 bot 已加入該頻道，並標記它 (oncall)、使用觸發前綴 (onchar)，或將 chatmode 設定為 "onmessage"。
認證錯誤：檢查你的 bot token、base URL，以及該帳號是否已啟用。
多帳號問題：環境變數僅適用於 default 帳號。
按鈕顯示為白框：Agent 可能傳送了格式錯誤的按鈕資料。檢查每個按鈕是否都包含 text 和 callback_data 欄位。
按鈕有渲染但點擊沒反應：確認 Mattermost 伺服器設定中的 AllowedUntrustedInternalConnections 包含 127.0.0.1 localhost，且 ServiceSettings 中的 EnablePostActionIntegration 為 true。
點擊按鈕回傳 404：按鈕 id 可能包含連字號 (-) 或底線 (_)。Mattermost 的 action router 在處理非字母數字的 ID 時會出錯。請只使用 [a-zA-Z0-9]。
Gateway 記錄 invalid _token：HMAC 不匹配。檢查你是否簽署了所有 context 欄位（而非其中一部分）、使用排序後的 key，並使用緊湊的 JSON 格式（不含空格）。請參考上方的 HMAC 章節。
Gateway 記錄 missing _token in context：_token 欄位不在按鈕的 context 中。確保在建立整合 payload 時已包含此欄位。
確認視窗顯示原始 ID 而非按鈕名稱：context.action_id 與按鈕的 id 不符。請將兩者設定為相同的過濾後數值。
Agent 不知道按鈕功能：在 Mattermost 頻道設定中加入 capabilities: ["inlineButtons"]。

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。