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 channels add --channel mattermost --bot-token <token> --http-url https://chat.example.com

​

原生 slash 命令

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // 当 Mattermost 无法直接访问网关时使用（反向代理/公网 URL）。
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

​

环境变量（默认账号）

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

​

聊天模式

{
  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 facts，因此这些标志在这里没有作用。

​

线程和会话

• off (默认)：仅当传入的帖子已经位于线程中时，才在线程中回复。
• first：对于顶级频道/群组帖子，在该帖子下方发起一个线程，并将对话路由到线程作用域的会话中。
• all 和 batched：在当前 Mattermost 中与 first 的行为相同，因为一旦 Mattermost 有了线程根消息，后续的分块和媒体就会继续留在同一个线程中。
• 即使设置了 replyToMode，直接消息默认仍为 off。

• off (默认)：直接消息保持为非线程式，处于单个滚动会话中。
• first、all 或 batched：每条顶级直接消息都会启动一个 Mattermost 线程，并由一个全新、独立的会话来支持。

{
  channels: {
    mattermost: {
      replyToMode: "all",
      replyToModeByChatType: {
        direct: "first",
      },
    },
  },
}

• 线程作用域的会话使用触发该消息的帖子 id 作为线程根。
• first 和 all 目前等价，因为一旦 Mattermost 有了线程根，后续的分块和媒体就会继续留在同一个线程中。
• 按聊天类型的覆盖设置优先于 replyToMode。如果没有 direct 覆盖，现有部署将继续保持扁平、非线程式的 DM。

​

访问控制（私信）

• 默认：channels.mattermost.dmPolicy = "pairing"（未知发送者会获得一个配对码）。其他值：allowlist、open、disabled。
• 通过以下方式批准：
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• 公开私信：channels.mattermost.dmPolicy="open" 加上 channels.mattermost.allowFrom=["*"]（配置 schema 会强制使用通配符）。
• 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 },
      },
    },
  },
}

​

外发投递目标

​

私信频道重试

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

• 这只适用于 DM 频道创建（/api/v4/channels/direct），不适用于每一次 Mattermost API 调用。
• 重试使用带抖动的指数退避，并适用于限流、5xx 响应以及网络或超时错误等瞬时故障。
• 除 429 之外的 4xx 客户端错误都被视为永久性错误，不会重试。

​

预览流式输出

{
  channels: {
    mattermost: {
      streaming: { mode: "partial" }, // 关闭 | partial | block | progress
    },
  },
}

​

读取频道历史记录（消息工具）

openclaw message read --channel mattermost --target channel:<channelId> --limit 5 --json

• 结果遵循 Mattermost 的有序帖子列表，并包含规范化的 timestampMs 和 timestampUtc 字段。
• limit 默认为 60，且上限为 Mattermost 的最大值 200。使用 before=<postId> 或 after=<postId> 进行分页；不能同时使用这两个游标。
• 直接操作员调用依赖 Mattermost 的频道成员资格和 read_channel 权限。提供商返回的 403 会作为正常的、可见的工具错误。
• 允许委托读取当前 Mattermost 对话。跨频道委托读取还需要在 channels.mattermost.groups 下配置目标频道 ID、配置 "*" 频道条目，或将 groupPolicy 设置为 "open"。跨账户和跨频道的私信读取会安全失败。
• 默认情况下禁用历史记录读取。将 channels.mattermost.actions.messages 设置为 true 以启用。可通过 channels.mattermost.accounts.<id>.actions.messages 针对每个账户覆盖该设置。

​

反应（消息工具）

• 使用 message action=react 并设置 channel=mattermost。
• messageId 是 Mattermost 帖子 ID。
• emoji 接受诸如 thumbsup 或 :+1: 这样的名称（冒号可选）。
• 设置 remove=true（布尔值）可移除反应。
• 反应的添加/移除事件会作为系统事件转发到路由后的 agent 会话，并且受与消息相同的 DM/群组策略检查约束。

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。

​

交互式按钮（message 工具）

message action=send channel=mattermost target=channel:<channelId> presentation={"blocks":[{"type":"buttons","buttons":[{"label":"是","value":"yes"},{"label":"否","value":"no"}]}]}

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

​

直接 API 集成（外部脚本）

{
  channel_id: "<channelId>",
  message: "请选择一个选项：",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // 仅限字母数字 - 见下文
            type: "button", // 必需，否则点击会被静默忽略
            name: "批准", // 显示标签
            style: "primary", // 可选："default"、"primary"、"danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // 必须与按钮 ID 匹配
                action: "approve",
                // ... 任何自定义字段 ...
                _token: "<hmac>", // 见下方 HMAC 部分
              },
            },
          },
        ],
      },
    ],
  },
}

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}

​

目录适配器

​

多账号

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "主账号", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "告警", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

​

故障排查

​

相关内容

• 频道路由 - 消息的会话路由
• 频道概览 - 所有支持的频道
• 群组 - 群聊行为和 mention gating
• 配对 - DM 认证和配对流程
• 安全性 - 访问模型和加固