Matrix（プラグイン）

Matrixは、オープンで分散型のメッセージングプロトコルです。OpenClawは、任意のホームサーバー上でMatrixユーザーとして接続するため、ボット用のMatrixアカウントが必要です。ログインすると、ボットに直接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

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

詳細: プラグイン

セットアップ

Matrixプラグインをインストール:
- npmから: openclaw plugins install @openclaw/matrix
- ローカルチェックアウトから: openclaw plugins install ./extensions/matrix
ホームサーバーでMatrixアカウントを作成:
- https://matrix.org/ecosystem/hosting/でホスティングオプションを閲覧
- または自分でホストします。
ボットアカウントのアクセストークンを取得:
- ホームサーバーで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）である必要があります。
Gatewayを再起動します（またはオンボーディングを完了します）。
任意のMatrixクライアント（Element、Beeperなど。https://matrix.org/ecosystem/clients/ を参照）からボットと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 crypto 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と一緒に保存されます。アクセストークン（デバイス）が変更されると、新しいストアが作成され、暗号化されたルームのためにボットを再検証する必要があります。

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

ルーティングモデル

返信は常に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はユーザーIDまたは表示名を受け入れます。ウィザードは、ディレクトリ検索が利用可能な場合、表示名をユーザーIDに解決します。

ルーム（グループ）

デフォルト: channels.matrix.groupPolicy = "allowlist"（メンション制限）。未設定の場合にデフォルトをオーバーライドするにはchannels.defaults.groupPolicyを使用します。
channels.matrix.groupsでルームを許可リストに追加（ルームID、エイリアス、または名前）:

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

requireMention: falseはそのルームで自動返信を有効にします。
groups."*"はルーム全体でメンション制限のデフォルトを設定できます。
groupAllowFromは、ルーム内でボットをトリガーできる送信者を制限します（オプション）。
ルームごとのusers許可リストは、特定のルーム内の送信者をさらに制限できます。
設定ウィザードはルーム許可リスト（ルーム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はスレッド内で返信しない場合の返信先メタデータを制御します:
- off（デフォルト）、first、all

機能

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

設定リファレンス（Matrix）

完全な設定: 設定

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

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許可リスト（ユーザーIDまたは表示名）。openには"*"が必要です。ウィザードは可能な場合、名前をIDに解決します。
channels.matrix.groupPolicy: allowlist | open | disabled（デフォルト: allowlist）。
channels.matrix.groupAllowFrom: グループメッセージ用の許可された送信者。
channels.matrix.allowlistOnly: DM + ルームに許可リストルールを強制。
channels.matrix.groups: グループ許可リスト + ルームごとの設定マップ。
channels.matrix.rooms: レガシーグループ許可リスト/設定。
channels.matrix.replyToMode: スレッド/タグの返信先モード。
channels.matrix.mediaMaxMb: インバウンド/アウトバウンドメディア上限（MB）。
channels.matrix.autoJoin: 招待処理（always | allowlist | off、デフォルト: always）。
channels.matrix.autoJoinAllowlist: 自動参加用の許可されたルームID/エイリアス。
channels.matrix.actions: アクションごとのツール制限（reactions/messages/pins/memberInfo/channelInfo）。