​

Matrix（プラグイン）

​

プラグインが必要

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

セットアップ

1. Matrix プラグインをインストールします:
   • npm から: openclaw plugins install @openclaw/matrix
   • ローカルチェックアウトから: openclaw plugins install ./extensions/matrix
2. ホームサーバー上で Matrix アカウントを作成します:
   • https://matrix.org/ecosystem/hosting/ でホスティングオプションを確認します。
   • または、自身でホストします。
3. ボットアカウント用のアクセストークンを取得します:
   • ホームサーバー上で、curl を使用して Matrix ログイン 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 に保存し、次回起動時に再利用します。
4. 認証情報を設定します:
   • 環境変数: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN（または MATRIX_USER_ID と MATRIX_PASSWORD）
   • または設定: channels.matrix.*
   • 両方が設定されている場合は、設定ファイルが優先されます。
   • アクセストークンを使用する場合、ユーザー ID は /whoami により自動取得されます。
   • 設定する場合、channels.matrix.userId は完全な Matrix ID である必要があります（例: @bot:example.org）。
5. Gateway（ゲートウェイ）を再起動します（またはオンボーディングを完了します）。
6. 任意の Matrix クライアント（Element、Beeper など。詳細は https://matrix.org/ecosystem/clients/ を参照）からボットとの DM を開始するか、ルームに招待します。Beeper では E2EE が必要なため、channels.matrix.encryption: true を設定し、デバイスを検証してください。 Beer には E2EE が必要なので、channels.matrix.encryption: true を設定してデバイスを確認します。 Beer には E2EE が必要なので、channels.matrix.encryption: true を設定してデバイスを確認します。

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

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

​

暗号化（E2EE）

• crypto モジュールがロードされると、暗号化されたルームは自動的に復号されます。
• 暗号化されたルームに送信する際、送信メディアは暗号化されます。
• 初回接続時に、OpenClaw は他のセッションに対してデバイス検証を要求します。
• 別の Matrix クライアント（Element など）でデバイスを検証し、キー共有を有効にします。 キーの共有を可能にしました
• crypto モジュールをロードできない場合、E2EE は無効化され、暗号化されたルームは復号されません。OpenClaw は警告をログに出力します。
• crypto モジュールが見つからないエラー（例: @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 でバイナリを取得してください。

​

マルチアカウント

{
  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 に解決します。 ディレクトリ検索で完全一致が見つかった場合、ウィザードは名前をユーザー ID に表示します。 ディレクトリ検索で完全一致が見つかった場合、ウィザードは名前をユーザー ID に表示します。
• 表示名やローカルパートのみ（例: "Alice" や "alice"）は使用しないでください。 これらは曖昧であり、allowlist照合では無視されます。 完全な@user:server形式のIDを使用してください。

​

ルーム（グループ）

• デフォルト: channels.matrix.groupPolicy = "allowlist"（メンション制御）。未設定の場合、channels.defaults.groupPolicy でデフォルトを上書きできます。 .tools: チャンネル上書きがない場合に使用される、チームごとのデフォルトツールポリシー上書き（allow/deny/alsoAllow`）。 .tools: チャンネル上書きがない場合に使用される、チームごとのデフォルトツールポリシー上書き（allow/deny/alsoAllow`）。
• 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 は、ルーム内でボットをトリガーできる送信者を制限します（完全な 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

​

機能

​

トラブルシューティング

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

openclaw pairing list matrix

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

​

設定リファレンス（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 許可リスト（完全な Matrix ユーザー ID）。open には "*" が必要です。ウィザードは可能な場合に名前を ID に解決します。 openには"*"が必要です。 可能な場合、ウィザードは 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）。