Mattermost

Trạng thái: Plugin có thể tải xuống (mã thông báo bot + sự kiện WebSocket). Hỗ trợ kênh, nhóm và DM. Mattermost là một nền tảng nhắn tin nhóm có thể tự lưu trữ; xem trang chính thức tại mattermost.com để biết chi tiết sản phẩm và tải xuống.

# Cài đặt

Cài đặt Mattermost trước khi cấu hình kênh:

openclaw plugins install @openclaw/mattermost

openclaw plugins install ./path/to/local/mattermost-plugin

Chi tiết: Plugin

# Thiết lập nhanh

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

# Lệnh gạch chéo gốc

Lệnh gạch chéo gốc là tùy chọn bật. Khi được bật, OpenClaw đăng ký các lệnh gạch chéo oc_* qua Mattermost API và nhận các POST gọi lại trên máy chủ HTTP của Gateway.

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

# Biến môi trường (tài khoản mặc định)

Đặt các biến này trên máy chủ Gateway nếu bạn muốn dùng biến môi trường:

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

# Chế độ trò chuyện

Mattermost tự động phản hồi DM. Hành vi kênh được kiểm soát bởi chatmode:

Ví dụ cấu hình:

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

Ghi chú:

• onchar vẫn phản hồi các @đề cập rõ ràng.
• channels.mattermost.requireMention được tôn trọng cho cấu hình cũ nhưng nên dùng chatmode.

# Luồng và phiên

Dùng channels.mattermost.replyToMode để kiểm soát việc trả lời trong kênh và nhóm ở lại kênh chính hay bắt đầu một luồng dưới bài đăng kích hoạt.

• off (mặc định): chỉ trả lời trong một luồng khi bài đăng đến đã ở trong một luồng.
• first: với bài đăng kênh/nhóm cấp cao nhất, bắt đầu một luồng dưới bài đăng đó và định tuyến cuộc trò chuyện tới một phiên theo phạm vi luồng.
• all: hiện tại có cùng hành vi như first đối với Mattermost.
• Tin nhắn trực tiếp bỏ qua thiết lập này và vẫn không theo luồng.

Ví dụ cấu hình:

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

Ghi chú:

• Các phiên theo phạm vi luồng dùng id bài đăng kích hoạt làm gốc luồng.
• first và all hiện tương đương vì sau khi Mattermost có gốc luồng, các đoạn tiếp theo và phương tiện tiếp tục trong cùng luồng đó.

# Kiểm soát truy cập (DM)

• Mặc định: channels.mattermost.dmPolicy = "pairing" (người gửi không xác định nhận mã ghép nối).
• Phê duyệt qua:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• DM công khai: channels.mattermost.dmPolicy="open" cộng với channels.mattermost.allowFrom=["*"].

# Kênh (nhóm)

• Mặc định: channels.mattermost.groupPolicy = "allowlist" (bị chặn bởi yêu cầu đề cập).
• Cho phép người gửi bằng channels.mattermost.groupAllowFrom (khuyến nghị dùng ID người dùng).
• Ghi đè đề cập theo từng kênh nằm dưới channels.mattermost.groups.<channelId>.requireMention hoặc channels.mattermost.groups["*"].requireMention cho mặc định.
• So khớp @username có thể thay đổi và chỉ được bật khi channels.mattermost.dangerouslyAllowNameMatching: true.
• Kênh mở: channels.mattermost.groupPolicy="open" (bị chặn bởi yêu cầu đề cập).
• Ghi chú runtime: nếu channels.mattermost hoàn toàn thiếu, runtime quay về groupPolicy="allowlist" cho kiểm tra nhóm (ngay cả khi channels.defaults.groupPolicy được đặt).

Ví dụ:

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

# Đích để gửi đi

Dùng các định dạng đích này với openclaw message send hoặc cron/webhook:

• channel:<id> cho một kênh
• user:<id> cho một DM
• @username cho một DM (được phân giải qua Mattermost API)

# Thử lại kênh DM

Khi OpenClaw gửi tới đích DM Mattermost và cần phân giải kênh trực tiếp trước, mặc định nó sẽ thử lại các lỗi tạo kênh trực tiếp tạm thời.

Dùng channels.mattermost.dmChannelRetry để tinh chỉnh hành vi đó trên toàn cục cho Plugin Mattermost, hoặc channels.mattermost.accounts.<id>.dmChannelRetry cho một tài khoản.

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

Ghi chú:

• Điều này chỉ áp dụng cho việc tạo kênh DM (/api/v4/channels/direct), không phải mọi lệnh gọi Mattermost API.
• Thử lại áp dụng cho các lỗi tạm thời như giới hạn tốc độ, phản hồi 5xx, và lỗi mạng hoặc hết thời gian chờ.
• Lỗi máy khách 4xx ngoài 429 được xem là vĩnh viễn và không được thử lại.

# Truyền phát bản xem trước

Mattermost truyền phát suy nghĩ, hoạt động công cụ và văn bản trả lời một phần vào một bài đăng xem trước nháp duy nhất, được hoàn tất tại chỗ khi câu trả lời cuối cùng an toàn để gửi. Bản xem trước cập nhật trên cùng id bài đăng thay vì làm đầy kênh bằng tin nhắn theo từng đoạn. Kết quả cuối cùng là phương tiện/lỗi sẽ hủy các chỉnh sửa bản xem trước đang chờ và dùng cách gửi bình thường thay vì đẩy ra một bài đăng xem trước dùng một lần.

Bật qua channels.mattermost.streaming:

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

# Phản ứng (công cụ tin nhắn)

• Dùng message action=react với channel=mattermost.
• messageId là id bài đăng Mattermost.
• emoji chấp nhận tên như thumbsup hoặc :+1: (dấu hai chấm là tùy chọn).
• Đặt remove=true (boolean) để xóa một phản ứng.
• Sự kiện thêm/xóa phản ứng được chuyển tiếp dưới dạng sự kiện hệ thống tới phiên agent đã định tuyến.

Ví dụ:

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

Cấu hình:

• channels.mattermost.actions.reactions: bật/tắt hành động phản ứng (mặc định true).
• Ghi đè theo tài khoản: channels.mattermost.accounts.<id>.actions.reactions.

# Nút tương tác (công cụ tin nhắn)

Gửi tin nhắn có nút có thể nhấp. Khi người dùng nhấp vào nút, agent nhận lựa chọn và có thể phản hồi.

Bật nút bằng cách thêm inlineButtons vào khả năng của kênh:

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

Dùng message action=send với tham số buttons. Nút là mảng 2D (các hàng nút):

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

Trường nút:

Khi người dùng nhấp vào một nút:

# Tích hợp API trực tiếp (script bên ngoài)

Script bên ngoài và webhook có thể đăng nút trực tiếp qua Mattermost REST API thay vì đi qua công cụ message của agent. Dùng buildButtonAttachments() từ Plugin khi có thể; nếu đăng JSON thô, hãy làm theo các quy tắc sau:

Cấu trúc payload:

{
  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
              },
            },
          },
        ],
      },
    ],
  },
}

Tạo token HMAC

Gateway xác minh lượt nhấp nút bằng HMAC-SHA256. Script bên ngoài phải tạo token khớp với logic xác minh của Gateway:

Ví dụ 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}

# Bộ chuyển đổi thư mục

Plugin Mattermost bao gồm một bộ chuyển đổi thư mục để phân giải tên kênh và người dùng qua Mattermost API. Điều này cho phép các đích #channel-name và @username trong openclaw message send và các lần gửi cron/webhook.

Không cần cấu hình - bộ chuyển đổi dùng bot token từ cấu hình tài khoản.

# Nhiều tài khoản

Mattermost hỗ trợ nhiều tài khoản dưới 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" },
      },
    },
  },
}

# Khắc phục sự cố

# Liên quan

• Định tuyến kênh - định tuyến phiên cho tin nhắn
• Tổng quan về kênh - tất cả kênh được hỗ trợ
• Nhóm - hành vi trò chuyện nhóm và kiểm soát nhắc đến
• Ghép đôi - xác thực DM và luồng ghép đôi
• Bảo mật - mô hình truy cập và gia cố