diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index 24ac80710a6..deaf87e72c1 100644 --- a/docs/channels/matrix.md +++ b/docs/channels/matrix.md @@ -123,8 +123,11 @@ Example for account `ops`: For normalized account ID `ops-bot`, use: -- `MATRIX_OPS_BOT_HOMESERVER` -- `MATRIX_OPS_BOT_ACCESS_TOKEN` +- `MATRIX_OPS_X2D_BOT_HOMESERVER` +- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` + +Matrix escapes punctuation in account IDs to keep scoped env vars collision-free. +For example, `-` becomes `_X2D_`, so `ops-prod` maps to `MATRIX_OPS_X2D_PROD_*`. The interactive wizard only offers the env-var shortcut when those auth env vars are already present and the selected account does not already have Matrix auth saved in config. @@ -190,6 +193,9 @@ done: - Media replies still send attachments normally. If a stale preview can no longer be reused safely, OpenClaw redacts it before sending the final media reply. - Preview edits cost extra Matrix API calls. Leave streaming off if you want the most conservative rate-limit behavior. +`blockStreaming` does not enable draft previews by itself. +Use `streaming: "partial"` for preview edits; then add `blockStreaming: true` only if you also want completed assistant blocks to remain visible as separate progress messages. + ## Encryption and verification In encrypted (E2EE) rooms, outbound image events use `thumbnail_file` so image previews are encrypted alongside the full attachment. Unencrypted rooms still use plain `thumbnail_url`. No configuration is needed — the plugin detects E2EE state automatically. @@ -590,8 +596,17 @@ Current behavior: - Matrix room history is pending-only: OpenClaw buffers room messages that did not trigger a reply yet, then snapshots that window when a mention or other trigger arrives. - The current trigger message is not included in `InboundHistory`; it stays in the main inbound body for that turn. - Retries of the same Matrix event reuse the original history snapshot instead of drifting forward to newer room messages. -- Fetched room context (including reply and thread context lookups) is filtered by sender allowlists (`groupAllowFrom`), so non-allowlisted messages are excluded from agent context. -- This filtering is channel-level hardening behavior. Other channels may still expose supplemental context as received. + +## Context visibility + +Matrix supports the shared `contextVisibility` control for supplemental room context such as fetched reply text, thread roots, and pending history. + +- `contextVisibility: "all"` is the default. Supplemental context is kept as received. +- `contextVisibility: "allowlist"` filters supplemental context to senders allowed by the active room/user allowlist checks. +- `contextVisibility: "allowlist_quote"` behaves like `allowlist`, but still keeps one explicit quoted reply. + +This setting affects supplemental context visibility, not whether the inbound message itself can trigger a reply. +Trigger authorization still comes from `groupPolicy`, `groups`, `groupAllowFrom`, and DM policy settings. ## DM and room policy example @@ -780,13 +795,16 @@ Live directory lookup uses the logged-in Matrix account: - `initialSyncLimit`: startup sync event limit. - `encryption`: enable E2EE. - `allowlistOnly`: force allowlist-only behavior for DMs and rooms. +- `allowBots`: allow messages from other configured OpenClaw Matrix accounts (`true` or `"mentions"`). - `groupPolicy`: `open`, `allowlist`, or `disabled`. +- `contextVisibility`: supplemental room-context visibility mode (`all`, `allowlist`, `allowlist_quote`). - `groupAllowFrom`: allowlist of user IDs for room traffic. - `groupAllowFrom` entries should be full Matrix user IDs. Unresolved names are ignored at runtime. - `historyLimit`: max room messages to include as group history context. Falls back to `messages.groupChat.historyLimit`. Set `0` to disable. - `replyToMode`: `off`, `first`, or `all`. -- `streaming`: `off` (default) or `partial`. `partial` enables single-message draft previews with edit-in-place updates. -- `blockStreaming`: `true` enables separate progress messages; when unset, Matrix keeps `streaming: "off"` as final-only delivery. +- `markdown`: optional Markdown rendering configuration for outbound Matrix text. +- `streaming`: `off` (default), `partial`, `true`, or `false`. `partial` and `true` enable single-message draft previews with edit-in-place updates. +- `blockStreaming`: `true` enables separate progress messages for completed assistant blocks while draft preview streaming is active. - `threadReplies`: `off`, `inbound`, or `always`. - `threadBindings`: per-channel overrides for thread-bound session routing and lifecycle. - `startupVerification`: automatic self-verification request mode on startup (`if-unverified`, `off`). @@ -808,6 +826,13 @@ Live directory lookup uses the logged-in Matrix account: - `execApprovals.target`: `dm | channel | both` (default: `dm`). - `accounts`: named per-account overrides. Top-level `channels.matrix` values act as defaults for these entries. - `groups`: per-room policy map. Prefer room IDs or aliases; unresolved room names are ignored at runtime. Session/group identity uses the stable room ID after resolution, while human-readable labels still come from room names. +- `groups..account`: restrict one inherited room entry to a specific Matrix account in multi-account setups. +- `groups..allowBots`: room-level override for configured-bot senders (`true` or `"mentions"`). +- `groups..users`: per-room sender allowlist. +- `groups..tools`: per-room tool allow/deny overrides. +- `groups..autoReply`: room-level mention-gating override. `true` disables mention requirements for that room; `false` forces them back on. +- `groups..skills`: optional room-level skill filter. +- `groups..systemPrompt`: optional room-level system prompt snippet. - `rooms`: legacy alias for `groups`. - `actions`: per-action tool gating (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index 6eaa0ee1911..9c492774ba0 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -122,10 +122,12 @@ Full troubleshooting: [/channels/qqbot#troubleshooting](/channels/qqbot#troubles ### Matrix failure signatures -| Symptom | Fastest check | Fix | -| ----------------------------------- | -------------------------------------------- | ----------------------------------------------- | -| Logged in but ignores room messages | `openclaw channels status --probe` | Check `groupPolicy` and room allowlist. | -| DMs do not process | `openclaw pairing list matrix` | Approve sender or adjust DM policy. | -| Encrypted rooms fail | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. | +| Symptom | Fastest check | Fix | +| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- | +| Logged in but ignores room messages | `openclaw channels status --probe` | Check `groupPolicy`, room allowlist, and mention gating. | +| DMs do not process | `openclaw pairing list matrix` | Approve sender or adjust DM policy. | +| Encrypted rooms fail | `openclaw matrix verify status` | Re-verify the device, then check `openclaw matrix verify backup status`. | +| Backup restore is pending/broken | `openclaw matrix verify backup status` | Run `openclaw matrix verify backup restore` or rerun with a recovery key. | +| Cross-signing/bootstrap looks wrong | `openclaw matrix verify bootstrap` | Repair secret storage, cross-signing, and backup state in one pass. | Full setup and config: [Matrix](/channels/matrix)