Guide du Plugin de Transfert de Fichiers OpenClaw 2026 : file_fetch, dir_fetch et Workflows Cross-nœud Sécurisés sur Mac mini M4

Sorti début mai 2026, OpenClaw v2026.5.3 intègre un nouveau plugin de transfert de fichiers qui permet aux Agents IA d'exécuter directement des opérations sur des fichiers binaires entre nœuds appariés, sans commandes SCP manuelles ni lecteurs réseau partagés. Ce plugin introduit quatre outils Agent : file_fetch, dir_list, dir_fetch et file_write, tous dotés de politiques de chemins par nœud et d'une protection contre la traversée de liens symboliques. Ce guide couvre la configuration initiale, quatre patterns de workflows en production et le dépannage des erreurs courantes.

Qu'est-ce que le plugin de transfert de fichiers OpenClaw ?

Avant v2026.5.3, déplacer des fichiers entre nœuds OpenClaw appariés nécessitait d'exécuter des commandes SSH manuelles en dehors de la session Agent, ou que chaque équipe construise et maintienne ses propres intégrations MCP serveur personnalisées. Le plugin de transfert de fichiers résout ce problème en donnant à l'Agent OpenClaw des outils natifs pour lire et écrire des fichiers avec les nœuds appariés. Le modèle de permissions et les logs d'audit s'alignent parfaitement avec les autres appels d'outils OpenClaw.

Le plugin est inclus dans le package principal à partir de v2026.5.3 — aucune installation npm séparée n'est requise. Il doit cependant être explicitement activé dans la configuration, ce qui permet aux équipes de contrôler quels Agents ont un accès en écriture au système de fichiers de quels nœuds.

Installation et configuration

Le plugin de transfert de fichiers nécessite OpenClaw v2026.5.3 ou supérieur. Si vous utilisez une version antérieure, mettez d'abord à jour :

npx openclaw@latest update

Ou depuis une session Agent active :

/update

Après la mise à jour, vérifiez que le plugin est disponible :

openclaw plugin list | grep file-transfer

Vous devriez voir : file-transfer bundled v1.0.0. Si rien n'apparaît, la mise à jour n'est pas complète. Vérifiez avec openclaw --version que vous avez bien 2026.5.3 ou supérieur.

Activation dans openclaw.config.js

Le plugin est inclus mais désactivé par défaut. Ajoutez-le à votre fichier de configuration :

// 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 Mo }, 'sg-node-1': { allowedPaths: ['/Users/runner/artifacts'], readOnly: true // Lecture seule, écriture interdite } } } } };

Le tableau allowedPaths définit les chemins racines des répertoires auxquels le plugin peut accéder sur ce nœud. Les chemins en dehors de la liste blanche retournent une erreur de permission et l'opération n'est pas exécutée. readOnly: true autorise file_fetch, dir_list et dir_fetch tout en empêchant file_write vers ce nœud.

Après modification de la configuration, redémarrez OpenClaw pour l'appliquer :

openclaw restart

Confirmez que le plugin est actif :

/plugin status file-transfer

file_fetch : Récupérer des fichiers depuis un nœud apparié

file_fetch récupère un fichier unique depuis le chemin spécifié d'un nœud apparié et rend son contenu disponible à l'Agent. Pour les fichiers texte, il les décode et les place dans le contexte de l'Agent. Pour les fichiers binaires, l'Agent reçoit les octets bruts et peut ensuite les écrire ailleurs avec file_write.

Utilisation de base

Demandez simplement à l'Agent de récupérer un fichier en langage naturel :

Récupère le log de build depuis /Users/runner/builds/myapp/build.log sur hk-node-1 et résume les 100 dernières lignes.

L'Agent traduit cela en appel d'outil file_fetch en spécifiant le nœud, le chemin et l'encodage. Pour les fichiers binaires comme un package IPA compilé, l'Agent chaîne un file_fetch sur sg-node-1 et un file_write sur hk-node-1, gérant le transfert binaire de manière transparente.

Limites de taille de fichier et streaming

Les fichiers inférieurs à 10 Mo sont mis en mémoire tampon pendant le transfert. Les fichiers entre 10 Mo et maxFileSizeBytes sont streamés. Les fichiers dépassant maxFileSizeBytes sont rejetés avec une erreur de limite de taille. Pour les IPA de plus de 100 Mo ou les grands poids de modèles, configurez maxFileSizeBytes en conséquence.

dir_list et dir_fetch : Explorer et refléter des répertoires distants

dir_list retourne le contenu d'un répertoire sur un nœud apparié — noms de fichiers, tailles, timestamps de modification, types de fichiers (fichier/répertoire/lien symbolique). Il ne suit pas les liens symboliques par conception (la traversée de liens symboliques est toujours bloquée quelle que soit la configuration).

dir_fetch récupère récursivement tout un arbre de répertoires et le retourne sous forme de manifeste structuré incluant le contenu des fichiers. C'est l'outil le plus puissant pour refléter des répertoires de sortie de build entre nœuds.

dir_list : Vérifier la sortie de build distante

Exemple où l'Agent vérifie si un build est terminé sur un nœud CI avant de récupérer des artefacts :

Liste le contenu du répertoire /Users/runner/builds/output/ sur hk-node-1, trié par heure de modification, et dis-moi quels fichiers ont été créés dans les 10 dernières minutes.

L'Agent appelle dir_list avec des paramètres de tri et de filtrage. Cela permet des décisions conditionnelles du type « récupérer l'artefact s'il existe, sinon attendre et réessayer » sans que le développeur ait à écrire une logique de polling explicite.

dir_fetch : Refléter des artefacts de build

Pour synchroniser un répertoire complet de sortie de build d'un nœud CI vers un nœud d'archivage :

Refléte le répertoire /Users/runner/builds/v2.3.1/ de sg-node-1 vers /Users/archive/releases/v2.3.1/ sur hk-node-1. Ignore les fichiers qui existent déjà à la destination avec la même taille.

L'Agent chaîne un dir_fetch de sg-node-1 avec une série de file_write vers hk-node-1, ignorant les fichiers inchangés par comparaison de taille.

file_write : Écriture sécurisée de fichiers vers des nœuds distants

file_write écrit du contenu dans le chemin spécifié d'un nœud apparié. Il supporte à la fois le contenu texte et binaire, et possède une sémantique d'écriture atomique — il écrit dans un chemin temporaire sur le nœud cible puis se déplace atomiquement vers la destination finale, empêchant les états d'écriture partielle en cas d'interruption du transfert.

Distribution de fichiers de configuration

Cas d'utilisation courant : distribuer un fichier de configuration vers plusieurs nœuds simultanément (sans connexion SSH séparée à chaque nœud) :

Écris le contenu nginx.conf suivant dans /etc/nginx/nginx.conf sur hk-node-1, jp-node-1 et kr-node-1 simultanément : [contenu]

Les appels multi-outils d'OpenClaw dispatche trois opérations file_write en parallèle, complétant la distribution en une seule durée d'écriture plutôt qu'en trois sessions SSH successives.

Politiques de chemins et sécurité : Protection contre la traversée de liens symboliques

La fonctionnalité de sécurité la plus importante du plugin de transfert de fichiers est sa protection inconditionnelle contre la traversée de liens symboliques. Quelle que soit la configuration des politiques de chemins, le plugin ne suit pas les liens symboliques lors de la résolution des chemins de fichiers. Un Agent ou un prompt tentant d'accéder à /allowed/path/../../etc/passwd recevra une erreur de résolution de chemin, pas le contenu du fichier.

Fonctionnalité de sécurité	Comportement	Configurable ?
Blocage traversée liens symboliques	Tout lien symbolique dans le chemin est refusé lors de la résolution	Non — toujours appliqué
Application liste blanche chemins	Les chemins hors allowedPaths retournent une erreur de permission	Oui — via allowedPaths
Application nœud lecture seule	file_write bloqué, opérations de récupération autorisées	Oui — via flag readOnly
Limite de taille de fichier	Fichiers dépassant maxFileSizeBytes rejetés avant transfert	Oui — défaut 500 Mo
Log d'audit des opérations	Toutes opérations fichiers enregistrées dans la télémétrie OTEL	Non — toujours enregistré
Écriture atomique	Fichier temporaire + renommage atomique, pas d'écriture partielle en cas d'interruption	Non — toujours atomique

Bonne pratique : Liste blanche de chemins minimale

Définissez allowedPaths aussi étroitement que possible selon le rôle de chaque nœud. Un nœud de build CI n'a besoin d'accéder qu'au répertoire de sortie de build, pas à l'intégralité du répertoire home. Un nœud d'archivage peut nécessiter un accès en lecture-écriture au store d'artefacts, mais tout le reste devrait être en lecture seule.

4 Workflows pratiques (exemples réels sur Mac mini M4)

Workflow 1 : Synchronisation d'artefacts de build cross-nœud

Scénario : Vous exécutez vos builds iOS sur le nœud Hong Kong (builds rapides) mais votre équipe QA est proche du nœud Singapour. Vous voulez copier automatiquement l'IPA signé vers le nœud SG après chaque build pour la distribution QA.

Prompt Agent :

Une fois l'archive Xcode terminée sur hk-node-1, trouve le fichier .ipa le plus récent dans /Users/runner/builds/output/, récupère-le et écris-le dans /Users/qa-distribution/latest/ sur sg-node-1. Rapporte le nom de fichier et la taille.

L'Agent exécute le build, cherche le dernier IPA avec dir_list, le récupère avec file_fetch, le pousse vers le nœud SG avec file_write et rapporte le nom de fichier et le nombre d'octets — workflow de bout en bout sans SCP manuel.

Workflow 2 : Agrégation de logs multi-nœuds

Scénario : Vous exécutez des suites de tests en parallèle sur les 5 nœuds Hong Kong, Japon, Corée, Singapour et Est des États-Unis. Vous voulez agréger tous les fichiers JSON de résultats de tests dans un seul contexte d'analyse sans SSH manuels vers chaque nœud.

L'Agent émet 5 appels file_fetch parallèles, reçoit les 5 payloads JSON, les agrège et génère un tableau montrant le nombre de réussites/échecs et le test le plus lent pour chaque nœud. Une tâche qui prendrait 10–15 minutes manuellement est accomplie en environ 90 secondes grâce à l'automatisation.

Workflow 3 : Distribution de configuration en rolling update

Scénario : Vous mettez à jour les system prompts de l'Agent OpenClaw et voulez déployer en vous assurant que chaque nœud accepte la nouvelle configuration avant de passer au suivant. La logique séquentielle conditionnelle écriture→validation→continuer est gérée nativement par l'Agent, sans script d'orchestration externe.

Workflow 4 : Distribution de poids de modèles ML

Scénario : Vous avez affiné un LLM local sur un nœud de développement et voulez distribuer les poids du modèle vers 3 nœuds d'inférence exécutant OpenClaw + Ollama. Le mode streaming du plugin gère efficacement les grands fichiers binaires. Les vitesses de transfert rapportées par l'Agent aident à identifier la congestion réseau entre nœuds.

Dépannage : Erreurs courantes

Message d'erreur	Cause la plus probable	Solution
Plugin 'file-transfer' not found	Version OpenClaw inférieure à 2026.5.3	Exécuter npx openclaw@latest update et vérifier la version
Path not within allowed paths	Chemin de requête hors des allowedPaths configurés	Ajouter la racine du chemin aux allowedPaths du nœud concerné
Write not permitted on read-only node	Nœud avec readOnly: true et l'Agent appelle file_write	Passer à readOnly: false si l'accès en écriture est requis
File exceeds maxFileSizeBytes limit	Taille de fichier dépassant la limite configurée (défaut 500 Mo)	Augmenter maxFileSizeBytes dans la config du plugin ou diviser le fichier
Symlink traversal detected	Chemin contenant un lien symbolique ou se résolvant via un lien	Utiliser le chemin réel (non symbolique); traversée de liens jamais permise
Node 'xxx' not configured in file-transfer plugin	ID de nœud absent de l'objet nodes de la config plugin	Ajouter le nœud à la section nodes de la config du plugin
Transfert de grand fichier (> 1 Go) suspendu	Timeout passerelle avant fin du streaming	Augmenter gateway.streamTimeoutMs dans openclaw.config.js (défaut 300000ms)

Pourquoi les nœuds Mac mini M4 rendent les workflows de transfert de fichiers pratiques

La valeur du plugin de transfert de fichiers OpenClaw est amplifiée lorsqu'il s'exécute sur les nœuds Mac mini M4 de VpsGona. La raison pratique : le stockage local du M4 est du SSD NVMe haute vitesse, et il y a des liaisons montantes à haute bande passante entre les nœuds. Lire depuis un NVMe local et écrire vers un NVMe distant signifie que le goulot d'étranglement des transferts de fichiers cross-nœuds est presque toujours la bande passante réseau plutôt que les E/S disque, contrairement aux disques rotatifs ou au stockage réseau.

Le modèle de politiques de chemins par nœud s'adapte également bien à l'architecture multi-nœuds de VpsGona : le nœud de build HK, le nœud d'archivage SG et le nœud de distribution QA US East ont chacun des rôles différents dans le pipeline, et chacun devrait accéder uniquement aux répertoires pertinents pour son rôle.

Pour les équipes utilisant déjà OpenClaw pour l'orchestration multi-Agent ou l'automatisation de pipelines de données, le plugin de transfert de fichiers comble le dernier manque dans les workflows Mac mini M4 entièrement pilotés par Agent : déplacer des artefacts binaires entre nœuds sans quitter la session Agent. Consultez les disponibilités actuelles des nœuds et les tarifs sur la page de tarification VpsGona, et la configuration initiale des nœuds dans la documentation d'aide.