Mattermost

الحالة: Plugin قابل للتنزيل (رمز bot + أحداث WebSocket). القنوات والمجموعات والرسائل المباشرة مدعومة. 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_* عبر واجهة Mattermost API ويتلقى طلبات POST للردود على خادم 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",
      },
    },
  },
}

# متغيرات البيئة (الحساب الافتراضي)

اضبط هذه على مضيف Gateway إذا كنت تفضل متغيرات البيئة:

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

# أوضاع الدردشة

يرد Mattermost على الرسائل المباشرة تلقائيًا. يتحكم chatmode في سلوك القناة:

مثال الإعداد:

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

ملاحظات:

• لا يزال onchar يرد على @الإشارات الصريحة.
• يتم احترام channels.mattermost.requireMention للإعدادات القديمة، لكن chatmode مفضّل.

# المحادثات المتسلسلة والجلسات

استخدم channels.mattermost.replyToMode للتحكم فيما إذا كانت ردود القنوات والمجموعات تبقى في القناة الرئيسية أو تبدأ سلسلة محادثة تحت المنشور المشغّل.

• off (افتراضي): الرد في سلسلة محادثة فقط عندما يكون المنشور الوارد موجودًا فيها بالفعل.
• first: لمنشورات القناة/المجموعة ذات المستوى الأعلى، ابدأ سلسلة محادثة تحت ذلك المنشور ووجّه المحادثة إلى جلسة بنطاق سلسلة المحادثة.
• all: السلوك نفسه مثل first في Mattermost اليوم.
• تتجاهل الرسائل المباشرة هذا الإعداد وتبقى غير متسلسلة.

مثال الإعداد:

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

ملاحظات:

• تستخدم الجلسات بنطاق سلسلة المحادثة معرّف المنشور المشغّل كجذر لسلسلة المحادثة.
• first وall متكافئان حاليًا لأنه بمجرد أن يصبح لدى Mattermost جذر سلسلة محادثة، تستمر المقاطع اللاحقة والوسائط في سلسلة المحادثة نفسها.

# التحكم في الوصول (الرسائل المباشرة)

• الافتراضي: channels.mattermost.dmPolicy = "pairing" (يحصل المرسلون غير المعروفين على رمز إقران).
• الموافقة عبر:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• الرسائل المباشرة العامة: channels.mattermost.dmPolicy="open" بالإضافة إلى channels.mattermost.allowFrom=["*"].

# القنوات (المجموعات)

• الافتراضي: channels.mattermost.groupPolicy = "allowlist" (مقيّدة بالإشارة).
• اسمح للمرسلين باستخدام channels.mattermost.groupAllowFrom (يوصى بمعرّفات المستخدمين).
• تجاوزات الإشارة لكل قناة موجودة ضمن channels.mattermost.groups.<channelId>.requireMention أو channels.mattermost.groups["*"].requireMention كافتراضي.
• مطابقة @username قابلة للتغيير ولا تُفعّل إلا عندما تكون channels.mattermost.dangerouslyAllowNameMatching: true.
• القنوات المفتوحة: channels.mattermost.groupPolicy="open" (مقيّدة بالإشارة).
• ملاحظة وقت التشغيل: إذا كان channels.mattermost مفقودًا تمامًا، يعود وقت التشغيل إلى groupPolicy="allowlist" لفحوصات المجموعات (حتى إذا كان channels.defaults.groupPolicy مضبوطًا).

مثال:

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

# الأهداف للتسليم الصادر

استخدم صيغ الأهداف هذه مع openclaw message send أو cron/webhooks:

• channel:<id> لقناة
• user:<id> لرسالة مباشرة
• @username لرسالة مباشرة (تُحل عبر واجهة Mattermost API)

# إعادة محاولة قناة الرسائل المباشرة

عندما يرسل OpenClaw إلى هدف رسالة مباشرة في Mattermost ويحتاج إلى حل القناة المباشرة أولًا، فإنه يعيد محاولة إخفاقات إنشاء القناة المباشرة العابرة افتراضيًا.

استخدم channels.mattermost.dmChannelRetry لضبط هذا السلوك عمومًا لـ Mattermost plugin، أو channels.mattermost.accounts.<id>.dmChannelRetry لحساب واحد.

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

ملاحظات:

• ينطبق هذا فقط على إنشاء قناة الرسائل المباشرة (/api/v4/channels/direct)، وليس كل استدعاء لواجهة Mattermost API.
• تنطبق إعادة المحاولة على الإخفاقات العابرة مثل حدود المعدل، واستجابات 5xx، وأخطاء الشبكة أو انتهاء المهلة.
• تُعامل أخطاء العميل 4xx غير 429 على أنها دائمة ولا تُعاد محاولتها.

# بث المعاينة

يبث Mattermost التفكير، ونشاط الأدوات، ونص الرد الجزئي في منشور معاينة مسودة واحد يُنهى في مكانه عندما تكون الإجابة النهائية آمنة للإرسال. تُحدّث المعاينة على معرّف المنشور نفسه بدل إغراق القناة برسائل لكل مقطع. تلغي النهائيات الخاصة بالوسائط/الأخطاء تعديلات المعاينة المعلقة وتستخدم التسليم العادي بدل تفريغ منشور معاينة مؤقت.

فعّل عبر channels.mattermost.streaming:

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

# التفاعلات (أداة الرسائل)

• استخدم message action=react مع channel=mattermost.
• messageId هو معرّف منشور Mattermost.
• يقبل emoji أسماء مثل thumbsup أو :+1: (النقطتان اختياريتان).
• اضبط remove=true (منطقي) لإزالة تفاعل.
• تُمرر أحداث إضافة/إزالة التفاعلات كأحداث نظام إلى جلسة الوكيل الموجّهة.

أمثلة:

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 نشر الأزرار مباشرة عبر واجهة برمجة تطبيقات Mattermost REST بدلًا من المرور عبر أداة message الخاصة بالوكيل. استخدم buildButtonAttachments() من Plugin عندما يكون ذلك ممكنًا؛ وإذا نشرت JSON خامًا، فاتبع هذه القواعد:

بنية الحمولة:

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

# محوّل الدليل

يتضمن Mattermost Plugin محوّل دليل يحل أسماء القنوات والمستخدمين عبر واجهة برمجة تطبيقات Mattermost. يتيح هذا أهداف #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" },
      },
    },
  },
}

# استكشاف الأخطاء وإصلاحها

# ذات صلة

• توجيه القنوات - توجيه الجلسات للرسائل
• نظرة عامة على القنوات - جميع القنوات المدعومة
• المجموعات - سلوك محادثات المجموعات وبوابة الإشارات
• الإقران - مصادقة الرسائل المباشرة وتدفق الإقران
• الأمان - نموذج الوصول والتقوية