OpenClaw Dateiübertragung-Plugin Guide 2026: file_fetch, dir_fetch & Sichere Cross-Node-Workflows auf Mac mini M4

Das Anfang Mai 2026 erschienene OpenClaw v2026.5.3 enthält ein neues Dateiübertragung-Plugin, das es KI-Agenten ermöglicht, Binärdateioperationen direkt zwischen gepairten Knoten auszuführen – ohne manuelle SCP-Befehle oder freigegebene Netzwerklaufwerke. Das Plugin führt vier Agent-Tools ein: file_fetch, dir_list, dir_fetch und file_write. Alle verfügen über knotenspezifische Pfadrichtlinien und Schutz vor symbolischer Link-Traversierung. Dieser Guide behandelt die Ersteinrichtung, vier Produktions-Workflow-Muster und die Fehlerbehebung bei häufigen Fehlern.

Was ist das OpenClaw Dateiübertragung-Plugin?

Vor v2026.5.3 erforderte das Verschieben von Dateien zwischen gepairten OpenClaw-Knoten das Ausführen manueller SSH-Befehle außerhalb der Agent-Sitzung oder dass jedes Team seine eigenen benutzerdefinierten MCP-Server-Integrationen aufbaute und pflegte. Das Dateiübertragung-Plugin löst dieses Problem, indem es dem OpenClaw-Agent native Tools zum Lesen und Schreiben von Dateien mit gepairten Knoten gibt. Das Berechtigungsmodell und die Audit-Logs entsprechen vollständig anderen OpenClaw-Tool-Aufrufen.

Das Plugin ist ab v2026.5.3 im Hauptpaket gebündelt – keine separate npm-Installation erforderlich. Es muss jedoch explizit in der Konfiguration aktiviert werden, was Teams ermöglicht zu kontrollieren, welche Agents Schreibzugriff auf das Dateisystem welcher Knoten haben.

Installation und Konfiguration

Das Dateiübertragung-Plugin benötigt OpenClaw v2026.5.3 oder höher. Falls Sie eine ältere Version verwenden, aktualisieren Sie zuerst:

npx openclaw@latest update

Oder aus einer aktiven Agent-Sitzung:

/update

Überprüfen Sie nach der Aktualisierung, ob das Plugin verfügbar ist:

openclaw plugin list | grep file-transfer

Sie sollten sehen: file-transfer bundled v1.0.0. Wenn nichts zurückkommt, ist die Aktualisierung nicht vollständig. Überprüfen Sie mit openclaw --version, ob Sie 2026.5.3 oder höher haben.

Aktivierung in openclaw.config.js

Das Plugin ist gebündelt, aber standardmäßig deaktiviert. Fügen Sie es Ihrer Konfigurationsdatei hinzu:

// 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 // Nur Lesen, kein Schreiben } } } } };

Das allowedPaths-Array definiert die Verzeichnis-Root-Pfade, auf die das Plugin auf diesem Knoten zugreifen darf. Pfade außerhalb der Whitelist geben einen Berechtigungsfehler zurück und die Operation wird nicht ausgeführt. readOnly: true erlaubt file_fetch, dir_list und dir_fetch, verhindert aber file_write auf diesen Knoten.

Starten Sie OpenClaw neu, um die Konfiguration anzuwenden:

openclaw restart

Bestätigen Sie, dass das Plugin aktiv ist:

/plugin status file-transfer

file_fetch: Dateien von gepairten Knoten abrufen

file_fetch ruft eine einzelne Datei vom angegebenen Pfad eines gepairten Knotens ab und macht ihren Inhalt für den Agent verfügbar. Bei Textdateien dekodiert es den Inhalt und platziert ihn im Agent-Kontext. Bei Binärdateien empfängt der Agent die Rohdaten-Bytes und kann sie anschließend mit file_write anderswo schreiben.

Grundlegende Verwendung

Weisen Sie den Agent einfach in natürlicher Sprache an, eine Datei abzurufen:

Rufe das Build-Log von /Users/runner/builds/myapp/build.log auf hk-node-1 ab und fasse die letzten 100 Zeilen zusammen.

Der Agent übersetzt dies in einen file_fetch-Tool-Aufruf mit Knoten, Pfad und Kodierung. Bei Binärdateien wie einem kompilierten IPA-Paket verkettet der Agent einen file_fetch auf sg-node-1 mit einem file_write auf hk-node-1 und verarbeitet die Binärübertragung transparent.

Dateigrößenbeschränkungen und Streaming

Dateien unter 10 MB werden während der Übertragung im Speicher gepuffert. Dateien zwischen 10 MB und maxFileSizeBytes werden gestreamt. Dateien über maxFileSizeBytes werden mit einem Größenbegrenzungsfehler abgelehnt. Für IPAs über 100 MB oder große Modell-Gewichtsdateien konfigurieren Sie maxFileSizeBytes entsprechend.

dir_list und dir_fetch: Remote-Verzeichnisse durchsuchen und spiegeln

dir_list gibt den Inhalt eines Verzeichnisses auf einem gepairten Knoten zurück – Dateinamen, Größen, Änderungs-Zeitstempel, Dateitypen (Datei/Verzeichnis/symbolischer Link). Es folgt by Design keinen symbolischen Links (symbolische Link-Traversierung wird unabhängig von der Konfiguration immer blockiert).

dir_fetch ruft rekursiv einen gesamten Verzeichnisbaum ab und gibt ihn als strukturiertes Manifest mit Dateiinhalt zurück. Es ist das leistungsfähigste Tool zum Spiegeln von Build-Ausgabeverzeichnissen zwischen Knoten.

dir_list: Remote-Build-Ausgabe prüfen

Beispiel, wo der Agent prüft, ob ein Build auf einem CI-Knoten abgeschlossen ist, bevor er Artefakte abruft:

Liste den Inhalt des Verzeichnisses /Users/runner/builds/output/ auf hk-node-1, sortiert nach Änderungszeit, und sage mir, welche Dateien in den letzten 10 Minuten erstellt wurden.

Der Agent ruft dir_list mit Sortier- und Filterparametern auf. Dies ermöglicht bedingte Entscheidungen wie „Artefakt abrufen, wenn es existiert, sonst warten und erneut versuchen", ohne dass der Entwickler explizite Polling-Logik schreiben muss.

dir_fetch: Build-Artefakte spiegeln

Um ein komplettes Build-Ausgabeverzeichnis von einem CI-Knoten zu einem Archivierungsknoten zu synchronisieren:

Spiegele das Verzeichnis /Users/runner/builds/v2.3.1/ von sg-node-1 nach /Users/archive/releases/v2.3.1/ auf hk-node-1. Überspringe Dateien, die am Ziel bereits mit gleicher Größe vorhanden sind.

Der Agent verkettet einen dir_fetch von sg-node-1 mit einer Reihe von file_write-Aufrufen zu hk-node-1 und überspringt unveränderte Dateien per Größenvergleich.

file_write: Sicheres Schreiben von Dateien auf Remote-Knoten

file_write schreibt Inhalt in den angegebenen Pfad eines gepairten Knotens. Es unterstützt sowohl Text- als auch Binärinhalte und verfügt über atomare Schreib-Semantik – es schreibt in einen temporären Pfad auf dem Zielknoten und verschiebt dann atomar an das endgültige Ziel, wodurch partielle Schreibzustände bei Übertragungsunterbrechung verhindert werden.

Konfigurationsdatei-Verteilung

Häufiger Anwendungsfall: Eine Konfigurationsdatei gleichzeitig auf mehrere Knoten verteilen (ohne separate SSH-Verbindung zu jedem Knoten):

Schreibe den folgenden nginx.conf-Inhalt gleichzeitig in /etc/nginx/nginx.conf auf hk-node-1, jp-node-1 und kr-node-1: [Inhalt]

OpenClaws Multi-Tool-Aufrufe dispatchen drei file_write-Operationen parallel und schließen die Verteilung in einer einzigen Schreibdauer statt drei aufeinanderfolgenden SSH-Sitzungen ab.

Pfadrichtlinien und Sicherheit: Schutz vor symbolischer Link-Traversierung

Die wichtigste Sicherheitsfunktion des Dateiübertragung-Plugins ist sein bedingungsloser Schutz vor symbolischer Link-Traversierung. Unabhängig von der Pfadrichtlinienkonfiguration folgt das Plugin keinen symbolischen Links bei der Auflösung von Dateipfaden. Ein Agent oder Prompt, der versucht, auf /allowed/path/../../etc/passwd zuzugreifen, erhält einen Pfadauflösungsfehler, nicht den Dateiinhalt.

Sicherheitsfunktion	Verhalten	Konfigurierbar?
Symbolischer Link-Traversierung blockiert	Alle symbolischen Links im Pfad werden bei der Auflösung abgelehnt	Nein — immer erzwungen
Pfad-Whitelist-Durchsetzung	Pfade außerhalb allowedPaths geben Berechtigungsfehler zurück	Ja — via allowedPaths
Nur-Lesen-Knoten-Durchsetzung	file_write blockiert, Abrufoperationen erlaubt	Ja — via readOnly-Flag
Dateigrößenbeschränkung	Dateien über maxFileSizeBytes vor Übertragung abgelehnt	Ja — Standard 500 MB
Operations-Audit-Log	Alle Dateioperationen in OTEL-Telemetrie protokolliert	Nein — immer protokolliert
Atomares Schreiben	Temporäre Datei + atomares Umbenennen, kein Teilschreiben bei Unterbrechung	Nein — immer atomar

4 Praxis-Workflows (echte Beispiele auf Mac mini M4)

Workflow 1: Cross-Node Build-Artefakt-Synchronisation

Szenario: Sie führen iOS-Builds auf dem Hongkong-Knoten aus (Builds sind schnell), aber Ihr QA-Team ist näher am Singapur-Knoten. Sie möchten nach jedem Build das signierte IPA automatisch zum SG-Knoten für die QA-Verteilung kopieren.

Agent-Prompt:

Sobald das Xcode-Archiv auf hk-node-1 abgeschlossen ist, finde die neueste .ipa-Datei in /Users/runner/builds/output/, rufe sie ab und schreibe sie in /Users/qa-distribution/latest/ auf sg-node-1. Berichte Dateiname und Größe.

Der Agent führt den Build aus, sucht das neueste IPA mit dir_list, ruft es mit file_fetch ab, pusht es mit file_write zum SG-Knoten und berichtet Dateiname und Byte-Anzahl – End-to-End-Workflow ohne manuelles SCP.

Workflow 2: Multi-Node-Log-Aggregation

Szenario: Sie führen Test-Suites parallel auf allen 5 Knoten (HK, JP, KR, SG, US East) aus. Sie möchten alle Test-Ergebnis-JSON-Dateien in einem einzigen Analyse-Kontext aggregieren, ohne sich manuell per SSH zu jedem Knoten zu verbinden.

Der Agent stellt 5 parallele file_fetch-Aufrufe aus, empfängt die 5 JSON-Payloads, aggregiert sie und generiert eine Tabelle mit Pass/Fail-Zählungen und dem langsamsten Test pro Knoten. Eine Aufgabe, die manuell 10–15 Minuten dauern würde, wird durch Automatisierung in etwa 90 Sekunden erledigt.

Workflow 3: Rolling-Konfigurationsverteilung

Szenario: Sie aktualisieren die System-Prompts des OpenClaw-Agents und möchten schrittweise ausrollen, wobei Sie sicherstellen, dass jeder Knoten die neue Konfiguration akzeptiert, bevor Sie zum nächsten weitergehen. Die sequenzielle bedingte Schreiben→Validieren→Fortfahren-Logik wird nativ vom Agent verarbeitet, ohne externes Orchestrierungsskript.

Workflow 4: ML-Modell-Gewichtsverteilung

Szenario: Sie haben ein lokales LLM auf einem Entwicklungsknoten fein abgestimmt und möchten die Modell-Gewichte auf 3 Inferenzknoten verteilen, die OpenClaw + Ollama ausführen. Der Streaming-Modus des Plugins verarbeitet große Binärdateien effizient. Die vom Agent gemeldeten Übertragungsgeschwindigkeiten helfen dabei, Netzwerküberlastung zwischen Knoten zu identifizieren.

Fehlerbehebung: Häufige Fehler

Fehlermeldung	Wahrscheinlichste Ursache	Lösung
Plugin 'file-transfer' not found	OpenClaw-Version unter 2026.5.3	npx openclaw@latest update ausführen und Version prüfen
Path not within allowed paths	Anfragepfad außerhalb der konfigurierten allowedPaths	Pfad-Root zu allowedPaths des betreffenden Knotens hinzufügen
Write not permitted on read-only node	Knoten mit readOnly: true und Agent ruft file_write auf	Auf readOnly: false ändern, wenn Schreibzugriff benötigt wird
File exceeds maxFileSizeBytes limit	Dateigröße überschreitet konfiguriertes Limit (Standard 500 MB)	maxFileSizeBytes in Plugin-Konfiguration erhöhen oder Datei aufteilen
Symlink traversal detected	Pfad enthält symbolischen Link oder wird über einen solchen aufgelöst	Echten (nicht symbolischen) Pfad verwenden; symbolische Link-Traversierung ist niemals erlaubt
Node 'xxx' not configured in file-transfer plugin	Knoten-ID nicht im nodes-Konfigurationsobjekt des Plugins vorhanden	Knoten zum nodes-Abschnitt der Plugin-Konfiguration hinzufügen
Große Datei (> 1 GB) Übertragung hängt	Gateway-Timeout vor Abschluss des Streamings	gateway.streamTimeoutMs in openclaw.config.js erhöhen (Standard 300000ms)

Warum Mac mini M4-Knoten Dateiübertragung-Workflows praktikabel machen

Der Wert des OpenClaw Dateiübertragung-Plugins wird verstärkt, wenn es auf VpsGonas Mac mini M4-Knoten ausgeführt wird. Der praktische Grund: Der lokale Speicher des M4 ist schnelle NVMe-SSD, und zwischen den Knoten gibt es Hochbandbreiten-Uplinks. Das Lesen von einem lokalen NVMe und Schreiben auf ein entferntes NVMe bedeutet, dass der Engpass bei Cross-Node-Dateiübertragungen fast immer die Netzwerkbandbreite ist, nicht die Festplatten-I/O – anders als bei rotierenden Festplatten oder netzwerkgebundenem Speicher.

Das knotenspezifische Pfadrichtlinienmodell passt auch gut zu VpsGonas Multi-Knoten-Architektur: Der HK-Build-Knoten, der SG-Archivierungsknoten und der US East QA-Verteilungsknoten haben jeweils unterschiedliche Rollen in der Pipeline, und jeder sollte nur auf Verzeichnisse zugreifen können, die für seine Rolle relevant sind.

Für Teams, die OpenClaw bereits für Multi-Agent-Orchestrierung oder Datenpipeline-Automatisierung verwenden, schließt das Dateiübertragung-Plugin die letzte Lücke in vollständig Agent-gesteuerten Mac mini M4-Workflows: Binärartefakte zwischen Knoten verschieben, ohne die Agent-Sitzung zu verlassen. Aktuelle Knotenverfügbarkeit und Preise finden Sie auf der VpsGona-Preisseite, und für die anfängliche Knoteneinrichtung lesen Sie die Hilfedokumentation.