【最新版】MatrixでOpenClawを使う方法（DM・ルーム・E2EE対応）

2026年3月18日

Matrix

Matrix はオープンで分散型のメッセージングプロトコルです。OpenClaw は任意の homeserver 上で 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

セットアップ中に Matrix を選び、かつ git チェックアウトが検出されると、OpenClaw はローカルのインストールパスを自動で提案します。

詳細： Plugins

セットアップ

Matrix プラグインをインストールします：
- npm から：openclaw plugins install @openclaw/matrix
- ローカルチェックアウトから：openclaw plugins install ./extensions/matrix
homeserver 上にボット用の Matrix アカウントを作成します：
- ホスティングの選択肢： https://matrix.org/ecosystem/hosting/
- または自前でホストします。
ボットアカウントのアクセストークンを取得します：
- 自分の homeserver に対して、Matrix の login API を curl で呼び出します：
```
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 を自分の homeserver URL に置き換えてください。
- または channels.matrix.userId + channels.matrix.password を設定します。OpenClaw は同じログインエンドポイントを呼び出し、アクセストークンを ~/.openclaw/credentials/matrix/credentials.json に保存し、次回起動時に再利用します。
認証情報を設定します：
- 環境変数：MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN（または MATRIX_USER_ID + MATRIX_PASSWORD）
- または config：channels.matrix.*
- 両方が設定されている場合、config が優先されます。
- アクセストークンを使う場合、ユーザー ID は /whoami で自動取得されます。
- 設定する場合、channels.matrix.userId は完全な Matrix ID にしてください（例：@bot:example.org）。
Gateway を再起動します（またはセットアップを完了します）。
任意の Matrix クライアント（Element、Beeper など）からボットに DM を送るか、ルームに招待します： https://matrix.org/ecosystem/clients/。Beeper は E2EE が必要なので、channels.matrix.encryption: true を設定し、デバイスを検証してください。

最小構成（アクセストークン、user 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 で有効化：

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 でバイナリを取得してください。

crypto の状態は、アカウント + アクセストークン単位で ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/（SQLite DB）に保存されます。同期状態は同じ場所にある bot-storage.json に保存されます。アクセストークン（デバイス）が変わると新しいストアが作られ、暗号化ルームを扱うには再検証が必要です。

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

マルチアカウント

マルチアカウント対応：channels.matrix.accounts を使い、アカウントごとの認証情報と任意の name を設定します。共通パターンは gateway/configurationを参照してください。

各アカウントは任意の homeserver 上で別々の 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"] },
        },
      },
    },
  },
}

注記：

アカウントの起動は、同時 import による競合（race conditions）を避けるためシリアライズされます。
環境変数（MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN など）はデフォルトアカウントにのみ適用されます。
ベースのチャネル設定（DM ポリシー、グループポリシー、メンション制御など）は、アカウント単位で上書きしない限り全アカウントに適用されます。
bindings[].match.accountId を使うと、アカウントごとに別のエージェントへルーティングできます。
crypto の状態はアカウント + アクセストークン単位で保存されます（アカウントごとに別のキーストア）。

ルーティングモデル

返信は常に 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）。ウィザードは、ディレクトリ検索で 1 件の完全一致が見つかる場合に限り、表示名をユーザー ID に解決します。
表示名やローカルパートだけ（例："Alice" / "alice"）は曖昧なため、allowlist マッチングでは無視されます。必ず @user:server 形式の ID を使ってください。

ルーム（グループ）

デフォルト：channels.matrix.groupPolicy = "allowlist"（メンション制御）。未設定時のデフォルト上書きは channels.defaults.groupPolicy を使います。
ランタイム注意：channels.matrix が完全に欠けている場合、ルームチェックでは groupPolicy="allowlist" にフォールバックします（channels.defaults.groupPolicy が設定されていても同様）。
channels.matrix.groups でルーム（room ID またはエイリアス）を allowlist に登録できます。名前は、ディレクトリ検索で 1 件の完全一致が見つかる場合に限り ID に解決されます：

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

requireMention: false で、そのルームでは自動返信が有効になります。
groups."*" で、ルーム横断のメンション制御のデフォルトを設定できます。
groupAllowFrom は、ルームでボットをトリガーできる送信者を制限します（完全な Matrix ユーザー ID）。
ルーム単位の users allowlist で、特定ルーム内の送信者をさらに制限できます（完全な Matrix ユーザー ID を使用）。
設定ウィザードはルーム allowlist（room ID、エイリアス、名前）を促し、名前の解決は完全一致かつ一意な場合に限られます。
起動時、OpenClaw は allowlist 内のルーム/ユーザー名を ID に解決し、対応関係をログに出します。解決できないエントリは allowlist マッチングで無視されます。
招待はデフォルトで自動参加します。channels.matrix.autoJoin と channels.matrix.autoJoinAllowlist で制御できます。
ルームを一切許可しない場合、channels.matrix.groupPolicy: "disabled" を設定します（または allowlist を空に保ちます）。
レガシーキー：channels.matrix.rooms（groups と同形）。

スレッド

スレッド返信（reply threading）に対応しています。
channels.matrix.threadReplies は、返信をスレッド内に留めるかを制御します：
- off / inbound（デフォルト）/ always
channels.matrix.replyToMode は、スレッド外で返信する場合の reply-to メタデータを制御します：
- off（デフォルト）/ first / all

機能（Capabilities）

ダイレクトメッセージ：✅ サポート
ルーム：✅ サポート
スレッド：✅ サポート
メディア：✅ サポート
E2EE：✅ サポート（crypto モジュールが必要）
リアクション：✅ サポート（ツールで送信/読み取り）
投票：✅ 送信はサポート。受信した poll start はテキストに変換（回答/終了は無視）
位置情報：✅ サポート（geo URI。高度は無視）
ネイティブコマンド：✅ サポート

トラブルシューティング

まずはこのラダーを実行してください：

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

必要に応じて DM のペアリング状態を確認します：

openclaw pairing list matrix

よくある失敗：

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

追加の切り分けフロー： /channels/troubleshooting。

設定リファレンス（Matrix）

フル設定： Configuration

プロバイダオプション：

channels.matrix.enabled：チャネル起動の有効/無効
channels.matrix.homeserver：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 allowlist（完全な Matrix ユーザー ID）。open には "*" が必要。可能な場合、ウィザードが名前を ID に解決します。
channels.matrix.groupPolicy：allowlist | open | disabled（デフォルト：allowlist）
channels.matrix.groupAllowFrom：ルームメッセージの送信者 allowlist（完全な Matrix ユーザー ID）
channels.matrix.allowlistOnly：DM + ルームの allowlist ルールを強制
channels.matrix.groups：ルーム allowlist + ルーム単位設定のマップ
channels.matrix.rooms：レガシーのルーム allowlist/config
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）

参考

https://docs.openclaw.ai/channels/matrix.md

#ガイド

BizClaw 導入支援

OpenClaw の構築を
まるごと代行します

Mac mini のセットアップから Slack・iMessage 連携まで、届いた日から使える状態でお届けします。

サービスを見る

AIエージェントのメモリスタックとは？2026年に重要度が上がる理由をやさしく解説

2026年4月8日

OpenClaw vs Hermes vs Claude、創業者はどれを選ぶべき？2026年版の実務比較

2026年4月8日

X公式MCPサーバーとは？AIエージェント運用で何が変わるのかを実務目線で解説

2026年4月8日

【最新版】MatrixでOpenClawを使う方法（DM・ルーム・E2EE対応）

Matrix

プラグインが必要

セットアップ

暗号化（E2EE）

マルチアカウント

ルーティングモデル

アクセス制御（DM）

ルーム（グループ）

スレッド

機能（Capabilities）

トラブルシューティング

設定リファレンス（Matrix）

参考

OpenClaw の構築をまるごと代行します

関連記事

AIエージェントのメモリスタックとは？2026年に重要度が上がる理由をやさしく解説

OpenClaw vs Hermes vs Claude、創業者はどれを選ぶべき？2026年版の実務比較

X公式MCPサーバーとは？AIエージェント運用で何が変わるのかを実務目線で解説

OpenClaw の構築を
まるごと代行します