Руководство по плагину передачи файлов OpenClaw 2026: file_fetch, dir_fetch и безопасные кросс-узловые рабочие процессы на Mac mini M4

Вышедший в начале мая 2026 года OpenClaw v2026.5.3 включает новый плагин передачи файлов, который позволяет ИИ-агентам напрямую выполнять операции с бинарными файлами между сопряжёнными узлами — без ручных команд SCP или общих сетевых дисков. Плагин вводит четыре инструмента агента: file_fetch, dir_list, dir_fetch и file_write. Все они оснащены политиками путей для каждого узла и защитой от обхода символических ссылок. В этом руководстве рассматриваются начальная настройка, четыре производственных шаблона рабочих процессов и устранение распространённых ошибок.

Что такое плагин передачи файлов OpenClaw?

До v2026.5.3 перемещение файлов между сопряжёнными узлами OpenClaw требовало выполнения ручных команд SSH вне сессии агента или создания каждой командой собственных интеграций MCP-сервера. Плагин передачи файлов решает эту проблему, предоставляя агенту OpenClaw нативные инструменты для чтения и записи файлов с сопряжёнными узлами. Модель разрешений и журналы аудита полностью соответствуют другим вызовам инструментов OpenClaw.

Плагин включён в основной пакет начиная с v2026.5.3 — отдельная установка npm не требуется. Однако его необходимо явно активировать в конфигурации, что позволяет командам контролировать, какие агенты имеют доступ к записи файловой системы каких узлов.

Установка и настройка

Плагин передачи файлов требует OpenClaw v2026.5.3 или выше. Если используется более ранняя версия, сначала обновитесь:

npx openclaw@latest update

Или из активной сессии агента:

/update

После обновления убедитесь, что плагин доступен:

openclaw plugin list | grep file-transfer

Должно отобразиться: file-transfer bundled v1.0.0. Если ничего не возвращается, обновление не завершено. Проверьте с помощью openclaw --version, что версия 2026.5.3 или выше.

Активация в openclaw.config.js

Плагин входит в комплект, но по умолчанию отключён. Добавьте его в файл конфигурации:

// 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 МБ }, 'sg-node-1': { allowedPaths: ['/Users/runner/artifacts'], readOnly: true // Только чтение, запись запрещена } } } } };

Массив allowedPaths определяет корневые пути каталогов, к которым плагин может получить доступ на этом узле. Пути вне белого списка возвращают ошибку разрешений и операция не выполняется. readOnly: true разрешает file_fetch, dir_list и dir_fetch, запрещая при этом file_write на этот узел.

После изменения конфигурации перезапустите OpenClaw для применения изменений:

openclaw restart

Убедитесь, что плагин активен:

/plugin status file-transfer

file_fetch: Получение файлов с сопряжённых узлов

file_fetch получает один файл с указанного пути сопряжённого узла и делает его содержимое доступным для агента. Для текстовых файлов декодирует содержимое и помещает его в контекст агента. Для бинарных файлов агент получает необработанные байты и может затем записать их в другое место с помощью file_write.

Базовое использование

Просто укажите агенту получить файл на естественном языке:

Получи лог сборки с /Users/runner/builds/myapp/build.log на hk-node-1 и суммируй последние 100 строк.

Агент переводит это в вызов инструмента file_fetch с указанием узла, пути и кодировки. Для бинарных файлов, таких как скомпилированный IPA-пакет, агент объединяет file_fetch на sg-node-1 с file_write на hk-node-1, прозрачно обрабатывая бинарную передачу.

Ограничения размера файлов и потоковая передача

Файлы размером менее 10 МБ буферизуются в памяти во время передачи. Файлы от 10 МБ до maxFileSizeBytes передаются потоком. Файлы, превышающие maxFileSizeBytes, отклоняются с ошибкой ограничения размера. Для IPA-файлов более 100 МБ или больших весов моделей настройте maxFileSizeBytes соответственно.

dir_list и dir_fetch: Просмотр и зеркалирование удалённых каталогов

dir_list возвращает содержимое каталога на сопряжённом узле — имена файлов, размеры, временны́е метки изменения, типы файлов (файл/каталог/символическая ссылка). По замыслу не следует символическим ссылкам (обход символических ссылок всегда блокируется независимо от конфигурации).

dir_fetch рекурсивно получает всё дерево каталогов и возвращает его в виде структурированного манифеста с содержимым файлов. Это наиболее мощный инструмент для зеркалирования каталогов вывода сборки между узлами.

dir_list: Проверка удалённого вывода сборки

Пример, где агент проверяет завершение сборки на CI-узле перед получением артефактов:

Перечисли содержимое каталога /Users/runner/builds/output/ на hk-node-1, отсортированное по времени изменения, и скажи, какие файлы были созданы за последние 10 минут.

Агент вызывает dir_list с параметрами сортировки и фильтрации. Это позволяет принимать условные решения типа «получить артефакт, если существует, иначе ждать и повторить» без написания явной логики опроса.

dir_fetch: Зеркалирование артефактов сборки

Синхронизация всего каталога вывода сборки с CI-узла на узел архивирования:

Зеркалируй каталог /Users/runner/builds/v2.3.1/ с sg-node-1 в /Users/archive/releases/v2.3.1/ на hk-node-1. Пропускай файлы, которые уже существуют в назначении с тем же размером.

Агент объединяет dir_fetch с sg-node-1 с серией file_write на hk-node-1, пропуская неизменённые файлы по сравнению размеров.

file_write: Безопасная запись файлов на удалённые узлы

file_write записывает содержимое по указанному пути сопряжённого узла. Поддерживает как текстовое, так и бинарное содержимое и обладает атомарной семантикой записи — записывает во временный путь на целевом узле, затем атомарно перемещает в финальное место назначения, предотвращая частичные состояния записи при прерывании передачи.

Распространение файлов конфигурации

Распространённый сценарий использования: одновременное распространение файла конфигурации на несколько узлов (без отдельного SSH-подключения к каждому узлу):

Запиши следующее содержимое nginx.conf в /etc/nginx/nginx.conf на hk-node-1, jp-node-1 и kr-node-1 одновременно: [содержимое]

Мульти-инструментные вызовы OpenClaw диспетчеризуют три операции file_write параллельно, завершая распространение за одну длительность записи вместо трёх последовательных SSH-сессий.

Политики путей и безопасность: защита от обхода символических ссылок

Наиболее важная функция безопасности плагина передачи файлов — безусловная защита от обхода символических ссылок. Независимо от конфигурации политик путей плагин не следует символическим ссылкам при разрешении путей файлов. Агент или промпт, пытающийся получить доступ к /allowed/path/../../etc/passwd, получит ошибку разрешения пути, а не содержимое файла.

Функция безопасности	Поведение	Настраивается?
Блокировка обхода символических ссылок	Все символические ссылки в пути отклоняются при разрешении	Нет — всегда применяется
Применение белого списка путей	Пути вне allowedPaths возвращают ошибку разрешений	Да — через allowedPaths
Применение режима «только чтение»	file_write заблокирован, операции получения разрешены	Да — через флаг readOnly
Ограничение размера файла	Файлы, превышающие maxFileSizeBytes, отклоняются до передачи	Да — по умолчанию 500 МБ
Журнал аудита операций	Все файловые операции записываются в телеметрию OTEL	Нет — всегда записывается
Атомарная запись	Временный файл + атомарное переименование, без частичной записи при прерывании	Нет — всегда атомарная

4 практических рабочих процесса (реальные примеры на Mac mini M4)

Рабочий процесс 1: Кросс-узловая синхронизация артефактов сборки

Сценарий: iOS-сборки выполняются на гонконгском узле (быстрые сборки), но QA-команда ближе к сингапурскому узлу. После каждой сборки нужно автоматически копировать подписанный IPA на узел SG для QA-распространения.

Промпт агента:

После завершения архива Xcode на hk-node-1, найди последний .ipa-файл в /Users/runner/builds/output/, получи его и запиши в /Users/qa-distribution/latest/ на sg-node-1. Сообщи имя файла и размер.

Агент выполняет сборку, ищет последний IPA с помощью dir_list, получает его через file_fetch, отправляет на узел SG через file_write и сообщает имя файла и количество байт — сквозной рабочий процесс без ручного SCP.

Рабочий процесс 2: Агрегация логов с нескольких узлов

Сценарий: Наборы тестов выполняются параллельно на всех 5 узлах. Нужно агрегировать все JSON-файлы с результатами тестов в единый контекст анализа без ручного SSH-подключения к каждому узлу.

Агент выдаёт 5 параллельных вызовов file_fetch, получает 5 JSON-нагрузок, агрегирует их и генерирует таблицу с количеством успешных/неудачных тестов и самым медленным тестом для каждого узла. Задача, которая вручную занимала бы 10–15 минут, завершается за ~90 секунд.

Рабочий процесс 3: Последовательное распространение конфигурации

Сценарий: Обновление системных промптов агента OpenClaw с постепенным развёртыванием, обеспечивающим, что каждый узел принимает новую конфигурацию перед переходом к следующему. Последовательная условная логика запись→проверка→продолжить нативно обрабатывается агентом без внешних скриптов оркестрации.

Рабочий процесс 4: Распространение весов ML-модели

Сценарий: Локальная LLM дообучена на узле разработки, и веса модели нужно распространить на 3 узла вывода, работающих с OpenClaw + Ollama. Режим потоковой передачи плагина эффективно обрабатывает большие бинарные файлы. Скорости передачи, сообщаемые агентом, помогают выявить перегрузку сети между узлами.

Устранение неполадок: Распространённые ошибки

Сообщение об ошибке	Наиболее вероятная причина	Решение
Plugin 'file-transfer' not found	Версия OpenClaw ниже 2026.5.3	Выполнить npx openclaw@latest update и проверить версию
Path not within allowed paths	Запрашиваемый путь вне настроенных allowedPaths	Добавить корень пути в allowedPaths соответствующего узла
Write not permitted on read-only node	Узел с readOnly: true и агент вызывает file_write	Изменить на readOnly: false если нужен доступ к записи
File exceeds maxFileSizeBytes limit	Размер файла превышает настроенный лимит (по умолчанию 500 МБ)	Увеличить maxFileSizeBytes в конфигурации плагина или разделить файл
Symlink traversal detected	Путь содержит символическую ссылку или разрешается через неё	Использовать реальный (не символический) путь; обход символических ссылок всегда запрещён
Node 'xxx' not configured in file-transfer plugin	ID узла отсутствует в объекте конфигурации nodes плагина	Добавить узел в раздел nodes конфигурации плагина
Передача большого файла (> 1 ГБ) зависает	Таймаут шлюза до завершения потоковой передачи	Увеличить gateway.streamTimeoutMs в openclaw.config.js (по умолчанию 300000 мс)

Почему узлы Mac mini M4 делают рабочие процессы передачи файлов практичными

Ценность плагина передачи файлов OpenClaw многократно возрастает при работе на узлах Mac mini M4 VpsGona. Практическая причина: локальное хранилище M4 — это высокоскоростной NVMe-SSD, и между узлами есть высокоскоростные аплинки. Чтение с локального NVMe и запись на удалённый NVMe означают, что узкое место кросс-узловой передачи файлов — почти всегда пропускная способность сети, а не дисковый ввод-вывод, в отличие от вращающихся дисков или сетевого хранилища.

Модель политик путей для каждого узла также хорошо сочетается с многоузловой архитектурой VpsGona: узел сборки в Гонконге, узел архивирования в Сингапуре и узел QA-распространения на Восточном побережье США имеют разные роли в пайплайне, и каждый должен иметь доступ только к каталогам, относящимся к его роли.

Для команд, уже использующих OpenClaw для многоагентной оркестрации или автоматизации пайплайнов данных, плагин передачи файлов закрывает последний пробел в полностью агент-управляемых рабочих процессах Mac mini M4: перемещение бинарных артефактов между узлами без выхода из сессии агента. Текущую доступность узлов и цены смотрите на странице цен VpsGona, а для начальной настройки узла — в документации помощи.