マトリックス

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

インストール

openclaw plugins install @openclaw/matrix

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

​

セットアップ

1. 自分のホームサーバーで Matrix アカウントを作成します。
2. channels.matrix を homeserver + accessToken、または homeserver + userId + password のどちらかで設定します。
3. Gateway を再起動します。
4. ボットとの DM を開始するか、ルームに招待します（自動参加 を参照。新しい招待は autoJoin が許可した場合にのみ反映されます）。

​

対話型セットアップ

openclaw channels add
openclaw configure --section channels

​

最小設定

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

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

​

自動参加

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": { requireMention: true },
      },
    },
  },
}

​

許可リストターゲット形式

• DM（dm.allowFrom、groupAllowFrom、groups.<room>.users）: @user:server を使用します。表示名は変更可能なため、デフォルトでは無視されます。表示名エントリとの互換性が明示的に必要な場合にのみ、dangerouslyAllowNameMatching: true を設定してください。
• ルーム許可リストキー（groups、レガシー rooms）: !room:server または #alias:server を使用します。プレーンなルーム名はデフォルトでは無視されます。参加済みルーム名の検索との互換性が明示的に必要な場合にのみ、dangerouslyAllowNameMatching: true を設定してください。
• 招待許可リスト（autoJoinAllowlist）: !room:server、#alias:server、または * を使用します。プレーンなルーム名は拒否されます。

​

アカウント ID の正規化

​

キャッシュされた認証情報

• デフォルトアカウント: credentials.json
• 名前付きアカウント: credentials-<account>.json

​

環境変数

​

設定例

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

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        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",
    },
  },
}

​

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

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

{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}

• プレビューが Matrix のイベントごとのサイズ制限を超えて大きくなった場合、OpenClaw はプレビューストリーミングを停止し、最終版のみの配信にフォールバックします。
• メディア返信は常に通常どおり添付ファイルを送信します。古いプレビューを安全に再利用できなくなった場合、OpenClaw は最終的なメディア返信を送信する前にそれを redacts します。
• Matrix のプレビューストリーミングが有効な場合、ツール進行状況のプレビュー更新はデフォルトで有効です。回答テキストのプレビュー編集は維持しつつ、ツール進行状況を通常の配信経路のままにするには、streaming.preview.toolProgress: false を設定します。
• プレビュー編集には追加の Matrix API 呼び出しが必要です。最も保守的なレート制限プロファイルにしたい場合は、streaming: "off" のままにしてください。

​

承認メタデータ

​

quiet 確定プレビュー向けのセルフホスト型プッシュルール

​

ボット間ルーム

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

• allowBots: true は、許可されたルームと DM 内で、他の設定済み Matrix ボットアカウントからのメッセージを受け入れます。
• allowBots: "mentions" は、ルーム内でこのボットに見える形でメンションしている場合にのみ、それらのメッセージを受け入れます。DM は引き続き許可されます。
• groups.<room>.allowBots は、1 つのルームについてアカウントレベルの設定を上書きします。
• OpenClaw は自己返信ループを避けるため、同じ Matrix ユーザー ID からのメッセージは引き続き無視します。
• Matrix はここでネイティブなボットフラグを公開していません。OpenClaw は「ボット作成」を「この OpenClaw Gateway 上の別の設定済み Matrix アカウントによって送信されたもの」として扱います。

​

暗号化と検証

​

暗号化を有効化

openclaw matrix encryption setup

• --recovery-key <key> ブートストラップ前にリカバリーキーを適用します (以下で説明する stdin 形式を推奨)
• --force-reset-cross-signing 現在のクロス署名 ID を破棄し、新しいものを作成します (意図した場合のみ使用)

openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee

{
  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 --include-recovery-key --json

• Locally trusted: このクライアントでのみ信頼されています
• Cross-signing verified: SDK がクロス署名による検証を報告しています
• Signed by owner: 自分自身の自己署名キーで署名されています (診断専用)

​

リカバリーキーでこのデバイスを検証

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

• Recovery key accepted: Matrix がシークレットストレージまたはデバイス信頼のためにキーを受け入れました。
• Backup usable: 信頼済みのリカバリー素材でルームキーのバックアップを読み込めます。
• Device verified by owner: このデバイスは完全な Matrix クロス署名 ID の信頼を持っています。

openclaw matrix verify self

​

クロス署名のブートストラップまたは修復

openclaw matrix verify bootstrap

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

• --recovery-key-stdin (printf '%s\n' "$MATRIX_RECOVERY_KEY" | … と組み合わせる) または --recovery-key <key>
• --force-reset-cross-signing 現在のクロス署名 ID を破棄します (意図した場合のみ)

​

ルームキーバックアップ

openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

openclaw matrix verify backup reset --yes

​

検証の一覧表示、要求、応答

openclaw matrix verify list

openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

​

複数アカウントの注意事項

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --user-id '@assistant:example.org' \
  --password '<password>' \
  --device-name OpenClaw-Gateway

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --access-token '<token>'

openclaw matrix devices list
openclaw matrix devices prune-stale

​

プロファイル管理

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

​

スレッド

​

セッションルーティング (sessionScope)

• "per-user" (デフォルト): 同じルーティング先ピアを持つすべての DM ルームが 1 つのセッションを共有します。
• "per-room": ピアが同じでも、各 Matrix DM ルームが独自のセッションキーを持ちます。

​

返信スレッド化 (threadReplies)

• "off": 返信はトップレベルです。受信したスレッド内メッセージは親セッションに残ります。
• "inbound": 受信メッセージがすでにそのスレッド内にある場合にのみ、スレッド内で返信します。
• "always": トリガーとなったメッセージをルートとするスレッド内で返信します。その会話は最初のトリガー以降、対応するスレッドスコープのセッションを通じてルーティングされます。

​

スレッド継承とスラッシュコマンド

• インバウンドのスレッド化メッセージには、追加のエージェントコンテキストとしてスレッドルートメッセージが含まれます。
• メッセージツール送信は、同じ部屋（または同じ DM ユーザーターゲット）を対象にする場合、明示的な threadId が指定されていなければ、現在の Matrix スレッドを自動的に継承します。
• DM ユーザーターゲットの再利用は、現在のセッションメタデータが同じ Matrix アカウント上の同じ DM 相手であることを証明する場合にのみ有効になります。それ以外の場合、OpenClaw は通常のユーザースコープのルーティングにフォールバックします。
• /focus、/unfocus、/agents、/session idle、/session max-age、およびスレッドにバインドされた /acp spawn は、すべて Matrix の部屋と DM で動作します。
• トップレベルの /focus は、threadBindings.spawnSessions が有効な場合、新しい Matrix スレッドを作成し、それをターゲットセッションにバインドします。
• 既存の Matrix スレッド内で /focus または /acp spawn --thread here を実行すると、そのスレッドがその場でバインドされます。

​

ACP 会話バインディング

• 使い続けたい Matrix DM、部屋、または既存スレッド内で /acp spawn codex --bind here を実行します。
• トップレベルの Matrix DM または部屋では、現在の DM/部屋がチャットサーフェスのまま残り、以降のメッセージは生成された ACP セッションにルーティングされます。
• 既存の Matrix スレッド内では、--bind here が現在のスレッドをその場でバインドします。
• /new と /reset は、同じバインド済み ACP セッションをその場でリセットします。
• /acp close は ACP セッションを閉じ、バインディングを削除します。

• --bind here は子 Matrix スレッドを作成しません。
• threadBindings.spawnSessions は /acp spawn --thread auto|here を制御します。ここで OpenClaw は子 Matrix スレッドを作成またはバインドする必要があります。

​

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

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions
• threadBindings.defaultSpawnContext

• トップレベルの /focus と /acp spawn --thread auto|here が Matrix スレッドを作成/バインドしないようにするには、threadBindings.spawnSessions: false を設定します。
• ネイティブサブエージェントのスレッド生成で親トランスクリプトをフォークしないようにするには、threadBindings.defaultSpawnContext: "isolated" を設定します。

​

リアクション

• react は Matrix イベントにリアクションを追加します。
• reactions は Matrix イベントの現在のリアクション要約を一覧表示します。
• emoji="" はそのイベント上のボット自身のリアクションを削除します。
• remove: true はボットから指定された絵文字リアクションだけを削除します。

​

履歴コンテキスト

• channels.matrix.historyLimit は、Matrix の部屋メッセージがエージェントをトリガーしたときに、直近の部屋メッセージをいくつ InboundHistory として含めるかを制御します。messages.groupChat.historyLimit にフォールバックします。両方が未設定の場合、有効な既定値は 0 です。無効にするには 0 を設定します。
• Matrix の部屋履歴は部屋専用です。DM は通常のセッション履歴を引き続き使用します。
• Matrix の部屋履歴は保留中のみです。OpenClaw はまだ返信をトリガーしていない部屋メッセージをバッファし、メンションまたはその他のトリガーが到着したときにそのウィンドウのスナップショットを取得します。
• 現在のトリガーメッセージは InboundHistory に含まれません。そのターンのメインのインバウンド本文に残ります。
• 同じ Matrix イベントの再試行では、新しい部屋メッセージへ進まず、元の履歴スナップショットを再利用します。

​

コンテキスト可視性

• contextVisibility: "all" が既定です。補助コンテキストは受信したまま保持されます。
• contextVisibility: "allowlist" は、アクティブな部屋/ユーザー許可リストチェックで許可された送信者に補助コンテキストをフィルタリングします。
• contextVisibility: "allowlist_quote" は allowlist のように動作しますが、明示的に引用された返信を 1 つ保持します。

​

DM と部屋のポリシー

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

{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

ダイレクト部屋の修復

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

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

• m.direct にすでにマッピングされている厳密な 1:1 DM を優先します
• そのユーザーと現在参加中の任意の厳密な 1:1 DM にフォールバックします
• 正常な DM が存在しない場合、新しいダイレクト部屋を作成し、m.direct を書き換えます

​

実行承認

• enabled: Matrix ネイティブのプロンプトを通じて承認を配信します。未設定または "auto" の場合、少なくとも 1 人の承認者を解決できると Matrix が自動的に有効になります。明示的に無効にするには false を設定します。
• approvers: 実行リクエストを承認できる Matrix ユーザー ID（@owner:example.org）。省略可能です。channels.matrix.dm.allowFrom にフォールバックします。
• target: プロンプトの送信先です。"dm"（既定）は承認者の DM に送信します。"channel" は発信元の Matrix 部屋または DM に送信します。"both" は両方に送信します。
• agentFilter / sessionFilter: どのエージェント/セッションが Matrix 配信をトリガーするかを指定する省略可能な許可リストです。

• 実行承認 は execApprovals.approvers を使用し、dm.allowFrom にフォールバックします。
• Plugin 承認 は dm.allowFrom のみを通じて認可します。

• ✅ 1 回だけ許可
• ❌ 拒否
• ♾️ 常に許可（有効な実行ポリシーで許可されている場合）

​

スラッシュコマンド

​

マルチアカウント

{
  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 の値は、アカウントが上書きしない限り、名前付きアカウントの既定値として動作します。
• 継承された部屋エントリを groups.<room>.account で特定のアカウントにスコープします。account のないエントリはアカウント間で共有されます。既定アカウントがトップレベルで設定されている場合でも、account: "default" は引き続き機能します。

• 暗黙的なルーティング、プローブ、および CLI コマンドで優先する名前付きアカウントを選ぶには、defaultAccount を設定します。
• 複数のアカウントがあり、そのうち 1 つの名前が文字どおり default の場合、defaultAccount が未設定でも OpenClaw はそれを暗黙的に使用します。
• 複数の名前付きアカウントがあり、既定が選択されていない場合、CLI コマンドは推測を拒否します。defaultAccount を設定するか、--account <id> を渡してください。
• トップレベルの channels.matrix.* ブロックは、認証が完全な場合（homeserver + accessToken、または homeserver + userId + password）にのみ、暗黙的な default アカウントとして扱われます。名前付きアカウントは、キャッシュされた認証情報が認証をカバーしていれば、homeserver + userId から引き続き検出できます。

• OpenClaw が修復またはセットアップ中に単一アカウント設定をマルチアカウントへ昇格するとき、既存の名前付きアカウントが存在する場合、または defaultAccount がすでにその 1 つを指している場合は、それを保持します。Matrix の認証/ブートストラップキーだけが昇格後のアカウントへ移動し、共有配信ポリシーキーはトップレベルに残ります。

​

プライベート/LAN ホームサーバー

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

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

​

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

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

​

ターゲット解決

• ユーザー: @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

• ユーザー検索は、その homeserver 上の Matrix ユーザーディレクトリに問い合わせます。
• ルーム検索は、明示的なルーム ID とエイリアスを直接受け付けます。参加済みルーム名の検索はベストエフォートであり、dangerouslyAllowNameMatching: true が設定されている場合にのみランタイムのルーム許可リストへ適用されます。
• ルーム名を ID またはエイリアスに解決できない場合、ランタイムの許可リスト解決では無視されます。

​

設定リファレンス

​

アカウントと接続

• enabled: チャンネルを有効または無効にします。
• name: アカウントの任意の表示ラベル。
• defaultAccount: 複数の Matrix アカウントが設定されている場合の優先アカウント ID。
• accounts: 名前付きのアカウントごとのオーバーライド。トップレベルの channels.matrix 値はデフォルトとして継承されます。
• homeserver: homeserver URL。例: https://matrix.example.org。
• network.dangerouslyAllowPrivateNetwork: このアカウントが localhost、LAN/Tailscale IP、または内部ホスト名へ接続することを許可します。
• proxy: Matrix トラフィック用の任意の HTTP(S) プロキシ URL。アカウントごとのオーバーライドに対応しています。
• userId: 完全な Matrix ユーザー ID (@bot:example.org)。
• accessToken: トークンベース認証用のアクセストークン。プレーンテキストおよび SecretRef 値は、env/file/exec プロバイダー全体でサポートされます（シークレット管理）。
• password: パスワードベースログイン用のパスワード。プレーンテキストおよび SecretRef 値に対応しています。
• deviceId: 明示的な Matrix デバイス ID。
• deviceName: パスワードログイン時に使用されるデバイス表示名。
• avatarUrl: プロファイル同期および profile set 更新用に保存される自己アバター URL。
• initialSyncLimit: 起動時同期中に取得されるイベントの最大数。

​

暗号化

• encryption: E2EE を有効にします。デフォルト: false。
• startupVerification: "if-unverified"（E2EE がオンの場合のデフォルト）または "off"。このデバイスが未検証の場合、起動時に自己検証を自動要求します。
• startupVerificationCooldownHours: 次の自動起動時リクエストまでのクールダウン。デフォルト: 24。

​

アクセスとポリシー

• groupPolicy: "open"、"allowlist"、または "disabled"。デフォルト: "allowlist"。
• groupAllowFrom: ルームトラフィック用のユーザー ID の許可リスト。
• dm.enabled: false の場合、すべての DM を無視します。デフォルト: true。
• dm.policy: "pairing"（デフォルト）、"allowlist"、"open"、または "disabled"。ボットが参加し、ルームを DM として分類した後に適用されます。招待処理には影響しません。
• dm.allowFrom: DM トラフィック用のユーザー ID の許可リスト。
• dm.sessionScope: "per-user"（デフォルト）または "per-room"。
• dm.threadReplies: 返信スレッド化の DM 専用オーバーライド ("off"、"inbound"、"always")。
• allowBots: 他の設定済み Matrix ボットアカウントからのメッセージを受け付けます (true または "mentions")。
• allowlistOnly: true の場合、すべてのアクティブな DM ポリシー（"disabled" を除く）と "open" グループポリシーを "allowlist" に強制します。"disabled" ポリシーは変更しません。
• dangerouslyAllowNameMatching: true の場合、ユーザー許可リストエントリに対する Matrix 表示名ディレクトリ検索と、ルーム許可リストキーに対する参加済みルーム名検索を許可します。完全な @user:server ID と、ルーム ID またはエイリアスを優先してください。
• autoJoin: "always"、"allowlist"、または "off"。デフォルト: "off"。DM 形式の招待を含む、すべての Matrix 招待に適用されます。
• autoJoinAllowlist: autoJoin が "allowlist" の場合に許可されるルーム/エイリアス。エイリアスエントリは、招待されたルームが主張する状態ではなく、homeserver に対して解決されます。
• contextVisibility: 補足コンテキストの可視性（"all" がデフォルト、"allowlist"、"allowlist_quote"）。

​

返信動作

• replyToMode: "off"、"first"、"all"、または "batched"。
• threadReplies: "off"、"inbound"、または "always"。
• threadBindings: スレッドに紐づくセッションルーティングとライフサイクルのチャンネルごとのオーバーライド。
• streaming: "off"（デフォルト）、"partial"、"quiet"、またはオブジェクト形式 { mode, preview: { toolProgress } }。true ↔ "partial"、false ↔ "off"。
• blockStreaming: true の場合、完了したアシスタントブロックは個別の進捗メッセージとして保持されます。
• markdown: 送信テキスト用の任意の Markdown レンダリング設定。
• responsePrefix: 送信返信の前に付加される任意の文字列。
• textChunkLimit: chunkMode: "length" の場合の、文字単位の送信チャンクサイズ。デフォルト: 4000。
• chunkMode: "length"（デフォルト、文字数で分割）または "newline"（行境界で分割）。
• historyLimit: ルームメッセージがエージェントをトリガーしたときに InboundHistory として含められる最近のルームメッセージ数。messages.groupChat.historyLimit にフォールバックします。有効なデフォルトは 0（無効）。
• mediaMaxMb: 送信および受信処理のメディアサイズ上限（MB）。

​

リアクション設定

• ackReaction: このチャンネル/アカウント用の ack リアクションオーバーライド。
• ackReactionScope: スコープオーバーライド（"group-mentions" がデフォルト、"group-all"、"direct"、"all"、"none"、"off"）。
• reactionNotifications: 受信リアクション通知モード（"own" がデフォルト、"off"）。

​

ツールとルームごとのオーバーライド

• actions: アクションごとのツールゲート制御（messages、reactions、pins、profile、memberInfo、channelInfo、verification）。
• groups: ルームごとのポリシーマップ。セッション ID は解決後の安定したルーム ID を使用します。（rooms はレガシーエイリアスです。）
  • groups.<room>.account: 継承された 1 つのルームエントリを特定のアカウントに制限します。
  • groups.<room>.allowBots: チャンネルレベル設定のルームごとのオーバーライド (true または "mentions")。
  • groups.<room>.users: ルームごとの送信者許可リスト。
  • groups.<room>.tools: ルームごとのツール許可/拒否オーバーライド。
  • groups.<room>.autoReply: ルームごとのメンションゲート制御オーバーライド。true はそのルームのメンション要件を無効にし、false は再び有効にします。
  • groups.<room>.skills: ルームごとのスキルフィルター。
  • groups.<room>.systemPrompt: ルームごとのシステムプロンプトスニペット。

​

exec 承認設定

• execApprovals.enabled: Matrix ネイティブのプロンプトを通じて exec 承認を配信します。
• execApprovals.approvers: 承認を許可される Matrix ユーザー ID。dm.allowFrom にフォールバックします。
• execApprovals.target: "dm"（デフォルト）、"channel"、または "both"。
• execApprovals.agentFilter / execApprovals.sessionFilter: 配信用の任意のエージェント/セッション許可リスト。

​

関連

• チャンネル概要 - すべての対応チャンネル
• ペアリング - DM 認証とペアリングフロー
• グループ - グループチャット動作とメンションゲート制御
• チャンネルルーティング - メッセージのセッションルーティング
• セキュリティ - アクセスモデルと堅牢化