OpenClaw File Transfer 插件深度指南节点文件读取、目录归档传输与授权策略迁移【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawFile Transfer 是 OpenClaw 内置的文件传输插件包名openclaw/file-transfer它通过专用 node 命令让 Agent 在已配对节点上读取文件、列出目录、打包拉取整个目录树并写入文件从而绕过 bash stdout 截断限制。本文以 File Transfer 插件参考文档 为主体结合插件源码与 CLI 参考完整讲解四个工具的参数、默认值、授权策略模型、目录归档行为以及升级后的权限迁移命令帮助你完成插件的安装、配置、审计与安全加固。插件概览四个工具、一条 CLI、一种策略从插件清单 openclaw.plugin.json 可以看到插件的核心契约维度内容插件 IDfile-transfer包名openclaw/file-transfer安装方式OpenClaw 内置enabledByDefault: trueonStartup激活CLI 命令openclaw file-transfer含子命令approvals migrate契约类型tools暴露file_fetch、dir_list、dir_fetch、file_write四个工具分类documents-files这四个工具彼此独立可选允许其中一个并不会让其他工具自动可用node 命令与路径策略仍然分别生效详见 节点文件传输。插件入口 extensions/file-transfer/index.ts 在register()中完成四件事注册 CLI 命令组file-transfer注册 node invoke 策略registerNodeInvokePolicy这是所有授权检查的入口注册四个 Agent 工具全部通过createLazyTool懒加载首次调用才真正import对应实现降低启动开销注册四个节点宿主命令file.fetch、dir.list、dir.fetch、file.write均标记cap: file、dangerous: true走node.invoke通道执行。核心设计理念是文件字节通过 base64 编码后经node.invoke传输从而绕过 bash stdout 对二进制输出的截断单个往返可承载最大 16 MB 的二进制数据见 descriptors.ts 中FILE_FETCH_HARD_MAX_BYTES 16 * 1024 * 1024。默认拒绝路径授权策略模型插件的默认行为是DENY默认拒绝。操作者必须在配置文件~/.openclaw/openclaw.json的plugins.entries.file-transfer.config.nodes下显式添加策略块否则所有文件操作在到达节点前就会被拒绝见 policy.ts 顶部注释。完整配置模板如下{ plugins: { entries: { file-transfer: { config: { nodes: { nodeId-or-displayName: { ask: off, allowReadPaths: [~/Screenshots/**, /tmp/**], allowWritePaths: [~/Downloads/**], denyPaths: [**/.ssh/**, **/.aws/**], maxBytes: 16777216, followSymlinks: false }, *: { ask: on-miss } } } } } } }节点级配置项配置项类型默认值含义askoff \| on-miss \| alwaysoff询问模式见下文allowReadPathsstring[]无允许读取的路径 glob 列表allowWritePathsstring[]无允许写入的路径 glob 列表denyPathsstring[]无硬拒绝的路径 glob永远优先maxBytesnumber无取工具默认值单次传输的字节上限followSymlinksbooleanfalse是否允许跟随符号链接ask 三种模式off静默模式当前默认——匹配即允许不匹配即拒绝on-miss匹配则静默允许未匹配时弹出提示征求操作者批准always每次调用都提示操作者denyPaths仍然硬拒绝。策略匹配时支持~展开~/Downloads/**会展开为当前用户主目录并且节点选择支持按nodeId、displayName或通配符*匹配见 policy.ts 的resolveNodePolicy。评估顺序源码级policy.ts 中evaluateFilePolicyInternal的执行顺序是理解授权行为的关键原始路径含..段 → 直接拒绝检查的是未归一化的原始字符串防止/allowed/../etc/passwd这类字面穿越序列先匹配到/allowed/**导致字节在 realpath 事后检查前就跨过节点边界没有任何nodes配置 →NO_POLICY拒绝且不可询问因为操作者根本没启用存在旧版正向权限且policyVersion不是 2 →POLICY_MIGRATION_REQUIRED拒绝提示运行迁移命令denyPaths命中 →POLICY_DENIED硬拒绝不可询问ask: always→ 每次都询问allowReadPaths/allowWritePaths命中 → 静默允许matched-allowliteralGrants精确授权记录见下文命中 → 允许matched-literal并携带期望的 canonical path 供节点侧校验ask: on-miss未命中 → 可询问的拒绝其余情况 → 硬拒绝。精确授权literalGrants与符号链接防护除操作者手写的 glob 外策略还保存一种精确授权记录literalGrants每次操作者批准一次调用后系统会记录完整的四元组——稳定的节点 ID、命令、请求路径、以及节点权威的 canonical 路径policy.ts 的persistLiteralGrant。这些字符串是节点侧的不透明路径Gateway 不会对其做归一化或喂给 glob 匹配器。followSymlinks默认false提供了符号链接防护节点侧 handler 会在任何 I/O之前对请求路径新文件写入则对其父目录执行 realpath若与请求路径不一致则返回SYMLINK_REDIRECT拒绝。这能阻止用户可控目录中的符号链接如~/Downloads/evil → /etc把看似允许的路径重定向到被禁止的 canonical 位置。在 macOS 上/var → /private/var会误伤/var/folders路径时可显式设为true恢复跟随 事后校验的宽松行为。四个工具详解所有工具的参数 schema 定义在 descriptors.ts以下参数均来自该文件。node参数接受已配对节点的 ID、显示名或 IP由nodes status展示不接受local、host、gateway、auto等关键字——本地工作区文件请使用本地 file/exec 工具。file_fetch拉取单个文件从配对节点按绝对路径读取文件全部字节存入 Gateway 的 file-transfer 媒体库返回localPath与mediaId。支持图片以 image content block 返回小文本文件≤8 KB以内联方式返回。典型用途截图、照片、收据、日志、源代码。参数说明node已配对节点 ID / 显示名 / IPpath节点上的绝对路径服务端做 canonicalizemaxBytes最大读取字节数默认 8 MB硬上限 16 MB单次往返gatewayUrl/gatewayToken可选指定 Gateway 连接timeoutMs可选超时读取到的mediaId可复用作file_write的sourceMediaId做二进制拷贝要求节点具备写入能力。dir_list目录列表从配对节点获取目录列表非本地工作区。文本输出限制为 8192 UTF-8 字节展示完整文件名、isDir标记与可表示时的文件大小完整元数据保留在结构化 details 中。适合先发现远端路径再决定读取哪些文件。参数说明node已配对节点path节点上的目录绝对路径pageToken分页令牌来自上一次dir_list调用的文本nextPageToken配合相同的 node 和 path 使用maxEntries每页最大条目数默认 200硬上限 5000分页有讲究文本分页令牌text 的nextPageToken与结构化令牌可能不同传入文本的nextPageToken会从最后一个已展示条目之后继续若第一个条目就无法表示工具会明确报告分页无法推进。dir_fetch整目录归档拉取将配对节点的**整个目录树含 dotfiles 与隐藏目录**打包为 gzip tar 归档后在 Gateway 解包。文本输出限制 8192 字节展示rootDir、总fileCount及一段完整的relPath size 记录前缀完整清单与附件元数据保留在结构化 details 中。没有分页机制超过 16 MB压缩后的树会被拒绝。参数说明node已配对节点path节点上的目录绝对路径maxBytes最大 gzip tar 字节数默认 8 MB硬上限 16 MBgatewayUrl/gatewayToken/timeoutMs可选file_write写入文件向配对节点按绝对路径写入文件字节。采用原子写入临时文件 rename默认拒绝覆盖overwrite: true才替换默认拒绝通过符号链接目标写入除非策略显式允许跟随符号链接。参数说明node已配对节点path节点上的写入绝对路径contentBase64内联字节base64解码后最大 16 MBsourceMediaId复用之前file_fetch保存在媒体库中的mediaId不是本地路径也不是其他媒体库的 ID用于二进制拷贝mimeType内容类型提示不校验overwrite是否允许覆盖已有文件默认falsecreateParents是否创建缺失的父目录等价mkdir -p默认false目录归档传输的边界行为节点文件传输 对dir_fetch的归档安全做了详细说明要点如下逐后代策略检查file-transfer 策略会检查源树的每一个后代包括隐式目录归档未包含目录头时也会检查父路径任一后代被拒绝则整个传输被拒绝而不是过滤掉该项。5000 后代上限包含这些隐式目录共享父路径只计一次同一解析器归档成员身份由与解包相同的受限解析器与策略规划器校验不使用人可读的tar列表——这样 Unicode 与换行文件名能保留精确拼写生产方附加的 AppleDouble 文件会被检查而非隐藏严格校验仍然生效canonical 源路径/设备/inode 绑定、字节数与 SHA-256 校验、链接/穿越/碰撞检查、解包限制全部保留畸形归档头与目标平台不允许的文件名仍会拒绝文件名不会被截断或修复以让归档通过输出落盘每次成功的文件读取都会把字节存入 Gateway 的 file-transfer 媒体库并同时返回localPath和mediaId包括内联文本与图片已读取文件会保留清洗过的文件名主干媒体类型决定扩展名如train.py被识别为纯文本会变成train.txt并附加唯一后缀以区分重复读取。CLIopenclaw file-transfer approvals migrate权限迁移升级 OpenClaw 后旧版正向文件传输权限allowReadPaths/allowWritePaths中的条目会保持不活跃直到你逐一审查。拒绝规则、大小限制与符号链接设置在整个过程中继续生效不会因迁移而暂时放开。命令形式与选项openclaw file-transfer approvals migrate openclaw file-transfer approvals migrate --dry-run openclaw file-transfer approvals migrate --json选项效果--dry-run走完所有提示并打印计划不写任何配置--json以 JSON 输出未审查的权限后直接退出不提示、不写配置两个选项默认均为关闭cli.ts。运行位置约束迁移命令必须在 Gateway 主机的交互式终端中运行因为它直接更新该主机的 file-transfer 策略cli.ts当gateway.mode为remote时拒绝运行当 OpenClaw 配置无效时拒绝运行需先修复配置再重试。交互式审查流程命令逐条列出旧权限每项显示为node selector · read|write · path需要为每条选择一种结局选项行为Require exact reapproval移除这条含歧义的权限下次使用时弹窗询问一次并记录精确的节点、命令、请求路径与 canonical 目标Keep as an intentional wildcard保留该条目为操作者手写的 globRemove this permission直接删除这条正向权限全部选择后命令打印包含各结局数量的计划以及降级提示旧版 OpenClaw 无法读取迁移后的格式在一次确认后才写入配置。写入成功后报告相邻配置文件备份.bak的路径若无法校验备份也会明确说明cli.ts。脚本化与非交互使用--json不修改任何东西适合放入健康检查或升级脚本场景输出退出码没有需要审查的权限{status:ok,changed:false,message:No legacy permissions need review.}0仍有权限待审查{status:needs-input,changed:false,items:[...],command:openclaw file-transfer approvals migrate}2不带--json时命令先检查是否有工作可做非交互 shell 仅在仍有权限待审查时报错并提示到终端重跑而不是替每条权限猜测结局非交互且无待审查项时打印同样的 no-work 消息并以 0 退出因此重复的升级脚本可以保持安静docs/cli/file-transfer.md。迁移结果与降级迁移成功后写入新格式policyVersion升为 2选 exact 的条目进入pendingReapprovals下一次使用时询问并记录完整四元组选 keep-glob 的条目保留在allowReadPaths/allowWritePaths中approvals-migration.ts。需要降级时先还原迁移后报告的.bak文件再启动旧版 OpenClaw——旧版无法读取迁移后的格式还原备份同时也会恢复旧版权限语义。底层实现原理速览base64 单往返传输二进制字节 base64 编码后经node.invoke传输绕过 bash stdout 截断8 MB 默认 / 16 MB 硬上限单次往返定义于 descriptors.ts默认拒绝无策略配置时每个调用都被拒绝策略块必须写在plugins.entries.file-transfer.config.nodes下policy.ts字面..穿越拦截匹配任何 allow/deny glob 之前先拒绝原始字符串中含..段的路径Windows 反斜杠同样处理policy.tscanonical 路径绑定精确授权只在节点侧 canonical 路径校验通过后才持久化符号链接默认在 I/O 前被 realpath 检查拦截policy.ts懒加载工具四个工具首次调用才加载实现控制启动成本index.ts。相关文档File Transfer 插件参考本文主体来源CLI 参考openclaw file-transfer完整 flag 面与退出码节点文件传输目录归档边界、终端文件上传与媒体库细节。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考