Mattermost

REST v4 ポーリングおよび WebSocket クライアント。デフォルトでは、ボットは新しい投稿がないか 3 秒ごとにチャンネルをポーリングします。永続的な WebSocket 接続を介したほぼリアルタイムのイベント配信を行うには、listen_mode = "websocket" を設定します。リッスンモードに関係なく、返信の投稿は常に POST /api/v4/posts を介して送信されます。

エージェントと対話できるユーザー

受信側の送信者は、バインドされたエージェントに対して解決されたピアセットに照らして制御されます。これはエージェントが所属する peer_groups 設定から導出されます。照合では先頭の @ を取り除き、チャネルのネイティブな送信者識別子に対して大文字・小文字を区別せずに行われます。空のセットはすべてを拒否し、"*" を含むセットはすべてを受け入れます。それ以外の場合は、リストに記載された外部ピア（およびピアエージェント）のみが受け入れられます。これはゲートウェイのペアリング（gateway.require_pairing）とは別物であり、ペアリングはチャットチャネルの送信者ではなく HTTP/WebSocket クライアントを認証します。

mattermost のピアグループでは、channel に mattermost を設定し、許可された送信者を external_peers に列挙します（mattermost の場合、Mattermost ユーザーの UUID（ユーザー名ではありません）。["*"] は誰でも受け入れます）。オプションで、エージェント間ディスパッチ用のピア agents、ignore ブロックリスト、output_modality（mirror、voice、または text）を指定します。フィールドのリファレンスについては Peer Groups を参照してください。

この設定の場所:

特定のユーザーを許可リストに追加するには、System Console → User Management からそのユーザーIDをコピーします。Mattermost はユーザー名ではなくユーザーの UUID で照合し、メッセージ受信時にユーザー名を解決することはありません。

クイックスタート

以下のいずれかの方法でMattermostチャンネルを設定します（urlとbot_tokenシークレット、Authenticationを参照）。これだけで以下が利用できます。

1. ボットが所属するすべてのチームにわたって、ボットが読み取り可能なすべてのチャンネルを自動検出します。
2. DM チャンネルとグループ DM チャンネルは、チームチャンネルと併せて自動検出されポーリングされます。
3. 新しいDM（ボット起動後に作成されたもの）は、次回の60秒ごとのディスカバリー更新時に取得されます。
4. mention_only は DM およびグループ DM チャンネル内ではバイパスされます（1対1の会話ではボットを @-メンションする必要がないようにするため）。

ボットを制限するには、channel_ids、team_ids、または discover_dms で絞り込みます。

設定

bot_token と password は機密情報です：

channels.mattermost.<alias>.bot_token はシークレットです。 暗号化して保存され、平文の config.toml には記録されません。書き込み時に暗号化される以下のいずれかの方法で設定してください:

zeroclaw config set channels.mattermost.<alias>.bot_token    # マスク入力のプロンプトを表示し、暗号化して保存

フィールドリファレンス

zeroclaw config set channels.mattermost.<alias>.bot_token    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__mattermost__<alias>__bot_token=

zeroclaw config set channels.mattermost.<alias>.channel_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__channel_ids=

zeroclaw config set channels.mattermost.<alias>.discover_dms <value>

export ZEROCLAW_channels__mattermost__<alias>__discover_dms=

zeroclaw config set channels.mattermost.<alias>.excluded_tools <value>

export ZEROCLAW_channels__mattermost__<alias>__excluded_tools=

zeroclaw config set channels.mattermost.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__mattermost__<alias>__interrupt_on_new_message=

zeroclaw config set channels.mattermost.<alias>.listen_mode <value>

export ZEROCLAW_channels__mattermost__<alias>__listen_mode=

zeroclaw config set channels.mattermost.<alias>.login_id <value>

export ZEROCLAW_channels__mattermost__<alias>__login_id=

zeroclaw config set channels.mattermost.<alias>.mention_only <value>

export ZEROCLAW_channels__mattermost__<alias>__mention_only=

zeroclaw config set channels.mattermost.<alias>.password    # マスクされた入力、暗号化して保存

export ZEROCLAW_channels__mattermost__<alias>__password=

zeroclaw config set channels.mattermost.<alias>.proxy_url <value>

export ZEROCLAW_channels__mattermost__<alias>__proxy_url=

zeroclaw config set channels.mattermost.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__mattermost__<alias>__reply_min_interval_secs=

zeroclaw config set channels.mattermost.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__mattermost__<alias>__reply_queue_depth_max=

zeroclaw config set channels.mattermost.<alias>.team_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__team_ids=

zeroclaw config set channels.mattermost.<alias>.thread_replies <value>

export ZEROCLAW_channels__mattermost__<alias>__thread_replies=

zeroclaw config set channels.mattermost.<alias>.url <value>

export ZEROCLAW_channels__mattermost__<alias>__url=

チャンネル検出

スコープには2つのモードがあります。

1. 自動検出（channel_ids が空または ["*"] の場合）。起動時およびその後60秒ごとに、ボットは GET /api/v4/users/me/channels を呼び出し、結果を team_ids（パブリック/プライベートチャンネル）および discover_dms（DM/グループDM）でフィルタリングして、残った各チャンネルをポーリングします。実行中に新しく作成されたDMは、次の更新時に表示されます。
2. 明示的指定（channel_ids が * 以外の ID を含む空でないリストの場合）。起動時にボットは各エントリに対して GET /api/v4/channels/{id} を呼び出して type を取得し（mention_only のバイパスでどれが DM かを判別するため）、その後はそれらのチャンネルのみを永続的にポーリングします。定期的な再検出は行われません。

どちらのモードでも、各チャンネルは独自の since カーソルを持ちます。bot はチャンネルごとに処理した最大の create_at を追跡し、次の GET /api/v4/channels/{id}/posts 呼び出しで since=<ms> として渡します。カーソルはチャンネル間で混在しないため、動きの遅いチャンネルが、動きの活発なチャンネルの投稿を抑制することはありません。

WebSocket モード

listen_mode = "websocket" を設定して、REST ポーリングから永続的な WebSocket 接続（wss://<server>/api/v4/websocket）に切り替えます。WebSocket モード:

• 新しい投稿をほぼリアルタイムで配信します（3秒のポーリング遅延なし）。
• Mattermost サーバーへの HTTP 負荷を軽減します（N 回/3 秒のポーリングではなく、1 接続）。
• 失敗したセッションを共有チャネルスーパーバイザーに戻し、スーパーバイザーは設定済みの reliability.channel_initial_backoff_secs と reliability.channel_max_backoff_secs の値を使用して、上限付き指数バックオフで再接続します。
• Mattermost v4.0 以降が必要です（/api/v4/websocket エンドポイント）。

チャンネルの検出、mention_only、thread_replies、音声文字起こし、ピアグループ認可は、どちらのモードでも同じように動作します。

トレードオフ:

• WebSocket モードは、持続的な TCP+TLS 接続を維持する必要があります。
• 再接続中は、このリスナーがまだ Mattermost の接続再開／リプレイを要求しないため、チャンネルに投稿されたメッセージを取りこぼすことがあります。ポーリングは since= カーソルを使って未取得分を補完します。
• ポーリングモードは、継続的な HTTP トラフィックが発生する代わりに、一時的なネットワーク中断に対する耐性が高くなります。

ロールバックするには、listen_mode = "polling" を設定してください（またはフィールドを削除してください。ポーリングがデフォルトです）。

ダイレクトメッセージ

Mattermost はチャンネルを type で分類します:

G と D は ZeroClaw によって同一に扱われます。どちらも team_id を持たず、どちらも discover_dms によって制御され、どちらも暗黙的に mention_only をバイパスします（プライベートな会話には、フィルタリング対象となる環境ノイズが存在しないためです）。

DM 送信者の認可は、他のチャネルと同様に、引き続きチャネルのピアグループリゾルバーを経由します。discover_dms はあくまで設定項目であり、セキュリティ境界ではありません。エージェントに宛てて送信できるユーザーを決定するのはピアグループです。

スレッド

1. 受信した投稿が既存のスレッド内にある場合（root_id が設定されている）→ thread_replies の設定にかかわらず、返信は常にそのスレッドに送られます。
2. 受信した投稿がトップレベルで thread_replies = true（デフォルト）の場合 → 返信は受信した投稿を起点とするスレッドを開始します。
3. 受信した投稿がトップレベルで thread_replies = false の場合 → 返信はチャンネルのルートに投稿されます。

コンテキスト管理

Mattermostでの会話がスレッド内で行われる場合、そのスレッドは独立した会話となります。ZeroClawはスレッドごとに個別のセッションキーを生成するため、各スレッドは独立したコンテキストウィンドウと履歴を持ちます。あるスレッドのメッセージが別のスレッドに混在することはなく、エージェントが兄弟スレッドの過去のやり取りを参照することもありません。Mattermostではこれはthread_repliesによって制御されます。オンの場合、トップレベルのメッセージがスレッドを開始し、各スレッドが個別の会話となります。オフの場合、返信はチャンネルのルートに投稿され、履歴はスレッドではなく送信者とターゲットをキーとして管理されます。

• 分離こそが要点です。 各スレッドのコンテキストは自己完結しています。スレッドの外部に漏れることはなく、スレッドの外部からも何も漏れ込みません。並列スレッドは別々の会話状態を保持するため、無関係なタスクが互いに混ざり合うことはありません。
• 長いスレッドはコンテキストを増大させます。 スレッドはアクティブな間、履歴を蓄積していくため、非常に長いスレッドは他の長い会話と同様に、最終的にはモデルのコンテキストウィンドウを埋め尽くします。リセットするには新しいスレッドを開始してください。
• 処理中の作業はスレッドごとにスコープされます。 あるスレッドで新しいメッセージが届いても、別のスレッドで処理中の応答がキャンセルされることはありません。各スレッドのタスクは独立して動作します。

任意のサーフェスにスレッドの動作を設定します:

zeroclaw config set channels.mattermost.<alias>.thread_replies true     # スレッドの返信を有効化
zeroclaw config set channels.mattermost.<alias>.thread_replies false    # チャンネルルートでの返信

認証

2つのパス：

1. Bot token（推奨）。System Console → Integrations → Bot Accounts で作成し、アクセストークンをコピーして bot_token に保存します。トークンはパスワードのローテーションの影響を受けず、取り消しも容易です。
2. ログインフロー。login_id（メールアドレスまたはユーザー名）と password を設定します。bot は起動時に POST /api/v4/users/login を呼び出し、返されたセッショントークンをメモリにキャッシュします。ディスクへの永続化は行いません。

両方が設定されている場合は bot_token が優先されます。

ボイスメッセージ

[transcription] が設定されており、受信した投稿にテキスト本文なしで音声添付ファイル（MIMEタイプ audio/* または拡張子 ogg/mp3/m4a/wav/opus/flac）が含まれる場合、その音声は GET /api/v4/files/{file_id} 経由でダウンロードされ、設定されたトランスクリプションプロバイダーに転送されます。トランスクリプト結果には [Voice] というプレフィックスが付与され、メッセージ内容となります。25 MB を超える添付ファイルまたは transcription.max_duration_secs を超える長さの添付ファイルは、WARN ログとともに破棄されます。

セットアップ

1. Mattermost で: System Console → Integrations → Bot Accounts → Add Bot Account。ユーザー名（例: zeroclaw）を設定し、必要なスコープを有効にします。
2. アクセストークンをコピーします。ZeroClaw のシークレットバックエンドに保存してください。
3. ボットをアクティブにしたいチームに招待してください。DMの自動検出には追加の招待は不要です。どのユーザーでもボットにDMを送信できます。
4. mattermost.<alias> チャネルを作成し、ゲートウェイ、zerocode、または zeroclaw config set を通じてトークンを参照します。
5. [agents.<alias>] 内で channels = ["mattermost.<alias>"] を使用してチャネルをエージェントにバインドします。

運用上の注意事項

1. ポーリング間隔はチャネルごとに3秒です。検出されたN個のチャネルは、Mattermostサーバーに対して3秒ごとにN回のHTTP呼び出しを行うことを意味します。セルフホスト環境のデフォルト設定では、これを容易に処理できます。レート制限が厳しい共有クラウドテナントを使用している場合は、channel_ids または team_ids でスコープを絞ることを検討してください。
2. ボット ID は GET /api/v4/users/me を介して一度だけ取得され、プロセスの存続期間中はキャッシュされます。ユーザー名を変更するには再起動が必要です。
3. パスワードログインフローのセッショントークンはメモリ内にのみ保持されます。再起動すると再ログインが行われます。

関連項目も参照してください

• チャンネルの概要
• ピアグループ
• リファレンス: 設定スキーマ