OpenClaw 檔案傳輸外掛程式指南 2026：file_fetch、dir_fetch 與 Mac mini M4 跨節點安全工作流完全攻略

OpenClaw v2026.5.3 於 2026 年 5 月初發布，捆綁了一個全新的檔案傳輸外掛程式，讓 AI Agent 可以直接在配對的 Mac mini M4 節點之間執行二進位檔案操作，無需手動 SCP 指令或共享網路儲存。外掛程式引入四個 Agent 工具：file_fetch、dir_list、dir_fetch 和 file_write，每個工具都支援節點級路徑策略和符號連結穿越保護。本文從安裝配置到四個生產工作流模式，再到最常見錯誤排查，一一詳細說明。

OpenClaw 檔案傳輸外掛程式是什麼？

在 v2026.5.3 之前，在配對的 OpenClaw 節點之間移動檔案，要麼需要在 Agent 會話之外手動執行 SSH 指令，要麼需要每個團隊自行建置和維護自訂 MCP 伺服器整合。檔案傳輸外掛程式透過給 OpenClaw Agent 提供原生工具解決了這個問題——讀取來自配對節點的檔案，以及向配對節點寫入檔案，權限模型和稽核日誌與其他任何 OpenClaw 工具呼叫完全一致。

該外掛程式從 v2026.5.3 起隨主套件捆綁，無需單獨 npm 安裝，但需要在配置中顯式啟用——這讓團隊可以控制哪些 Agent 在哪些節點上具有檔案系統寫入權限。

底層運作原理

檔案傳輸外掛程式透過 OpenClaw 的閘道層運作。當 Agent 呼叫 file_fetch 時，閘道將請求路由到目標節點的外掛程式接收器，接收器根據節點配置的路徑策略驗證請求路徑，讀取檔案後透過閘道將二進位內容串流傳回 Agent 上下文。Agent 與目標節點檔案系統之間沒有直接網路連接——所有檔案操作都經過閘道的權限和稽核層。

這一架構有三個實際影響：

• 檔案傳輸操作記錄在 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 }, '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 提示中，用自然語言告訴 OpenClaw 要取得哪個檔案：

從 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 鏈式呼叫，透明地處理二進位傳輸。

檔案大小限制與串流傳輸

10 MB 以下檔案在傳輸期間緩衝在記憶體中。10 MB 到 maxFileSizeBytes 之間的檔案以串流傳輸——Agent 收到串流控制代碼而非完整記憶體緩衝。超過 maxFileSizeBytes 的檔案以大小限制錯誤拒絕。對於大型建置產物（超過 100 MB 的 IPA、模型權重檔案），相應調整外掛程式配置中的 maxFileSizeBytes，同時注意超大傳輸會增加閘道會話延遲。

dir_list 與 dir_fetch：瀏覽和映象遠端目錄

dir_list 回傳配對節點上某個目錄的內容——檔案名稱、大小、修改時間戳記和檔案類型（檔案/目錄/符號連結）。設計上不追蹤符號連結（無論配置如何，符號連結穿越始終被阻止）。

dir_fetch 遞迴取得完整的目錄樹，並以包含檔案內容的結構化清單形式回傳。這是外掛程式中功能最強大的工具，適用於在節點之間映象建置輸出目錄等用途。

dir_list：檢查遠端建置輸出

範例：Agent 在取得產物前檢查 CI 節點上的建置是否已完成，並可依修改時間排序過濾最近 10 分鐘建立的檔案。這讓 Agent 可以做條件判斷——「如果產物存在就取得，如果不存在就等待重試」——開發者無需撰寫顯式的輪詢邏輯。

dir_fetch：映象建置產物目錄

將完整建置輸出目錄從 CI 節點同步到封存節點時，Agent 鏈式呼叫 sg-node-1 的 dir_fetch 與一系列 hk-node-1 的 file_write，用大小比對跳過未更改檔案。對於大多數檔案在執行之間沒有變化的目錄，這比樸素的 rsync 等效方案效率更高。

file_write：安全地向遠端節點推送檔案

file_write 向配對節點上的指定路徑寫入內容，支援文字和二進位內容，具備原子寫入語義——檔案先寫入目標節點的暫存路徑，再原子地移動到最終目的地，防止傳輸中斷時出現部分寫入狀態。

配置檔案分發

常見用途：同時向多個節點分發配置檔案，無需逐一 SSH 登入。OpenClaw 的多工具呼叫並行分發操作，完成時間僅相當於單次寫入，而不是多次串行 SSH 會話。

建置產物部署

Agent 可以在單個工作流程中將建置步驟與 file_write 部署串聯起來：封存 MyApp，用發行憑證簽署，然後將生成的 IPA 寫入指定節點的目標路徑。

路徑安全策略：防止符號連結穿越攻擊

檔案傳輸外掛程式最重要的安全特性是無條件的符號連結穿越保護。無論路徑策略如何配置，外掛程式在解析檔案路徑時絕不追蹤符號連結。嘗試存取 /allowed/path/../../etc/passwd 的 Agent 或提示收到的是路徑解析錯誤，而不是檔案內容。

安全特性	行為	可配置？
符號連結穿越阻斷	路徑中所有符號連結在解析時被拒絕	否——始終強制執行
路徑白名單執行	allowedPaths 之外的路徑回傳權限錯誤	是——透過 allowedPaths 配置
唯讀節點執行	file_write 被阻止；取得操作仍允許	是——透過 readOnly 旗標
檔案大小限制	超過 maxFileSizeBytes 的檔案在傳輸前被拒絕	是——預設 500 MB
操作稽核日誌	所有檔案操作記錄在 OTEL 遙測中，含路徑、大小、延遲、結果	否——始終記錄
原子寫入	寫入使用暫存檔案 + 原子重新命名；中斷時無部分寫入	否——始終原子

最佳實踐：最小化路徑白名單

根據每個節點的角色，將 allowedPaths 定義得盡量窄。CI 建置節點只需要存取其建置輸出目錄，而不是整個主目錄。封存節點可能需要對其產物儲存進行讀寫存取，但對其他一切內容應該是唯讀的。三節點流水線的最小配置範例與簡體中文版本相同，HK CI 設為唯讀，SG 封存和 JP 演示節點設為讀寫。

4 個在 Mac mini M4 上使用檔案傳輸外掛程式的真實工作流

工作流 1：跨節點建置產物同步

場景：您在香港節點上執行 iOS 建置（建置速度快），但 QA 團隊距離新加坡節點更近。每次建置後，自動將簽署的 IPA 複製到 SG 節點供 QA 分發。Agent 執行：建置 → 用 dir_list 找到最新 IPA → 用 file_fetch 取得 → 用 file_write 推送到 SG 節點 → 回報檔案名稱和位元組數。整個流程在無需手動 SCP 的情況下一氣呵成。

工作流 2：多節點日誌聚合分析

場景：您在香港、日本、韓國、新加坡和美國東部五個節點上並行執行測試套件。Agent 並行發出五個 file_fetch 呼叫，收到五個 JSON 負載，解析並產生彙整表——包含每個節點的通過/失敗數量和最慢測試案例。手動需要 10–15 分鐘的操作，自動化後約 90 秒完成。

工作流 3：滾動配置部署

場景：您更新了 OpenClaw Agent 系統提示，想要逐節點推送新配置，確認每個節點接受新配置後再進入下一個。這種順序條件邏輯——寫入、驗證、繼續——完全由 Agent 原生處理，無需外部編排腳本。

工作流 4：ML 模型權重分發

場景：您在開發節點上微調了本地 LLM，想把模型權重分發到三個執行 OpenClaw + Ollama 的推理節點。Ollama + OpenClaw 本地推理設定請參考Ollama 本地 LLM 指南。外掛程式的串流模式高效處理大型二進位檔案，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	檔案大小超過配置限制（預設 500 MB）	增大外掛程式配置中的 maxFileSizeBytes，或分割檔案
Symlink traversal detected	路徑包含或經過符號連結	使用實際（非符號連結）路徑；符號連結追蹤永遠不被允許
Node 'xxx' not configured in file-transfer plugin	節點 ID 不在外掛程式的 nodes 配置物件中	在外掛程式配置的 nodes 部分新增該節點
大檔案傳輸（> 1 GB）掛起	串流傳輸完成前閘道逾時	增大 openclaw.config.js 中的 gateway.streamTimeoutMs（預設 300000 ms）

為什麼 Mac mini M4 節點讓檔案傳輸工作流更實用

OpenClaw 檔案傳輸外掛程式的價值在執行於 VpsGona Mac mini M4 節點上時成倍放大，原因很實際：M4 本地儲存是高速 NVMe SSD，節點之間有高頻寬上行鏈路。本地 NVMe 讀取和遠端 NVMe 寫入——而非旋轉磁碟或網路附加儲存——意味著跨節點檔案傳輸的瓶頸幾乎總是網路頻寬而非磁碟 I/O。對於上面描述的多節點工作流，這意味著產物同步和日誌聚合操作在數秒內完成，而不是數分鐘。

節點級路徑策略模型也非常適合 VpsGona 的多節點架構：您的 HK 建置節點、SG 封存節點和 US East QA 分發節點各自在流水線中扮演不同角色，應該只能存取與其職責相關的目錄。外掛程式的節點級配置自然地映射到 VpsGona 的節點角色分離部署模式。

對於已經在使用 OpenClaw 進行多 Agent 編排或資料流水線自動化的團隊，檔案傳輸外掛程式填補了全 Agent 驅動 Mac mini M4 工作流的最後空缺：在節點之間移動二進位產物，無需退出 Agent 會話。當前節點可用性及開始建置多節點 OpenClaw 流水線，請造訪 VpsGona 定價頁，初始節點配置參考部署文件。