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

# คำสั่งสแลชแบบเนทีฟ

คำสั่งสแลชแบบเนทีฟเป็นแบบเลือกเปิดใช้ เมื่อเปิดใช้ OpenClaw จะลงทะเบียนคำสั่งสแลช oc_* ผ่าน Mattermost API และรับ callback 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 ตอบกลับ DM โดยอัตโนมัติ พฤติกรรมของช่องควบคุมด้วย chatmode:

ตัวอย่างการกำหนดค่า:

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

หมายเหตุ:

• onchar ยังตอบกลับ @mention ที่ระบุชัดเจน
• channels.mattermost.requireMention ยังรองรับสำหรับการกำหนดค่าเก่า แต่แนะนำให้ใช้ chatmode

# เธรดและเซสชัน

ใช้ channels.mattermost.replyToMode เพื่อควบคุมว่าการตอบกลับในช่องและกลุ่มจะอยู่ในช่องหลักหรือเริ่มเธรดใต้โพสต์ที่ทริกเกอร์

• off (ค่าเริ่มต้น): ตอบกลับในเธรดเฉพาะเมื่อโพสต์ขาเข้าอยู่ในเธรดอยู่แล้ว
• first: สำหรับโพสต์ระดับบนสุดในช่อง/กลุ่ม ให้เริ่มเธรดใต้โพสต์นั้นและกำหนดเส้นทางการสนทนาไปยังเซสชันที่มีขอบเขตตามเธรด
• all: พฤติกรรมเหมือนกับ first สำหรับ Mattermost ในปัจจุบัน
• ข้อความโดยตรงจะไม่ใช้การตั้งค่านี้และยังคงไม่เป็นเธรด

ตัวอย่างการกำหนดค่า:

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

หมายเหตุ:

• เซสชันที่มีขอบเขตตามเธรดใช้ id ของโพสต์ที่ทริกเกอร์เป็นรากของเธรด
• ปัจจุบัน first และ all เทียบเท่ากัน เพราะเมื่อ Mattermost มีรากของเธรดแล้ว ชิ้นส่วนติดตามผลและสื่อจะดำเนินต่อในเธรดเดียวกันนั้น

# การควบคุมการเข้าถึง (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 (แนะนำให้ใช้ ID ผู้ใช้)
• การแทนที่ 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" สำหรับการตรวจสอบกลุ่ม (แม้จะตั้ง 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 (แก้หาผ่าน Mattermost API)

# การ retry ช่อง DM

เมื่อ OpenClaw ส่งไปยังเป้าหมาย DM ของ Mattermost และต้องแก้หาช่องโดยตรงก่อน โดยค่าเริ่มต้นจะ retry ความล้มเหลวชั่วคราวในการสร้างช่องโดยตรง

ใช้ channels.mattermost.dmChannelRetry เพื่อปรับพฤติกรรมนั้นโดยรวมสำหรับ Plugin Mattermost หรือ channels.mattermost.accounts.<id>.dmChannelRetry สำหรับบัญชีเดียว

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

หมายเหตุ:

• มีผลเฉพาะกับการสร้างช่อง DM (/api/v4/channels/direct) ไม่ใช่ทุกการเรียก Mattermost API
• การ retry ใช้กับความล้มเหลวชั่วคราว เช่น การจำกัดอัตรา การตอบกลับ 5xx และข้อผิดพลาดเครือข่ายหรือ timeout
• ข้อผิดพลาดไคลเอนต์ 4xx นอกเหนือจาก 429 ถือเป็นข้อผิดพลาดถาวรและจะไม่ retry

# การสตรีมตัวอย่าง

Mattermost สตรีมการคิด กิจกรรมของเครื่องมือ และข้อความตอบกลับบางส่วนลงใน โพสต์ตัวอย่างแบบร่าง เดียวที่ finalizes ในตำแหน่งเดิมเมื่อคำตอบสุดท้ายปลอดภัยที่จะส่ง ตัวอย่างจะอัปเดตบน id โพสต์เดียวกันแทนการสแปมช่องด้วยข้อความต่อชิ้น ส่วนสุดท้ายที่เป็นสื่อ/ข้อผิดพลาดจะยกเลิกการแก้ไขตัวอย่างที่ค้างอยู่และใช้การส่งปกติแทนการ flush โพสต์ตัวอย่างทิ้ง

เปิดใช้ผ่าน channels.mattermost.streaming:

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

# ปฏิกิริยา (เครื่องมือข้อความ)

• ใช้ message action=react กับ channel=mattermost
• messageId คือ id โพสต์ของ Mattermost
• emoji รับชื่อ เช่น thumbsup หรือ :+1: (โคลอนเป็นทางเลือก)
• ตั้งค่า remove=true (boolean) เพื่อลบปฏิกิริยา
• เหตุการณ์เพิ่ม/ลบปฏิกิริยาจะถูกส่งต่อเป็นเหตุการณ์ระบบไปยังเซสชัน agent ที่ถูกกำหนดเส้นทาง

ตัวอย่าง:

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

# ปุ่มโต้ตอบ (เครื่องมือข้อความ)

ส่งข้อความพร้อมปุ่มที่คลิกได้ เมื่อผู้ใช้คลิกปุ่ม agent จะได้รับการเลือกและสามารถตอบกลับได้

เปิดใช้ปุ่มโดยเพิ่ม inlineButtons ไปยังความสามารถของช่อง:

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

ใช้ message action=send พร้อมพารามิเตอร์ buttons ปุ่มเป็นอาร์เรย์ 2 มิติ (แถวของปุ่ม):

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

ฟิลด์ของปุ่ม:

เมื่อผู้ใช้คลิกปุ่ม:

# การผสานรวม API โดยตรง (สคริปต์ภายนอก)

สคริปต์ภายนอกและ webhooks สามารถโพสต์ปุ่มโดยตรงผ่าน Mattermost REST API แทนการผ่านเครื่องมือ message ของเอเจนต์ ใช้ 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 มีอะแดปเตอร์ไดเรกทอรีที่ resolve ชื่อช่องและชื่อผู้ใช้ผ่าน Mattermost API ซึ่งเปิดใช้งานเป้าหมาย #channel-name และ @username ใน openclaw message send และการส่ง cron/webhook

ไม่ต้องตั้งค่า - อะแดปเตอร์ใช้ bot token จากการตั้งค่าบัญชี

# หลายบัญชี

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

# การแก้ไขปัญหา

# ที่เกี่ยวข้อง

• การกำหนดเส้นทางช่อง - การกำหนดเส้นทางเซสชันสำหรับข้อความ
• ภาพรวมช่อง - ช่องที่รองรับทั้งหมด
• กลุ่ม - พฤติกรรมแชตกลุ่มและการ gating การ mention
• การจับคู่ - การตรวจสอบสิทธิ์ DM และโฟลว์การจับคู่
• ความปลอดภัย - โมเดลการเข้าถึงและการเสริมความแข็งแกร่ง