OpenClaw ファイル転送プラグインガイド 2026：file_fetch・dir_fetch・Mac mini M4クロスノードセキュアワークフロー完全解説

2026年5月初旬にリリースされたOpenClaw v2026.5.3には、AI Agentがペアリングされたノード間でバイナリファイル操作を直接実行できる新しいファイル転送プラグインが同梱されています。手動のSCPコマンドや共有ネットワークドライブは不要になります。このプラグインは4つのAgentツールを導入しています：file_fetch、dir_list、dir_fetch、file_write。いずれもノード単位のパスポリシーとシンボリックリンク走査保護を備えています。本ガイドでは初期設定から4つの本番ワークフローパターン、よくあるエラーのトラブルシューティングまで詳しく解説します。

OpenClawファイル転送プラグインとは？

v2026.5.3以前は、ペアリングされたOpenClawノード間でファイルを移動するには、Agentセッション外で手動SSHコマンドを実行するか、各チームが独自のカスタムMCPサーバー統合を構築・維持する必要がありました。ファイル転送プラグインはOpenClaw Agentにペアリングノードとのファイル読み書きのネイティブツールを提供することでこの問題を解決します。権限モデルと監査ログは他のOpenClawツール呼び出しと完全に一致しています。

このプラグインはv2026.5.3からメインパッケージに同梱されており、個別のnpmインストールは不要です。ただし設定で明示的に有効化する必要があります。これにより、チームはどのAgentがどのノードでファイルシステム書き込みアクセスを持つかを制御できます。

アーキテクチャの仕組み

ファイル転送プラグインはOpenClawのゲートウェイ層を通じて動作します。AgentがFile_fetchを呼び出すと、ゲートウェイがリクエストをターゲットノードのプラグインレシーバーにルーティングし、レシーバーがノードの設定済みパスポリシーに対してリクエストパスを検証し、ファイルを読み込んでバイナリコンテンツをゲートウェイ経由でAgentコンテキストにストリームで返します。

このアーキテクチャの3つの実際的な影響：

• ファイル転送操作はOpenClawのOTELテレメトリーに、要求パス・転送バイト数・レイテンシー・成功/失敗を含め、他のツール呼び出しと同等の詳細度で記録されます。
• パスポリシーはクライアント側ではなくゲートウェイ層で強制されるため、プロンプトインジェクションやAgentの幻覚による迂回が不可能です。
• バイナリファイル（コンパイル済みアーティファクト、IPAパッケージ、モデルウェイト、画像）もそのまま転送されます。テキストファイルだけに限定されません。

インストールと設定

ファイル転送プラグインにはOpenClaw v2026.5.3以降が必要です。古いバージョンを使用している場合はまず更新してください：

npx openclaw@latest update

またはアクティブなAgentセッション内で：

/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 MB }, '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はペアリングノードの指定パスから単一ファイルを取得し、その内容をAgentが利用できるようにします。テキストファイルの場合はデコードしてAgentコンテキストに配置します。バイナリファイルの場合はAgentが生バイトを受け取り、その後file_writeで別の場所に書き込めます。

基本的な使い方

Agentプロンプトで自然言語でファイル取得を指示するだけです：

hk-node-1の/Users/runner/builds/myapp/build.logからビルドログを取得して、最後の100行を要約してください。

Agentはこれをfile_fetchツール呼び出しに変換し、ノード、パス、エンコーディングを指定します。コンパイル済みIPAパッケージなどのバイナリファイルの場合、Agentはsg-node-1のfile_fetchとhk-node-1のfile_writeを連鎖させ、バイナリ転送を透過的に処理します。

ファイルサイズ制限とストリーミング

10MB未満のファイルは転送中にメモリにバッファリングされます。10MBからmaxFileSizeBytesまでのファイルはストリーミングされます。maxFileSizeBytesを超えるファイルはサイズ制限エラーで拒否されます。100MBを超えるIPAや大型モデルウェイトにはmaxFileSizeBytesを適切に設定してください。

dir_list と dir_fetch：リモートディレクトリの閲覧とミラーリング

dir_listはペアリングノード上のディレクトリの内容を返します——ファイル名、サイズ、更新タイムスタンプ、ファイルタイプ（ファイル/ディレクトリ/シンボリックリンク）。設計上シンボリックリンクは追跡しません（シンボリックリンク走査は設定によらず常にブロックされます）。

dir_fetchはディレクトリツリー全体を再帰的に取得し、ファイル内容を含む構造化されたマニフェストとして返します。ノード間でビルド出力ディレクトリをミラーリングするような用途に最も強力なツールです。

dir_list：リモートビルド出力の確認

例：アーティファクトを取得する前にCIノードでビルドが完了したかAgentが確認する場合：

hk-node-1の/Users/runner/builds/output/ディレクトリの内容を更新時刻順に一覧表示し、過去10分以内に作成されたファイルを教えてください。

AgentはソートとフィルタリングパラメーターでDir_listを呼び出します。これにより「アーティファクトが存在する場合は取得し、なければ待ってリトライする」といった条件付きの判断が可能になり、開発者が明示的なポーリングロジックを記述する必要がなくなります。

dir_fetch：ビルドアーティファクトのミラーリング

ビルド出力ディレクトリ全体をCIノードからアーカイブノードに同期する場合：

sg-node-1の/Users/runner/builds/v2.3.1/ディレクトリをhk-node-1の/Users/archive/releases/v2.3.1/にミラーリングしてください。宛先に同じサイズのファイルが既に存在する場合はスキップしてください。

Agentはsg-node-1のdir_fetchとhk-node-1への一連のfile_writeを連鎖させ、サイズ比較で未変更のファイルをスキップします。

file_write：リモートノードへのセキュアなファイル書き込み

file_writeはペアリングノードの指定パスにコンテンツを書き込みます。テキストとバイナリコンテンツの両方に対応し、アトミック書き込みセマンティクスを備えています——ターゲットノードの一時パスに書き込んでから最終目的地にアトミックに移動するため、転送中断時の部分書き込み状態を防止します。

設定ファイルの配布

よくあるユースケース：複数のノードに設定ファイルを同時配布する（各ノードに個別SSHログインする必要なし）：

以下のnginx.confの内容をhk-node-1、jp-node-1、kr-node-1の/etc/nginx/nginx.confに同時に書き込んでください：[内容]

OpenClawのマルチツール呼び出しが3つのfile_write操作を並行してディスパッチし、3回のSSHセッションではなく1回の書き込み時間で配布が完了します。

ビルドアーティファクトのデプロイ

Agentはビルドステップとfile_writeデプロイを1つのワークフローで連鎖させることができます：MyAppをアーカイブして配布証明書で署名し、生成されたIPAをsg-node-1の指定パスに書き込みます。

パスポリシーとセキュリティ：シンボリックリンク走査防止

ファイル転送プラグインの最も重要なセキュリティ機能は、無条件のシンボリックリンク走査保護です。パスポリシーの設定によらず、プラグインはファイルパスを解決する際にシンボリックリンクを追跡しません。/allowed/path/../../etc/passwdにアクセスしようとするAgentやプロンプトが受け取るのはファイルの内容ではなくパス解決エラーです。

セキュリティ機能	動作	設定可能？
シンボリックリンク走査ブロック	パス内のすべてのシンボリックリンクが解決時に拒否される	いいえ——常に強制
パスホワイトリスト執行	allowedPaths外のパスはパーミッションエラーを返す	はい——allowedPathsで設定
読み取り専用ノード執行	file_writeがブロックされ、取得操作は許可される	はい——readOnlyフラグで設定
ファイルサイズ制限	maxFileSizeBytesを超えるファイルは転送前に拒否	はい——デフォルト500MB
操作監査ログ	すべてのファイル操作がOTELテレメトリーに記録	いいえ——常に記録
アトミック書き込み	一時ファイル＋アトミックリネームを使用、中断時に部分書き込みなし	いいえ——常にアトミック

ベストプラクティス：最小パスホワイトリスト

各ノードの役割に応じてallowedPathsをできる限り狭く定義してください。CIビルドノードはビルド出力ディレクトリへのアクセスだけが必要であり、ホームディレクトリ全体へのアクセスは不要です。アーカイブノードはアーティファクトストアへの読み書きアクセスが必要かもしれませんが、それ以外はすべて読み取り専用にすべきです。

4つの実践的なワークフロー（Mac mini M4での実例）

ワークフロー1：クロスノードビルドアーティファクト同期

シナリオ：香港ノードでiOSビルドを実行（ビルドが高速）しているが、QAチームはシンガポールノードに近い。各ビルド後に署名済みIPAをSGノードに自動コピーしてQAに配布したい。

Agentプロンプト：

hk-node-1でXcodeアーカイブが完了したら、/Users/runner/builds/output/の最新の.ipaファイルを確認し、取得して、sg-node-1の/Users/qa-distribution/latest/に書き込んでください。ファイル名とサイズを報告してください。

Agentはビルドを実行し、dir_listで最新IPAを検索し、file_fetchで取得し、file_writeでSGノードにプッシュし、ファイル名とバイト数を報告します——手動SCPなしで一気通貫のワークフローです。

ワークフロー2：マルチノードログ集計

シナリオ：香港、日本、韓国、シンガポール、米国東部の5ノードで並行してテストスイートを実行。各ノードに手動でSSHすることなく、すべてのテスト結果JSONファイルを単一の分析コンテキストに集計したい。

AgentはAgentは5つの並行file_fetch呼び出しを発行し、5つのJSONペイロードを受け取り、それらを集計して各ノードの合否数と最も遅いテストを示すテーブルを生成します。手動では10〜15分かかる作業が自動化により約90秒で完了します。

ワークフロー3：ローリング設定配布

シナリオ：OpenClaw Agentのシステムプロンプトを更新し、各ノードが新しい設定を受け入れることを確認してから次のノードに進む形でロールアウトしたい。書き込み→検証→続行という順次条件ロジックはAgentがネイティブに処理し、外部オーケストレーションスクリプトは不要です。

ワークフロー4：MLモデルウェイトの配布

シナリオ：開発ノードでローカルLLMをファインチューニングし、OpenClaw + Ollamaを実行している3つの推論ノードにモデルウェイトを配布したい。Ollama + OpenClawガイドも参照してください。プラグインのストリーミングモードは大型バイナリファイルを効率的に処理します。Agentが報告する転送速度はノード間のネットワーク輻輳の有無を特定するのに役立ちます。

トラブルシューティング：よくあるエラー

エラーメッセージ	最も考えられる原因	対処法
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が設定されAgentがfile_writeを呼び出した	書き込みアクセスが必要ならreadOnly: falseに変更
File exceeds maxFileSizeBytes limit	ファイルサイズが設定制限（デフォルト500MB）を超過	プラグイン設定のmaxFileSizeBytesを増加するか、ファイルを分割
Symlink traversal detected	パスがシンボリックリンクを含むか、シンボリックリンク経由で解決される	実際の（シンボリックリンクでない）パスを使用；シンボリックリンク追跡は常に不可
Node 'xxx' not configured in file-transfer plugin	ノードIDがプラグインのnodes設定オブジェクトに存在しない	プラグイン設定のnodesセクションにノードを追加
大型ファイル（> 1GB）の転送がハングする	ストリーミング完了前にゲートウェイがタイムアウト	openclaw.config.jsのgateway.streamTimeoutMsを増加（デフォルト300000ms）

Mac mini M4ノードがファイル転送ワークフローを実用的にする理由

OpenClawファイル転送プラグインの価値は、VpsGonaのMac mini M4ノードで実行することで倍増します。実際的な理由は：M4のローカルストレージは高速NVMe SSDであり、ノード間には高帯域幅のアップリンクがあります。ローカルNVMeからの読み取りとリモートNVMeへの書き込みは、旋転ディスクやネットワーク接続ストレージとは異なり、クロスノードファイル転送のボトルネックはほぼ常にディスクI/Oではなくネットワーク帯域幅になります。

ノード単位のパスポリシーモデルはVpsGonaのマルチノードアーキテクチャにも適しています：HKビルドノード、SGアーカイブノード、US East QA配布ノードはそれぞれパイプライン内で異なる役割を持ち、それぞれの役割に関連するディレクトリのみにアクセスできるべきです。

すでにOpenClawをマルチAgentオーケストレーションやデータパイプライン自動化に使用しているチームにとって、ファイル転送プラグインは完全なAgent駆動Mac mini M4ワークフローの最後のギャップを埋めます：Agentセッションを離れることなくノード間でバイナリアーティファクトを移動できます。現在のノードの可用性と料金はVpsGona料金ページで確認し、初期ノードのセットアップはヘルプドキュメントを参照してください。