加密

为 Matrix 账户启用端到端加密，验证 Gateway 设备，并在加密状态发生漂移时修复它。

加密与验证¶

在加密（E2EE）房间中，出站图像事件使用 thumbnail_file，以便图像预览与完整附件一起加密；未加密房间使用普通 thumbnail_url。无需配置 - 插件会自动检测 E2EE 状态。

所有 openclaw matrix 命令都接受 --verbose（完整诊断信息）、--json（机器可读输出）和 --account <id>（多账户设置）。默认输出简洁。

启用加密¶

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

引导秘密存储和交叉签名，在需要时创建房间密钥备份，然后打印状态和后续步骤。常用标志：

• --recovery-key-stdin 从标准输入读取恢复密钥，而不在进程参数中暴露它；--recovery-key <key> 仍可用于兼容性
• --force-reset-cross-signing 丢弃当前交叉签名身份并创建新身份（仅限有意使用）

对于新账户，在创建时启用 E2EE：

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

--encryption 是 --enable-e2ee 的别名。两个设置命令都会在保存已启用配置之前完成其 Matrix 客户端操作，因此正在运行的 Gateway 可以在这些操作完成后重新加载。如果引导失败，加密设置仍会保存；请使用报告中的诊断信息和后续步骤完成验证。

设置过程会保留在其运行期间所做的无关配置更改。如果所选账户发生变化，设置会保留该较新的配置，并要求你检查并重新运行命令。

手动配置等效项：

{
  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

使用 --include-recovery-key 时，文本输出会确认原始恢复密钥是否可用，并提示你添加 --json。文本输出永远不会打印密钥本身；请妥善保管包含恢复密钥的 JSON 输出。

verify status 报告三个独立的信任信号（--verbose 会显示全部）：

• Locally trusted：仅由此客户端信任
• Cross-signing verified：SDK 报告通过交叉签名完成验证
• Signed by owner：由你自己的自签名密钥签名（仅用于诊断）

只有当 Cross-signing verified 为 yes 时，Verified by owner 才为 yes；仅本地信任或仅所有者签名是不够的。

--allow-degraded-local-state 会返回尽力而为的诊断信息，而无需先准备 Matrix 账户；适用于离线或部分配置的探测。

使用恢复密钥验证此设备¶

通过标准输入管道传递恢复密钥，而不是在命令行上传递：

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

该命令报告三种状态：

• Recovery key accepted：Matrix 已接受该密钥用于秘密存储或设备信任。
• Backup usable：可以使用受信任的恢复材料加载房间密钥备份。
• Device verified by owner：此设备具有完整的 Matrix 交叉签名身份信任。

当完整身份信任未完成时，它会以非零状态退出，即使恢复密钥已解锁备份材料。在这种情况下，请从另一个 Matrix 客户端完成自我验证：

openclaw matrix verify self

verify self 会等待 Cross-signing verified: yes 后才成功退出。使用 --timeout-ms <ms> 调整等待时间。

字面密钥形式 openclaw matrix verify device "<recovery-key>" 也可以使用，但密钥会留在 shell 历史记录中。

引导或修复交叉签名¶

openclaw matrix verify bootstrap

用于加密账户的修复/设置命令。按顺序，它会：

• 引导秘密存储，在可能时复用现有恢复密钥
• 引导交叉签名并上传缺失的公钥
• 标记并交叉签名当前设备
• 如果尚不存在，则创建服务器端房间密钥备份

如果 homeserver 要求使用 UIA 上传交叉签名密钥，OpenClaw 会先尝试无认证，然后尝试 m.login.dummy，再尝试 m.login.password（需要 channels.matrix.password）。

常用标志：

• --recovery-key-stdin（与 printf '%s\n' "$MATRIX_RECOVERY_KEY" | ... 配合使用）或 --recovery-key <key>
• --force-reset-cross-signing 用于丢弃当前交叉签名身份（仅限有意操作；需要已存储的当前有效恢复密钥，或通过 --recovery-key-stdin 提供）

房间密钥备份¶

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

backup status 显示是否存在服务器端备份，以及此设备是否可以解密它。backup restore 将备份的房间密钥导入本地加密存储；如果恢复密钥已在磁盘上，请省略 --recovery-key-stdin。

OpenClaw 会读取先前编辑，仅通知新被提及的接收者。如果编辑报告其历史未完全解密，请使用 backup restore 恢复缺失的房间密钥，然后重试编辑。如果这些密钥不可用，请发送新消息。

要用新的基线替换损坏的备份（接受丢失无法恢复的旧历史；如果当前备份密钥无法加载，还可以重新创建秘密存储）：

openclaw matrix verify backup reset --yes

仅当先前恢复密钥应有意停止解锁新的备份基线时，才添加 --rotate-recovery-key。

列出、请求和响应验证¶

openclaw matrix verify list

列出所选账户的待验证请求。

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

从此账户发送验证请求。--own-user 请求自我验证（在同一用户的另一个 Matrix 客户端中接受提示）；--user-id/--device-id/--room-id 用于指定其他用户。--own-user 不能与其他目标指定标志组合使用。

对于较低层级的生命周期处理——通常是在跟踪来自其他客户端的传入请求时——这些命令作用于特定的请求 <id>（由 verify list 和 verify request 打印）：

accept、start、sas、confirm-sas、mismatch-sas 和 cancel 均接受 --user-id 和 --room-id 作为 DM 后续提示，前提是验证锚定在特定的直接消息（DM）房间中。

多账户说明¶

如果没有指定 --account <id>，Matrix CLI 命令将使用隐式默认账户。如果存在多个命名账户且未设置 channels.matrix.defaultAccount，命令将拒绝猜测并要求您进行选择。当命名账户的 E2EE 被禁用或不可用时，错误将指向该账户的配置键，例如 channels.matrix.accounts.assistant.encryption。

如果 `verify status` 显示当前设备不再列在 homeserver 上，请创建一个新的 OpenClaw Matrix 设备。对于密码登录：

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

对于令牌认证，请在您的 Matrix 客户端或管理 UI 中创建一个新的访问令牌，然后更新 OpenClaw：

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

将 `assistant` 替换为失败命令中的账户 ID，或者省略 `--account` 以使用默认账户。

旧的 OpenClaw 管理设备可能会累积。列出并清理：

openclaw matrix devices list
openclaw matrix devices prune-stale