夜雨聆风文件传输 · 配对节点 · node.invoke · v2026.5.3 ——
OpenClaw 在本版将设备间的文件交换从
「只能靠 shell 拼凑」推进到了
「开箱即用的内置能力」。
项目概述：个人 AI 助理的设备原生路线
OpenClaw 是一个运行在自有设备上的个人 AI 助理，
Gateway 作为控制平面，真正的助理体验散布在日常使用的
各即时通讯渠道——它支持 WhatsApp、Telegram、Slack、
Discord、Signal、Microsoft Teams、Matrix、飞书、微信等
20 多个平台。源码（TypeScript，MIT）已积累超过 36 万 Star。
它与聊天机器人的核心差异在于设备配对：
macOS 笔记本、iOS 手机、Android 手机、Linux 服务器
都可以注册为配对节点（Paired Nodes），AI 助理通过
Gateway 调度在本地设备上执行真实操作——读写文件、
运行本地命令、操控浏览器、接入 Google Meet。
设备间的文件传输一直是这套架构中最后一个
「你需要自己想办法」的缺口。
旧版痛点：设备间文件交换没有第一方方案
假设你的 Android 手机和 macOS 笔记本都注册到同一个
OpenClaw Gateway，你想让 AI 助理从手机取一张截图回桌面分析。
旧版做到这一点很绕：你可以写 bash 脚本通过 adb 或 scp 拉文件，
但需要配置权限、处理二进制回显截断、担心路径逃逸。
更麻烦的是，AI 助理通过 shell 工具读文件时，输出是文本流，
对图片、PDF、压缩包等二进制数据天然不友好。
超 16 KB 的 base64 输出在 shell stdout 里就丢数据了。
反过来，写入场景同样缺位——如果你希望 AI 助理把生成的
配置文件直接推送到服务器节点，旧版没有统一的入口。
要么自己写一个插件，要么放弃。
对一个标榜「设备原生」的架构来说，这是一个明显的断层。
本版 Gateway 启动性能也做了 lazy-load 改造：插件发现、
cron、schema 等模块从「启动时全量加载」改为
「就绪后按需加载」，减少了日常启动等待时间。
File Transfer 插件：四把工具补齐操作闭环
v2026.5.3 引入的 @openclaw/file-transfer 插件
在 Gateway 初始化时自动激活（enabledByDefault: true），
通过专用的 node.invoke 通道替代 bash 执行，
一次性绕开了 stdout 截断和管道污染问题。
插件提供了四个 Agent 工具：
• file_fetch——从配对节点读取任意文件，以 base64
载荷传输，上限 16 MB。AI 助理可取回图片、音频、
PDF 等二进制文件进行后续分析。
•
dir_list——列出节点目录内容，作为浏览与定位入口。
•
dir_fetch——递归拉取整个目录的 tar 归档，
同样以 base64 传输。适合批量备份日志或配置文件。
• file_write——向配对节点写入文件，
实现「AI 生成数据，写入指定设备路径」。
四个工具共享一套节点级路径策略。配置时以节点 ID 为 key，
分别设定 allowReadPaths / allowWritePaths / denyPaths，
以及单次传输上限 maxBytes。默认拒绝符号链接穿越
（followSymlinks: false），每次操作需要 operator 审批，
支持「仅此一次」或「始终允许」两种授权模式。
此外，WhatsApp 新增了 Channel/Newsletter 发送目标支持；
流式输出方面引入了统一的 streaming.mode: "progress" 配置，
让 Discord、Telegram、Slack、Matrix、Teams 共享一套
进度条语义；插件安装管道也做了整体加固，处理了
npm prerelease 版本回退和 beta channel 优先级等边界情况。
传输管道：基于 node.invoke 的四层安全设计
文件传输插件的实现不依赖 Agent 端的 bash shell，
而是走 OpenClaw 的 node.invoke 内建通道。
NodeHost 侧注册了四个命令（file.fetch、dir.list、
dir.fetch、file.write），每个命令在收到 Agent 的
调用请求后经历四层把关：
第一层：权限预检——解析真实路径，检查符号链接是否
会逃逸出权限范围。若路径解析结果与原始请求不一致，
则触发策略二次判定，拒绝未授权的 symlink 穿越。
第二层：Operator 审批——请求拼接为「读取文件：/path」
或「写入文件：/path」的审批弹窗，operator 可选择拒绝、
允许一次或始终允许。始终允许的决定会持久化到 allowReadPaths
和 allowWritePaths 配置中。
第三层：传输执行——通过才是真正的 IO 操作。
对于 dir.fetch，预检阶段会先返回待传输文件的条目列表
供策略审核，实际操作后再做一次归档条目级校验。
两层检查确保即使节点端存在符号链接，也不会把
不该传的文件打包进来。
第四层：审计追踪——所有操作的节点 ID、目标路径、
决策结果、耗时都写入审计文件，方便事后排查。
这四层设计的实质是给 node.invoke 通道增加了一个
带状态的文件策略引擎（FileTransferNodeInvokePolicy），
将 16 MB 以内的二进制文件交换变成了与普通工具调用
同样安全的操作——这正是设备原生架构应有的基础能力。
