Mattermost

ステータス: ダウンロード可能なPlugin（ボットトークン + WebSocketイベント）。チャンネル、プライベートチャンネル、グループDM、DMに対応しています。Mattermostはセルフホスト可能なチームメッセージングプラットフォームです（mattermost.com）。

インストール

openclaw plugins install @openclaw/mattermost

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

詳細: Plugin

クイックセットアップ

{  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

ネイティブスラッシュコマンド

ネイティブスラッシュコマンドはオプトインです。有効にすると、OpenClawはボットが所属するすべてのチームにoc_*スラッシュコマンドを登録し、Gateway HTTPサーバーでコールバックPOSTを受信します。

{  channels: {    mattermost: {      commands: {        native: true,        nativeSkills: true,        callbackPath: "/api/channels/mattermost/command",        // MattermostからGatewayへ直接到達できない場合に使用します（リバースプロキシ/公開URL）。        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",      },    },  },}

登録されるコマンド: /oc_status、/oc_model、/oc_models、/oc_new、/oc_help、/oc_think、/oc_reasoning、/oc_verbose、/oc_queue。nativeSkills: trueを指定すると、スキルコマンドも/oc_<skill>として登録されます。

環境変数（デフォルトアカウント）

環境変数を使用する場合は、Gatewayホストに以下を設定します。

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

チャットモード

Mattermost は DM に自動的に応答します。チャンネルでの動作は chatmode で制御します。

設定例：

{  channels: {    mattermost: {      chatmode: "onchar",      oncharPrefixes: [">", "!"], // デフォルト    },  },}

注：

• onchar でも明示的な @メンションには応答します。
• channels.mattermost.requireMention も引き続き適用されますが、chatmode が推奨されます。チャンネルごとの groups.<channelId>.requireMention 設定は、どちらよりも優先されます。
• ボットがチャンネルのスレッドに表示される返信を送信した後は、同じスレッド内の後続メッセージに新たな @メンションや onchar プレフィックスがなくても応答するため、複数ターンのスレッド会話が継続します。参加状態は、そのスレッドでボットが最後に返信してから 7 日間記憶され、Gateway の再起動後も保持されます。ボットが閲覧しただけのスレッドには影響しません。明示的なメンションを再び必須にするには、新しいトップレベルメッセージを開始してください。
• 参加済みスレッドのフォローアップがメンションゲートを回避しないようにするには、channels.mattermost.implicitMentions.threadParticipation: false を設定します。アカウント単位のオーバーライドには channels.mattermost.accounts.<id>.implicitMentions を使用します。現在 Mattermost は replyToBot または quotedBot の情報を生成しないため、これらのフラグはここでは効果がありません。

スレッドとセッション

チャンネルおよびグループへの返信をメインチャンネルに残すか、トリガーとなった投稿の下にスレッドを開始するかを制御するには、channels.mattermost.replyToMode を使用します。

• off（デフォルト）：受信した投稿がすでにスレッド内にある場合にのみ、スレッド内で返信します。
• first：トップレベルのチャンネル／グループ投稿では、その投稿の下にスレッドを開始し、会話をスレッドスコープのセッションにルーティングします。
• all と batched：現在の Mattermost では first と同じ動作です。Mattermost にスレッドルートが作成されると、後続のチャンクとメディアも同じスレッド内で継続するためです。
• replyToMode が設定されている場合でも、ダイレクトメッセージのデフォルトは off です。

direct、group、または channel のチャットでモードをオーバーライドするには、channels.mattermost.replyToModeByChatType を使用します。ダイレクトメッセージでスレッドを使用するには、direct を設定します。

• off（デフォルト）：ダイレクトメッセージはスレッド化されず、1 つの継続的なセッションに保持されます。
• first、all、または batched：トップレベルのダイレクトメッセージごとに、新しい独立したセッションを使用する Mattermost スレッドを開始します。

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

注：

• スレッドスコープのセッションでは、トリガーとなった投稿 ID をスレッドルートとして使用します。
• first と all は現在同等です。Mattermost にスレッドルートが作成されると、後続のチャンクとメディアも同じスレッド内で継続するためです。
• チャット種別ごとのオーバーライドは replyToMode より優先されます。direct のオーバーライドがなければ、既存のデプロイではスレッド化されていないフラットな DM が維持されます。

アクセス制御（DM）

• デフォルト：channels.mattermost.dmPolicy = "pairing"（不明な送信者にはペアリングコードが発行されます）。その他の値：allowlist、open、disabled。
• 承認方法：
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• 公開 DM：channels.mattermost.dmPolicy="open" と channels.mattermost.allowFrom=["*"]（設定スキーマによりワイルドカードが必須になります）。
• channels.mattermost.allowFrom にはユーザー ID（推奨）と accessGroup:<name> エントリを指定できます。アクセスグループを参照してください。

チャンネル（グループ）

• デフォルト：channels.mattermost.groupPolicy = "allowlist"（メンション必須）。
• channels.mattermost.groupAllowFrom で送信者を許可リストに登録します（ユーザー ID を推奨）。
• channels.mattermost.groupAllowFrom には accessGroup:<name> エントリを指定できます。アクセスグループを参照してください。
• チャンネルごとのメンションのオーバーライドは channels.mattermost.groups.<channelId>.requireMention に、デフォルト設定は channels.mattermost.groups["*"].requireMention に配置します。
• @username の照合は変更可能で、channels.mattermost.dangerouslyAllowNameMatching: true の場合にのみ有効になります。
• 公開チャンネル：channels.mattermost.groupPolicy="open"（メンション必須）。
• 解決順序：channels.mattermost.groupPolicy、次に channels.defaults.groupPolicy、最後に "allowlist"。
• ランタイムに関する注記：channels.mattermost セクションが完全に欠落している場合、グループチェックではランタイムがフェイルクローズして groupPolicy="allowlist" になります（channels.defaults.groupPolicy が設定されている場合も同様）。また、警告が一度だけログに記録されます。

例：

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

外部配信のターゲット

openclaw message send または cron/webhooks では、次のターゲット形式を使用します。

外部への送信では、メッセージごとに添付ファイルを最大 1 個までサポートします。複数のファイルは別々に分けて送信してください。

DM チャンネルの再試行

OpenClaw が Mattermost の DM ターゲットに送信する際、最初にダイレクトチャンネルを解決する必要がある場合、デフォルトでは一時的なダイレクトチャンネル作成エラーを再試行します。

Mattermost plugin 全体でこの動作を調整するには channels.mattermost.dmChannelRetry を、1 つのアカウントで調整するには channels.mattermost.accounts.<id>.dmChannelRetry を使用します。デフォルト値：

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

注：

• これは DM チャンネルの作成（/api/v4/channels/direct）のみに適用され、すべての Mattermost API 呼び出しには適用されません。
• 再試行ではジッター付き指数バックオフを使用し、レート制限、5xx レスポンス、ネットワークエラー、タイムアウトエラーなどの一時的なエラーに適用されます。
• 429 以外の 4xx クライアントエラーは永続的なエラーとして扱われ、再試行されません。

プレビューストリーミング

Mattermost は、思考、ツールのアクティビティ、返信の部分的なテキストを 下書きプレビュー投稿 にストリーミングし、最終回答を安全に送信できるようになると、その場で確定します。partial モードでは、チャンクごとのメッセージでチャンネルを埋め尽くす代わりに、同じ投稿 ID のプレビューを更新します。block モードでは、完了したテキストとツールアクティビティのブロックの間でプレビューが切り替わるため、前のブロックは次のブロックで上書きされず、それぞれ独立した投稿として表示されたままになります。メディアまたはエラーを含む最終回答では、保留中のプレビュー編集をキャンセルし、使い捨てのプレビュー投稿を確定する代わりに通常の配信を使用します。

プレビューストリーミングは partial モードで デフォルトで有効 です。channels.mattermost.streaming.mode で設定します（従来のスカラー値またはブール値の streaming は openclaw doctor --fix によって移行されます）：

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

リアクション（メッセージツール）

• message action=react を channel=mattermost とともに使用します。
• messageId は Mattermost の投稿 ID です。
• emoji には、thumbsup や :+1: のような名前を指定できます（コロンは省略可能です）。
• リアクションを削除するには remove=true（ブール値）を設定します。
• リアクションの追加および削除イベントは、メッセージと同じ DM／グループポリシーチェックに従い、ルーティングされたエージェントセッションへシステムイベントとして転送されます。

例：

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：リアクション操作を有効または無効にします（デフォルトは true）。
• アカウントごとの上書き：channels.mattermost.accounts.<id>.actions.reactions。

インタラクティブボタン（メッセージツール）

クリック可能なボタン付きのメッセージを送信します。ユーザーがボタンをクリックすると、エージェントは選択内容を受信して応答できます。

ボタンは、セマンティックな presentation ペイロード（通常のエージェント返信および message action=send 内）から生成されます。OpenClaw は値ボタンを Mattermost のインタラクティブボタンとしてレンダリングし、URL ボタンをメッセージテキスト内に表示したままにし、選択メニューを読みやすいテキストにダウングレードします。

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

プレゼンテーションボタンのフィールド：

エージェントのシステムプロンプトでボタンのサポートを通知するには、チャンネル機能に inlineButtons を追加します：

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

ユーザーがボタンをクリックした場合：

API の直接統合（外部スクリプト）

外部スクリプトと Webhook は、エージェントの message ツールを経由せず、Mattermost REST API を介してボタンを直接投稿できます。OpenClaw の message ツールを推奨します。直接統合する場合は、@openclaw/mattermost/api.js から buildButtonAttachments をインポートしてください。生の 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                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 API を介してチャンネル名とユーザー名を解決するディレクトリアダプターが含まれています。これにより、openclaw message send および cron/webhook 配信で #channel-name と @username のターゲットを使用できます。

設定は不要です。アダプターはアカウント設定の 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" },      },    },  },}

アカウントの値はトップレベルのフィールドを上書きします。アカウントが指定されていない場合に使用するアカウントは、channels.mattermost.defaultAccount で選択します。

トラブルシューティング

関連項目

• チャンネルルーティング - メッセージのセッションルーティング
• チャンネルの概要 - サポートされているすべてのチャンネル
• グループ - グループチャットの動作とメンションによる制御
• ペアリング - DM の認証とペアリングの流れ
• セキュリティ - アクセスモデルと堅牢化