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>.approval_timeout_secs <value>

export ZEROCLAW_channels__mattermost__<alias>__approval_timeout_secs=

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>.purpose_as_instructions <value>

export ZEROCLAW_channels__mattermost__<alias>__purpose_as_instructions=

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" を設定してください（またはフィールドを削除してください。ポーリングがデフォルトです）。

チャット経由のツール承認（approval_timeout_secs）

ツールに承認が必要な場合（always_ask に含まれている場合、またはリスクプロファイルで自動承認されない場合）、エージェントはリクエストをメッセージが届いたチャネルに投稿して応答を待ちます。承認への応答方法は2つあり、どちらが使えるかは listen_mode によって決まります。

トークンで返信してください。 これはすべての listen モードで動作します:

承認が必要です [a1b2c3]
ツール: shell
引数: command: pwd

返信: "a1b2c3 yes"、"a1b2c3 no"、または "a1b2c3 always"

a1b2c3 yes
a1b2c3 no
a1b2c3 always

保留中のトークンに一致する返信は判断として扱われ、モデルには届きません。

リアクションをタップ: この方法には listen_mode = "websocket" が必要です。ボットは自身の確認投稿に ✅ と ❌ を付けます。どちらかをタップすると、その投稿に応答したことになります。リアクションは reaction_added WebSocket イベントとしてボットに届きますが、ポーリングリスナーは投稿を読み取るだけでリアクションを検知しないため、listen_mode = "polling" の場合は絵文字が付与されません。セキュリティ確認でボタンが黙って何もしないのは、ボタンがないより悪い状態です。ワンタップ承認を使いたい場合は、listen_mode = "websocket" を設定してください(WebSocket モードを参照)。

always に絵文字を付けていないのは意図的です。単一の呼び出しを許可するのではなく、セッション単位の許可リストエントリを付与します。✅ の近くでの誤タップによってセッションが広がるのは安易すぎるため、always への切り替えは入力を伴う明示的な判断のままとしています。

Mattermostでは、ここで_ボタン_などのインタラクティブなメッセージ機能は提供されていません。これらはintegration URLにPOSTされますが、それにはボットがポーリングやWebSocketクライアントから公開できないインバウンドHTTPエンドポイントが必要です。リアクションは、ボットがすでに保持している接続上で動作する、ワンタップの操作手段です。

回答できるユーザーと回答場所。 トークンは認証用のパスワードではなく相関子(correlator)であり、チャンネルへ平文で送信されるため、すべてのメンバーがそれを読むことができます。そのため、次の2つの条件を両方満たす必要があります。回答するユーザーは、エイリアスのピアグループに属している必要があります。これは、エージェントがどのユーザーのメッセージに基づいて動作するかを決める権限と同じものです。また、回答はプロンプトが投稿されたチャンネルに届いている必要があります。1つのボットが多数のチャンネルにサービスを提供するため、別のルームに送られたトークンは、認可されたユーザーからのものであってもそこでは回答として扱われません。バインディングはスレッド単位ではなくチャンネル単位で行われるため、プロンプトのスレッド内ではなくチャンネルに直接返信しても問題ありません。いずれかのチェックに失敗した返信やタップはWARNでログに記録されて無視されます。プロンプトは未解決のまま残るため、認可されたオペレーターは正しい場所で引き続き回答できます。

チャンネル内の全員がツールの引数を閲覧できます。 プロンプトにはツール名と引数の概要が含まれます。これらを表示しても問題ないメンバーのチャンネルに承認依頼を振り分けてください。

approval_timeout_secs は待機時間の上限を指定します。デフォルトは 300 秒で、0 を指定すると承認を待たずに即座に拒否されます。承認を無効化するわけではないため、0 は無期限に待つ方法ではなく、ゲートされたツールをすべて拒否する方法です。タイムアウトすると要求は拒否され、トークンは破棄されるため、その後に届いた返信やタップによって、もはや誰も待っていない呼び出しが承認されることはありません。タイムアウトや、プロンプトに到達できない場合は、人間が拒否したのではなく、ランタイムが独自の判断で拒否したものとして記録されます。

決定は確定しています。リアクションを削除しても回答は取り消されず、最初の有効な回答によって両方のパスのプロンプトが終了します。

ボットが絵文字を付けられない場合（多くは権限の問題です）、failed to seed Mattermost approval reaction を WARN レベルでログに記録します。ただし、プロンプトは返信による操作で引き続き機能します。

チャンネルの目的を指示として扱う (purpose_as_instructions)

デフォルトではオフです。有効にすると、各ルームのMattermostのchannel purposeが、チャンネル由来のコンテキストとしてエージェントのシステムプロンプトに挿入されます。これにより、ルームごとに設定エントリを用意しなくても、1つのルームでエージェントの役割を特化させられます:

[channels.mattermost.default]
purpose_as_instructions = true

チャンネルの目的を設定して、そのルームが何のためのものかを記述します。たとえば「AUR リポジトリ向けの Arch Linux パッケージメンテナンス」のように設定します。エージェントはこれを、ルームの焦点、トーン、どのスキルを使うべきかについて権威あるものとして扱います。

エージェントのルールについては、権威を持ちません。挿入されたテキストはチャンネルから提供されたものとしてラベル付けされ、機能の付与、制限の緩和、運用ルールの上書きを行う権限は明示的に否定されています。それらのルールと矛盾する場合は、ルールが優先されます。ツールを有効にしたり、ピアグループを広げたり、自律レベルを変更したりすることはできません。

これを有効にすると何が、誰に付与されるか

これを有効にするかどうかは信頼に関する判断であり、上の警告から推測させるのではなく、その性質を率直に明記しておく価値があります。

Mattermostのmanage_public_channel_properties / manage_private_channel_properties権限によって用途が決まり、デフォルトのスキームではこれらはすべてのチャンネルメンバーに付与されています。これは通常、この設定を管理する人よりも広い範囲であり、エイリアスのpeer_groupsとは全く重なりません可能性があります。ZeroClawの正規のピアではないためエージェントから直接回答を得ることはできないメンバーでも、ルームの用途を編集できてしまいます。

このテキストはシステムプロンプトに届きます。その周囲のフレーミングは、このテキストがチャネル経由で供給されたものであり、エージェントに命令するのではなく状況を説明するものであり、エージェントのルールを上書きしないことをモデルに伝えています。しかし、フレーミングは強い事前分布であって、境界ではありません。指示のように読めるテキストは、その場でエージェントが何をするかに影響しうるものであり、どれだけエスケープを施しても、それは変わりません。自然言語であり、モデルはそれを自然言語として読むからです。

このフィーチャーが行う判断を明示すると: あるエイリアスで purpose_as_instructions を有効にすると、それらのルームの purpose を編集できる全員が、既存のエージェント権限の範囲内で、そのルームにおけるエージェントの動作を指示できるようになります。有効化するのは、その人たちがエージェントに設定された機能を扱うことを信頼できる場合に限ってください。信頼できない場合は、無効のままにするか(デフォルトは無効です)、権限スキームで manage_*_channel_properties を、それを持つべき人に限定してください。

それでも purpose にできないのは、これらの機能を 広げる ことです。purpose は、ツールの有効化、ピアの追加、自律性レベルの変更、自身のツール呼び出しの承認のいずれもできません。これらは設定と承認パスによって決まり、そのどちらもプロンプトのテキストを読み取りません。

構造的に、テキストは封じ込められています。注入の前に、山括弧と制御文字を取り除いたうえで1行に平坦化されるため、自身のセクションを閉じたり、別のセクションを開いたり、オペレーターのプロンプトの別の部分のように見えるMarkdownの見出しを偽造したりすることはできません。また、長さは500文字に制限されています。これはフィールドに対するMattermost自身の250文字の上限を上回る値です(チャンネルヘッダーは1024文字まで許可)。そのため、正当な用途が削られることはなく、侵害されたサーバーがプロンプト全体を貼り付けることもできません。

編集された目的は次のメッセージから反映されますが、反映までの遅延は listen_mode によって異なります:

チャンネルの目的をクリアすると、そのインジェクションは停止します。以前の値が保持されるわけではありません。目的が設定されていないルームは、何も寄与しません。

To元に戻すには、purpose_as_instructions = false を設定します(またはフィールドを削除します。デフォルトはオフです)。エイリアスがオプトインしていない場合はキャッシュされるものがないため、チャンネルの状態をクリーンアップする必要はありません。

ダイレクトメッセージ

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. ボットトークン（推奨）。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. パスワードログインフローのセッショントークンはメモリ内にのみ保持されます。再起動すると再ログインが行われます。

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

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