Mattermost

Status: 可下载插件（机器人令牌 + WebSocket 事件）。支持渠道、群组和私信。Mattermost 是可自托管的团队消息平台；产品详情和下载请参阅官方站点 mattermost.com。

# 安装

配置渠道前先安装 Mattermost：

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 会通过 Mattermost API 注册 oc_* 斜杠命令，并在 Gateway 网关 HTTP 服务器上接收回调 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",
      },
    },
  },
}

# 环境变量（默认账号）

如果你偏好环境变量，请在 Gateway 网关主机上设置这些值：

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

# 聊天模式

Mattermost 会自动回复私信。渠道行为由 chatmode 控制：

配置示例：

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

说明：

• onchar 仍会回复显式 @ 提及。
• 旧版配置仍会遵循 channels.mattermost.requireMention，但首选使用 chatmode。

# 线程和会话

使用 channels.mattermost.replyToMode 控制渠道和群组回复是留在主渠道中，还是在触发帖文下启动线程。

• off（默认）：仅当入站帖文本来已在线程中时，才在线程中回复。
• first：对于顶层渠道/群组帖文，在该帖文下启动线程，并将对话路由到线程范围的会话。
• all：目前在 Mattermost 中的行为与 first 相同。
• 直接消息会忽略此设置，并保持非线程模式。

配置示例：

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

说明：

• 线程范围的会话使用触发帖文 ID 作为线程根。
• first 和 all 目前等价，因为一旦 Mattermost 有线程根，后续分块和媒体会继续留在同一线程中。

# 访问控制（私信）

• 默认：channels.mattermost.dmPolicy = "pairing"（未知发送者会收到配对码）。
• 通过以下方式批准：
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• 公开私信：channels.mattermost.dmPolicy="open" 加 channels.mattermost.allowFrom=["*"]。

# 渠道（群组）

• 默认：channels.mattermost.groupPolicy = "allowlist"（受提及限制）。
• 使用 channels.mattermost.groupAllowFrom 允许发送者（建议使用用户 ID）。
• 每个渠道的提及覆盖位于 channels.mattermost.groups.<channelId>.requireMention 下，默认值可使用 channels.mattermost.groups["*"].requireMention。
• @username 匹配是可变的，且仅在 channels.mattermost.dangerouslyAllowNameMatching: true 时启用。
• 开放渠道：channels.mattermost.groupPolicy="open"（受提及限制）。
• 运行时说明：如果完全缺少 channels.mattermost，运行时会在群组检查中回退到 groupPolicy="allowlist"（即使已设置 channels.defaults.groupPolicy）。

示例：

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

# 出站投递目标

将这些目标格式用于 openclaw message send 或 cron/webhook：

• channel:<id> 表示渠道
• user:<id> 表示私信
• @username 表示私信（通过 Mattermost API 解析）

# 私信渠道重试

当 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 会将思考、工具活动和部分回复文本流式传输到单个草稿预览帖文中，并在最终答案可安全发送时就地定稿。预览会更新同一个帖文 ID，而不是用每个分块消息刷屏渠道。媒体/错误最终消息会取消待处理的预览编辑，并使用正常投递，而不是刷新一个一次性预览帖文。

通过 channels.mattermost.streaming 启用：

{
  channels: {
    mattermost: {
      streaming: "partial", // off | partial | block | progress
    },
  },
}

# 表情回应（消息工具）

• 使用 message action=react 并设置 channel=mattermost。
• messageId 是 Mattermost 帖文 ID。
• emoji 接受 thumbsup 或 :+1: 这样的名称（冒号可选）。
• 设置 remove=true（布尔值）可移除表情回应。
• 表情回应添加/移除事件会作为系统事件转发给路由到的智能体会话。

示例：

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。

# 交互式按钮（消息工具）

发送带可点击按钮的消息。当用户点击按钮时，智能体会收到选择并可以响应。

通过向渠道能力添加 inlineButtons 启用按钮：

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

使用带有 buttons 参数的 message action=send。按钮是二维数组（按钮行）：

message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]

按钮字段：

当用户点击按钮时：

# 直接 API 集成（外部脚本）

外部脚本和 webhook 可以通过 Mattermost REST API 直接发布按钮，而不是经过智能体的 message 工具。尽可能使用插件中的 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 (for name lookup)
                action: "approve",
                // ... any custom fields ...
                _token: "<hmac>", // see HMAC section below
              },
            },
          },
        ],
      },
    ],
  },
}

HMAC 令牌生成

Gateway 网关使用 HMAC-SHA256 验证按钮点击。外部脚本必须生成与 Gateway 网关验证逻辑匹配的令牌：

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 以及 cron/webhook 投递中启用 #channel-name 和 @username 目标。

无需配置：适配器使用账号配置中的 bot 令牌。

# 多账号

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

# 故障排除

# 相关内容

• 渠道路由 - 消息的会话路由
• 渠道概览 - 所有受支持的渠道
• 群组 - 群聊行为和提及门控
• 配对 - 私信认证和配对流程
• 安全 - 访问模型和加固