Mattermost

ステータス: ダウンロード可能な Plugin (ボットトークン + WebSocket イベント)。チャンネル、グループ、DM に対応しています。Mattermost はセルフホスト可能なチームメッセージングプラットフォームです。製品詳細とダウンロードについては、公式サイト mattermost.com を参照してください。

# インストール

チャンネルを設定する前に Mattermost をインストールしてください:

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

# 環境変数 (デフォルトアカウント)

環境変数を使用する場合は、Gateway ホストでこれらを設定します:

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

# チャットモード

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

設定例:

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

メモ:

• onchar は明示的な @メンションにも引き続き応答します。
• channels.mattermost.requireMention はレガシー設定では尊重されますが、chatmode が推奨されます。

# スレッドとセッション

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

• off (デフォルト): 受信投稿がすでにスレッド内にある場合にのみ、スレッド内で返信します。
• first: トップレベルのチャンネル/グループ投稿の場合、その投稿の下にスレッドを開始し、会話をスレッドスコープのセッションにルーティングします。
• all: 現在の Mattermost では first と同じ動作です。
• ダイレクトメッセージはこの設定を無視し、スレッド化されません。

設定例:

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

メモ:

• スレッドスコープのセッションは、トリガーとなった投稿 ID をスレッドルートとして使用します。
• first と all は現在同等です。Mattermost にスレッドルートがあると、後続のチャンクとメディアは同じスレッド内で継続されるためです。

# アクセス制御 (DM)

• デフォルト: channels.mattermost.dmPolicy = "pairing" (不明な送信者にはペアリングコードが付与されます)。
• 承認方法:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• 公開 DM: channels.mattermost.dmPolicy="open" に加えて channels.mattermost.allowFrom=["*"]。

# チャンネル (グループ)

• デフォルト: channels.mattermost.groupPolicy = "allowlist" (メンションゲート付き)。
• channels.mattermost.groupAllowFrom で送信者を許可リストに登録します (ユーザー ID 推奨)。
• チャンネルごとのメンション上書きは、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/Webhook では、これらのターゲット形式を使用します:

• チャンネルには channel:<id>
• DM には user:<id>
• DM には @username (Mattermost API 経由で解決)

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

メモ:

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

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

Mattermost は思考、ツールアクティビティ、部分的な返信テキストを 1 つの下書きプレビュー投稿にストリーミングし、最終回答を安全に送信できるようになった時点でその場で確定します。プレビューはチャンクごとのメッセージでチャンネルを埋めるのではなく、同じ投稿 ID 上で更新されます。メディア/エラーの最終応答では、保留中のプレビュー編集をキャンセルし、使い捨てのプレビュー投稿をフラッシュする代わりに通常の配信を使用します。

channels.mattermost.streaming で有効にします:

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

# リアクション (メッセージツール)

• channel=mattermost で message action=react を使用します。
• messageId は Mattermost の投稿 ID です。
• 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"],
    },
  },
}

buttons パラメーター付きで message action=send を使用します。ボタンは 2D 配列 (ボタンの行) です:

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

ボタンフィールド:

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

# 直接 API 連携（外部スクリプト）

外部スクリプトと Webhook は、エージェントの message ツールを経由する代わりに、Mattermost REST API を使ってボタンを直接投稿できます。可能な場合は Plugin の 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 (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 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" },
      },
    },
  },
}

# トラブルシューティング

# 関連

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