Mattermost

Trạng thái: plugin có thể tải xuống (token bot + sự kiện WebSocket). Hỗ trợ các kênh, kênh riêng tư, DM nhóm và DM. Mattermost là nền tảng nhắn tin nhóm có thể tự lưu trữ (mattermost.com).

Cài đặt

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

openclaw channels add --channel mattermost --bot-token <token> --http-url https://chat.example.com

Lệnh gạch chéo nguyên bản

Các lệnh gạch chéo nguyên bản là tính năng cần chủ động bật. Khi được bật, OpenClaw đăng ký các lệnh gạch chéo oc_* trên mọi nhóm mà bot là thành viên và nhận các yêu cầu 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",        // Sử dụng khi Mattermost không thể truy cập trực tiếp Gateway (proxy ngược/URL công khai).        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",      },    },  },}

Các lệnh đã đăng ký: /oc_status, /oc_model, /oc_models, /oc_new, /oc_help, /oc_think, /oc_reasoning, /oc_verbose, /oc_queue. Với nativeSkills: true, các lệnh Skills cũng được đăng ký dưới dạng /oc_<skill>.

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

Đặt các biến sau 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 tin nhắn trực tiếp. Hành vi trong kênh được kiểm soát bởi chatmode:

Ví dụ cấu hình:

{  channels: {    mattermost: {      chatmode: "onchar",      oncharPrefixes: [">", "!"], // mặc định    },  },}

Lưu ý:

• onchar vẫn phản hồi các lượt @đề cập tường minh.
• channels.mattermost.requireMention vẫn được áp dụng, nhưng ưu tiên chatmode. Các cài đặt groups.<channelId>.requireMention theo từng kênh được ưu tiên hơn cả hai.
• Sau khi bot gửi phản hồi hiển thị trong một luồng của kênh, các tin nhắn tiếp theo trong cùng luồng đó sẽ được trả lời mà không cần @đề cập mới hoặc tiền tố onchar, nhờ đó cuộc trò chuyện nhiều lượt trong luồng tiếp tục liền mạch. Trạng thái tham gia được ghi nhớ trong 7 ngày kể từ lần cuối bot phản hồi trong luồng đó và vẫn tồn tại sau khi Gateway khởi động lại. Các luồng mà bot chỉ quan sát không bị ảnh hưởng; hãy bắt đầu một tin nhắn cấp cao nhất mới để yêu cầu đề cập tường minh trở lại.
• Đặt channels.mattermost.implicitMentions.threadParticipation: false để ngăn các phản hồi tiếp nối trong luồng đã tham gia bỏ qua điều kiện đề cập. Giá trị ghi đè cho tài khoản sử dụng channels.mattermost.accounts.<id>.implicitMentions. Mattermost hiện không tạo các dữ kiện replyToBot hoặc quotedBot, vì vậy các cờ đó không có tác dụng ở đây.

Luồng và phiên

Sử dụng channels.mattermost.replyToMode để kiểm soát việc phản hồi trong kênh và nhóm tiếp tục ở kênh chính hay bắt đầu một luồng bên dưới bài đăng kích hoạt.

• off (mặc định): chỉ phản hồi trong luồng khi bài đăng đến đã nằm trong một luồng.
• first: đối với bài đăng cấp cao nhất trong kênh/nhóm, bắt đầu một luồng bên dưới bài đăng đó và định tuyến cuộc trò chuyện đến một phiên có phạm vi luồng.
• all và batched: hiện có cùng hành vi với first trên Mattermost, vì sau khi Mattermost có bài đăng gốc của luồng, các phần tin nhắn và nội dung đa phương tiện tiếp theo vẫn tiếp tục trong cùng luồng đó.
• Tin nhắn trực tiếp mặc định sử dụng off ngay cả khi replyToMode được đặt.

Sử dụng channels.mattermost.replyToModeByChatType để ghi đè chế độ cho các cuộc trò chuyện direct, group hoặc channel. Đặt direct để bật luồng cho tin nhắn trực tiếp:

• off (mặc định): tin nhắn trực tiếp không sử dụng luồng và nằm trong một phiên liên tục.
• first, all hoặc batched: mỗi tin nhắn trực tiếp cấp cao nhất bắt đầu một luồng Mattermost được hỗ trợ bởi một phiên mới, độc lập.

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

Lưu ý:

• Các phiên có phạm vi luồng sử dụng ID của bài đăng kích hoạt làm bài đăng gốc của luồng.
• first và all hiện tương đương nhau vì sau khi Mattermost có bài đăng gốc của luồng, các phần tin nhắn và nội dung đa phương tiện tiếp theo vẫn tiếp tục trong cùng luồng đó.
• Các giá trị ghi đè theo loại trò chuyện được ưu tiên hơn replyToMode. Nếu không có giá trị ghi đè direct, các bản triển khai hiện có vẫn giữ tin nhắn trực tiếp dạng phẳng, không sử dụng luồng.

Kiểm soát truy cập (tin nhắn trực tiếp)

• Mặc định: channels.mattermost.dmPolicy = "pairing" (người gửi không xác định nhận được mã ghép nối). Các giá trị khác: allowlist, open, disabled.
• Phê duyệt qua:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• Tin nhắn trực tiếp công khai: channels.mattermost.dmPolicy="open" cùng với channels.mattermost.allowFrom=["*"] (lược đồ cấu hình bắt buộc ký tự đại diện).
• channels.mattermost.allowFrom chấp nhận ID người dùng (khuyến nghị) và các mục accessGroup:<name>. Xem Nhóm truy cập.

Kênh (nhóm)

• Mặc định: channels.mattermost.groupPolicy = "allowlist" (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).
• channels.mattermost.groupAllowFrom chấp nhận các mục accessGroup:<name>. Xem Nhóm truy cập.
• Các giá trị ghi đè yêu cầu đề cập theo từng kênh nằm trong channels.mattermost.groups.<channelId>.requireMention hoặc channels.mattermost.groups["*"].requireMention cho giá trị mặc định.
• Việc đối chiếu @username có thể thay đổi và chỉ được bật khi channels.mattermost.dangerouslyAllowNameMatching: true.
• Kênh mở: channels.mattermost.groupPolicy="open" (yêu cầu đề cập).
• Thứ tự phân giải: channels.mattermost.groupPolicy, sau đó channels.defaults.groupPolicy, rồi "allowlist".
• Lưu ý về runtime: nếu phần channels.mattermost hoàn toàn không tồn tại, runtime sẽ đóng an toàn về groupPolicy="allowlist" khi kiểm tra nhóm (ngay cả khi channels.defaults.groupPolicy được đặt) và ghi nhật ký cảnh báo một lần.

Ví dụ:

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

Đích gửi đi

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

Mỗi lần gửi đi hỗ trợ tối đa một tệp đính kèm cho mỗi tin nhắn; hãy chia nhiều tệp thành các lần gửi riêng biệt.

Thử lại kênh tin nhắn trực tiếp

Khi OpenClaw gửi đến một đích tin nhắn trực tiếp Mattermost và trước tiên cần phân giải kênh trực tiếp, theo mặc định, hệ thống sẽ thử lại các lỗi tạm thời khi tạo kênh trực tiếp.

Sử dụng channels.mattermost.dmChannelRetry để điều 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. Giá trị mặc định:

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

Lưu ý:

• Điều này chỉ áp dụng cho việc tạo kênh tin nhắn trực tiếp (/api/v4/channels/direct), không áp dụng cho mọi lệnh gọi API Mattermost.
• Các lần thử lại sử dụng thời gian chờ tăng theo cấp số nhân kèm độ dao động và á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ờ.
• Các lỗi máy khách 4xx ngoài 429 được coi là vĩnh viễn và không được thử lại.

Truyền trực tiếp bản xem trước

Mattermost truyền trực tiếp quá trình suy nghĩ, hoạt động của công cụ và văn bản trả lời từng phần vào một bài đăng xem trước dạng bản nháp, bài đăng này được hoàn tất tại chỗ khi câu trả lời cuối cùng đã an toàn để gửi. Ở chế độ partial, bản xem trước được cập nhật trên cùng một ID bài đăng thay vì làm ngập kênh bằng tin nhắn cho từng đoạn. Ở chế độ block, bản xem trước luân phiên giữa văn bản đã hoàn tất và các khối hoạt động của công cụ, vì vậy các khối trước đó vẫn hiển thị dưới dạng bài đăng riêng thay vì bị khối tiếp theo ghi đè. Kết quả cuối chứa nội dung đa phương tiện/lỗi sẽ hủy các chỉnh sửa bản xem trước đang chờ và sử dụng cơ chế gửi thông thường thay vì hoàn tất một bài đăng xem trước dùng rồi bỏ.

Truyền trực tiếp bản xem trước được bật theo mặc định ở chế độ partial. Cấu hình qua channels.mattermost.streaming.mode (các giá trị vô hướng/boolean cũ streaming được openclaw doctor --fix di chuyển):

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

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

• Sử dụng message action=react với channel=mattermost.
• messageId là ID bài đăng Mattermost.
• emoji chấp nhận các tên như thumbsup hoặc :+1: (dấu hai chấm là tùy chọn).
• Đặt remove=true (boolean) để xóa phản ứng.
• Các 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 đến phiên tác tử được định tuyến, tuân theo cùng các bước kiểm tra chính sách tin nhắn trực tiếp/nhóm như tin nhắn.

Ví dụ:

message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsupmessage 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 các thao tác phản ứng (mặc định là 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ó các nút có thể nhấp. Khi người dùng nhấp vào một nút, tác tử sẽ nhận được lựa chọn và có thể phản hồi.

Các nút đến từ tải trọng ngữ nghĩa presentation (trong các câu trả lời thông thường của tác tử và trong message action=send). OpenClaw kết xuất các nút giá trị dưới dạng nút tương tác Mattermost, giữ các nút URL hiển thị trong văn bản tin nhắn và hạ cấp menu chọn thành văn bản dễ đọc.

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

Các trường của nút trình bày:

Để thông báo khả năng hỗ trợ nút trong lời nhắc hệ thống của tác tử, hãy thêm inlineButtons vào các khả năng của kênh:

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

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

Tích hợp API trực tiếp (tập lệnh bên ngoài)

Các tập lệnh và Webhook bên ngoài có thể đăng nút trực tiếp qua API REST Mattermost thay vì đi qua công cụ message của tác tử. Nên ưu tiên công cụ message của OpenClaw. Đối với tích hợp trực tiếp, hãy nhập buildButtonAttachments từ @openclaw/mattermost/api.js; nếu đăng JSON thô, hãy tuân theo các quy tắc sau:

Cấu trúc tải trọng:

{  channel_id: "<channelId>",  message: "Chọn một tùy chọn:",  props: {    attachments: [      {        actions: [          {            id: "mybutton01", // chỉ ký tự chữ và số - xem bên dưới            type: "button", // bắt buộc, nếu không các lần nhấp sẽ bị bỏ qua mà không có thông báo            name: "Phê duyệt", // nhãn hiển thị            style: "primary", // tùy chọn: "default", "primary", "danger"            integration: {              url: "https://gateway.example.com/mattermost/interactions/default",              context: {                action_id: "mybutton01", // phải khớp với ID nút                action: "approve",                // ... các trường tùy chỉnh bất kỳ ...                _token: "<hmac>", // xem phần HMAC bên dưới              },            },          },        ],      },    ],  },}

Tạo token HMAC

Gateway xác minh các lần nhấp vào nút bằng HMAC-SHA256. Các tập lệnh 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ộ điều hợp thư mục

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

Không cần cấu hình — bộ điều hợp sử dụng token bot từ cấu hình tài khoản.

Nhiều tài khoản

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

Các giá trị tài khoản ghi đè các trường cấp cao nhất; channels.mattermost.defaultAccount chọn tài khoản được sử dụng khi không chỉ định tài khoản nào.

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ề các kênh — tất cả các kênh được hỗ trợ
• Nhóm — hành vi trò chuyện nhóm và kiểm soát bằng lượt đề cập
• Ghép nối — luồng xác thực DM và ghép nối
• Bảo mật — mô hình truy cập và tăng cường bảo mật