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 会轮换，请同步更新环境变量。