Developer and self-hosted
Mattermost
स्थिति: डाउनलोड करने योग्य Plugin (बॉट टोकन + WebSocket इवेंट)। चैनल, समूह और DM समर्थित हैं। Mattermost एक स्वयं-होस्ट करने योग्य टीम मैसेजिंग प्लेटफ़ॉर्म है; उत्पाद विवरण और डाउनलोड के लिए आधिकारिक साइट mattermost.com देखें।
इंस्टॉल करें
चैनल कॉन्फ़िगर करने से पहले Mattermost इंस्टॉल करें:
npm registry
openclaw plugins install @openclaw/mattermostLocal checkout
openclaw plugins install ./path/to/local/mattermost-pluginविवरण: Plugins
त्वरित सेटअप
Ensure plugin is available
ऊपर दिए गए कमांड से @openclaw/mattermost इंस्टॉल करें, फिर यदि Gateway पहले से चल रहा है तो उसे रीस्टार्ट करें।
Create a Mattermost bot
Mattermost बॉट खाता बनाएं और बॉट टोकन कॉपी करें।
Copy the base URL
Mattermost बेस URL कॉपी करें (जैसे, https://chat.example.com)।
Configure OpenClaw and start the gateway
न्यूनतम कॉन्फ़िग:
{ channels: { mattermost: { enabled: true, botToken: "mm-token", baseUrl: "https://chat.example.com", dmPolicy: "pairing", }, },}नेटिव स्लैश कमांड
नेटिव स्लैश कमांड ऑप्ट-इन हैं। सक्षम होने पर, OpenClaw Mattermost API के माध्यम से oc_* स्लैश कमांड रजिस्टर करता है और Gateway HTTP सर्वर पर कॉलबैक POST प्राप्त करता है।
{ 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", }, }, },}Behavior notes
native: "auto"Mattermost के लिए डिफ़ॉल्ट रूप से अक्षम रहता है। सक्षम करने के लिएnative: trueसेट करें।- यदि
callbackUrlछोड़ा गया है, तो OpenClaw Gateway होस्ट/पोर्ट +callbackPathसे एक बनाता है। - मल्टी-अकाउंट सेटअप के लिए,
commandsको शीर्ष स्तर पर याchannels.mattermost.accounts.<id>.commandsके अंतर्गत सेट किया जा सकता है (अकाउंट मान शीर्ष-स्तरीय फ़ील्ड को ओवरराइड करते हैं)। - कमांड कॉलबैक उन प्रति-कमांड टोकन से सत्यापित होते हैं जो OpenClaw द्वारा
oc_*कमांड रजिस्टर करने पर Mattermost लौटाता है। - OpenClaw प्रत्येक कॉलबैक स्वीकार करने से पहले वर्तमान Mattermost कमांड रजिस्ट्रेशन रीफ़्रेश करता है, ताकि हटाए गए या फिर से जनरेट किए गए स्लैश कमांड के पुराने टोकन Gateway रीस्टार्ट के बिना स्वीकार होना बंद हो जाएं।
- यदि Mattermost API यह पुष्टि नहीं कर सकता कि कमांड अभी भी वर्तमान है, तो कॉलबैक सत्यापन बंद-स्थिति में विफल होता है; विफल सत्यापन थोड़े समय के लिए कैश होते हैं, समवर्ती लुकअप को मिलाया जाता है, और ताज़े लुकअप की शुरुआत को प्रति कमांड रेट-लिमिट किया जाता है ताकि रीप्ले दबाव सीमित रहे।
- जब रजिस्ट्रेशन विफल हुआ हो, स्टार्टअप आंशिक रहा हो, या कॉलबैक टोकन resolved कमांड के रजिस्टर्ड टोकन से मेल न खाता हो, तो स्लैश कॉलबैक बंद-स्थिति में विफल होते हैं (एक कमांड के लिए वैध टोकन किसी दूसरे कमांड के लिए upstream सत्यापन तक नहीं पहुंच सकता)।
Reachability requirement
कॉलबैक endpoint Mattermost सर्वर से पहुंच योग्य होना चाहिए।
callbackUrlकोlocalhostपर सेट न करें, जब तक Mattermost उसी होस्ट/नेटवर्क नेमस्पेस पर OpenClaw के साथ न चल रहा हो।callbackUrlको अपने Mattermost बेस URL पर सेट न करें, जब तक वह URL/api/channels/mattermost/commandको OpenClaw पर रिवर्स-प्रॉक्सी न करता हो।- एक त्वरित जांच
curl https://<gateway-host>/api/channels/mattermost/commandहै; GET को OpenClaw से405 Method Not Allowedलौटाना चाहिए,404नहीं।
Mattermost egress allowlist
यदि आपका कॉलबैक निजी/tailnet/आंतरिक पतों को लक्षित करता है, तो Mattermost ServiceSettings.AllowedUntrustedInternalConnections को कॉलबैक होस्ट/डोमेन शामिल करने के लिए सेट करें।
पूर्ण URL नहीं, होस्ट/डोमेन प्रविष्टियां उपयोग करें।
- सही:
gateway.tailnet-name.ts.net - गलत:
https://gateway.tailnet-name.ts.net
पर्यावरण चर (डिफ़ॉल्ट अकाउंट)
यदि आप env vars पसंद करते हैं, तो इन्हें Gateway होस्ट पर सेट करें:
MATTERMOST_BOT_TOKEN=...MATTERMOST_URL=https://chat.example.com
चैट मोड
Mattermost DM का अपने-आप उत्तर देता है। चैनल व्यवहार chatmode से नियंत्रित होता है:
oncall (default)
चैनलों में केवल @mention किए जाने पर उत्तर दें।
onmessage
हर चैनल संदेश का उत्तर दें।
onchar
जब संदेश trigger prefix से शुरू हो, तब उत्तर दें।
कॉन्फ़िग उदाहरण:
{ channels: { mattermost: { chatmode: "onchar", oncharPrefixes: [">", "!"], }, },}नोट्स:
oncharफिर भी स्पष्ट @mentions का उत्तर देता है।- लेगेसी कॉन्फ़िग के लिए
channels.mattermost.requireMentionका सम्मान किया जाता है, लेकिनchatmodeको प्राथमिकता दी जाती है। - बॉट द्वारा चैनल थ्रेड में दृश्यमान उत्तर भेजने के बाद, उसी थ्रेड में बाद के संदेशों का उत्तर नए @mention या
oncharprefix के बिना दिया जाता है, ताकि बहु-टर्न थ्रेड वार्तालाप चलते रहें। भागीदारी थ्रेड निष्क्रियता के 7 दिनों तक याद रखी जाती है (हर उत्तर पर रीफ़्रेश होती है) और Gateway रीस्टार्ट के बाद भी बनी रहती है। जिन थ्रेड को बॉट ने केवल देखा है, वे अप्रभावित रहते हैं; फिर से स्पष्ट mention आवश्यक करने के लिए नया top-level संदेश शुरू करें।
थ्रेडिंग और सेशन
channels.mattermost.replyToMode का उपयोग करके नियंत्रित करें कि चैनल और समूह उत्तर मुख्य चैनल में रहें या triggering पोस्ट के अंतर्गत थ्रेड शुरू करें।
off(डिफ़ॉल्ट): केवल तब थ्रेड में उत्तर दें जब inbound पोस्ट पहले से किसी थ्रेड में हो।first: top-level चैनल/समूह पोस्ट के लिए, उस पोस्ट के अंतर्गत थ्रेड शुरू करें और वार्तालाप को thread-scoped session पर रूट करें।all: Mattermost के लिए आजfirstजैसा ही व्यवहार।- डायरेक्ट मैसेज इस सेटिंग को अनदेखा करते हैं और non-threaded रहते हैं।
कॉन्फ़िग उदाहरण:
{ channels: { mattermost: { replyToMode: "all", }, },}नोट्स:
- Thread-scoped sessions triggering पोस्ट id को thread root के रूप में उपयोग करते हैं।
firstऔरallअभी समान हैं क्योंकि Mattermost के पास thread root हो जाने पर follow-up chunks और media उसी थ्रेड में जारी रहते हैं।
एक्सेस नियंत्रण (DMs)
- डिफ़ॉल्ट:
channels.mattermost.dmPolicy = "pairing"(अज्ञात भेजने वालों को pairing code मिलता है)। - इसके माध्यम से अनुमोदित करें:
openclaw pairing list mattermostopenclaw pairing approve mattermost <CODE>
- सार्वजनिक DMs:
channels.mattermost.dmPolicy="open"औरchannels.mattermost.allowFrom=["*"]। channels.mattermost.allowFromaccessGroup:<name>प्रविष्टियां स्वीकार करता है। Access groups देखें।
चैनल (समूह)
- डिफ़ॉल्ट:
channels.mattermost.groupPolicy = "allowlist"(mention-gated)। channels.mattermost.groupAllowFromसे भेजने वालों को allowlist करें (user IDs अनुशंसित)।channels.mattermost.groupAllowFromaccessGroup:<name>प्रविष्टियां स्वीकार करता है। Access groups देखें।- प्रति-चैनल mention overrides
channels.mattermost.groups.<channelId>.requireMentionया डिफ़ॉल्ट के लिएchannels.mattermost.groups["*"].requireMentionके अंतर्गत रहते हैं। @usernamematching mutable है और केवल तब सक्षम होता है जबchannels.mattermost.dangerouslyAllowNameMatching: trueहो।- खुले चैनल:
channels.mattermost.groupPolicy="open"(mention-gated)। - रनटाइम नोट: यदि
channels.mattermostपूरी तरह अनुपस्थित है, तो रनटाइम समूह जांचों के लिएgroupPolicy="allowlist"पर fallback करता है (भले हीchannels.defaults.groupPolicyसेट हो)।
उदाहरण:
{ channels: { mattermost: { groupPolicy: "open", groups: { "*": { requireMention: true }, "team-channel-id": { requireMention: false }, }, }, },}आउटबाउंड डिलीवरी के लिए target
इन target formats को openclaw message send या Cron/Webhook के साथ उपयोग करें:
- चैनल के लिए
channel:<id> - DM के लिए
user:<id> - DM के लिए
@username(Mattermost API के माध्यम से resolved)
DM चैनल retry
जब OpenClaw Mattermost DM target को भेजता है और पहले direct channel resolve करना पड़ता है, तो यह डिफ़ॉल्ट रूप से transient direct-channel creation failures को retry करता है।
Mattermost Plugin के लिए इस व्यवहार को globally tune करने के लिए channels.mattermost.dmChannelRetry उपयोग करें, या किसी एक अकाउंट के लिए channels.mattermost.accounts.<id>.dmChannelRetry।
{ channels: { mattermost: { dmChannelRetry: { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 10000, timeoutMs: 30000, }, }, },}नोट्स:
- यह केवल DM channel creation (
/api/v4/channels/direct) पर लागू होता है, हर Mattermost API call पर नहीं। - Retries transient failures पर लागू होते हैं, जैसे rate limits, 5xx responses, और network या timeout errors।
429के अलावा 4xx client errors को स्थायी माना जाता है और retry नहीं किया जाता।
प्रीव्यू स्ट्रीमिंग
Mattermost thinking, tool activity, और partial reply text को एक draft preview post में stream करता है, जो अंतिम उत्तर भेजने के लिए सुरक्षित होने पर उसी स्थान पर final हो जाता है। Preview updates प्रति-chunk messages से चैनल को spam करने के बजाय उसी post id पर होते हैं। Media/error finals pending preview edits को cancel करते हैं और throwaway preview post flush करने के बजाय सामान्य delivery उपयोग करते हैं।
channels.mattermost.streaming के माध्यम से सक्षम करें:
{ channels: { mattermost: { streaming: "partial", // off | partial | block | progress }, },}Streaming modes
partialसामान्य विकल्प है: एक preview post जिसे reply बढ़ने पर edit किया जाता है, फिर पूर्ण उत्तर के साथ final किया जाता है।blockpreview post के अंदर append-style draft chunks उपयोग करता है।progressgeneration के दौरान status preview दिखाता है और completion पर ही अंतिम उत्तर पोस्ट करता है।offpreview streaming को अक्षम करता है।
Streaming behavior notes
- यदि stream को उसी स्थान पर final नहीं किया जा सकता (उदाहरण के लिए post mid-stream में delete हो गया), तो OpenClaw नया final post भेजने पर fallback करता है ताकि reply कभी खोए नहीं।
- Thinking-only payloads को channel posts से suppress किया जाता है, जिसमें वह text भी शामिल है जो
> Thinkingblockquote के रूप में आता है। अन्य surfaces में thinking देखने के लिए/reasoning onसेट करें; Mattermost final post केवल उत्तर रखता है। - channel-mapping matrix के लिए Streaming देखें।
Reactions (message tool)
channel=mattermostके साथmessage action=reactउपयोग करें।messageIdMattermost post id है।emojithumbsupया:+1:जैसे names स्वीकार करता है (colons वैकल्पिक हैं)।- reaction हटाने के लिए
remove=true(boolean) सेट करें। - Reaction add/remove events routed agent session को system events के रूप में forward किए जाते हैं।
उदाहरण:
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कॉन्फ़िग:
channels.mattermost.actions.reactions: reaction actions सक्षम/अक्षम करें (डिफ़ॉल्ट true)।- प्रति-अकाउंट override:
channels.mattermost.accounts.<id>.actions.reactions।
Interactive buttons (message tool)
Clickable buttons वाले संदेश भेजें। जब user button पर क्लिक करता है, तो agent selection प्राप्त करता है और उत्तर दे सकता है।
सामान्य एजेंट उत्तरों में semantic presentation payloads भी शामिल हो सकते हैं। OpenClaw value बटनों को Mattermost interactive buttons के रूप में render करता है, URL बटनों को message text में visible रखता है, और select menus को readable text में downgrade करता है।
Channel capabilities में inlineButtons जोड़कर buttons enable करें:
{ channels: { mattermost: { capabilities: ["inlineButtons"], }, },}buttons parameter के साथ message action=send का उपयोग करें। Buttons एक 2D array होते हैं (buttons की rows):
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]Button fields:
textstringrequiredDisplay label.
callback_datastringrequiredClick पर वापस भेजा गया value (action ID के रूप में उपयोग होता है)।
style"default" | "primary" | "danger"Button style.
जब कोई user button पर click करता है:
Buttons replaced with confirmation
सभी buttons को confirmation line से बदल दिया जाता है (उदा., "✓ Yes selected by @user")।
Agent receives the selection
एजेंट selection को inbound message के रूप में प्राप्त करता है और जवाब देता है।
Implementation notes
- Button callbacks HMAC-SHA256 verification का उपयोग करते हैं (automatic, कोई config आवश्यक नहीं)।
- Mattermost अपने API responses से callback data हटा देता है (security feature), इसलिए click पर सभी buttons हटा दिए जाते हैं - partial removal संभव नहीं है।
- Hyphens या underscores वाले Action IDs अपने-आप sanitize हो जाते हैं (Mattermost routing limitation)।
Config and reachability
channels.mattermost.capabilities: capability strings की array। Agent system prompt में buttons tool description enable करने के लिए"inlineButtons"जोड़ें।channels.mattermost.interactions.callbackBaseUrl: button callbacks के लिए optional external base URL (उदाहरण के लिएhttps://gateway.example.com)। इसका उपयोग तब करें जब Mattermost gateway तक उसके bind host पर सीधे नहीं पहुंच सकता।- Multi-account setups में, आप वही field
channels.mattermost.accounts.<id>.interactions.callbackBaseUrlके अंतर्गत भी set कर सकते हैं। - यदि
interactions.callbackBaseUrlomit किया गया है, OpenClaw callback URL कोgateway.customBindHost+gateway.portसे derive करता है, फिरhttp://localhost:<port>पर fall back करता है। - Reachability rule: button callback URL Mattermost server से reachable होना चाहिए।
localhostकेवल तब काम करता है जब Mattermost और OpenClaw same host/network namespace पर run करते हैं। - यदि आपका callback target private/tailnet/internal है, तो उसके host/domain को Mattermost
ServiceSettings.AllowedUntrustedInternalConnectionsमें जोड़ें।
Direct API integration (external scripts)
External scripts और webhooks, एजेंट के message tool से गुजरने के बजाय Mattermost REST API के माध्यम से सीधे buttons post कर सकते हैं। जब संभव हो Plugin से buildButtonAttachments() का उपयोग करें; यदि raw JSON post कर रहे हैं, तो इन नियमों का पालन करें:
Payload structure:
{ 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 token generation
Gateway button clicks को HMAC-SHA256 से verify करता है। External scripts को ऐसे tokens generate करने होंगे जो Gateway की verification logic से match करें:
Derive the secret from the bot token
HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)
Build the context object
_token को छोड़कर सभी fields के साथ context object build करें।
Serialize with sorted keys
Sorted keys और no spaces के साथ serialize करें (Gateway sorted keys के साथ JSON.stringify का उपयोग करता है, जो compact output बनाता है)।
Sign the payload
HMAC-SHA256(key=secret, data=serializedContext)
Add the token
Resulting hex digest को context में _token के रूप में जोड़ें।
Python example:
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}Common HMAC pitfalls
- Python का
json.dumpsdefault रूप से spaces जोड़ता है ({"key": "val"})। JavaScript के compact output ({"key":"val"}) से match करने के लिएseparators=(",", ":")का उपयोग करें। - हमेशा सभी context fields (minus
_token) sign करें। Gateway_tokenstrip करता है, फिर बचे हुए सभी fields sign करता है। Subset sign करने से silent verification failure होता है। sort_keys=Trueका उपयोग करें - Gateway signing से पहले keys sort करता है, और Mattermost payload store करते समय context fields reorder कर सकता है।- Secret को bot token (deterministic) से derive करें, random bytes से नहीं। Secret, buttons बनाने वाली process और verify करने वाले Gateway में समान होना चाहिए।
Directory adapter
Mattermost Plugin में एक directory adapter शामिल है जो Mattermost API के माध्यम से channel और user names resolve करता है। इससे openclaw message send और cron/webhook deliveries में #channel-name और @username targets enable होते हैं।
कोई configuration आवश्यक नहीं है - adapter account config से bot token का उपयोग करता है।
Multi-account
Mattermost channels.mattermost.accounts के अंतर्गत multiple accounts support करता है:
{ 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" }, }, }, },}Troubleshooting
No replies in channels
सुनिश्चित करें कि bot channel में है और उसे mention करें (oncall), trigger prefix (onchar) का उपयोग करें, या chatmode: "onmessage" set करें।
Auth or multi-account errors
- Bot token, base URL, और account enabled है या नहीं, जांचें।
- Multi-account issues: env vars केवल
defaultaccount पर apply होते हैं।
Native slash commands fail
Unauthorized: invalid command token.: OpenClaw ने callback token accept नहीं किया। Typical causes:- slash command registration failed या startup पर केवल partially completed हुआ
- callback wrong Gateway/account पर hit कर रहा है
- Mattermost में अभी भी old commands हैं जो previous callback target की ओर point कर रहे हैं
- Gateway slash commands reactivate किए बिना restart हुआ
- यदि native slash commands काम करना बंद कर दें, तो logs में
mattermost: failed to register slash commandsयाmattermost: native slash commands enabled but no commands could be registeredदेखें। - यदि
callbackUrlomit किया गया है और logs warning देते हैं कि callbackhttp://127.0.0.1:18789/...पर resolved हुआ, तो वह URL शायद केवल तब reachable है जब Mattermost, OpenClaw के same host/network namespace पर run करता है। इसके बजाय explicit externally reachablecommands.callbackUrlset करें।
Buttons issues
- Buttons white boxes के रूप में appear होते हैं: एजेंट malformed button data भेज रहा हो सकता है। जांचें कि प्रत्येक button में
textऔरcallback_dataदोनों fields हैं। - Buttons render होते हैं लेकिन clicks कुछ नहीं करते: verify करें कि Mattermost server config में
AllowedUntrustedInternalConnectionsमें127.0.0.1 localhostशामिल है, और ServiceSettings मेंEnablePostActionIntegrationtrueहै। - Buttons click पर 404 return करते हैं: button
idमें संभवतः hyphens या underscores हैं। Mattermost का action router non-alphanumeric IDs पर break करता है। केवल[a-zA-Z0-9]का उपयोग करें। - Gateway logs
invalid _token: HMAC mismatch। जांचें कि आप सभी context fields sign करते हैं (subset नहीं), sorted keys का उपयोग करते हैं, और compact JSON (no spaces) का उपयोग करते हैं। ऊपर HMAC section देखें। - Gateway logs
missing _token in context:_tokenfield button के context में नहीं है। Integration payload build करते समय सुनिश्चित करें कि यह शामिल है। - Confirmation button name के बजाय raw ID दिखाता है:
context.action_idbutton केidसे match नहीं करता। दोनों को same sanitized value पर set करें। - Agent को buttons के बारे में पता नहीं है: Mattermost channel config में
capabilities: ["inlineButtons"]जोड़ें।
Related
- Channel Routing - messages के लिए session routing
- Channels Overview - सभी supported channels
- Groups - group chat behavior और mention gating
- Pairing - DM authentication और pairing flow
- Security - access model और hardening