OpenClaw从入门到应用——频道：Matrix

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》Matrix 是一个开放、去中心化的消息传递协议。OpenClaw 以 Matrix用户的身份连接到任何家服务器因此您需要为机器人准备一个 Matrix 账户。登录后您可以直接向机器人发送私信或将其邀请到房间Matrix “群组”。Beeper 也是一个有效的客户端选项但需要启用端到端加密E2EE。状态通过插件支持vector-im/matrix-bot-sdk。支持私信、房间、线程、媒体、表情回应、投票发送 以文本形式接收投票开始消息、位置信息以及端到端加密附带加密支持。需要插件Matrix 以插件形式提供不捆绑在核心安装包中。通过命令行安装npm 仓库openclaw pluginsinstallopenclaw/matrix本地代码库从 git 仓库运行时openclaw pluginsinstall./extensions/matrix如果您在配置/引导过程中选择了 Matrix 并且检测到 git 代码库OpenClaw 会自动提供本地安装路径。详情插件设置步骤安装 Matrix 插件从 npm 安装openclaw plugins install openclaw/matrix从本地代码库安装openclaw plugins install ./extensions/matrix在家服务器上创建一个 Matrix 账户在 https://matrix.org/ecosystem/hosting/ 浏览托管选项或者自行托管。获取机器人账户的访问令牌使用curl通过 Matrix 登录 API 向您的家服务器发送请求curl--requestPOST\--urlhttps://matrix.example.org/_matrix/client/v3/login\--headerContent-Type: application/json\--data{ type: m.login.password, identifier: { type: m.id.user, user: your-user-name }, password: your-password }将matrix.example.org替换为您的家服务器 URL。或者设置channels.matrix.userIdchannels.matrix.passwordOpenClaw 会调用相同的登录端点将访问令牌存储在~/.openclaw/credentials/matrix/credentials.json中并在下次启动时复用。配置凭据环境变量MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN或MATRIX_USER_IDMATRIX_PASSWORD或者配置文件channels.matrix.*如果两者都设置配置文件优先。使用访问令牌时用户 ID 会通过/whoami自动获取。设置时channels.matrix.userId应为完整的 Matrix ID例如bot:example.org。重启网关或完成引导过程。从任意 Matrix 客户端Element、Beeper 等参见 https://matrix.org/ecosystem/clients/向机器人发送私信或将其邀请到房间。Beeper 需要端到端加密因此请设置channels.matrix.encryption: true并验证设备。最小配置访问令牌用户 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 加密 SDK支持。使用channels.matrix.encryption: true启用如果加密模块加载成功加密房间中的消息将自动解密。向加密房间发送消息时出站媒体将加密。首次连接时OpenClaw 会向您的其他会话请求设备验证。在其他 Matrix 客户端Element 等中验证设备以启用密钥共享。如果无法加载加密模块E2EE 将被禁用加密房间将无法解密OpenClaw 会记录警告。如果遇到缺少加密模块的错误例如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获取二进制文件。加密状态按账户 访问令牌存储在~/.openclaw/matrix/accounts/家服务器/用户ID/crypto/中SQLite 数据库。同步状态与其并存在bot-storage.json中。如果访问令牌设备发生更改将创建新的存储区并且机器人必须在加密房间中重新验证。设备验证启用 E2EE 后机器人将在启动时向您的其他会话请求验证。打开 Element或其他客户端并批准验证请求以建立信任。验证后机器人即可解密加密房间中的消息。多账户多账户支持使用channels.matrix.accounts为每个账户配置凭据和可选的name。参见gateway/configuration了解通用模式。每个账户作为独立的 Matrix 用户运行在任何家服务器上。每个账户的配置继承自顶级channels.matrix设置并可覆盖任何选项私信策略、群组、加密等。{ 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] }, }, }, }, }, }注意账户启动是串行的以避免并发模块导入时的竞争条件。环境变量MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN等仅适用于默认账户。基础通道设置私信策略、群组策略、提及控制等适用于所有账户除非每个账户单独覆盖。使用bindings[].match.accountId将每个账户路由到不同的代理。加密状态按账户 访问令牌存储每个账户独立的密钥存储区。路由模型回复始终回到 Matrix。私信共享代理的主会话房间映射到群组会话。访问控制私信默认channels.matrix.dm.policy pairing。未知发送者会收到配对码。批准方式openclaw pairing list matrixopenclaw pairing approve matrix 用户ID公开私信channels.matrix.dm.policyopen加上channels.matrix.dm.allowFrom[*]。channels.matrix.dm.allowFrom接受完整的 Matrix 用户 ID例如user:server。当目录搜索找到唯一的精确匹配时向导会将显示名称解析为用户 ID。不要使用显示名称或纯本地部分例如Alice或alice。它们会产生歧义并且会被忽略。请使用完整的user:serverID。房间群组默认channels.matrix.groupPolicy allowlist受提及门控。使用channels.defaults.groupPolicy可在未设置时覆盖默认值。运行时注意如果完全缺少channels.matrix运行时会在房间检查中回退到groupPolicyallowlist即使设置了channels.defaults.groupPolicy。使用channels.matrix.groups添加房间到白名单房间 ID 或别名当目录搜索找到唯一的精确匹配时名称会被解析为 ID{ channels: { matrix: { groupPolicy: allowlist, groups: { !roomId:example.org: { allow: true }, #alias:example.org: { allow: true }, }, groupAllowFrom: [owner:example.org], }, }, }requireMention: false允许在该房间中自动回复。groups.*可以为所有房间设置提及门控的默认值。groupAllowFrom限制哪些发送者可以在房间中触发机器人使用完整的 Matrix 用户 ID。每个房间的users白名单可以进一步限制特定房间内的发送者使用完整的 Matrix 用户 ID。配置向导会提示房间白名单房间 ID、别名或名称并且仅在精确唯一匹配时解析名称。启动时OpenClaw 会将白名单中的房间/用户名解析为 ID并记录映射关系未解析的条目将在白名单匹配时被忽略。默认自动接受邀请通过channels.matrix.autoJoin和channels.matrix.autoJoinAllowlist控制。要不允许任何房间请设置channels.matrix.groupPolicy: disabled或保留空白的白名单。旧版键名channels.matrix.rooms与groups形状相同。线程支持回复线程。channels.matrix.threadReplies控制回复是否保留在线程中off、inbound默认、alwayschannels.matrix.replyToMode控制当不在线程中回复时的回复元数据off默认、first、all功能特性功能状态私信✅ 支持房间✅ 支持线程✅ 支持媒体✅ 支持端到端加密E2EE✅ 支持需要加密模块表情回应✅ 支持通过工具发送/读取投票✅ 支持发送接收到的投票开始消息会转换为文本忽略投票回应/结束位置信息✅ 支持geo URI忽略海拔原生命令✅ 支持故障排查首先运行以下诊断命令openclaw status openclaw gateway status openclaw logs--followopenclaw doctor openclaw channels status--probe然后根据需要确认私信配对状态openclaw pairing list matrix常见故障已登录但房间消息被忽略房间被groupPolicy或房间白名单阻止。私信被忽略当channels.matrix.dm.policypairing时发送者待批准。加密房间失败加密支持或加密设置不匹配。故障排查流程请参阅通道故障排查配置参考Matrix完整配置配置提供者选项channels.matrix.enabled启用/禁用通道启动。channels.matrix.homeserver家服务器 URL。channels.matrix.userIdMatrix 用户 ID使用访问令牌时可省略。channels.matrix.accessToken访问令牌。channels.matrix.password用于登录的密码令牌会被存储。channels.matrix.deviceName设备显示名称。channels.matrix.encryption启用端到端加密E2EE默认false。channels.matrix.initialSyncLimit初始同步限制。channels.matrix.threadRepliesoff | inbound | always默认inbound。channels.matrix.textChunkLimit出站文本块大小字符数。channels.matrix.chunkModelength默认或newline在按长度分块前先按空行段落边界分割。channels.matrix.dm.policypairing | allowlist | open | disabled默认pairing。channels.matrix.dm.allowFrom私信白名单完整的 Matrix 用户 ID。open需要*。向导会尽可能将名称解析为 ID。channels.matrix.groupPolicyallowlist | open | disabled默认allowlist。channels.matrix.groupAllowFrom群组消息的白名单发送者完整的 Matrix 用户 ID。channels.matrix.allowlistOnly强制对私信和房间应用白名单规则。channels.matrix.groups群组白名单 每个房间的设置映射。channels.matrix.rooms旧版群组白名单/配置。channels.matrix.replyToMode线程/标签的回复模式。channels.matrix.mediaMaxMb入站/出站媒体大小上限MB。channels.matrix.autoJoin邀请处理策略always | allowlist | off默认always。channels.matrix.autoJoinAllowlist允许自动加入的房间 ID/别名。channels.matrix.accounts多账户配置以账户 ID 为键每个账户继承顶级设置。channels.matrix.actions按动作进行工具门控表情回应/消息/置顶/成员信息/频道信息。