Matrix（プラグイン）

Matrixはオープンで分散型のメッセージングプロトコルです。OpenClawは任意のホームサーバー上のMatrixユーザーとして接続するため、Bot用のMatrixアカウントが必要です。ログインすると、Botに直接DMを送ったり、ルーム（Matrixの「グループ」）に招待したりできます。Beeperも有効なクライアントオプションですが、E2EEを有効にする必要があります。

ステータス：プラグイン経由でサポート（@vector-im/matrix-bot-sdk）。ダイレクトメッセージ、ルーム、スレッド、メディア、リアクション、投票（送信 + poll-startをテキストとして）、位置情報、E2EE（暗号化サポート付き）。

プラグインが必要

Matrixはプラグインとして提供され、コアインストールにはバンドルされていません。

CLI経由でインストール（npmレジストリ）：

openclaw plugins install @openclaw/matrix

ローカルチェックアウト（gitリポジトリから実行する場合）：

openclaw plugins install ./extensions/matrix

設定/オンボーディング中にMatrixを選択し、gitチェックアウトが検出された場合、OpenClawは自動的にローカルインストールパスを提案します。

詳細：プラグイン

セットアップ

Matrixプラグインをインストールします：
- npmから：openclaw plugins install @openclaw/matrix
- ローカルチェックアウトから：openclaw plugins install ./extensions/matrix
ホームサーバー上にMatrixアカウントを作成します：
- ホスティングオプションはhttps://matrix.org/ecosystem/hosting/で確認できます
- または自分でホスティングします。
Botアカウントのアクセストークンを取得します：
- ホームサーバーで curl を使用してMatrix login APIを呼び出します：
```
curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "your-user-name"
  },
  "password": "your-password"
}'
```
- matrix.example.org をあなたのホームサーバーURLに置き換えてください。
- または channels.matrix.userId + channels.matrix.password を設定します：OpenClawは同じログインエンドポイントを呼び出し、アクセストークンを ~/.openclaw/credentials/matrix/credentials.json に保存し、次回起動時に再利用します。
認証情報を設定します：
- 環境変数：MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN（または MATRIX_USER_ID + MATRIX_PASSWORD）
- または設定：channels.matrix.*
- 両方が設定されている場合、設定が優先されます。
- アクセストークン使用時：ユーザーIDは /whoami 経由で自動取得されます。
- 設定する場合、channels.matrix.userId は完全なMatrix ID（例：@bot:example.org）である必要があります。
ゲートウェイを再起動します（またはオンボーディングを完了します）。
任意のMatrixクライアント（Element、Beeperなど。https://matrix.org/ecosystem/clients/を参照）からBotにDMを送るか、ルームに招待します。BeeperはE2EEが必要なため、channels.matrix.encryption: true を設定し、デバイスを検証してください。

最小設定（アクセストークン、ユーザーID自動取得）：

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

E2EE設定（エンドツーエンド暗号化有効）：

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

暗号化（E2EE）

エンドツーエンド暗号化はRust暗号化SDKを通じてサポートされています。

channels.matrix.encryption: true で有効にします：

暗号化モジュールが読み込まれると、暗号化されたルームは自動的に復号されます。
暗号化されたルームに送信する際、送信メディアも暗号化されます。
初回接続時、OpenClawは他のセッションにデバイス検証をリクエストします。
別のMatrixクライアント（Elementなど）でデバイスを検証し、鍵共有を有効にしてください。
暗号化モジュールが読み込めない場合、E2EEは無効になり、暗号化されたルームは復号できません。OpenClawは警告をログに記録します。
暗号化モジュールのエラー（例：@matrix-org/matrix-sdk-crypto-nodejs-*）が表示される場合、@matrix-org/matrix-sdk-crypto-nodejs のビルドスクリプトを許可し、pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs を実行するか、node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js でバイナリを取得してください。

暗号化状態はアカウント + アクセストークンごとに ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/（SQLiteデータベース）に保存されます。同期状態は隣接する bot-storage.json に保存されます。アクセストークン（デバイス）が変更されると、新しいストアが作成され、暗号化されたルームではBotを再検証する必要があります。

デバイス検証： E2EEが有効な場合、Botは起動時に他のセッションに検証をリクエストします。Element（または別のクライアント）を開き、検証リクエストを承認して信頼を確立してください。検証が完了すると、Botは暗号化されたルームでメッセージを復号できるようになります。

マルチアカウント

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

各アカウントは任意のホームサーバー上で別々のMatrixユーザーとして実行されます。アカウントごとの設定はトップレベルの channels.matrix 設定を継承し、任意のオプション（DMポリシー、グループ、暗号化など）をオーバーライドできます。

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

注意事項：

アカウントの起動は、同時モジュールインポートとの競合を避けるためにシリアライズされます。
環境変数（MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN など）はデフォルトアカウントにのみ適用されます。
ベースチャンネル設定（DMポリシー、グループポリシー、メンションゲーティングなど）は、アカウントごとにオーバーライドされない限りすべてのアカウントに適用されます。
bindings[].match.accountId を使用して各アカウントを異なるエージェントにルーティングします。
暗号化状態はアカウント + アクセストークンごとに保存されます（アカウントごとに個別のキーストア）。

ルーティングモデル

返信は常にMatrixに戻ります。
DMはエージェントのメインセッションを共有し、ルームはグループセッションにマッピングされます。

アクセス制御（DM）

デフォルト：channels.matrix.dm.policy = "pairing"。不明な送信者にはペアリングコードが表示されます。
以下の方法で承認します：
- openclaw pairing list matrix
- openclaw pairing approve matrix <CODE>
パブリックDM：channels.matrix.dm.policy="open" + channels.matrix.dm.allowFrom=["*"]。
channels.matrix.dm.allowFrom は完全なMatrix ユーザーID（例：@user:server）を受け付けます。ウィザードはディレクトリ検索で単一の完全一致が見つかった場合、表示名をユーザーIDに解決します。
表示名や裸のローカルパート（例："Alice" や "alice"）は使用しないでください。これらは曖昧であり、許可リストのマッチングでは無視されます。完全な @user:server IDを使用してください。

ルーム（グループ）

デフォルト：channels.matrix.groupPolicy = "allowlist"（メンションゲーティング）。未設定時のデフォルトをオーバーライドするには channels.defaults.groupPolicy を使用します。
ランタイムの注意：channels.matrix が完全に欠落している場合、ランタイムはルームチェックに対して groupPolicy="allowlist" にフォールバックします（channels.defaults.groupPolicy が設定されていても）。
channels.matrix.groups でルームを許可リストに登録します（ルームIDまたはエイリアス。名前はディレクトリ検索で単一の完全一致が見つかった場合にIDに解決されます）：

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

requireMention: false でそのルームの自動返信を有効にします。
groups."*" でルーム間のメンションゲーティングのデフォルトを設定できます。
groupAllowFrom はルーム内でBotをトリガーできる送信者を制限します（完全なMatrix ユーザーID）。
ルームごとの users 許可リストで、特定のルーム内の送信者をさらに制限できます（完全なMatrix ユーザーIDを使用）。
設定ウィザードはルーム許可リスト（ルームID、エイリアス、または名前）のプロンプトを表示し、名前は完全かつ一意の一致のみで解決されます。
起動時、OpenClawは許可リスト内のルーム/ユーザー名をIDに解決し、マッピングをログに記録します。解決されなかったエントリは許可リストのマッチングでは無視されます。
招待はデフォルトで自動参加されます。channels.matrix.autoJoin と channels.matrix.autoJoinAllowlist で制御します。
ルームなしを許可するには、channels.matrix.groupPolicy: "disabled" を設定します（または空の許可リストを保持します）。
レガシーキー：channels.matrix.rooms（groups と同じ形式）。

スレッド

返信スレッドがサポートされています。
channels.matrix.threadReplies は返信がスレッド内に留まるかどうかを制御します：
- off、inbound（デフォルト）、always
channels.matrix.replyToMode はスレッドで返信しない場合のreply-toメタデータを制御します：
- off（デフォルト）、first、all

機能

機能	ステータス
ダイレクトメッセージ	✅ サポート済み
ルーム	✅ サポート済み
スレッド	✅ サポート済み
メディア	✅ サポート済み
E2EE	✅ サポート済み（暗号化モジュールが必要）
リアクション	✅ サポート済み（ツール経由で送信/読み取り）
投票	✅ 送信サポート。受信poll startはテキストに変換されます（回答/終了は無視）
位置情報	✅ サポート済み（geo URI、高度は無視）
ネイティブコマンド	✅ サポート済み

トラブルシューティング

まず以下の手順を実行してください：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

必要に応じてDMペアリング状態を確認してください：

openclaw pairing list matrix

よくある障害：

ログインしているがルームメッセージが無視される：groupPolicy またはルーム許可リストによりブロックされています。
DMが無視される：channels.matrix.dm.policy="pairing" の場合、送信者が承認待ちです。
暗号化されたルームが失敗する：暗号化サポートまたは暗号化設定の不一致です。

トリアージフローについて：/channels/troubleshooting。

設定リファレンス（Matrix）

完全な設定：Configuration

プロバイダーオプション：

channels.matrix.enabled：チャンネルの起動を有効/無効にします。
channels.matrix.homeserver：ホームサーバーURL。
channels.matrix.userId：MatrixユーザーID（アクセストークンがあれば省略可能）。
channels.matrix.accessToken：アクセストークン。
channels.matrix.password：ログイン用パスワード（トークンが保存されます）。
channels.matrix.deviceName：デバイス表示名。
channels.matrix.encryption：E2EEを有効化（デフォルト：false）。
channels.matrix.initialSyncLimit：初期同期制限。
channels.matrix.threadReplies：off | inbound | always（デフォルト：inbound）。
channels.matrix.textChunkLimit：送信テキストのチャンクサイズ（文字数）。
channels.matrix.chunkMode：length（デフォルト）または newline（長さチャンキングの前に空行（段落境界）で分割）。
channels.matrix.dm.policy：pairing | allowlist | open | disabled（デフォルト：pairing）。
channels.matrix.dm.allowFrom：DM許可リスト（完全なMatrixユーザーID）。open には "*" が必要です。ウィザードは可能な場合に名前をIDに解決します。
channels.matrix.groupPolicy：allowlist | open | disabled（デフォルト：allowlist）。
channels.matrix.groupAllowFrom：グループメッセージの許可された送信者（完全なMatrixユーザーID）。
channels.matrix.allowlistOnly：DMとルームの両方で許可リストルールを強制します。
channels.matrix.groups：グループ許可リスト + ルームごとの設定マップ。
channels.matrix.rooms：レガシーグループ許可リスト/設定。
channels.matrix.replyToMode：スレッド/タグのreply-toモード。
channels.matrix.mediaMaxMb：インバウンド/アウトバウンドメディア上限（MB）。
channels.matrix.autoJoin：招待処理（always | allowlist | off、デフォルト：always）。
channels.matrix.autoJoinAllowlist：自動参加のための許可されたルームID/エイリアス。
channels.matrix.accounts：アカウントIDでキー付けされたマルチアカウント設定（各アカウントはトップレベル設定を継承）。
channels.matrix.actions：アクションごとのツールゲーティング（reactions/messages/pins/memberInfo/channelInfo）。