MINARA使用 Minara客戶端與界面消息平臺
Mattermost
自託管 Mattermost，出站使用 bot-token，入站僅通過 outgoing webhook 支持公開頻道。
🟡 出站已就緒，入站僅通過 outgoing webhook 支持公開頻道。 接入成本最低。Mattermost 的 WebSocket bot 模式（支持私信和私有頻道）將在後續版本中支持。
功能概覽
- 出站文本：通過
POST /api/v4/posts配合 bot 個人訪問 token 發送；支持通過root_id實現線程回覆。 - 入站 outgoing webhook：監聽路徑為
/webhooks/mattermost。當公開頻道中出現已配置的觸發詞時，Mattermost 會向該 URL 發起 POST 請求。 - 本版本僅支持文本。 通過 Mattermost Files API 上傳文件及解析附件的功能暫未實現。
- 文本上限 16383 字符（Mattermost 默認
PostMessageMaxRunes）。
配置步驟
1. 創建 bot 賬號
- 以系統管理員身份登錄 Mattermost
- 進入 System Console → "Integrations" → "Bot Accounts"，點擊 "Add Bot Account"
- 填寫用戶名（如
minara）、顯示名稱及可選頭像。保存後，Mattermost 會顯示 Bot Personal Access Token，請立即保存（之後無法再次查看） - 在目標頻道的輸入框執行
/invite @minara，將 bot 加入該頻道
2. 配置 outgoing webhook（可選，用於入站）
- 同一頁面，進入 "Integrations" → "Outgoing Webhooks"，點擊 "Add Outgoing Webhook"
- 配置如下：
- Channel：webhook 監聽的公開頻道
- Trigger words：如
@bot、!minara（Mattermost 僅在消息以觸發詞開頭時觸發 webhook） - Callback URLs：
https://<your-host>/webhooks/mattermost
- 保存後複製生成的 Token（即
MATTERMOST_OUTGOING_WEBHOOK_TOKEN）
3. 配置 Minara
minara auth messaging add
# 从列表中选择 `mattermost`。或直接設置環境變量：
MATTERMOST_URL=https://mattermost.example.com
MATTERMOST_BOT_TOKEN=<personal access token>
MATTERMOST_DEFAULT_CHANNEL_ID=<channel id from Channel URL>
MATTERMOST_OUTGOING_WEBHOOK_TOKEN=<outgoing-webhook token>打開頻道後，URL 中會顯示頻道 ID：
https://mattermost.example.com/team/channels/<id>，其中 <id> 即為頻道 ID。
4. 測試
minara auth messaging test mattermost入站 Webhook
Mattermost 的 outgoing webhook 會向 /webhooks/mattermost 發送 application/x-www-form-urlencoded 格式的 POST 請求，字段如下：
token=<webhook token>
channel_id=<channel id>
user_id=<user id>
user_name=<username>
text=<the user's message>
post_id=<message id>
trigger_word=<matched trigger>
from_webhook=falseMinara 會以常數時間比較 token 字段與 MATTERMOST_OUTGOING_WEBHOOK_TOKEN。from_webhook === "true" 標誌用於過濾自循環（即 bot 自身的消息通過觸發詞再次到達）。
限制與注意事項
- outgoing webhook 僅在公開頻道中觸發。 私有頻道和私信需要通過 WebSocket bot 路徑實現（計劃中）。請合理配置觸發詞，避免高頻頻道持續觸發 Agent。
- 觸發詞須位於消息開頭。 Mattermost 只匹配消息起始處的觸發詞。
@bot hello有效，hello @bot無效。 - 常數時間比較，非 HMAC。 token 是入站的唯一認證憑據，請妥善保密。
- 不支持流式編輯。 Mattermost 提供
PUT /posts/<id>接口，但網關暫未接入。
故障排查
出站報 "401 Unauthorized"
MATTERMOST_BOT_TOKEN 有誤、已過期，或權限範圍限於其他團隊。在 System Console 生成新 token 並更新環境變量。
"Outgoing webhook 未觸發"
- 頻道為私有頻道（僅支持公開頻道）
- 消息未以觸發詞開頭
- webhook 配置的頻道與實際頻道不一致
"入站報 401"
MATTERMOST_OUTGOING_WEBHOOK_TOKEN 不匹配。重新創建 webhook 後 token 會輪換，請同步更新環境變量。