Matrix

MatrixのルームでZeroClawを実行します。エンドツーエンド暗号化（E2EE）対応のルームも含みます。

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

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

matrix のピアグループは channel を matrix に設定し、許可する送信者を external_peers に列挙し（matrix の場合は完全な Matrix ユーザー ID @user:server.tld、["*"] は誰でも受け入れます）、必要に応じてクロスエージェントディスパッチ用にピア agents を指定し、ignore ブロックリスト、output_modality（mirror、voice、または text）を設定します。フィールドのリファレンスは Peer Groups を参照してください。

この設定の場所:

このガイドが対象とする一般的な失敗モード：

Matrix は正しく設定されており、チェックもパスしていますが、ボットが応答しません。

よくある質問（FAQ）

Matrix が接続されているように見えるが返信がない場合、まず以下を確認してください：

1. 送信者がエージェントのピアセットに含まれています（テスト用: external_peers = ["*"]）。
2. ボットアカウントは正確なターゲットルームに参加している。
3. 資格情報はボットアカウントに属します（トークンパスでのwhoamiチェック、§5Cを参照）。
4. 暗号化されたルームを復号できます: recovery_key が設定されている (推奨)、またはキーがボットデバイスに共有されています。
5. 設定変更後、デーモンが再起動されました。

1. 要件

メッセージフローをテストする前に:

1. ボットアカウントがターゲットルームに参加している。
2. 認証情報はボットアカウントの認証に使用します。user_id + password（推奨、§2 を参照）か、access_token（トークン方式、§3）のいずれかを使用します。
3. allowed_rooms には対象のルームを含めます（すべての参加済みルームを許可する場合は空にします）。エントリは受信した各メッセージの正規ルーム ID（!room:server）と文字どおり照合されるため、ここには正規ルーム ID を列挙してください。ZeroClaw はこの許可リストに対して #alias:server エントリを解決しません。（エイリアスが解決されるのは、cron の delivery.to のような送信先のみです。）ルームの正規 ID は、クライアント上で確認できます（Element の場合: ルーム設定 → 詳細 → 内部ルーム ID）。
4. ピアグループは送信者を認可します（オープンテストの場合は external_peers = ["*"]、§6 を参照）。
5. E2EEルームの場合、ボットは復号できます。recovery_key（推奨）を使用するとキーが自動的に復元されるか、またはキーがボットデバイスに手動で共有されます。

2. 設定

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

export ZEROCLAW_channels__matrix__<alias>__access_token=

zeroclaw config set channels.matrix.<alias>.ack_reactions <value>

export ZEROCLAW_channels__matrix__<alias>__ack_reactions=

zeroclaw config set channels.matrix.<alias>.allowed_rooms <value>

export ZEROCLAW_channels__matrix__<alias>__allowed_rooms=

zeroclaw config set channels.matrix.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__matrix__<alias>__approval_timeout_secs=

zeroclaw config set channels.matrix.<alias>.device_id <value>

export ZEROCLAW_channels__matrix__<alias>__device_id=

zeroclaw config set channels.matrix.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__matrix__<alias>__draft_update_interval_ms=

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

export ZEROCLAW_channels__matrix__<alias>__excluded_tools=

zeroclaw config set channels.matrix.<alias>.homeserver <value>

export ZEROCLAW_channels__matrix__<alias>__homeserver=

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

export ZEROCLAW_channels__matrix__<alias>__interrupt_on_new_message=

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

export ZEROCLAW_channels__matrix__<alias>__mention_only=

zeroclaw config set channels.matrix.<alias>.message_max_bytes <value>

export ZEROCLAW_channels__matrix__<alias>__message_max_bytes=

zeroclaw config set channels.matrix.<alias>.multi_message_delay_ms <value>

export ZEROCLAW_channels__matrix__<alias>__multi_message_delay_ms=

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

export ZEROCLAW_channels__matrix__<alias>__password=

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

export ZEROCLAW_channels__matrix__<alias>__recovery_key=

zeroclaw config set channels.matrix.<alias>.reply_in_thread <value>

export ZEROCLAW_channels__matrix__<alias>__reply_in_thread=

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

export ZEROCLAW_channels__matrix__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__matrix__<alias>__reply_queue_depth_max=

zeroclaw config set channels.matrix.<alias>.stream_draft_delete <value>

export ZEROCLAW_channels__matrix__<alias>__stream_draft_delete=

zeroclaw config set channels.matrix.<alias>.stream_draft_lines <value>

export ZEROCLAW_channels__matrix__<alias>__stream_draft_lines=

zeroclaw config set channels.matrix.<alias>.stream_mode <value>

export ZEROCLAW_channels__matrix__<alias>__stream_mode=

zeroclaw config set channels.matrix.<alias>.stream_reasoning <value>

export ZEROCLAW_channels__matrix__<alias>__stream_reasoning=

zeroclaw config set channels.matrix.<alias>.stream_tool_arguments <value>

export ZEROCLAW_channels__matrix__<alias>__stream_tool_arguments=

zeroclaw config set channels.matrix.<alias>.user_id <value>

export ZEROCLAW_channels__matrix__<alias>__user_id=

Matrix は [channels.matrix.<alias>] ブロックとして設定します。以下のいずれかの方法で設定できます。

推奨設定: パスワード + リカバリーキー

Matrix を実行する公式かつ最も手間のかからない方法は、ZeroClaw に新規ログインさせて、独自のデバイス ID を管理させることです:

• device_id を省略してください。 ログイン時にホームサーバーに割り当てさせます。ZeroClaw は割り当てられた id を session.json に保存し、再起動のたびに再利用するため、調べたり、コピーしたり、同期を保ったりする値はありません。手作業で device_id を固定することは、キー共有が壊れる最も一般的な原因です。
• access_token を省略する場合。 これが未設定の場合、ZeroClaw はパスワードログインにフォールバックします。新規ログインは自動リカバリーのパス（§8）でも使用されるため、ボットはオペレーターの操作なしに破損したローカル状態から自己修復します。
• password を設定します。 access_token がない場合、user_id と password でログインを実行します。
• recovery_key を設定します。 これにより、サーバー側バックアップからルームキーを復元し、起動のたびに新しく登録されたデバイスを自動的にクロス署名します。絵文字による検証も、手動でのキー共有も、ブートストラップも不要です。Element からの取得方法については §5I を参照してください。

完全な推奨ブロックでは、homeserver、user_id、password、recovery_key を設定し、access_token と device_id は未設定のままにします。

access_token + device_id のパス（§3）は引き続き機能し、既存のトークンを再利用する必要がある運用者向けに完全に文書化されていますが、安定した device_id を自分で保持する必要があるため、特別な理由がない限りパスワード + リカバリーキーを使用することをお勧めします。

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

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

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

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

homeserver は必須です。推奨される設定では、user_id、password、recovery_key も設定してください。access_token と device_id は §3 のトークンベースのパスでのみ必要です。allowed_rooms は、ボットが応答するルームを任意で制限します。送信者の認可には ピアグループ を使用します。フィールドの完全な一覧: config リファレンス。

まだ recovery_key をお持ちでない場合は？ §5I を参照してください。Element での生成方法を順を追って説明しています。代わりにトークンルートを使いますか？ access_token と安定した device_id を一度に発行するパスワードログイン API 呼び出しについては §3 を参照してください。すでにお持ちのトークンの device_id を調べるには、§5H を参照してください。

user_id と device_id について

• パスワード + リカバリーキーの推奨セットアップでは、user_id を設定し、device_id は未設定のままにします。ホームサーバーが割り当て、ZeroClaw がそれを永続化します。
• ZeroClaw は Matrix の /_matrix/client/v3/account/whoami から ID を読み取ります。
• access_token のパスを使う場合のみ、device_id を手動で設定します。トークンログインではサーバーがすでに発行したデバイスが含まれており、ZeroClaw は E2EE セッションの復元にその正確な ID を必要とします（その見つけ方は §5H を参照）。

スレッドとコンテキスト

Matrix の会話がスレッド内で行われる場合、そのスレッドはそれ自体が独立した会話となります。ZeroClaw はスレッドごとに個別のセッションキーを導出するため、すべてのスレッドは独立したコンテキストウィンドウと履歴を保持します。あるスレッドのメッセージが別のスレッドに漏れることはなく、エージェントが同階層の別スレッドの過去のやり取りを参照することもありません。Matrix ではこれは reply_in_thread で制御されます。これがオンの場合、トップレベルのメッセージがスレッドを開き、各スレッドが個別の会話となります。オフの場合、返信はチャンネルのルートに投稿され、履歴はスレッドではなく送信者とターゲットをキーとして管理されます。

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

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

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

3. トークンパス（代替手段）: access_token と device_id の取得

[!IMPORTANT] このセクションは access_token パスのみを対象としています。§2 で推奨されているパスワード + リカバリーキーのセットアップに従った場合は、スキップできます。アクセストークンや手動管理の device_id は必要ありません。

このパスは、既存のトークンを再利用する必要がある場合（たとえば別のデプロイからコピーしたトークンなど）に使用します。Element はトークンを直接公開していないため、トークンを発行する標準的な方法は、アクセストークンと安定したデバイス ID を同時に返すワンショットのパスワードログイン API 呼び出しです。トークンログインはデバイスを伴うため、このパスでは device_id が必須であり、安定したままでなければなりません。

オペレーターアカウントに既にトークンがある場合は、§4に進んでください。既存のトークンのdevice_idを調べるだけの場合は、§5Hのオプション1（whoami）またはオプション2（Element）を参照してください。

ステップ1: パスワードログインでトークンを発行する

これを一度だけ実行します。your.homeserver、ボットのユーザー名、パスワードを置き換え、任意の短い device_id 文字列（英数字、スペースなし。これは ZeroClaw が再起動のたびに再利用する_サーバー側_のデバイスラベルです）を選択してください。

curl -sS -X POST https://your.homeserver/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"YOUR_BOT_USERNAME"},"password":"YOUR_PASSWORD","device_id":"NEW_DEVICE_ID"}'

応答:

{"user_id": "@bot:example.com", "access_token": "syt_...", "device_id": "NEWDEVICE"}

手順2: 両方の値を ZeroClaw に適用する

レスポンスに含まれる access_token、device_id、user_id を [channels.matrix.<alias>] ブロックに記述し（設定場所については §2 を参照）、zeroclaw service restart で再起動してください。

注釈

• 最初にトークンを貼り付けたときは、そのコピーを保管しておいてください。シークレットは保存時に暗号化され、zeroclaw config get ではトークンフィールドに [masked] と表示されるため、後から取得することはできません。§5C の curl 検証スニペットで必要になる場合は、メモ書きに控えておいてください。
• 再起動のたびに同じ device_id を再利用する: これを変更するとサーバー側で新しいデバイス登録が強制され、暗号化されたルームでの鍵共有と検証が壊れます。§8 の自動リカバリーパスは、消去が本当に正しい選択である稀なケースを処理します。
• ウィザードを再実行せずに後からアクセストークンをローテーションする場合: 設定内の access_token フィールドを更新し（§2 を参照）、zeroclaw service restart を実行します。
• 起動時にトークンが期限切れまたは無効と表示される: 同じ curl で新しいトークンを生成し、Step 2 を繰り返してください。

4. クイック検証

まだ設定していない場合は§2のフィールドセットを適用し、zeroclaw service restart（バックグラウンド）または zeroclaw daemon（フォアグラウンド）で再起動してください。設定済みのMatrixルームでプレーンテキストのメッセージを送信します。確認事項:

• ZeroClawのログでは、Matrixリスナーが重複した同期/認証エラーなしで開始されていることが示されています。
• 暗号化されたルームでは、ボットは許可されたユーザーからの暗号化されたメッセージを読み取り、返信することができます。

5. 「応答なし」のトラブルシューティング

順番に処理してください。

A. ルームとメンバーシップ

• ボットアカウントがルームに参加していることを確認してください。
• allowed_rooms にルームを設定する場合は、#alias:server ではなく、正規 ルームID（!room:server）を指定する必要があります。許可リストではエイリアスは解決されないため、エイリアスのエントリは何にもマッチせず、警告なく無視されます。正規IDは Element の「ルーム設定」→「詳細」→「内部ルームID」で確認できます。

B. 送信者許可リスト（ピアグループ）

送信者はエージェントのピアセットに含まれている必要があります。本ページ上部の エージェントと通信できる相手 を参照してください。診断のため、一時的に external_peers = ["*"] を設定してデーモンを再起動してください。

C. トークンとアイデンティティ

シークレットは保存時に暗号化されており、取得できません。zeroclaw config get は、シークレットフィールドに対して [masked] を出力します。以下のチェックを実行するには、§3 で発行したアクセストークン（または新たに発行したもの）と、自身のホームサーバーの URL を使用してください。

トークンをサーバー側で検証します:

curl -sS -H Authorization: Bearer <access_token> \
  "https://your.homeserver/_matrix/client/v3/account/whoami"

• 返された user_id はボットアカウントと一致している必要があります。
• device_id がレスポンスに含まれていない場合は、手動で設定してください（§5Hを参照）。
• アクセストークンをローテーションする場合は、設定内の access_token フィールドを更新し（§2 を参照）、その後 zeroclaw service restart を実行してください。

D. E2EE固有のチェック

• ボットデバイスが信頼できるデバイスからルームキーを受信している必要があります。
• このデバイスにキーが共有されていない場合、暗号化されたイベントを復号できません。
• 信頼されたMatrixセッションからデバイスの信頼性とキー共有を確認します。
• matrix_sdk_crypto::backups: Trying to backup room keys but no backup key was found: このデバイスではまだキーバックアップのリカバリーが有効になっていません。メッセージのフローには影響しません（致命的ではありません）が、設定を完了する価値はあります（§5Iを参照）。
• 受信者にボットのメッセージが「未検証」と表示される場合は、信頼できる Matrix セッションからボットのデバイスを検証/署名し、再起動後も device_id が変わらないようにしてください。

E. ログレベル

ZeroClawはデフォルトでmatrix_sdk、matrix_sdk_base、matrix_sdk_cryptoをwarnに抑制します。これらはinfoでは出力が多すぎるためです。デバッグ用にSDKの出力を復元するには次のようにします:

RUST_LOG=info,matrix_sdk=info,matrix_sdk_base=info,matrix_sdk_crypto=info zeroclaw daemon

F. メッセージフォーマット (Markdown)

• ZeroClawは、Matrixの返信をマークダウン対応の m.room.message テキストコンテンツとして送信します。
• formatted_body をサポートする Matrix クライアントは、強調表示、リスト、コードブロックをレンダリングします。
• フォーマットがプレーンテキストとして表示される場合: まずクライアントの機能を確認し、ZeroClawがMarkdown対応のMatrix出力を行うビルドを実行していることを確認してください。

G. フレッシュスタートテスト

設定変更後、デーモンを再起動して新しいメッセージを送信してください。古いタイムラインの履歴は再送信されません。

H. 既存のトークンの device_id を確認する

これは access_token 経由の場合にのみ必要です（§3）。推奨されるパスワード＋リカバリーキーの設定では device_id を完全に省略します。ホームサーバーが ID を割り当て、ZeroClaw がそれを永続化するため、参照すべきものはありません。推奨される設定に切り替えている場合は、このセクションをスキップしてください。

本当に device_id を固定する必要がある場合（パスワードでログインするのではなく既存のアクセストークンを再利用しているため）は、これを使ってそのトークンに紐付けられたものを見つけてください。トークン経路を使う新規ボットについては、§3 を参照してください。そこにあるパスワードログインのフローでは、両方の値がまとめて返されます。

ZeroClaw では、トークンパスでの E2EE セッション復元のために安定した device_id が必要です。これがないと、再起動のたびに新しいデバイスが登録され、キー共有とデバイス検証が機能しなくなります。

オプション1: whoami（最も簡単）

curl -sS -H Authorization: Bearer <access_token> \
  "https://your.homeserver/_matrix/client/v3/account/whoami"

トークンがデバイスセッションにバインドされている場合、応答に device_id が含まれます:

{"user_id": "@bot:example.com", "device_id": "ABCDEF1234"}

device_id が指定されていない場合、そのトークンはデバイスログインを経由せずに（例: admin API 経由で）作成されたものです。§3 を参照して、新しいトークンと device_id をまとめて発行してください。

オプション2: Element または別の Matrix クライアントから

1. Element でボットアカウントとしてログインします。
2. 設定 → セッション。
3. アクティブなセッションのデバイスIDをコピーします。
4. 設定で device_id を指定し（§2を参照）、zeroclaw service restart を実行してください。device_id は変更しないでください。変更すると新しいデバイス登録が強制され、既存のキー共有や検証が壊れてしまいます。

H（続き）。Cryptoストアの削除復元

症状: Matrixのワンタイムキーアップロードの競合が検出され、無限再試行ループを回避するために同期が停止しました となり、チャネルが利用できなくなります。

原因: ローカル暗号ストアが削除されましたが、古いデバイスはまだホームサーバーに登録されているワンタイムキーを持っています。SDK は古いキーがまだサーバー側に存在するため新しいキーをアップロードできず、無限 OTK 競合ループが発生します。

修正: 新規ログイン

新しいログインは、新しい device_id を持つ新しいデバイスを作成し、OTK の競合を完全に回避します（UIA によるデバイス削除は不要です）。

1. ZeroClaw を停止します。

   sh

   zeroclaw service stop
   

2. 新しいアクセストークンと device_id を取得します:

   sh

   curl -sS -X POST "https://matrix.org/_matrix/client/v3/login" \
     -H "Content-Type: application/json" \
     -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"YOUR_BOT_USERNAME"},"password":"YOUR_PASSWORD","device_id":"NEW_DEVICE_ID"}'
   

   返された access_token と device_id を保存してください。

3. ローカル暗号ストアを削除します:

   sh

   rm -rf ~/.zeroclaw/state/matrix/
   

4. 新しい認証情報を適用します: 設定に access_token (シークレット、§2 を参照) と device_id を指定してください。

5. 再起動:

   sh

   zeroclaw service start
   

最初の再起動時に予想されること

• Our own device might have been deleted: 無害です。古いデバイスは削除されています。
• Failed to decrypt a room event: リセット前の古いメッセージ。復元できません。
• Matrix E2EE recovery successful: ルームキーがサーバーバックアップから復元されました（recovery_key が設定されている場合のみ。§5I を参照）。
• 新しいメッセージは正常に復号化されて動作します。

予防: ローカルステートディレクトリを削除する際には、フレッシュログインを計画してください。フレッシュスタートが必要な場合は、まず新しい認証情報を取得し、ストアを削除し、設定を更新してください。

I. リカバリーキー (E2EE に推奨)

リカバリーキーを設定すると、ZeroClaw はサーバー側のバックアップからルームキーとクロス署名シークレットを自動的に復元できます。デバイスのリセット、暗号ストアの削除、新規インストールのいずれも自動的に復元されます。絵文字による検証や手動でのキー共有は不要です。

ステップ 1: Element からリカバリーキーを取得する

1. Element（ウェブまたはデスクトップ）でボットアカウントにログインします。
2. 設定 → セキュリティとプライバシー → 暗号化 → セーフバックアップ
3. バックアップがすでに設定されている場合、リカバリーキーは最初に有効にしたときに表示されました。保存していれば、それを使用します。
4. バックアップが設定されていない場合は、「Set up Secure Backup」→「Generate a Security Key」をクリックします。Element がキー（EsTj 3yST y93F SLpB ... のような形式）を表示するので、安全な場所にコピーしてください。
5. キー表示の先に進むと、保存したことを証明するために、Element は確認ボックスでキーの再入力を求めます。これを貼り付けて続行し、セットアップを完了します。これは recovery_key に入力したものと同じ値です。
6. （任意）キーを保存したら、ボットの Element セッションからログアウトします。アカウントメニュー → すべての設定 → アカウント、続いて このデバイスを削除 をクリックします。ログインしたままでも問題ありませんが、削除しておくとデバイス一覧が整理された状態に保てます。

手順2: リカバリーキーをZeroClawに追加する

ZeroClaw にリカバリーキーを適用します:

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

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

その後、zeroclaw service restartを実行します。リカバリーキーは保存時に即座に暗号化されます。

ステップ 3: 再起動

zeroclaw service restart

起動時に以下が表示されます:

Matrix E2EE recovery successful — room keys and cross-signing secrets restored from server backup.

今後、ローカルの暗号化ストアが削除されても、ZeroClawは次回起動時に自動的に復元されます。

6. デバッグログ

Matrixチャネル固有の診断:

RUST_LOG=zeroclaw::channels::matrix=debug zeroclaw daemon

サーフェス:

• セッション復元の確認
• 各同期サイクルの完了
• OTKコンフリクトフラグの状態
• ヘルスチェック結果
• 一時的なエラーと致命的な同期エラーの分類

SDKレベルの詳細についても：

RUST_LOG=zeroclaw::channels::matrix=debug,matrix_sdk_crypto=debug zeroclaw daemon

7. 運用上の注意事項

• Matrixトークンをログとスクリーンショットから除外します。
• 寛容な external_peers = ["*"] から始めて、検証後に明示的なユーザー ID に絞り込んでください。
• allowed_rooms では常に正規のルームIDを使用してください。エイリアスは受信側の許可リストでは解決されません（送信側の delivery.to でのみ解決されます）。
• スレッド機能: channels.matrix.reply_in_thread が true（デフォルト）の場合、ボットのすべての返信は、ユーザーのメッセージをルートとするスレッド内に配置されます。トップレベルのユーザーメッセージは新しいスレッドを開始し、既存のスレッドは継続されます。メインルームのタイムラインには、ユーザーが開始したメッセージのみが表示されます。
• スレッドルートのコンテキスト: ZeroClaw が任意のスレッドで最初に受信するインバウンドメッセージには [Thread root from @sender]: <root body> というプレフィックスが付与され、エージェントが返信のトリガーとなった会話を把握できるようになっています。ボット自身が開始したスレッドではこのプリアンブルはスキップされます。トラッキングはメモリ内のみで行われ、デーモンの再起動後は、各アクティブスレッドの次のメッセージでプリアンブルがちょうど一度だけ再注入されます。
• インラインリプライ メディア: channels.matrix.mention_only = true を設定すると、ボットは（メンション対象となるテキスト本文を持たない）裸のメディアアップロードを無視します。ユーザーがそのように破棄されたイベントに対して質問付きでインラインリプライした場合（@bot can you see this?）、ZeroClaw はリプライの m.relates_to.m.in_reply_to.event_id をたどり、親イベントを取得して、そのメディアを現在のメッセージに取り込みます。これにより、元のアップロードがフィルターで除外されていても、エージェントのビジョンパイプラインがその画像を認識できます。
• 添付ファイルもテキストと並んでスレッド化されます: room.send_attachment の呼び出しは、スレッドアンカーが存在する場合に EnforceThread::Threaded を伴う AttachmentConfig::reply(...) を運ぶため、PDF / 画像 / ボイスメモはメインのタイムラインではなくボットのスレッド内に配置されます。
• 送信メディアマーカー: エージェントは返信テキスト内に [image:url|path]、[file:url|path]、[voice:url|path]、[video:...]、[audio:...]（および大文字／[document:...] のエイリアス）を出力します。ZeroClaw はそのバイトを取得し（http(s):// の場合は HTTP、それ以外はローカル読み込み）、適切な Matrix メッセージイベントとしてアップロードします。ターゲットが見つからない、または読み取れない場合は致命的ではありません: チャネルは警告をログに記録し、該当するマーカーのみを削除し、(note: I couldn't deliver the file at <path>.) という行を追加します。これにより、オペレーターは返信が黙って削除されるのではなく、何が試みられたかを確認できます。
• 音声メッセージ (MSC3245): org.matrix.msc3245.voice フィールドを持つ受信 m.audio イベントは {workspace_dir}/matrix_files/ に保存され、エージェントに設定された文字起こしプロバイダーを通して処理されるため、エージェントは文字起こしテキストとソースパスの両方を取得できます。送信される音声ノートは [voice:<url|path>] マーカーを使用します。ZeroClaw は voice フラグ + ゼロ波形を設定して m.audio としてアップロードするため、Element はそのバブルを音声ノートとしてレンダリングします。文字起こしプロバイダーの設定については Model Providers を参照してください。
• 確認リアクション: channels.matrix.ack_reactions（デフォルトは true）で制御します。有効にすると、ボットは処理中に👀、完了時に✅でリアクションします。false に設定すると、ルームをリアクションなしに保てます。
• 永続セッション: 初回ログイン成功時、ZeroClaw は ~/.zeroclaw/state/matrix/session.json を書き込みます（user_id + device_id + access_token + 任意の refresh_token）。以降の再起動では、その blob から restore_session() を呼び出すため、再ログインは不要です。matrix-rust-sdk の SQLite 暗号ストアは、その隣の ~/.zeroclaw/state/matrix/store/ に配置されます。session.json が存在する限り、設定内の access_token をローテーションしてもファイルを削除するまで効果はありません: 保存済みのトークンが優先されます。設定値からの再ログインを強制するには、session.json を削除してください。
• クロス署名: recovery_key がアカウントのサーバーサイドシークレットストレージに保存されている値と一致する場合、ZeroClaw は起動のたびに recovery().recover(key) を実行し、SDK が既存のマスター／自己署名／ユーザー署名キーをインポートして、新たに登録されたデバイスが自動的に署名されます。ブートストラップも UIA もキーローテーションも不要です。 アカウントにまだクロス署名が設定されていない場合は、recovery_key を設定する前に、Element（Settings → Security & Privacy → Secure Backup）でリカバリーキーを生成してください。
• Cron 配信: delivery.to は単純なルーム ID（!abc:server）またはエイリアス（#room:server）である必要があります。<sender>||<room> と記述された古い設定も許容されます。ZeroClaw は最後の !/# で始まるセグメントを抽出し、不正な値について警告します。

ストリーミング

Matrix は stream_mode 設定を使用して応答をストリーミングします。

• off（デフォルト）: エージェントの処理が完了すると、応答全体が1つのメッセージとして投稿されます。最もシンプルで、書きかけの回答が表示されることはありません。
• partial: ボットはすぐにドラフトを投稿し、回答がストリーミングされるにつれてその場で編集します。draft_update_interval_ms が編集の間隔を調整します。Matrix がレート制限する場合は値を大きくしてください。
• multi_message: 各段落が個別のメッセージとして投稿され、multi_message_delay_ms で区切られます。1つの長い文章の塊になってしまうような長い回答に適しています。

任意のサーフェスに設定します:

zeroclaw config set channels.matrix.<alias>.stream_mode <value>

Matrix 固有の仕様: partial モードでは、ツール実行ステータスは回答テキストと同じ編集パイプラインを通じて表示されます。single_message モードでは、ツール/進捗ステータスの更新が1つのスライド式ドラフトに編集され、最終回答は別の Matrix メッセージとして送信されます。stream_draft_lines は表示する進捗行を制御します。0 は行数制限だけを解除し、2つ目の進捗メッセージが作成されることはありません。message_max_bytes はドラフトと最終イベントのコンテンツ両方に上限を設けます。Markdown ソースだけでなく、レンダリング済み Markdown（生成された HTML を含む）と Matrix の返信/編集リレーションメタデータをカウントします。サイズ超過した進捗は、最も古い行またはエントリを丸ごと削除して、ウィンドウに最新のアクティビティを残します。個々の項目が大きすぎる場合は、表示されるアラートに置き換えられます。別個の最終応答には、UTF-8 セーフなプレフィックスが保持されます。進捗コンテンツは Markdown のレンダリング前にエスケープされるため、推論は行をまたいでも読みやすいままになり、ユーザー/モデル/ツールのコンテンツによって Markdown や HTML の書式が導入されることはありません。512 未満の値は、その実効最小値として扱われるため、空でないシリアライズ済み Matrix イベントを収めることができます。この予算は、承認プロンプト、システム通知、スケジュール配信、その他の通常の送信には適用されません。予算は Matrix イベントの上限未満に設定してください。stream_reasoning は、その進捗ドラフトにおけるプロバイダーの推論の可視性を制御します。off は推論に基づくドラフト更新を抑制し、status は生の推論テキストなしで稼働確認のティックを出力し、full はプロバイダーの生の推論テキストを進捗ドラフトに出力します。stream_draft_delete は、永続化された進捗トランスクリプトを最終回答の投稿前に削除するかどうかを制御します。削除に失敗してもログに記録され、最終回答の配信は引き続き行われます。トランスクリプトの保持が有効な場合でも、プレースホルダーだけのドラフトは最終回答の前に削除されます。multi_message モードでは、各段落がそれぞれ専用のスレッドメッセージとして投稿されます。分割はコードフェンスを認識するため、フェンスで囲まれたブロック内の空行によってコードブロックがメッセージ間で分割されることはありません。

stream_tool_arguments は、single_message の進捗行に表示されるツール引数を制御します。設定がないか空の場合は、ツールごとの保守的なデフォルトが使用されます。スキルラッパー、プラグイン、MCP ツール、解決されない名前については、名前だけが表示されます。単一の default_base エントリで none、safe、all のいずれかを選択できます。一方、名前の完全一致によるツールルールでは、そのベースを置き換えたり、フィールドを追加・削除したりできます。

stream_tool_arguments = [
    { default_base = "safe", argument_chars = 60 },
    { tool = "delegate", base = "none", include = ["agent", "background", "prompt"], argument_chars = 0 },
    { tool = "mock_tool", base = "all", exclude = ["token"] },
]

ルールの順序は関係なく、重複するツールエントリまたはデフォルトエントリは拒否され、省略されたルールの base は default_base を継承します。include はベースの選択後にフィールドを追加し、exclude はフィールドを削除します。実行時専用フィールドは表示されず、認証情報を示す名前のフィールドは、選択されたすべての値内で再帰的にマスキングされます。また、レンダリングされるすべての値は、Matrix に届く前に認証情報の漏えい検出と1行正規化を通過します。複合値を含めることは、引き続きオペレーターによる明示的な開示判断ですが、認証情報のマスキングを回避することはありません。safe モードでは、推奨されるトップレベルのスカラー引数だけがレンダリングされ、null、配列、オブジェクトは省略されます。all を選択するか、include で引数を指定することは、複合値をコンパクトな JSON としてレンダリングすることへのオペレーターによる明示的なオプトインです。デフォルトエントリの argument_chars は、継承される値ごとの上限を 60 から変更します。同じフィールドをツールルールに指定すると、そのツールでは上書きされます。0 を指定すると値全体が保持されますが、レンダリングされた下書きには message_max_bytes による上限が引き続き適用されます。明示的な all は未知のツールにも適用されます。1つの拡張ツールだけで引数を有効にする場合は、名前を完全一致させるルールを使用してください。

8. 破損したローカル状態からの自動リカバリー

matrix-rust-sdk のデフォルトの SQLite ストアは単一デバイス用であり、ローカルビューがホームサーバーと同期した状態を維持していることを前提としています。この前提を回復不能なまでに破壊する2つの障害モードがあります。ZeroClaw は起動時にそれぞれを検出し、（password と user_id の両方が設定されている場合）~/.zeroclaw/state/matrix/ を自動的に消去して再認証し、サーバー側で新しいデバイスが作成されるようにします。

• 孤立した暗号化状態。 store/ ディレクトリは存在するが session.json が存在しない（手動でのクリーンアップ、前回のインストールの中断など）。孤立した暗号化状態の上に新規ログインすると、自己修復しない Duplicate one-time keys / SigningKeyChanged の競合が再発します。
• StateStoreDataKey::OneTimeKeyAlreadyUploaded フラグが設定されています。 SDK は、重複した OTK アップロードを初めて検出したときに、このキーをステートストアに永続化します（SDK 自身のコメントによると、「we forgot about some of our one-time keys. This will lead to UTDs.」）。これは再起動後も保持され、唯一の修正方法はワイプして再登録することです。

device_id のずれは検出されますが、許容され、消去されません。 channels.matrix.device_id が session.json に保存されているデバイス ID と異なる場合、チャネルは警告をログに記録し、保存された ID（ログイン時にホームサーバーが実際に割り当てた値）を優先します。ずれが生じるたびに消去すると、自動リカバリ自体が新しい ID を生成するため、リカバリループが発生し、設定とセッションが恒久的に同期しなくなります。

recover() 自体が失敗した場合（通常は MAC check for the secret storage key failed）、チャネルはホームサーバーのデフォルトのシークレットストレージキー ID、キーイベントにパスフレーズ情報が含まれているかどうか、空白を除去した入力の長さ、および完全なエラーチェーンをログに記録します。これらは、リカバリーキーの値を漏らすことなく、どの レイヤーがリカバリーキーを拒否したかを示します。リカバリーの失敗は致命的ではなく（自動ワイプはトリガーされません）、ボットは処理を続行しますが、新しいデバイスはクロス署名されません。

password + user_id が設定されていない場合、自動リカバリーは実行できません。チャネルは実行可能なエラーを返し、2つの選択肢を示します。それらを設定するか、rm -rf ~/.zeroclaw/state/matrix/ を手動で実行するかのいずれかです。

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

• ネットワーク展開
• 設定リファレンス: ライブスキーマから生成されます
• チャンネルの概要