---
summary: "将文件上传到节点终端并使用文件传输插件移动文件"
read_when:
  - "将文件拖到配对节点终端中"
  - "在节点上列出、获取或写入文件"
  - "读取目录获取限制和传输策略检查"
title: "Node 文件传输"
sidebarTitle: "文件传输"
---

## <a id="terminal-file-uploads"></a> 终端文件上传

Control UI 可以将文件拖到打开的配对节点终端中。本机节点主机通告 admin-only `terminal.upload` 命令；当配对升级首次出现时批准它。每个文件限制为 16 MiB，暂存在该节点上的私有临时目录中，并作为 shell 引用的路径返回到终端而不执行它。

路径插入支持 PowerShell、`cmd.exe` 和已识别的 POSIX shell（`sh`、Bash、Dash、Ash、Ksh、Zsh 和 Fish），包括 Windows 上的 Git Bash。其他 shell 重写会被拒绝，因为它们的引用规则无法安全推断；在 WSL 内运行节点主机以获得本机 WSL 路径。包含 `%` 或 `!` 的 `cmd.exe` 路径也会被拒绝，因为该 shell 即使在双引号内也会扩展这些字符。

## <a id="agent-file-transfers"></a> 代理文件传输

[文件传输插件](/plugins/reference/file-transfer)提供独立可选择的目录列表、获取和写入工具。允许一种工具并不意味着其他工具也可用；节点命令和路径策略仍然适用。

### <a id="gateway-workspace-files"></a> Gateway 工作区文件

文件传输插件可以将网关工作区文件调用者连接到已配对的节点。配置代理 ID、确切节点 ID 以及节点的绝对 POSIX 工作空间路径：

```json5 validate=false
// plugins.entries.file-transfer.config
{
  policyVersion: 2,
  workspaces: {
    main: { nodeId: "<paired-node-id>", remoteRoot: "/workspace" },
  },
  nodes: {
    "<paired-node-id>": {
      ask: "off",
      allowReadPaths: ["/workspace/AGENTS.md"],
      allowWritePaths: ["/workspace/AGENTS.md"],
      followSymlinks: false,
    },
  },
}
```

放置不会授予访问权限。分别授权所需的节点命令和文件路径；该示例仅授予 `AGENTS.md`。网关调用者保留自己的文档白名单。使用已解析的工作区根目录。文档读取和写入拒绝符号链接。当节点策略允许时，引导程序读取可以遵循根目录内的目录别名；最终文件符号链接仍然被拒绝。当配置的节点不可用或其工作区服务停止时，没有本地文件回退。共享网关工作区的代理必须使用相同的节点和远程根；相同的映射共享一个绑定，而冲突的映射将导致启动失败。

| 工作区操作                       | Node 命令 |
| ----------------------------------------- | ------------ |
| 读取字节及其解析的源路径 | `file.fetch` |
| 写入字节                               | `file.write` |
| 列出目录条目                    | `dir.list`   |
| 读取类型、大小和修改时间    | `file.stat`  |

`file.stat` 不添加模型工具。根据现有的读取路径策略，它接受常规文件和目录，而不获取内容或列出父级。对于引导读取，`file.fetch.rootPath` 将父别名解析限制为已解析的工作空间根；它不会授予超出节点策略的访问权限。一元读写保留16个MiB传输限制；目录读取消耗现有的 `dir.list` 页。 `file.write.expectedSha256` 验证提交的字节，而不是以前的文件版本。所有者文档冲突检查保留在网关中。

此映射仅涵盖工作区文件。内存搜索、技能管理和附件暂存需要各自的工作空间功能；仅此映射并不能实现完整的存储分割或启动代理工具。

### <a id="workspace-skill-installation"></a> Workspace技能安装

配对工作区使用本机 Skill 安装程序进行源发布、源记录以及 ClawHub 更新和删除。网关保留安装策略并更改挂钩；该节点保留已安装的文件和来源。本地工作区保留其现有的安装路径。

允许 `workspace.skills` 和 `file.create`、对工作区的读取访问权限以及对这些路径的写入访问权限（将 `/workspace` 替换为配置的根目录）：

- `/workspace/skills` 和 `/workspace/skills/**`，包括本机替换分期。
- `/workspace/.clawhub/lock.json` 用于安装跟踪。
- `/workspace/.openclaw/skill-installs/**` 用于临时源上传。

适配器在上传有界源存档之前打开已承认的节点操作。节点提取私有副本并等待网关的安装策略决策，然后再发布它。当该操作结束时，它会退出暂存。源传输保留文件插件的存档和提取限制；链接和特殊文件被拒绝。断开连接的节点显式失败。

ClawHub 更新和删除保留本机版本和本地修改检查。通过现有工作区目录发现已安装的技能；这不会将远程技能添加到通道命令菜单中。

### <a id="binary-transfers-for-services"></a> 服务的二进制传输

插件服务可以使用现有的节点通道来传输文件字节：

- 当两个主机都支持时，`file.fetch` 接受二进制传输，并受调用者的字节限制和节点策略限制。现有的一元调用保持其当前的行为。
- `file.create` 通过该通道接收字节并发布完整文件，而不替换现有文件。它在发布之前检查承认的大小和 SHA-256 摘要。

这两个命令都保留节点配对、文件路径授权和批准检查。这些传输命令不会自动暂存任务附件；工作区适配器提供这种集成。

### <a id="transferred-files"></a> 传输的文件

每次成功的文件获取都会将字节保存在网关的文件传输媒体存储中，并返回 `localPath` 和 `mediaId`，包括内联文本和图像。获取的文件在保存的副本和转发的附件中保留经过清理的文件名主干。检测到的媒体类型选择扩展名：分类为纯文本的 `train.py` 变为 `train.txt`。保存的副本包含一个独特的后缀，以保持重复的提取不同。

当节点写入可用时，将 `mediaId` 作为 `sourceMediaId` 传递以重用保存的字节。 `sourceMediaId` 不接受本地路径或来自其他媒体存储的 ID。对于内联字节，请改用 `contentBase64`。

目录工具最多返回 8192 UTF-8 字节的模型可见文本，包括外部内容包装器。 `dir_list` 显示完整名称、目录标志和大小。要继续文本限制列表，请将 **text's** `nextPageToken` 作为具有相同节点和路径的 `pageToken` 传递；它会在最后显示的条目之后立即恢复。默认请求仍为 200 个条目，上限为 5000。完整返回的元数据和原始页面令牌保留在结构化详细信息中。

`dir_fetch` 保存整个树并显示其本地 `rootDir`、总计 `fileCount` 以及完整 `relPath` 和大小记录的有界前缀。将`rootDir`与列出的`relPath`结合起来进行本地后续操作。省略的文件仍保存在该根目录下，并且可以使用可用的本地文件或目录功能进行检查；抓取没有分页。完整的清单和附件元数据保留在结构化细节中。如果路径超出文本预算或将通过安全清理重写，则文本会报告遗漏而不是显示部分或更改的路径。无法显示其第一个条目的列表明确报告分页无法前进。

如果无法读取已保存文件的元数据，`dir_fetch` 会失败，而不是报告传输成功但清单不完整。

目录获取策略检查源树后代，然后检查由用于提取的相同有界解析器和策略规划器承认的存档成员身份。它不使用人类可读的 `tar` 列表：承认的 Unicode 和换行符名称保留其确切的拼写，并且生产者添加的 AppleDouble 文件会被检查而不是隐藏。即使存档省略了目录头，也会检查父路径。 5000 个后代上限包括那些隐式目录，仅对共享父目录进行一次计数。被拒绝的路径会拒绝整个传输。已解决的源 path/device/inode 绑定、字节计数和 SHA-256 验证、link/traversal/collision 检查和提取限制仍然适用。格式错误的存档标头和目标平台文件名限制仍然会被拒绝；文件名不会被截断或修复以进行归档。