加密
为 Matrix 账户启用端到端加密,验证网关设备,并在加密状态漂移时修复加密状态。
加密与验证¶
在加密(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从 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 的别名。两个 setup 命令都会在保存已启用配置之前完成其 Matrix 客户端操作,因此正在运行的 Gateway 可以在这些工作稳定后重新加载。如果引导失败,加密设置仍会保存;请使用报告中的诊断信息和后续步骤完成验证。
setup 会保留运行期间所做的无关配置更改。如果所选账户发生变化,setup 会保留该较新配置不变,并要求你审查它并重新运行命令。
手动配置等效项:
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: { policy: "pairing" },
},
},
}
状态与信任信号¶
使用 --include-recovery-key 时,文本输出会确认原始恢复密钥是否可用,并提示你添加 --json。文本输出永远不会打印密钥本身;请妥善保管包含恢复密钥的 JSON 输出。
verify status 报告三个独立的信任信号(--verbose 会显示全部):
Locally trusted:仅由此客户端信任Cross-signing verified:SDK 报告通过交叉签名完成验证Signed by owner:由你自己的自签名密钥签名(仅用于诊断)
Verified by owner 仅在 Cross-signing verified 为 yes 时才是 yes;仅本地信任或仅所有者签名是不够的。
--allow-degraded-local-state 会返回尽力而为的诊断信息,而无需先准备 Matrix 账户;适用于离线或仅部分配置的检查。
使用恢复密钥验证此设备¶
通过 stdin 管道传入恢复密钥,而不是在命令行上传递它:
该命令报告三种状态:
Recovery key accepted:Matrix 已接受该密钥用于秘密存储或设备信任。Backup usable:可以使用受信任的恢复材料加载房间密钥备份。Device verified by owner:此设备具有完整的 Matrix 交叉签名身份信任。
当完整身份信任未完成时,它会以非零状态退出,即使恢复密钥已解锁备份材料。在这种情况下,请从另一个 Matrix 客户端完成自我验证:
verify self 会等待 Cross-signing verified: yes 后才成功退出。使用 --timeout-ms <ms> 调整等待时间。
字面量密钥形式 openclaw matrix verify device "<recovery-key>" 也可用,但密钥会留在 shell 历史记录中。
引导或修复交叉签名¶
这是用于加密账户的修复/设置命令。按顺序,它会:
- 引导秘密存储,在可能时复用现有恢复密钥
- 引导交叉签名并上传缺失的公钥
- 标记并对当前设备进行交叉签名
- 如果尚不存在,则创建服务器端房间密钥备份
如果 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 恢复缺失的房间密钥,然后重试该编辑。如果这些密钥不可用,请发送一条新消息。
要将损坏的备份替换为新的基线(接受丢失无法恢复的旧历史;如果当前备份密钥无法加载,还可以重建秘密存储):
仅当先前恢复密钥应有意停止解锁新的备份基线时,才添加 --rotate-recovery-key。
列出、请求和响应验证¶
列出所选账户的待验证请求。
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 打印):
| 命令 | 用途 |
|---|---|
openclaw matrix verify accept <id> |
接受入站请求 |
openclaw matrix verify start <id> |
启动 SAS 流程 |
openclaw matrix verify sas <id> |
打印 SAS 表情符号或十进制数字 |
openclaw matrix verify confirm-sas <id> |
确认 SAS 与另一客户端显示的内容一致 |
openclaw matrix verify mismatch-sas <id> |
当表情符号或十进制数字不匹配时拒绝 SAS |
openclaw matrix verify cancel <id> |
取消;可接受可选的 --reason <text> 和 --code <matrix-code> |
accept、start、sas、confirm-sas、mismatch-sas 和 cancel 在验证锚定到特定直接消息房间时,均接受 --user-id 和 --room-id 作为 DM 后续提示。
多账户说明¶
如果不使用 --account <id>,Matrix CLI 命令会使用隐式默认账户。当存在多个命名账户且未设置 channels.matrix.defaultAccount 时,命令不会猜测,而是要求你进行选择。当某个命名账户的 E2EE 被禁用或不可用时,错误会指向该账户的配置键,例如 channels.matrix.accounts.assistant.encryption。
启动行为
当 encryption: true 时,startupVerification 默认为 "if-unverified"。启动时,未验证的设备会在另一个 Matrix 客户端中请求自我验证,跳过重复项并应用冷却时间(默认 24 小时)。可通过 startupVerificationCooldownHours 调整,或使用 startupVerification: "off" 禁用。
启动时还会执行一次保守的加密引导流程,复用当前的密钥存储和交叉签名身份。如果引导状态损坏,即使没有 channels.matrix.password,OpenClaw 也会尝试受保护的修复;如果 homeserver 要求密码 UIA,启动过程会记录警告并保持非致命状态。已由所有者签名的设备会被保留。
有关完整的升级流程,请参阅 Matrix 迁移。
验证通知
Matrix 会将验证生命周期通知以 m.notice 消息形式发布到严格的 DM 验证房间中:请求、就绪(包含“使用表情符号验证”的指引)、开始/完成,以及在可用时的 SAS(表情符号/十进制)详情。
来自另一个 Matrix 客户端的入站请求会被跟踪并自动接受。对于自我验证,OpenClaw 会自动启动 SAS 流程,并在表情符号验证可用时确认其自身一侧——你仍需在 Matrix 客户端中比较并确认“它们匹配”。
验证系统通知不会转发到代理聊天管道。
已删除或无效的 Matrix 设备
如果 `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 客户端或管理界面中创建一个新的访问令牌,然后更新 OpenClaw:
openclaw matrix account add \
--account assistant \
--homeserver https://matrix.example.org \
--access-token '<token>'
将 `assistant` 替换为失败命令中的账户 ID,或省略 `--account` 以使用默认账户。
加密存储
Matrix E2EE 使用官方 matrix-js-sdk 的 Rust 加密路径,并以 fake-indexeddb 作为 IndexedDB 垫片。加密状态持久化在账户的 state/openclaw.sqlite 数据库中,并带有严格的文件权限。七月之前的 crypto-idb-snapshot.json 导入已弃用;有关恢复指导,请参阅 Matrix 迁移。
加密运行时状态位于 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ 下,包括同步存储、加密存储、恢复密钥、IDB 快照、线程绑定和启动验证状态。当令牌发生变化但账户身份保持不变时,OpenClaw 会复用最佳现有根目录,以便先前状态仍然可见。
单个较旧的 token-hash 根目录可能是正常的令牌轮换连续性路径。如果 OpenClaw 记录 matrix: multiple populated token-hash storage roots detected,请在确认所选活动根目录健康后,再检查账户目录并归档过期的同级根目录。建议将过期根目录移动到 _archive/ 目录中,而不是立即删除。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw