OpenClaw

OpenClaw Mattermost 渠道

企业平台
中等

将 OpenClaw 连接到 Mattermost 这一开源企业消息平台，使您的 AI 助手能够参与私信、群组频道和团队对话。该集成使用 Bot Token 认证和 WebSocket 事件进行实时双向通信，支持灵活的聊天模式和细粒度的访问控制策略。

快速信息
难度中等
分类企业平台
支持功能数5 / 6

Mattermost 支持的功能

文本消息

支持

媒体与文件

支持

消息反应

支持

消息线程

支持

语音消息

不支持

群聊

支持

Mattermost 前置条件

  • 一台 Mattermost 服务器（自托管或云端），并拥有管理员权限以创建 Bot 账户
  • 在 Mattermost 系统控制台中创建的 Bot 账户及其 Bot Token
  • Mattermost 服务器的 Base URL 可从 OpenClaw Gateway 访问
  • 已安装并运行 OpenClaw Gateway
  • 已通过 'openclaw plugins install @openclaw/mattermost' 安装 Mattermost 插件

Mattermost 快速设置

1

安装 Mattermost 插件

运行 'openclaw plugins install @openclaw/mattermost' 为您的 Gateway 添加 Mattermost 支持。

2

在 Mattermost 中创建 Bot 账户

前往 Mattermost 系统控制台 > Integrations > Bot Accounts。点击 'Add Bot Account'，设置显示名称和描述，然后复制生成的 Bot Token。确保在系统控制台 > Integrations > Integration Management 中将 'Enable Bot Account Creation' 设置为 true。

3

配置并启动

在 ~/.openclaw/openclaw.json 中添加 Mattermost 渠道配置，填入您的 botToken、baseUrl 和所需的策略。使用 'openclaw start' 启动 Gateway。向 Bot 发送私信或在频道中 @提及它以验证连接。

Mattermost 配置示例

config.json
{
  "channels": {
    "mattermost": {
      "enabled": true,
      "botToken": "your-bot-token",
      "baseUrl": "https://mattermost.example.com",
      "dmPolicy": "pairing",
      "chatmode": "oncall"
    }
  }
}

Mattermost 深入了解

架构概览

OpenClaw 通过 Mattermost 的 REST API 和 WebSocket 事件流与其连接。启动时，Gateway 使用您的 Bot Token 进行身份验证，建立持久的 WebSocket 连接，并开始监听消息事件。 当消息匹配当前聊天模式的触发条件（提及、前缀或所有消息）时，Gateway 会将其转发给您的 AI Agent。Agent 的回复将通过 Mattermost REST API 发送回同一频道或私信会话。 该集成支持丰富的功能，包括媒体附件、消息表情回应、会话回复和群组频道管理 -- 是功能最完善的企业渠道集成之一。
WebSocket 连接在断开时会自动重新连接。
每个账户会生成唯一的会话密钥（agent:<agentId>:mattermost:<accountName>）用于独立的对话跟踪。

创建 Bot 账户

Mattermost Bot 账户是专用的服务账户，不占用用户许可证配额。 1. 前往系统控制台 > Integrations > Bot Accounts。 2. 确保在 Integration Management 中启用了 'Enable Bot Account Creation'。 3. 点击 'Add Bot Account'，填写显示名称、描述和图标。 4. 选择适当的角色（不建议使用 System Admin，请使用默认的 Member 角色）。 5. 立即复制生成的 Bot Token -- 该令牌不会再次显示。 Bot 必须被添加到需要操作的频道中。团队管理员或系统管理员可以手动将 Bot 添加到频道，用户也可以通过 @提及来邀请它。
openclaw.json
{
  "channels": {
    "mattermost": {
      "botToken": "your-bot-token",
      "baseUrl": "https://mattermost.example.com"
    }
  }
}
请妥善保管 Bot Token。如果丢失，需要在系统控制台中重新生成。
Bot 账户不占用 Mattermost 许可证席位配额。

聊天模式

OpenClaw 支持三种聊天模式，用于控制 Bot 在频道中何时响应消息： **oncall（默认）** -- Bot 仅在被 @提及时响应。这是繁忙频道中最安全的模式，Bot 只有在被明确调用时才会回复。 **onmessage** -- Bot 会响应所有允许用户的每条消息。最适合专用 Bot 频道或低流量环境，在这些场景中每条消息都应得到回复。 **onchar** -- Bot 在消息以特定前缀字符开头时响应（例如 '!' 或 '/'）。通过 oncharPrefixes 配置触发前缀。当您需要明确但简洁的激活方式而不必输入完整 Bot 名称时，此模式非常有用。
openclaw.json
{
  "channels": {
    "mattermost": {
      "chatmode": "onchar",
      "oncharPrefixes": ["!", "/ai"]
    }
  }
}
在私信中，无论聊天模式如何设置，Bot 都会响应所有消息。
建议在团队频道中使用 oncall 模式以避免干扰。

DM 策略

DM（私信）策略控制谁可以通过私信与 Bot 交互。 **pairing（默认）** -- 仅 allowFrom 数组中明确列出的用户可以向 Bot 发送私信。这是最严格的模式，适合精确控制哪些用户有权访问。 **open** -- 任何向 Bot 发送私信的 Mattermost 用户都会收到回复。当您希望 Bot 在组织内广泛可用时使用此模式。 allowFrom 字段接受 Mattermost 用户 ID。您可以在系统控制台 > Users 中找到用户 ID，也可以通过 Mattermost API 获取。
openclaw.json
{
  "channels": {
    "mattermost": {
      "dmPolicy": "pairing",
      "allowFrom": ["user-id-1", "user-id-2"]
    }
  }
}
将 dmPolicy 设置为 'open' 允许 Mattermost 服务器上的任何用户通过私信消耗 AI 配额。在大型服务器上请谨慎使用。

群组和频道策略

群组策略控制 Bot 在接收群组消息时参与哪些频道。 **allowlist（默认）** -- Bot 仅在 groupAllowFrom 中明确列出的频道中响应。其他频道中的消息将被静默忽略。 **open** -- Bot 会在其被添加到的任何频道中响应。这种方式很方便，但如果 Bot 被添加到过多频道，可能导致意外交互。 groupAllowFrom 字段接受 Mattermost 频道 ID。您可以从频道 URL 中获取频道 ID，也可以通过 Mattermost API 查询。
openclaw.json
{
  "channels": {
    "mattermost": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["channel-id-1", "channel-id-2"]
    }
  }
}
在生产环境中使用 allowlist 模式，以防止 Bot 在意外频道中响应。
无论群组策略如何设置，Bot 都必须是频道成员才能接收消息。

多账户设置

OpenClaw 支持同时运行多个 Mattermost Bot 账户，每个账户可以连接到不同的 Mattermost 服务器或使用不同的配置。 使用 accounts.<name> 模式配置多个账户。每个账户拥有独立的 Bot Token、Base URL、聊天模式和访问策略。 这对于运行多个 Mattermost 实例的组织（例如生产环境和测试环境）或不同团队需要不同行为的 Bot 时非常有用。
openclaw.json
{
  "channels": {
    "mattermost": {
      "accounts": {
        "production": {
          "botToken": "prod-bot-token",
          "baseUrl": "https://mattermost.company.com",
          "chatmode": "oncall",
          "dmPolicy": "pairing",
          "allowFrom": ["user-1", "user-2"]
        },
        "dev-team": {
          "botToken": "dev-bot-token",
          "baseUrl": "https://mm-dev.company.com",
          "chatmode": "onmessage",
          "dmPolicy": "open"
        }
      }
    }
  }
}

主动消息发送

AI Agent 可以使用 mattermost 工具操作主动向 Mattermost 频道和用户发送消息。这支持定时通知、告警和自动更新等场景，无需用户触发。 支持的目标格式： - channel:<channel-id> -- 按 ID 发送到指定频道 - user:<user-id> -- 按 ID 向指定用户发送私信 - @username -- 按用户名向用户发送私信 Bot 必须有权限在目标频道中发布消息或向目标用户发起私信。
agent-action.json
{
  "action": "mattermost",
  "params": {
    "message": "Daily standup reminder: please post your updates!",
    "to": "channel:abc123def456"
  }
}
请使用频道 ID（而非名称）以确保可靠投递。频道名称可能会被修改。
Bot 必须是目标频道的成员才能发布消息。

富消息功能

Mattermost 支持丰富的消息功能，OpenClaw 充分利用了这些功能： **媒体附件** -- Bot 可以发送和接收图片、文件及其他附件。用户分享的媒体会被转发给 AI Agent 进行处理。 **表情回应** -- Bot 可以为消息添加表情回应。这对于确认反馈或状态指示很有用。 **会话回复** -- Bot 支持 Mattermost 的会话模型。当用户在会话中回复时，Bot 会在该会话内保持上下文。 **Markdown** -- Mattermost 原生支持 Markdown 渲染，因此 Bot 的回复可以包含格式化文本、代码块、表格和链接。
会话回复有助于保持对话有序，尤其是在繁忙的频道中。
文件附件受 Mattermost 服务器上传大小限制的约束。

速率限制与最佳实践

Mattermost 对其 REST API 实施速率限制以保护服务器性能。默认限制为： - 每用户每秒 10 个请求（持续速率） - 100 个请求的突发容量 这些限制适用于 Bot 账户的 API 调用，包括发送消息、添加表情回应和上传文件。 生产部署的最佳实践： 1. 在繁忙频道中使用 oncall 或 onchar 聊天模式以减少不必要的 API 调用。 2. 将 groupPolicy 保持为 allowlist 以防止 Bot 在所有频道中响应。 3. 在 Mattermost 系统控制台 > Environment > Rate Limiting 中监控 Bot 的 API 使用情况。 4. 对于高流量部署，考虑为不同团队运行独立的账户。
如果 Bot 超出速率限制，Mattermost 将返回 HTTP 429 错误。Gateway 会进行退避重试，但持续过载可能需要调整配置。

Mattermost 配置参考

enabled
Type: booleanDefault: true

启用或禁用 Mattermost 渠道

botToken
Type: stringDefault: ""

从 Mattermost 系统控制台 > Bot Accounts 获取的 Bot Token

baseUrl
Type: stringDefault: ""

Mattermost 服务器的完整 URL（例如 https://mattermost.example.com）

chatmode
Type: stringDefault: "oncall"

聊天触发模式：'oncall'（提及触发）、'onmessage'（所有消息）或 'onchar'（前缀触发）

oncharPrefixes
Type: string[]Default: []

当 chatmode 为 'onchar' 时触发 Bot 的前缀字符

dmPolicy
Type: stringDefault: "pairing"

DM 访问策略：'pairing'（仅允许列表中的用户）或 'open'（任何用户）

allowFrom
Type: string[]Default: []

允许向 Bot 发送私信的 Mattermost 用户 ID（与 dmPolicy: pairing 配合使用）

groupPolicy
Type: stringDefault: "allowlist"

群组频道策略：'allowlist'（仅指定频道）或 'open'（任何频道）

groupAllowFrom
Type: string[]Default: []

允许 Bot 响应的 Mattermost 频道 ID（与 groupPolicy: allowlist 配合使用）

requireMention
Type: booleanDefault: true

旧版设置 -- 建议使用 chatmode: 'oncall' 代替

accounts.<id>.botToken
Type: stringDefault: ""

多账户模式中特定账户的 Bot Token

accounts.<id>.baseUrl
Type: stringDefault: ""

特定账户的 Mattermost 服务器 URL

accounts.<id>.chatmode
Type: stringDefault: "oncall"

特定账户的聊天触发模式

accounts.<id>.dmPolicy
Type: stringDefault: "pairing"

特定账户的 DM 访问策略

Mattermost 常见问题

Mattermost 故障排查

Bot 不响应消息

聊天模式或访问策略可能过滤了消息。

检查 chatmode 是否与您预期的触发方式匹配（oncall 需要 @提及，onchar 需要前缀）。确认 dmPolicy 和 allowFrom 包含该用户的 ID（私信场景），或 groupPolicy 和 groupAllowFrom 包含频道 ID（群组消息场景）。
启动时 WebSocket 连接失败

baseUrl 不正确、Bot Token 无效或服务器不可达。

确认 baseUrl 指向正确的 Mattermost 服务器（需包含协议，例如 https://）。确保 Bot Token 有效且未被撤销。检查 Gateway 与 Mattermost 服务器之间的网络连通性和防火墙规则。
Bot 无法在频道中发送消息

Bot 不是目标频道的成员。

通过 Mattermost 手动将 Bot 添加到频道（点击频道中的 'Add Members'），或通过 @提及其用户名来邀请它。Bot 必须是频道成员才能发送消息。
媒体附件未被处理

Mattermost 服务器的文件上传设置可能限制了文件类型或大小。

检查系统控制台 > Environment > File Storage 中的上传限制。确保 Bot 账户有权访问文件附件。确认 Gateway 能够访问 Mattermost 文件 API 端点。
日志中出现速率限制错误（HTTP 429）

Bot 在短时间内发送了过多的 API 请求。

将聊天模式从 onmessage 切换到 oncall 或 onchar 以减少 API 调用。限制 Bot 活跃的频道数量。检查系统控制台 > Environment > Rate Limiting 以查看或调整服务器端速率限制。
查看完整文档返回所有渠道

相关渠道

Feishu / Lark

Medium

OpenClaw 通过 WebSocket 的飞书/Lark 集成

配置指南

Slack

Medium

OpenClaw 通过 Bolt SDK 的工作区应用集成

配置指南

Google Chat

Medium

OpenClaw 通过 HTTP 端点的 Google Chat API 应用

配置指南