Mattermost

وضعیت: Plugin قابل دانلود (توکن بات + رویدادهای WebSocket). کانال‌ها، گروه‌ها و DMها پشتیبانی می‌شوند. Mattermost یک پلتفرم پیام‌رسانی تیمی قابل میزبانی شخصی است؛ برای جزئیات محصول و دانلودها، سایت رسمی را در mattermost.com ببینید.

# نصب

پیش از پیکربندی کانال، Mattermost را نصب کنید:

openclaw plugins install @openclaw/mattermost

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

جزئیات: Plugins

# راه‌اندازی سریع

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

# دستورهای slash بومی

دستورهای slash بومی اختیاری هستند. وقتی فعال شوند، OpenClaw دستورهای slash با نام oc_* را از طریق API Mattermost ثبت می‌کند و POSTهای callback را روی سرور HTTP 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",
      },
    },
  },
}

# متغیرهای محیطی (حساب پیش‌فرض)

اگر env varها را ترجیح می‌دهید، این‌ها را روی میزبان Gateway تنظیم کنید:

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

# حالت‌های چت

Mattermost به‌صورت خودکار به DMها پاسخ می‌دهد. رفتار کانال با chatmode کنترل می‌شود:

نمونه پیکربندی:

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

نکته‌ها:

• onchar همچنان به @mentionهای صریح پاسخ می‌دهد.
• channels.mattermost.requireMention برای پیکربندی‌های قدیمی رعایت می‌شود، اما chatmode ترجیح داده می‌شود.

# رشته‌ها و sessionها

از channels.mattermost.replyToMode استفاده کنید تا کنترل کنید پاسخ‌های کانال و گروه در کانال اصلی بمانند یا زیر پست triggerکننده یک thread شروع کنند.

• off (پیش‌فرض): فقط وقتی پست ورودی از قبل داخل یک thread است، در thread پاسخ بده.
• first: برای پست‌های سطح بالای کانال/گروه، زیر همان پست یک thread شروع کن و گفتگو را به یک session محدود به thread هدایت کن.
• all: برای Mattermost فعلاً همان رفتار first را دارد.
• پیام‌های مستقیم این تنظیم را نادیده می‌گیرند و بدون thread می‌مانند.

نمونه پیکربندی:

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

نکته‌ها:

• sessionهای محدود به thread از id پست triggerکننده به‌عنوان ریشه thread استفاده می‌کنند.
• first و all در حال حاضر معادل‌اند، چون وقتی Mattermost یک ریشه thread داشته باشد، chunkهای پیگیری و رسانه‌ها در همان thread ادامه پیدا می‌کنند.

# کنترل دسترسی (DMها)

• پیش‌فرض: channels.mattermost.dmPolicy = "pairing" (فرستنده‌های ناشناس یک کد pairing دریافت می‌کنند).
• تأیید از طریق:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• DMهای عمومی: channels.mattermost.dmPolicy="open" به‌همراه channels.mattermost.allowFrom=["*"].

# کانال‌ها (گروه‌ها)

• پیش‌فرض: channels.mattermost.groupPolicy = "allowlist" (محدودشده با mention).
• فرستنده‌ها را با channels.mattermost.groupAllowFrom در allowlist قرار دهید (شناسه‌های کاربری توصیه می‌شوند).
• بازنویسی‌های mention برای هر کانال زیر channels.mattermost.groups.<channelId>.requireMention یا برای مقدار پیش‌فرض زیر channels.mattermost.groups["*"].requireMention قرار می‌گیرند.
• تطبیق @username تغییرپذیر است و فقط وقتی channels.mattermost.dangerouslyAllowNameMatching: true فعال باشد، فعال می‌شود.
• کانال‌های باز: channels.mattermost.groupPolicy="open" (محدودشده با mention).
• نکته runtime: اگر channels.mattermost کاملاً وجود نداشته باشد، runtime برای بررسی‌های گروه به groupPolicy="allowlist" fallback می‌کند (حتی اگر channels.defaults.groupPolicy تنظیم شده باشد).

نمونه:

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

# هدف‌ها برای تحویل خروجی

از این قالب‌های هدف با openclaw message send یا cron/webhooks استفاده کنید:

• channel:<id> برای یک کانال
• user:<id> برای یک DM
• @username برای یک DM (از طریق API Mattermost resolve می‌شود)

# تلاش دوباره برای کانال DM

وقتی OpenClaw به یک هدف DM در Mattermost پیام می‌فرستد و ابتدا باید کانال مستقیم را resolve کند، به‌طور پیش‌فرض شکست‌های گذرای ایجاد کانال مستقیم را دوباره تلاش می‌کند.

برای تنظیم این رفتار به‌صورت سراسری برای Plugin Mattermost از channels.mattermost.dmChannelRetry، یا برای یک حساب از channels.mattermost.accounts.<id>.dmChannelRetry استفاده کنید.

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

نکته‌ها:

• این فقط روی ایجاد کانال DM (/api/v4/channels/direct) اعمال می‌شود، نه هر فراخوانی API Mattermost.
• تلاش‌های دوباره روی شکست‌های گذرا مانند rate limitها، پاسخ‌های 5xx و خطاهای شبکه یا timeout اعمال می‌شوند.
• خطاهای client از نوع 4xx به‌جز 429 دائمی در نظر گرفته می‌شوند و دوباره تلاش نمی‌شوند.

# استریم پیش‌نمایش

Mattermost فرایند فکر کردن، فعالیت ابزار و متن پاسخ جزئی را در یک پست پیش‌نویس پیش‌نمایش واحد stream می‌کند که وقتی پاسخ نهایی برای ارسال امن باشد، در همان‌جا نهایی می‌شود. پیش‌نمایش به‌جای پر کردن کانال با پیام‌های هر chunk، روی همان post id به‌روزرسانی می‌شود. خروجی‌های نهایی رسانه/خطا، ویرایش‌های معلق پیش‌نمایش را لغو می‌کنند و به‌جای flush کردن یک پست پیش‌نمایش دورریختنی، از تحویل عادی استفاده می‌کنند.

فعال‌سازی از طریق channels.mattermost.streaming:

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

# واکنش‌ها (ابزار پیام)

• از message action=react با channel=mattermost استفاده کنید.
• messageId شناسه پست Mattermost است.
• emoji نام‌هایی مانند thumbsup یا :+1: را می‌پذیرد (دو نقطه‌ها اختیاری هستند).
• برای حذف یک واکنش، remove=true (boolean) را تنظیم کنید.
• رویدادهای افزودن/حذف واکنش به‌عنوان رویدادهای سیستمی به session عامل routeشده فوروارد می‌شوند.

نمونه‌ها:

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

از message action=send با پارامتر buttons استفاده کنید. دکمه‌ها یک آرایه دوبعدی هستند (ردیف‌های دکمه‌ها):

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

فیلدهای دکمه:

وقتی کاربری روی دکمه‌ای کلیک می‌کند:

# یکپارچه‌سازی مستقیم API (اسکریپت‌های خارجی)

اسکریپت‌های خارجی و webhooks می‌توانند به‌جای عبور از ابزار message متعلق به agent، دکمه‌ها را مستقیماً از طریق Mattermost REST API ارسال کنند. در صورت امکان از buildButtonAttachments() در Plugin استفاده کنید؛ اگر JSON خام ارسال می‌کنید، این قواعد را دنبال کنید:

ساختار 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
              },
            },
          },
        ],
      },
    ],
  },
}

تولید توکن 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}

# آداپتر دایرکتوری

Plugin مربوط به Mattermost شامل یک آداپتر دایرکتوری است که نام کانال‌ها و کاربران را از طریق Mattermost API حل می‌کند. این کار هدف‌های #channel-name و @username را در openclaw message send و تحویل‌های cron/webhook فعال می‌کند.

هیچ پیکربندی‌ای لازم نیست - آداپتر از توکن 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" },
      },
    },
  },
}

# عیب‌یابی

# مرتبط

• مسیریابی کانال - مسیریابی نشست برای پیام‌ها
• نمای کلی کانال‌ها - همهٔ کانال‌های پشتیبانی‌شده
• گروه‌ها - رفتار گفت‌وگوی گروهی و گیت mention
• جفت‌سازی - احراز هویت DM و جریان جفت‌سازی
• امنیت - مدل دسترسی و مقاوم‌سازی