OpenClaw File Transfer Plugin Guide 2026: file_fetch, dir_fetch, and Secure Cross-Node Workflows on Mac mini M4

OpenClaw v2026.5.3, released in early May 2026, bundles a new file transfer plugin that gives the AI agent direct access to binary file operations across paired Mac mini M4 nodes — without manual SCP commands or shared network drives. The plugin introduces four agent tools: file_fetch, dir_list, dir_fetch, and file_write, each with per-node path policies and symlink traversal protection. This guide covers everything from initial setup through four production workflow patterns, with a troubleshooting section for the errors developers hit most often.

What Is the OpenClaw File Transfer Plugin?

Before v2026.5.3, moving files between paired OpenClaw nodes required either manual SSH commands executed outside the agent session or custom MCP server integrations that each team had to build and maintain independently. The file transfer plugin solves this by giving the OpenClaw agent native tools for reading files from and writing files to paired nodes — with the same permission model and audit trail as any other OpenClaw tool call.

The plugin is bundled starting in v2026.5.3, meaning no separate npm install is required — it ships with the main OpenClaw package. You still need to explicitly enable it in your configuration, which allows teams to control which agents have file system write access on which nodes.

How It Works Under the Hood

The file transfer plugin operates through OpenClaw's gateway layer. When the agent invokes file_fetch, the gateway routes the request to the target node's plugin receiver, which validates the requested path against the node's configured path policy, reads the file, and streams the binary content back through the gateway to the agent's context. The agent never has a direct network connection to the target node's filesystem — all file operations pass through the gateway's permission and audit layer.

This architecture has three practical consequences:

• File transfer operations are logged in OpenClaw's OTEL telemetry with the same detail as any other tool call — path requested, bytes transferred, latency, success/failure.
• Path policies are enforced at the gateway level, not client-side, making them impossible to bypass through prompt injection or agent hallucination.
• Binary files (compiled artifacts, IPA packages, model weights, images) are transferred intact — the plugin is not limited to text files.

Installing and Enabling the File Transfer Plugin

The file transfer plugin requires OpenClaw v2026.5.3 or later. If you're on an earlier version, update first:

npx openclaw@latest update

Or from within an active agent session:

/update

After updating, verify the plugin is available:

openclaw plugin list | grep file-transfer

You should see file-transfer bundled v1.0.0 in the output. If the command returns nothing, your update did not complete — run openclaw --version to confirm you're on 2026.5.3+.

Enabling in openclaw.config.js

Add the plugin to your configuration file. The plugin is disabled by default even though it's bundled:

// openclaw.config.js module.exports = { plugins: ['file-transfer'], pluginConfig: { 'file-transfer': { nodes: { 'hk-node-1': { allowedPaths: ['/Users/runner/builds', '/tmp/openclaw-transfer'], readOnly: false, maxFileSizeBytes: 500 * 1024 * 1024 // 500 MB }, 'sg-node-1': { allowedPaths: ['/Users/runner/artifacts'], readOnly: true } } } } };

The allowedPaths array defines the directory roots accessible to the plugin on each node. Paths outside these roots return a permission error without executing the operation. The readOnly flag prevents file_write on that node while still allowing file_fetch, dir_list, and dir_fetch.

Restart OpenClaw after editing the config:

openclaw restart

Confirm the plugin is active:

/plugin status file-transfer

file_fetch: Downloading Files from a Paired Node

file_fetch retrieves a single file from a specified path on a paired node and makes its content available to the agent. For text files, the content is decoded and placed in the agent's context. For binary files, the agent receives the raw bytes which it can then write to another location using file_write.

Basic Usage

In an agent prompt, you instruct OpenClaw to fetch a file naturally:

Fetch the build log from hk-node-1 at /Users/runner/builds/myapp/build.log and summarize the last 100 lines.

The agent translates this to a file_fetch tool call:

{ "tool": "file_fetch", "node": "hk-node-1", "path": "/Users/runner/builds/myapp/build.log", "encoding": "utf-8" }

For binary files such as compiled IPA packages:

Fetch MyApp.ipa from /Users/runner/builds/MyApp.ipa on sg-node-1 and write it to /tmp/transfer/MyApp.ipa on hk-node-1.

The agent chains a file_fetch on sg-node-1 with a file_write on hk-node-1, handling the binary transfer transparently.

File Size Limits and Streaming

Files under 10 MB are buffered in memory during transfer. Files between 10 MB and the configured maxFileSizeBytes are streamed — the agent receives a streaming handle rather than buffering the entire file. Files exceeding maxFileSizeBytes are rejected with a size limit error. For large build artifacts (IPA files over 100 MB, model weight files), set maxFileSizeBytes in your plugin config accordingly, keeping in mind that very large transfers through the gateway increase session latency.

dir_list and dir_fetch: Browsing and Mirroring Directories

dir_list returns the contents of a directory on a paired node — file names, sizes, modification timestamps, and file types (file/directory/symlink). It does not follow symlinks by design (symlink traversal is always blocked regardless of configuration).

dir_fetch recursively fetches an entire directory tree and delivers it as a structured manifest with file content. This is the most powerful tool in the plugin for use cases like mirroring build output directories between nodes.

dir_list: Inspecting Remote Build Output

Example: an agent checking whether a build has completed on a CI node before fetching artifacts:

List the contents of /Users/runner/builds/output/ on hk-node-1, sorted by modification time, and tell me which files were created in the last 10 minutes.

The agent calls dir_list with {"sort": "mtime", "order": "desc"} parameters and filters the result by modification timestamp. This lets agents make conditional decisions — "if the artifact exists, fetch it; if not, wait and retry" — without the developer needing to write explicit polling logic.

dir_fetch: Mirroring Build Artifacts

For syncing an entire build output directory from a CI node to an archive node:

Mirror the /Users/runner/builds/v2.3.1/ directory from sg-node-1 to /Users/archive/releases/v2.3.1/ on hk-node-1. Skip any files that already exist at the destination and have the same size.

The agent chains dir_fetch on sg-node-1 with a series of file_write calls on hk-node-1, using the size comparison to skip unchanged files. This is materially more efficient than a naive rsync-equivalent for directories where most files haven't changed between runs.

file_write: Pushing Files to Remote Nodes Safely

file_write writes content to a specified path on a paired node. It supports both text and binary content and includes atomic write semantics — the file is written to a temporary path on the target node and moved atomically to the final destination, preventing partial-write states if the transfer is interrupted.

Configuration File Distribution

A common use case: distributing a configuration file to multiple nodes simultaneously. Instead of SSH-ing to each node separately:

Write the following nginx.conf content to /etc/nginx/nginx.conf on hk-node-1, jp-node-1, and kr-node-1 simultaneously: [content here]

OpenClaw's multi-tool calling dispatches three file_write operations in parallel, completing the distribution in the time of a single write rather than three sequential SSH sessions.

Build Artifact Deployment

The agent can chain a build step with a file_write deployment in a single workflow:

Archive MyApp, sign it with the distribution certificate, then write the resulting IPA to /Users/runner/distribution/MyApp-latest.ipa on sg-node-1.

Path Policies and Security: Preventing Symlink Traversal

The file transfer plugin's most important security feature is its unconditional symlink traversal protection. Regardless of path policy configuration, the plugin never follows symlinks when resolving file paths. An agent or prompt that attempts to access /allowed/path/../../etc/passwd receives a path resolution error, not the file.

Security Feature	Behavior	Configurable?
Symlink traversal blocking	All symlinks in path are rejected at resolution time	No — always enforced
Path allowlist enforcement	Paths outside allowedPaths return permission error	Yes — via allowedPaths config
Read-only node enforcement	file_write blocked; fetch operations still allowed	Yes — via readOnly flag
File size limit	Files over maxFileSizeBytes are rejected before transfer begins	Yes — default 500 MB
Operation audit logging	All file operations logged in OTEL telemetry with path, size, latency, result	No — always logged
Atomic writes	Writes use temp file + atomic rename; no partial writes on interrupt	No — always atomic

Best Practice: Minimal Path Allowlists

Define allowedPaths to be as narrow as possible for each node's role. A CI build node only needs access to its build output directory, not its entire home directory. An archive node may need read-write access to its artifact store but should be read-only for everything else. The plugin makes it straightforward to implement least-privilege file access without additional infrastructure.

Example minimal configuration for a three-node pipeline:

nodes: { 'hk-ci': { allowedPaths: ['/Users/runner/builds/output'], readOnly: true // CI node: only fetch artifacts, never write }, 'sg-archive': { allowedPaths: ['/Users/archive/releases'], readOnly: false // Archive node: write new releases }, 'jp-staging': { allowedPaths: ['/var/www/staging', '/tmp/deploy'], readOnly: false // Staging node: deploy artifacts } }

4 Real-World Workflows Using the File Transfer Plugin on Mac mini M4

Workflow 1: Cross-Node Build Artifact Sync

Scenario: You run iOS builds on a Hong Kong node for fast build times, but your QA team is closer to the Singapore node. After each build, you want to automatically copy the signed IPA to the SG node for QA distribution.

Agent prompt:

After completing the Xcode archive on hk-node-1, check /Users/runner/builds/output/ for the newest .ipa file, fetch it, and write it to /Users/qa-distribution/latest/ on sg-node-1. Then notify me of the file name and size.

The agent: runs the build, uses dir_list to find the newest IPA, uses file_fetch to retrieve it, uses file_write to push it to the SG node, and reports the filename and byte count — all in one uninterrupted workflow without manual SCP steps.

Workflow 2: Multi-Node Log Aggregation

Scenario: You're running parallel test suites on HK, JP, KR, SG, and US East nodes. You want to aggregate all test result JSON files into a single analysis context without manually SSH-ing to each node.

Agent prompt:

Fetch the test-results.json file from /Users/runner/test-output/ on each of the five nodes (hk, jp, kr, sg, us-east), combine the results into a single table showing pass/fail counts and slowest tests per node.

The agent dispatches five parallel file_fetch calls, receives five JSON payloads, parses them, and produces the aggregated table — a workflow that would take 10–15 minutes manually becomes a 90-second automated operation.

Workflow 3: Rolling Configuration Deployment

Scenario: You've updated your OpenClaw agent system prompt and want to roll it out to all active nodes, verifying each node accepts the new config before moving to the next.

Agent prompt:

Write the updated system-prompt.txt to /Users/agent/config/ on hk-node-1. If the write succeeds, verify the file size matches the source, then proceed to jp-node-1, then kr-node-1, continuing only if each write succeeds.

The sequential conditional logic — write, verify, proceed — is handled by the agent natively without external orchestration scripts.

Workflow 4: ML Model Weight Distribution

Scenario: You've fine-tuned a local LLM on your development node and want to distribute the model weights to three inference nodes running OpenClaw with Ollama. See the Ollama + OpenClaw guide for context on local model inference setup.

Agent prompt:

The fine-tuned model weights are at /Users/dev/models/my-model-v2.gguf on hk-node-1 (file is approximately 4.2 GB). Distribute this file to /Users/ollama/models/ on sg-node-1 and us-east-node-1. Run the transfer in parallel and report transfer speed for each node.

The plugin's streaming mode handles large binary files efficiently. The agent reports transfer speeds, which helps identify if one node has network congestion — useful operational data for future node selection decisions.

Troubleshooting: Common File Transfer Plugin Errors

Error Message	Most Likely Cause	Fix
Plugin 'file-transfer' not found	OpenClaw version below 2026.5.3	Run npx openclaw@latest update and confirm version
Path not within allowed paths	Requested path is outside allowedPaths in config	Add the path root to allowedPaths for the relevant node
Write not permitted on read-only node	Node has readOnly: true and agent called file_write	Change to readOnly: false if write access is needed
File exceeds maxFileSizeBytes limit	File size exceeds the configured limit (default 500 MB)	Increase maxFileSizeBytes in plugin config, or split the file
Symlink traversal detected	Path contains or resolves through a symlink	Use the real (non-symlinked) path; symlink following is never allowed
Node 'xxx' not configured in file-transfer plugin	Node ID not present in plugin's nodes config object	Add the node to the nodes section in plugin config
Transfer hangs for large files (>1 GB)	Gateway timeout before streaming completes	Increase gateway.streamTimeoutMs in openclaw.config.js (default 300000 ms)

Why Mac mini M4 Nodes Make File Transfer Workflows Practical

The OpenClaw file transfer plugin's value multiplies significantly when running on VpsGona's Mac mini M4 nodes for one practical reason: the M4's local storage is fast NVMe SSD, and the nodes have high-bandwidth uplinks between them. File reads from local NVMe and writes to remote NVMe — rather than spinning disk or network-attached storage — mean that the bottleneck in cross-node file transfers is almost always network bandwidth rather than disk I/O. For the multi-node workflows described above, this means artifact sync and log aggregation operations complete in seconds rather than minutes.

The per-node path policy model is also well-suited to VpsGona's multi-node architecture: your HK build node, SG archive node, and US East QA distribution node each serve distinct roles in your pipeline and should have access to only the directories relevant to their function. The plugin's node-level configuration maps naturally to VpsGona's node-per-role deployment pattern.

For teams already using OpenClaw for multi-agent orchestration or data pipeline automation, the file transfer plugin closes the last gap in fully agent-driven Mac mini M4 workflows: moving binary artifacts between nodes without leaving the agent session. Check current node availability and start building your multi-node OpenClaw pipeline on the VpsGona pricing page, and refer to the deployment documentation for initial node setup.