OpenClaw v2026.5.3 shipped a bundled file-transfer plugin. It gives an agent four new tools (file_fetch, dir_list, dir_fetch, and file_write) for moving binary files between paired nodes: your phone, a laptop, a Raspberry Pi, the machine running the . Every path is denied by default until an operator allowlists it, symlink traversal is refused unless you opt in, and each round trip is capped at 16 MB. If you’ve ever wanted your agent to pull a screenshot off your phone or drop a config file onto a remote box without you SSH-ing in, this is the feature.
What the file-transfer plugin actually does
Before v2026.5.3, an OpenClaw agent could read and write files on whatever machine the agent process ran on, but it had no clean way to touch files on a different paired node. The new plugin closes that gap. The four tools map to the obvious operations:
| Tool | What it does |
|---|---|
file_fetch | Reads a file from a paired node and returns its bytes to the agent |
dir_list | Lists the contents of a directory on a paired node |
dir_fetch | Pulls a whole directory (within limits) from a paired node |
file_write | Writes bytes to a path on a paired node |
These are binary-safe: images, PDFs, archives, and small databases all move intact, not just text. The plugin is bundled with the core install as of 2026.5.3, so there’s no separate ClawHub download; you enable it through plugin config like any other official plugin.
Why it’s locked down by default
The obvious risk with “let the agent move files around your machines” is that the agent moves the wrong file. OpenClaw’s design answer is default-deny everything and make the operator opt in path by path.
- Per-node path policy. Allowed paths live under
plugins.entries.file-transfer.config.nodes. Until you add a node and a path there, the tools refuse to touch anything. This is a deliberate “fail closed” choice, the same posture the 2026.4.29 release applied to restricted tool profiles. - Operator approval. File operations route through OpenClaw’s approval flow, so a sensitive write can require a human yes/no before it lands.
- Symlink traversal refused. By default the plugin will not follow a symlink out of an allowed directory. If you have a legitimate reason to follow links, there’s an explicit
followSymlinksopt-in, but you have to ask for it. - 16 MB ceiling per round trip. A single transfer can’t exceed 16 MB. This bounds both accidental huge pulls and the memory footprint of a transfer.
If you want the full picture of how OpenClaw scopes what an agent can reach, the OpenClaw security guide covers the broader model. File transfer is one more surface that follows the same principle.
Setting it up
The plugin needs three things: the plugin enabled, at least one paired node, and an allowlisted path on that node.
- Pair the node. If your phone or second machine isn’t already paired, follow the pairing walkthrough: install the node app, point it at your URL, approve the request.
- Enable the plugin. In your OpenClaw config, make sure
file-transferis among your enabled plugins. Since it’s bundled in 2026.5.3+, this is a config toggle, not an install. - Allowlist a path. Under
plugins.entries.file-transfer.config.nodes, add the node and the directory you’re willing to expose. Keep it narrow; a~/transfersfolder beats your home directory. Start read-only if you only needfile_fetch/dir_fetch, and add write access only when you needfile_write. - Test with a small file. Drop a 1 KB text file in the allowed directory and ask the agent to fetch it. Confirm the approval prompt behaves the way you expect before you trust it with anything real.
If you’re running OpenClaw on an always-on box like a Mac Mini and pairing a laptop to it, the always-on machine is usually the one you allowlist paths on, since that’s where files tend to accumulate.
What it’s good for
A few patterns that come up:
- Phone-to-server captures. Your phone takes a screenshot or photo; you ask the agent to pull it into a project folder on the server. No cloud drive round trip.
- Pushing config to a remote node. Edit a config locally, have the agent
file_writeit to a Raspberry Pi or other headless node, no manualscp. - Log collection.
dir_lista logs directory on a paired node, thendir_fetchthe recent files for the agent to summarize. - Moving small artifacts between machines mid-task. A build output on one node, an upload step on another: the agent can shuttle the file rather than asking you to.
The 16 MB cap means this is not a backup tool or a way to move large media libraries. It’s for the small, frequent transfers that otherwise interrupt a workflow.
What didn’t change
The plugin doesn’t widen what an agent can do on its own host. Local file tools (tools.fs) are still governed separately, and the 2026.4.29 change means a restricted tool profile won’t quietly grant them just because you configured a section. File transfer is additive: a new, separately-gated capability for cross-node work. And it doesn’t bypass approvals; if your setup requires operator sign-off on writes, file-transfer writes go through the same gate.
If you want context on how nodes, the , and the agent fit together in the first place, how OpenClaw works and what OpenClaw is are the starting points.
FAQ
Do I need to install anything from ClawHub to use file transfer?
No. As of v2026.5.3 the file-transfer plugin is bundled with the core install. You enable it through plugin config; there’s no separate package to download.
Can the agent read any file on a paired node?
No. Every path is denied until an operator adds it to plugins.entries.file-transfer.config.nodes. The tools refuse to touch anything outside an allowlisted directory, and they won’t follow symlinks out of one unless you set followSymlinks.
What’s the file size limit? 16 MB per round trip. For anything larger you’d need to split it or use a different mechanism; this plugin is built for small, frequent transfers, not bulk data movement.
Does file transfer work with Docker deployments? Yes. The plugin operates at the node/ layer, so a Dockerized OpenClaw can pair nodes and transfer files the same way. Just be mindful that paths inside a container are container paths, so allowlist accordingly.
Is file_write safe to enable?
It’s as safe as the path you allowlist and the approvals you require. Keep write access scoped to a dedicated directory, require operator approval for writes if your threat model warrants it, and don’t allowlist anything you’d be unhappy to see overwritten.
Bottom line
The file-transfer plugin is one of OpenClaw’s more practical 2026.5.x additions: a real capability (cross-node binary file movement) wrapped in a fail-closed policy so it doesn’t become a foot-gun. Pair your nodes, enable the plugin, allowlist a narrow path, test with a small file, and your agent can stop asking you to move things by hand.
Sources: