OpenClaw Matrixプラグイン設定ガイド：5分で接続完了

Matrixは、OpenClaw用のMatrixチャンネルプラグインです。 公式のmatrix-js-sdkを使用しており、DM、ルーム、スレッド、メディア、リアクション、投票、位置情報、そしてE2EEをサポートしています。

必要なプラグイン

Matrixはプラグインとして提供されており、OpenClawのコア本体には同梱されていません。

npmからインストールする場合：

openclaw plugins install @openclaw/matrix

ローカルのチェックアウトからインストールする場合：

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

プラグインの動作やインストールルールについては、Pluginsを参照してください。

セットアップ

1. プラグインをインストールします。
2. ホームサーバーでMatrixアカウントを作成します。
3. channels.matrixを以下のいずれかで設定します：
   • homeserver + accessToken
   • homeserver + userId + password
4. Gatewayを再起動します。
5. ボットとDMを開始するか、ルームに招待してください。

対話的なセットアップパス：

openclaw channels add
openclaw configure --section channels

Matrixウィザードで実際に聞かれる項目：

• homeserver URL
• 認証方法：access token または password
• password認証を選択した場合のみ user ID
• 任意のデバイス名
• E2EEを有効にするかどうか
• 今すぐMatrixルームへのアクセスを設定するかどうか

重要なウィザードの挙動：

• 選択したアカウントのMatrix認証環境変数が既に存在し、そのアカウントの認証情報が設定ファイルに保存されていない場合、ウィザードは環境変数のショートカットを提案し、そのアカウントに対してenabled: trueのみを書き込みます。
• 対話形式で別のMatrixアカウントを追加すると、入力されたアカウント名は設定や環境変数で使用されるアカウントIDに正規化されます。例えば、Ops Botはops-botになります。
• DMのAllowlistプロンプトでは、フル形式の@user:server値を即座に受け付けます。表示名は、ライブディレクトリ検索で正確に1つだけ一致した場合のみ機能します。それ以外の場合、ウィザードはフル形式のMatrix IDで再試行するよう求めます。
• ルームのAllowlistプロンプトでは、ルームIDやエイリアスを直接受け付けます。参加済みルームの名前をライブで解決することもできますが、解決できない名前はセットアップ時に入力されたまま保持され、実行時のAllowlist解決では無視されます。!room:serverまたは#alias:serverの使用をおすすめします。
• 実行時のルームやセッションの識別には、不変のMatrixルームIDが使用されます。ルームで宣言されたエイリアスは検索の入力としてのみ使用され、長期的なセッションキーや不変のグループ識別子としては使用されません。
• 保存前にルーム名を解決するには、openclaw channels resolve --channel matrix "Project Room"を使用してください。

Tokenベースの最小限の設定：

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}

Passwordベースの設定（ログイン後にTokenがキャッシュされます）：

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

Matrixはキャッシュされた認証情報を~/.openclaw/credentials/matrix/に保存します。 デフォルトアカウントはcredentials.jsonを使用し、名前付きアカウントはcredentials-<account>.jsonを使用します。

環境変数の対応表（設定ファイルのキーが設定されていない場合に使用されます）：

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

デフォルト以外のアカウントでは、アカウントスコープの環境変数を使用してください：

• MATRIX_<ACCOUNT_ID>_HOMESERVER
• MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
• MATRIX_<ACCOUNT_ID>_USER_ID
• MATRIX_<ACCOUNT_ID>_PASSWORD
• MATRIX_<ACCOUNT_ID>_DEVICE_ID
• MATRIX_<ACCOUNT_ID>_DEVICE_NAME

アカウント名がopsの場合の例：

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

正規化されたアカウントIDがops-botの場合は以下を使用します：

• MATRIX_OPS_BOT_HOMESERVER
• MATRIX_OPS_BOT_ACCESS_TOKEN

対話型ウィザードは、これらの認証環境変数が既に存在し、かつ選択したアカウントにMatrix認証が設定ファイルに保存されていない場合にのみ、環境変数のショートカットを提示します。

設定例

これは、DMペアリング、ルームAllowlist、およびE2EEを有効にした実用的なベースライン設定です。

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}

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

Matrixの返信ストリーミングはオプトイン方式です。

OpenClawに1つの下書き返信を送信させ、モデルがテキストを生成している間にその下書きをその場で編集し、返信が完了したときに確定させたい場合は、channels.matrix.streamingを"partial"に設定してください。

{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

• streaming: "off"がデフォルトです。OpenClawは最終的な返信を待ち、一度だけ送信します。
• streaming: "partial"は、複数の部分的なメッセージを送信する代わりに、1つの編集可能なプレビューメッセージを作成します。
• プレビューが1つのMatrixイベントに収まらなくなった場合、OpenClawはプレビューのストリーミングを停止し、通常の最終配信にフォールバックします。
• メディアの返信は、通常通り添付ファイルを送信します。古いプレビューを安全に再利用できない場合、OpenClawは最終的なメディア返信を送信する前にそのプレビューを削除（redact）します。
• プレビューの編集には、追加のMatrix APIコールが発生します。レート制限を最も抑えたい場合は、ストリーミングをオフのままにしてください。

暗号化と検証

暗号化（E2EE）されたルームでは、画像のプレビューも本体と一緒に暗号化されるよう、アウトバウンドの画像イベントに thumbnail_file が使用されます。暗号化されていないルームでは、引き続き通常の thumbnail_url が使用されます。これに関する設定は不要で、プラグインが E2EE の状態を自動的に検知します。

Bot 間の通信

デフォルトでは、他の設定済み OpenClaw Matrix アカウントからの Matrix メッセージは無視されます。

エージェント間の Matrix 通信を意図的に行いたい場合は、allowBots を使用してください。

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

• allowBots: true は、許可されたルームや DM において、他の設定済み Matrix Bot アカウントからのメッセージを受け入れます。
• allowBots: "mentions" は、ルーム内でこの Bot が明示的にメンションされた場合のみ、それらのメッセージを受け入れます。DM は常に許可されます。
• groups.<room>.allowBots は、特定のルームに対してアカウントレベルの設定を上書きします。
• 自己返信のループを避けるため、OpenClaw は同じ Matrix ユーザー ID からのメッセージは引き続き無視します。
• Matrix にはネイティブな Bot フラグが存在しないため、OpenClaw は「この OpenClaw Gateway 上の別の設定済み Matrix アカウントによって送信されたもの」を Bot による投稿として扱います。

共有ルームで Bot 間の通信を有効にする場合は、厳格なルームの許可リスト（allowlist）とメンション要件を併用することをお勧めします。

暗号化を有効にする設定例です：

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

検証ステータスを確認するには、以下のコマンドを使用します：

openclaw matrix verify status

詳細なステータス（完全な診断情報）を表示する場合：

openclaw matrix verify status --verbose

マシン読み取り可能な出力に、保存されているリカバリキーを含める場合：

openclaw matrix verify status --include-recovery-key --json

クロス署名と検証状態をセットアップ（ブートストラップ）する場合：

openclaw matrix verify bootstrap

マルチアカウントのサポート：channels.matrix.accounts を使用し、アカウントごとの認証情報とオプションの name を設定します。共通のパターンについては Configuration reference を参照してください。

ブートストラップの詳細な診断情報を表示する場合：

openclaw matrix verify bootstrap --verbose

ブートストラップの前に、クロス署名の ID リセットを強制的に実行する場合：

openclaw matrix verify bootstrap --force-reset-cross-signing

リカバリキーを使用してこのデバイスを検証する場合：

openclaw matrix verify device "<your-recovery-key>"

デバイス検証の詳細を表示する場合：

openclaw matrix verify device "<your-recovery-key>" --verbose

ルームキーのバックアップ状態を確認する場合：

openclaw matrix verify backup status

バックアップ状態の詳細な診断情報を表示する場合：

openclaw matrix verify backup status --verbose

サーバーのバックアップからルームキーを復元する場合：

openclaw matrix verify backup restore

復元の詳細な診断情報を表示する場合：

openclaw matrix verify backup restore --verbose

現在のサーバーバックアップを削除し、新しいバックアップのベースラインを作成する場合：

openclaw matrix verify backup reset --yes

すべての verify コマンドは、デフォルトでは簡潔な出力を返します（内部 SDK のログも抑制されます）。詳細な診断情報が必要な場合のみ --verbose を使用してください。スクリプトなどで利用する場合は、--json を指定すると完全なマシン読み取り可能な出力が得られます。

マルチアカウント設定では、--account <id> を渡さない限り、Matrix CLI コマンドは暗黙的にデフォルトのアカウントを使用します。複数の名前付きアカウントを設定している場合は、あらかじめ channels.matrix.defaultAccount を設定しておかないと、CLI 操作が停止してアカウントの選択を求められます。特定の名前付きアカウントに対して検証やデバイス操作を行いたい場合は、常に --account を使用してください。

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

名前付きアカウントで暗号化が無効、または利用不可の場合、Matrix の警告や検証エラーはそのアカウントの設定キー（例：channels.matrix.accounts.assistant.encryption）を指し示します。

「検証済み（verified）」の意味

OpenClaw は、この Matrix デバイスがあなた自身のクロス署名 ID によって検証されている場合にのみ、そのデバイスを「検証済み」として扱います。実際には、openclaw matrix verify status --verbose を実行すると、以下の 3 つの信頼シグナルが表示されます。

• Locally trusted: このデバイスは現在のクライアントによってのみ信頼されています。
• Cross-signing verified: SDK が、クロス署名を通じてデバイスが検証されていると報告しています。
• Signed by owner: デバイスがあなた自身のセルフ署名キーによって署名されています。

Verified by owner が yes になるのは、クロス署名による検証、またはオーナーによる署名が存在する場合のみです。ローカルな信頼だけでは、OpenClaw がデバイスを完全に検証済みと見なすには不十分です。

ブートストラップの役割

openclaw matrix verify bootstrap は、暗号化された Matrix アカウントの修復とセットアップのためのコマンドです。このコマンドは、以下の処理を順番に実行します。

• シークレットストレージをセットアップし、可能な場合は既存のリカバリキーを再利用します。
• クロス署名をセットアップし、不足している公開クロス署名キーをアップロードします。
• 現在のデバイスにマークを付け、クロス署名を試みます。
• サーバー側にルームキーのバックアップが存在しない場合、新しく作成します。

クロス署名キーのアップロードにインタラクティブな認証が必要な場合、OpenClaw はまず認証なしで試行し、次に m.login.dummy、そして channels.matrix.password が設定されている場合は m.login.password を使用してアップロードを試みます。

--force-reset-cross-signing は、現在のクロス署名 ID を破棄して新しい ID を作成したい場合にのみ使用してください。

現在のルームキーバックアップを破棄し、将来のメッセージのために新しいバックアップベースラインを開始したい場合は、openclaw matrix verify backup reset --yes を使用します。これを行うと、復旧不可能な古い暗号化履歴は利用できないままになることを理解した上で実行してください。

新しいバックアップベースライン

将来の暗号化メッセージを正常に機能させつつ、古い履歴の損失を許容できる場合は、以下のコマンドを順番に実行してください。

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

特定のアカウントを対象にする場合は、各コマンドに --account <id> を追加してください。

起動時の挙動

encryption: true の場合、Matrix は startupVerification のデフォルト値を "if-unverified" に設定します。起動時にこのデバイスがまだ未検証である場合、Matrix は別の Matrix クライアントで自己検証を行うようリクエストを送信します。すでにリクエストが保留中の場合は重複を避け、再起動後のリトライにはローカルのクールダウン期間が適用されます。デフォルトでは、リクエストの作成に成功した場合よりも、失敗した場合の方が早くリトライされます。自動リクエストを無効にするには startupVerification: "off" を設定し、リトライの間隔を調整したい場合は startupVerificationCooldownHours を設定してください。

また、起動時には自動的に控えめな暗号化ブートストラップが実行されます。このパスでは、まず現在のシークレットストレージとクロス署名 ID の再利用を試み、明示的なブートストラップ修復フローを実行しない限り、クロス署名のリセットは行いません。

起動時にブートストラップの状態に不備が見つかり、かつ channels.matrix.password が設定されている場合、OpenClaw はより厳格な修復パスを試みることができます。現在のデバイスがすでにオーナー署名されている場合、OpenClaw はそれを自動的にリセットせず、その ID を保持します。

以前の公開 Matrix プラグインからのアップグレードについて：

• OpenClaw は、可能な限り同じ Matrix アカウント、アクセス・トークン、デバイス ID を自動的に再利用します。
• Matrix の移行処理が実行される前に、OpenClaw は ~/Backups/openclaw-migrations/ にリカバリ・スナップショットを作成または再利用します。
• 複数の Matrix アカウントを使用している場合、古いフラットなストレージレイアウトからアップグレードする前に channels.matrix.defaultAccount を設定してください。これにより、どのアカウントがレガシーな状態を引き継ぐべきかを OpenClaw が判断できます。
• 以前のプラグインが Matrix ルームキーのバックアップ復号キーをローカルに保存していた場合、起動時または openclaw doctor --fix の実行時に、新しいリカバリキーフローへ自動的にインポートされます。
• 移行の準備後に Matrix アクセス・トークンが変更された場合、起動時にトークンハッシュのストレージルートをスキャンし、自動バックアップ復元を諦める前に保留中のレガシーな復元状態を探します。
• 同じアカウント、ホームサーバー、ユーザーで後からアクセス・トークンが変更された場合、OpenClaw は空のディレクトリから開始するのではなく、最も完全な既存のトークンハッシュ・ストレージルートを再利用することを優先します。
• 次回の Gateway 起動時に、バックアップされたルームキーが新しい暗号化ストアに自動的に復元されます。
• 古いプラグインにバックアップされていないローカルのみのルームキーがあった場合、OpenClaw は警告を表示します。それらのキーは以前の Rust 暗号化ストアから自動的にエクスポートできないため、一部の古い暗号化履歴は手動で復旧するまで利用できない可能性があります。
• 詳細なアップグレード手順、制限事項、復旧コマンドについては Matrix migration を参照してください。

暗号化されたランタイム状態は、~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ の下にあるアカウントごと、ユーザーごとのトークンハッシュルートに整理されます。このディレクトリには、同期ストア（bot-storage.json）、暗号化ストア（crypto/）、リカバリキーファイル（recovery-key.json）、IndexedDB スナップショット（crypto-idb-snapshot.json）、スレッドバインディング（thread-bindings.json）、および起動時の検証状態（startup-verification.json）が含まれます。トークンが変更されてもアカウントの ID が同じであれば、OpenClaw はそのアカウントの最適な既存ルートを再利用するため、以前の同期状態や暗号化状態、スレッドバインディングなどが引き続き保持されます。

Node crypto store モデル

このプラグインの Matrix E2EE は、Node.js 上で動作する公式の matrix-js-sdk Rust 暗号化パスを使用しています。このパスは、暗号化状態を再起動後も保持するために IndexedDB による永続化を必要とします。

OpenClaw は現在、Node.js 環境で以下の方法によりこれを提供しています。

• SDK が期待する IndexedDB API のシムとして fake-indexeddb を使用。
• initRustCrypto の前に、crypto-idb-snapshot.json から Rust 暗号化 IndexedDB の内容を復元。
• 初期化後および実行中に、更新された IndexedDB の内容を crypto-idb-snapshot.json に書き戻して永続化。

これはストレージの互換性を保つための仕組みであり、独自の暗号化実装ではありません。スナップショットファイルは機密性の高いランタイム状態であるため、制限されたファイル権限で保存されます。OpenClaw のセキュリティモデルでは、Gateway ホストとローカルの OpenClaw 状態ディレクトリはすでに信頼された境界内にあるため、これは主に運用の継続性のための設計であり、別のリモート信頼境界を設けるものではありません。

今後の改善予定：

• 永続的な Matrix キー素材に対する SecretRef サポートの追加。これにより、リカバリキーやストア暗号化シークレットをローカルファイルだけでなく、OpenClaw のシークレットプロバイダーから取得できるようになります。

プロフィール管理

選択したアカウントの Matrix プロフィールを更新するには、以下のコマンドを使用します。

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

特定のアカウントを対象にする場合は、--account <id> を追加してください。

Matrix は mxc:// 形式のアバター URL を直接受け入れます。http:// または https:// の URL を渡した場合、OpenClaw はまずそれを Matrix にアップロードし、解決された mxc:// URL を channels.matrix.avatarUrl（または選択したアカウントの上書き設定）に保存します。

自動検証通知

Matrix は、検証ライフサイクルの通知を m.notice メッセージとして、DM 検証ルームに直接投稿するようになりました。これには以下が含まれます。

• 検証リクエストの通知
• 検証準備完了の通知（「絵文字で検証」の具体的な案内を含む）
• 検証の開始と完了の通知
• 利用可能な場合の SAS（絵文字および数値）の詳細

他の Matrix クライアントからの検証リクエストは OpenClaw によって追跡され、自動的に承認されます。自己検証フローの場合、OpenClaw は絵文字検証が利用可能になると自動的に SAS フローを開始し、自身の側を承認します。他の Matrix ユーザーやデバイスからの検証リクエストの場合、OpenClaw はリクエストを自動承認した後、SAS フローが通常通り進むのを待ちます。検証を完了させるには、引き続き Matrix クライアントで絵文字や数値を比較し、「一致する」ことを確認する必要があります。

OpenClaw は、自身が開始した重複するフローを盲目的に自動承認することはありません。起動時、すでに自己検証リクエストが保留中の場合は、新しいリクエストの作成をスキップします。

検証プロトコルやシステム通知はエージェントのチャットパイプラインには転送されないため、NO_REPLY が生成されることはありません。

デバイスの整理

OpenClaw が管理する古い Matrix デバイスがアカウントに蓄積されると、暗号化ルームの信頼関係の把握が難しくなることがあります。以下のコマンドでデバイスを一覧表示できます。

openclaw matrix devices list

不要になった OpenClaw 管理デバイスを削除するには、以下のコマンドを使用します。

openclaw matrix devices prune-stale

ダイレクトルームの修復

ダイレクトメッセージ（DM）の状態が同期しなくなった場合、OpenClaw は古い 1 対 1 ルームを指す古い m.direct マッピングを保持してしまうことがあります。特定の相手に対する現在のマッピングを確認するには、以下のコマンドを使用します。

openclaw matrix direct inspect --user-id @alice:example.org

これを修復するには、以下のコマンドを実行します。

openclaw matrix direct repair --user-id @alice:example.org

修復フローは、プラグイン内部で Matrix 特有のロジックを実行します。

• すでに m.direct にマップされている厳格な 1 対 1 DM を優先します。
• それがない場合は、そのユーザーと現在参加している厳格な 1 対 1 DM を探します。
• 適切な DM が存在しない場合は、新しいダイレクトルームを作成し、それを指すように m.direct を書き換えます。

修復フローは古いルームを自動的に削除しません。適切な DM を選択してマッピングを更新するだけなので、新しい Matrix 送信、検証通知、その他のダイレクトメッセージフローが再び正しいルームをターゲットにするようになります。

スレッド

Matrix は、自動返信とメッセージツールによる送信の両方で、ネイティブな Matrix スレッドをサポートしています。

• threadReplies: "off" は、返信をトップレベルに保ち、インバウンドのスレッドメッセージを親セッションに維持します。
• threadReplies: "inbound" は、受信したメッセージがすでにスレッド内にある場合にのみ、そのスレッド内で返信します。
• threadReplies: "always" は、ルーム内での返信をトリガーとなったメッセージを起点とするスレッド内に保持し、その会話を最初のトリガーメッセージから一致するスレッドスコープのセッションにルーティングします。
• dm.threadReplies は、DM に対してのみトップレベルの設定を上書きします。例えば、ルームのスレッドは分離したまま、DM はフラットな状態に保つことができます。
• インバウンドのスレッドメッセージには、エージェントのコンテキストとしてスレッドのルートメッセージが含まれます。
• メッセージツールによる送信は、送信先が同じルームまたは同じ DM ユーザーである場合、明示的な threadId が指定されない限り、現在の Matrix スレッドを自動的に継承します。
• Matrix ではランタイムのスレッドバインディングがサポートされています。/focus, /unfocus, /agents, /session idle, /session max-age, およびスレッドに紐付いた /acp spawn が Matrix ルームおよび DM で機能します。
• トップレベルの Matrix ルームや DM で /focus を実行すると、新しい Matrix スレッドが作成され、threadBindings.spawnSubagentSessions=true の場合にターゲットセッションにバインドされます。
• 既存の Matrix スレッド内で /focus または /acp spawn --thread here を実行すると、その現在のスレッドがバインドされます。

ACP 会話バインディング

Matrix のルームや DM、既存のスレッドを、チャット画面を変えることなく永続的な ACP ワークスペースに変換できます。

スムーズな操作フロー：

• 使用したい Matrix の DM、ルーム、または既存のスレッド内で /acp spawn codex --bind here を実行します。
• トップレベルの Matrix DM やルームでは、現在の DM/ルームがチャット画面として維持され、今後のメッセージは生成された ACP セッションにルーティングされます。
• 既存の Matrix スレッド内では、--bind here によってそのスレッドがその場でバインドされます。
• /new や /reset を使うと、バインドされた同じ ACP セッションをその場でリセットできます。
• /acp close を実行すると、ACP セッションが終了し、バインディングが解除されます。

注意点：

• --bind here は子スレッドを作成しません。
• threadBindings.spawnAcpSessions は、OpenClaw が子スレッドを作成またはバインドする必要がある /acp spawn --thread auto|here の場合にのみ必要です。

スレッドバインディング設定

Matrix は session.threadBindings からグローバルなデフォルト設定を継承しますが、チャンネルごとのオーバーライドもサポートしています：

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSubagentSessions
• threadBindings.spawnAcpSessions

Matrix のスレッドバインドに関連する spawn フラグはオプトイン方式です：

• トップレベルの /focus で新しい Matrix スレッドを作成・バインドできるようにするには、threadBindings.spawnSubagentSessions: true を設定します。
• /acp spawn --thread auto|here で ACP セッションを Matrix スレッドにバインドできるようにするには、threadBindings.spawnAcpSessions: true を設定します。

リアクション

Matrix は、外部へのリアクション送信、受信したリアクションの通知、および受信した Ack リアクションをサポートしています。

• 外部へのリアクションツールは channels["matrix"].actions.reactions で制御されます。
• react は特定の Matrix イベントにリアクションを追加します。
• reactions は特定の Matrix イベントの現在のリアクション概要をリスト表示します。
• emoji="" は、そのイベントに対するボットアカウント自身のリアクションを削除します。
• remove: true は、ボットアカウントから指定された絵文字リアクションのみを削除します。

Ack リアクションは、以下の標準的な OpenClaw 解決順序を使用します：

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• エージェントのアイデンティティ絵文字（フォールバック）

Ack リアクションのスコープは以下の順序で解決されます：

• channels["matrix"].accounts.<accountId>.ackReactionScope
• channels["matrix"].ackReactionScope
• messages.ackReactionScope

リアクション通知モードは以下の順序で解決されます：

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• デフォルト：own

現在の動作：

• reactionNotifications: "own" は、ボットが作成した Matrix メッセージを対象とした m.reaction イベントが追加された場合に、それを転送します。
• reactionNotifications: "off" は、リアクションのシステムイベントを無効にします。
• リアクションの削除は、Matrix では独立した m.reaction の削除ではなく「編集（redactions）」として表示されるため、まだシステムイベントには統合されていません。

履歴コンテキスト

• channels.matrix.historyLimit は、Matrix ルームのメッセージがエージェントをトリガーした際に、直近のメッセージをいくつ InboundHistory として含めるかを制御します。
• 設定がない場合は messages.groupChat.historyLimit にフォールバックされます。無効にするには 0 を設定してください。
• Matrix ルームの履歴はルーム限定です。DM では引き続き通常のセッション履歴が使用されます。
• Matrix ルームの履歴は「保留中（pending）」のみが対象です。OpenClaw はまだ返信をトリガーしていないルームメッセージをバッファリングし、メンションなどのトリガーが届いた際にそのウィンドウのスナップショットを作成します。
• 現在のトリガーメッセージは InboundHistory には含まれず、そのターンのメインの受信ボディに残ります。
• 同じ Matrix イベントをリトライする場合、新しいルームメッセージへとずれるのではなく、元の履歴スナップショットを再利用します。
• 取得されたルームコンテキスト（返信やスレッドコンテキストのルックアップを含む）は、送信者の許可リスト（groupAllowFrom）によってフィルタリングされるため、許可リストにないメッセージはエージェントのコンテキストから除外されます。

DM とルームポリシーの例

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

メンションによる制限や許可リストの動作については、Groups を参照してください。

Matrix DM のペアリング例：

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

承認されていない Matrix ユーザーが承認前にメッセージを送り続けた場合、OpenClaw は同じ保留中のペアリングコードを再利用します。また、新しいコードを発行する代わりに、短いクールダウンの後に再度リマインドの返信を送信することがあります。

共通の DM ペアリングフローとストレージレイアウトについては、Pairing を参照してください。

マルチアカウントの設定例

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

channels.matrix のトップレベルに記述した値は、個別のアカウントで上書きしない限り、すべての名前付きアカウントのデフォルト設定として機能します。

継承されたルームのエントリを特定の Matrix アカウントに紐付けるには、groups.<room>.account（または以前の rooms.<room>.account）を使用してください。account を指定しないエントリはすべての Matrix アカウントで共有されます。また、トップレベルの channels.matrix.* にデフォルトアカウントが直接設定されている場合、account: "default" と指定したエントリも引き続き動作します。

認証設定の一部を共有しているだけでは、それだけで暗黙のデフォルトアカウントが作成されるわけではありません。OpenClaw がトップレベルの default アカウントを自動生成するのは、そのデフォルト設定に新しい認証情報（homeserver と accessToken、または homeserver と userId および password）が含まれている場合のみです。名前付きアカウントは、キャッシュされた認証情報が後で認証を満たす場合、homeserver と userId から引き続き検出可能です。

暗黙的なルーティング、プロービング、CLI 操作で特定のアカウントを優先的に使用したい場合は、defaultAccount を設定しましょう。

複数の名前付きアカウントを設定する場合は、defaultAccount を指定するか、暗黙的なアカウント選択に依存する CLI コマンドを実行する際に --account <id> を渡すようにしてください。特定のコマンドでこの選択を上書きしたい場合は、openclaw matrix verify ... や openclaw matrix devices ... に --account <id> を付与して実行します。

プライベート/LAN 内の homeserver

デフォルトでは、OpenClaw は SSRF 保護のため、アカウントごとに明示的に許可しない限り、プライベートまたは内部の Matrix homeserver をブロックします。

homeserver が localhost、LAN/Tailscale の IP、または内部ホスト名で動作している場合は、その Matrix アカウントで allowPrivateNetwork を有効にする必要があります。

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: true,
      accessToken: "syt_internal_xxx",
    },
  },
}

CLI で設定する場合は、以下のようになります。

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

この設定は、信頼できるプライベート/内部ターゲットのみを許可するものです。http://matrix.example.org:8008 のような公開されている平文の homeserver は引き続きブロックされます。セキュリティのため、可能な限り https:// を使用することをお勧めします。

Matrix トラフィックのプロキシ設定

Matrix のデプロイメントで明示的なアウトバウンド HTTP(S) プロキシが必要な場合は、channels.matrix.proxy を設定してください。

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

名前付きアカウント（Named accounts）を使用している場合は、channels.matrix.accounts.<id>.proxy を指定することで、トップレベルのデフォルト設定を個別に上書きできます。OpenClaw は、実行時の Matrix トラフィックとアカウントのステータス確認（status probes）の両方に同じプロキシ設定を使用します。

ターゲットの解決

OpenClaw がルームやユーザーのターゲットを要求する箇所では、Matrix は以下の形式を受け入れます。

• ユーザー: @user:server, user:@user:server, または matrix:user:@user:server
• ルーム: !room:server, room:!room:server, または matrix:room:!room:server
• エイリアス: #alias:server, channel:#alias:server, または matrix:channel:#alias:server

ライブディレクトリの検索には、ログイン中の Matrix アカウントが使用されます。

• ユーザー検索は、その homeserver 上の Matrix ユーザーディレクトリに対してクエリを実行します。
• ルーム検索は、明示的なルーム ID やエイリアスを直接受け入れます。それらで見つからない場合は、そのアカウントが参加しているルーム名の検索を試みます。
• 参加済みルーム名の検索はベストエフォートで行われます。ルーム名を ID やエイリアスに解決できない場合、実行時の allowlist 解決では無視されます。

設定リファレンス

• enabled: チャンネルを有効または無効にします。
• name: アカウントを識別するための任意のラベルです。
• defaultAccount: 複数の Matrix アカウントが設定されている場合に優先されるアカウント ID です。
• homeserver: homeserver の URL です（例: https://matrix.example.org）。
• allowPrivateNetwork: プライベートまたは内部の homeserver への接続を許可します。homeserver が localhost、LAN/Tailscale の IP、または matrix-synapse などの内部ホストとして解決される場合に有効にしてください。
• proxy: Matrix 通信に使用するオプションの HTTP(S) proxy URL です。名前付きアカウントでは、トップレベルのデフォルト設定を独自の設定で上書きできます。
• userId: Matrix のフルユーザー ID です（例: @bot:example.org）。
• accessToken: トークンベース認証用のアクセス権限トークンです。env/file/exec プロバイダーを通じて、channels.matrix.accessToken や channels.matrix.accounts.<id>.accessToken でプレーンテキストおよび SecretRef 値がサポートされています。詳細は Secrets Management を参照してください。
• password: パスワードベースのログイン用パスワードです。プレーンテキストおよび SecretRef 値がサポートされています。
• deviceId: 明示的な Matrix デバイス ID です。
• deviceName: パスワードログイン時のデバイス表示名です。
• avatarUrl: プロフィール同期や set-profile 更新用に保存されるアバターの URL です。
• initialSyncLimit: 起動時の同期イベント制限数です。
• encryption: E2EE を有効にします。
• allowlistOnly: DM やルームに対して、ホワイトリストのみの動作を強制します。
• groupPolicy: open、allowlist、または disabled のいずれかを指定します。
• groupAllowFrom: ルーム通信を許可するユーザー ID のホワイトリストです。
• groupAllowFrom のエントリは、Matrix のフルユーザー ID である必要があります。解決できない名前は実行時に無視されます。
• historyLimit: グループ履歴のコンテキストとして含めるルームメッセージの最大数です。設定されていない場合は messages.groupChat.historyLimit が使用されます。無効にするには 0 を設定してください。
• replyToMode: off、first、または all を指定します。
• streaming: off（デフォルト）または partial を指定します。partial を選択すると、インプレース編集による更新が可能な単一メッセージのドラフトプレビューが有効になります。
• threadReplies: off、inbound、または always を指定します。
• threadBindings: スレッドに紐づくセッションルーティングとライフサイクルのチャンネルごとの上書き設定です。
• startupVerification: 起動時の自動自己検証リクエストモードです（if-unverified、off）。
• startupVerificationCooldownHours: 自動起動検証リクエストを再試行するまでのクールダウン時間（時間単位）です。
• textChunkLimit: 送信メッセージのチャンクサイズです。
• chunkMode: length または newline を指定します。
• responsePrefix: 送信される返信に付与するオプションのメッセージプレフィックスです。
• ackReaction: このチャンネル/アカウント用のオプションの確認（ack）リアクション上書き設定です。
• ackReactionScope: オプションの確認リアクションスコープの上書き設定です（group-mentions、group-all、direct、all、none、off）。
• reactionNotifications: 受信リアクションの通知モードです（own、off）。
• mediaMaxMb: Matrix メディア処理におけるメディアサイズの制限（MB）です。送信および受信メディアの処理に適用されます。
• autoJoin: 招待への自動参加ポリシーです（always、allowlist、off）。デフォルトは off です。
• autoJoinAllowlist: autoJoin が allowlist の場合に許可されるルームまたはエイリアスです。エイリアスエントリは招待処理中にルーム ID に解決されます。OpenClaw は招待されたルームが主張するエイリアスの状態を信頼しません。
• dm: DM ポリシーブロックです（enabled、policy、allowFrom、threadReplies）。
• dm.allowFrom のエントリは、ライブディレクトリ検索ですでに解決済みでない限り、Matrix のフルユーザー ID である必要があります。
• dm.threadReplies: DM 専用のスレッドポリシー上書き設定です（off、inbound、always）。DM における返信の配置とセッション分離の両方について、トップレベルの threadReplies 設定を上書きします。
• accounts: アカウントごとの名前付き上書き設定です。トップレベルの channels.matrix の値がこれらのエントリのデフォルトとして機能します。
• groups: ルームごとのポリシーマップです。ルーム ID またはエイリアスの使用を推奨します。解決できないルーム名は実行時に無視されます。セッション/グループの識別には解決後の恒久的なルーム ID が使用されますが、人間が読めるラベルには引き続きルーム名が使用されます。
• rooms: groups のレガシーなエイリアスです。
• actions: アクションごとのツール制限設定です（messages、reactions、pins、profile、memberInfo、channelInfo、verification）。

関連ドキュメント

• Channels Overview — サポートされているすべてのチャンネル
• Pairing — DM 認証とペアリングのフロー
• Groups — グループチャットの動作とメンション制限
• Channel Routing — メッセージのセッションルーティング
• Security — アクセスモデルとセキュリティ強化

AI Setup Assistant