file-transfer 插件概述
OpenClaw v2026.5.4 增强了 file-transfer 插件，新增 4 个工具：
- file_fetch：从远程节点获取文件
- dir_list：列出远程目录
- dir_fetch：批量获取目录文件
- file_write：写入文件到远程节点
支持二进制文件操作，适合跨设备 Agent 工作流。
为什么需要
多设备工作流
很多场景跨多台设备：
- Mac + iOS：iPhone 拍照在 Mac 处理
- Mac + Linux 服务器：本地开发，远程部署
- 多个 Mac：家里和公司
- 物联网：树莓派等小设备
之前的痛点：
- 传文件麻烦（云盘上传下载）
- Agent 无法直接访问其他设备文件
- 跨设备工作流碎片化
file-transfer 的解决
让 Agent 像操作本地文件一样操作远程节点的文件。
配置 file-transfer
启用插件
# 安装
openclaw plugins install @openclaw/file-transfer
# 启用
openclaw plugins enable file-transfer
配置节点
plugins:
file-transfer:
enabled: true
nodes:
# 远程 Mac
home-mac:
host: "home-mac.local"
port: 18789
# 路径策略：默认拒绝
allowedPaths:
- "/Users/shared/openclaw"
- "/tmp"
# 限制
maxBytesPerRoundTrip: 16777216 # 16MB
rateLimit: "100/minute"
# 树莓派
pi:
host: "raspberrypi.local"
allowedPaths:
- "/home/pi/data"
maxBytesPerRoundTrip: 8388608 # 8MB
配对节点
每对节点需要建立信任：
# 在第一个节点上
openclaw nodes pair --invite
# 输出邀请码：abc-123-xyz
# 在第二个节点上
openclaw nodes pair --accept abc-123-xyz
4 个核心工具
1. file_fetch
从远程节点获取文件：
用户：获取 home-mac 上 Documents 里的会议纪要
Agent：
[调用 file_fetch]
[node: home-mac]
[path: /Users/me/Documents/meeting-notes.md]
返回文件内容...
2. dir_list
列出远程目录：
用户：home-mac 上 Documents 有哪些文件？
Agent：
[调用 dir_list]
[node: home-mac]
[path: /Users/me/Documents]
返回：
- meeting-notes.md (15 KB)
- project-plan.pdf (245 KB)
- expenses.xlsx (8 KB)
- screenshots/ (目录)
3. dir_fetch
批量获取目录文件：
用户：把 pi 的 sensor-data 目录里的所有 JSON 文件取过来
Agent：
[调用 dir_fetch]
[node: pi]
[path: /home/pi/data/sensor-data]
[pattern: "*.json"]
返回：35 个 JSON 文件
[超过 16MB 限制时自动分批]
4. file_write
写入文件到远程节点：
用户：把生成的报告写到 home-mac 的 Reports 目录
Agent：
[调用 file_write]
[node: home-mac]
[path: /Users/me/Reports/2026-05-report.md]
[content: ...]
返回：成功，已写入 12 KB
安全机制
默认拒绝
每个节点必须显式声明允许的路径：
nodes:
home-mac:
allowedPaths:
- "/Users/me/openclaw-shared"
- "/tmp"
# 没有列出的路径默认拒绝
字节限制
nodes:
home-mac:
maxBytesPerRoundTrip: 16777216 # 16MB
防止：
- 意外大文件传输
- 资源耗尽
- 网络拥塞
速率限制
nodes:
pi:
rateLimit:
perMinute: 100
perHour: 1000
审批门控
敏感操作需要审批：
nodes:
home-mac:
approvalRequired:
- file_write # 写入需要审批
- paths:
- "/Users/me/Documents" # 这个目录写入需审批
审计日志
plugins:
file-transfer:
audit:
enabled: true
logFile: "/var/log/openclaw-file-transfer.log"
记录所有操作，便于追溯。
实际应用场景
场景 1：跨设备照片处理
用户：iPhone 拍了一些产品照，处理后放到 Dropbox
Agent：
[file_fetch from iPhone] 拍照文件夹
[本地处理] 调整大小、加水印
[file_write to Mac] Dropbox 同步目录
[通知] 处理完成
场景 2：分布式数据收集
# 多个传感器节点
nodes:
sensor-1:
host: "sensor-1.iot"
allowedPaths: ["/data"]
sensor-2:
host: "sensor-2.iot"
allowedPaths: ["/data"]
sensor-3:
host: "sensor-3.iot"
allowedPaths: ["/data"]
用户：收集所有传感器今天的数据
Agent：
[dir_fetch from sensor-1]
[dir_fetch from sensor-2]
[dir_fetch from sensor-3]
[本地聚合分析]
[生成报告]
场景 3：远程开发
用户：在远程服务器上有个 Bug，帮我看看
Agent：
[file_fetch] 远程服务器的代码
[本地分析]
[file_write] 修复后的代码到远程
[exec] 远程重启服务
[验证] 修复成功
场景 4：多设备文件同步
# 自动同步配置
cron:
- schedule: "0 18 * * *" # 每天 18:00
flow: daily-sync
# workflows/daily-sync.lobster
steps:
- id: home-to-cloud
tool: file-transfer
action: dir_fetch
args:
node: home-mac
path: "/Users/me/Documents/today"
- id: upload-cloud
tool: dropbox-upload
args:
files: $home-to-cloud.files
性能优化
压缩传输
plugins:
file-transfer:
compression:
enabled: true
algorithm: "zstd" # 或 gzip、lz4
level: 3 # 1-9，平衡速度和压缩率
二进制文件可能效果不明显，文本文件可减少 70%+ 流量。
增量传输
nodes:
home-mac:
incremental:
enabled: true
cacheDir: "~/.openclaw/file-cache"
只传输变化部分。
并行传输
plugins:
file-transfer:
parallel:
enabled: true
maxConcurrent: 4
多文件并行传输。
故障排查
节点不可达
openclaw nodes status home-mac
可能原因：
- 网络不通
- 节点未运行 OpenClaw
- 配对失效
路径被拒绝
错误：路径 /Users/me/Private 不在允许列表
修改配置或使用允许的路径。
文件过大
错误：文件 100MB 超过限制 16MB
解决：
- 分块传输
- 使用其他工具（rsync、scp）
- 提高 limit（注意性能）
nodes:
home-mac:
maxBytesPerRoundTrip: 67108864 # 64MB
与其他工具对比
对比 SSH/SCP
| 维度 | file-transfer | SSH/SCP |
|---|---|---|
| Agent 友好 | 是 | 需要封装 |
| 安全 | 多层防护 | SSH 密钥 |
| 性能 | 良好 | 优秀 |
| 跨平台 | 原生支持 | 通用 |
file-transfer 不替代 SSH，而是为 Agent 提供更友好的接口。
对比 rsync
- rsync：批量同步专家
- file-transfer：单文件操作灵活
可以配合使用：rsync 做大批量同步，file-transfer 做精细操作。
注意事项
- file-transfer 增强需要 OpenClaw v2026.5.4 或更高版本
- 配对设备前确保信任
- 路径策略默认拒绝，仔细配置
- 16MB 限制可调，但注意性能
- 不要传敏感数据（如密码文件）
- 审计日志保留至少 30 天
- 跨网络（公网）传输考虑加密
- 大量小文件用 dir_fetch 比循环 file_fetch 更快
- 配合 Lobster 审批门控保证安全