Gateway
安全檔案操作
OpenClaw 使用 @openclaw/fs-safe 執行安全性敏感的本機檔案操作：限制於根目錄內的讀取／寫入、原子取代、封存檔解壓縮、暫存工作區、JSON 狀態，以及機密檔案處理。
它是供受信任的 OpenClaw 程式碼接收不受信任的路徑名稱時使用的函式庫防護機制，而非沙箱。主機檔案系統權限、作業系統使用者、容器，以及代理程式／工具原則，仍會界定實際的影響範圍。
預設：不使用 Python 輔助程式
OpenClaw 預設將 fs-safe 的 POSIX Python 輔助程式設為關閉：
- 除非操作人員選擇啟用，否則閘道不應啟動常駐的 Python 輔助程序；
- 大多數安裝環境不需要額外強化父目錄異動操作；
- 停用 Python 可讓桌面、Docker、CI 和封裝應用程式環境中的執行階段行為保持一致且可預測。
OpenClaw 只會變更_預設值_。明確設定一律優先：
# OpenClaw 預設行為：僅使用 Node 的 fs-safe 備援機制。OPENCLAW_FS_SAFE_PYTHON_MODE=off # 在輔助程式可用時選擇啟用；無法使用時則採用備援機制。OPENCLAW_FS_SAFE_PYTHON_MODE=auto # 如果輔助程式無法啟動，則以封閉方式失敗。OPENCLAW_FS_SAFE_PYTHON_MODE=require # 可選的明確直譯器路徑。OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3通用的 fs-safe 環境變數名稱也可使用：FS_SAFE_PYTHON_MODE 和 FS_SAFE_PYTHON。
如果輔助程式是安全防護策略的一部分，請使用 require（而非 auto）；若輔助程式無法啟動，auto 會無提示地退回僅使用 Node 的行為。
不使用 Python 時仍受保護的項目
關閉輔助程式後，OpenClaw 仍可獲得 fs-safe 僅使用 Node 的防護機制：
- 拒絕相對路徑逸出（
..）、絕對路徑，以及只允許純名稱時出現的路徑分隔符號； - 透過受信任的根目錄控制代碼解析操作，而非使用臨時拼湊的
path.resolve(...).startsWith(...)檢查； - 對要求此原則的 API 拒絕符號連結和硬連結模式；
- 在 API 傳回或使用檔案內容時，以身分一致性檢查開啟檔案；
- 透過同層暫存檔與重新命名的原子操作寫入狀態／設定檔；
- 對讀取和封存檔解壓縮強制套用位元組限制；
- 在 API 要求時，為機密資料和狀態檔案套用私密檔案模式。
這涵蓋 OpenClaw 的一般威脅模型：受信任的閘道程式碼在單一受信任操作人員邊界內，處理來自不受信任模型／外掛／頻道路徑的輸入。
Python 增加的保護
在 POSIX 上，可選的輔助程式會維持單一常駐 Python 程序，並使用相對於檔案描述元的檔案系統操作來執行父目錄異動：重新命名、移除、建立目錄、取得狀態／列出內容，以及部分寫入路徑。
這可縮小相同 UID 競爭條件的時間窗口，避免另一個程序在驗證與異動之間置換父目錄；在不受信任的本機程序可修改 OpenClaw 所操作之相同目錄的主機上，這是一層縱深防禦。
如果您的部署環境存在此風險，且保證有 Python 可用，請設定：
OPENCLAW_FS_SAFE_PYTHON_MODE=require外掛與核心指南
- 當路徑來自訊息、模型輸出、設定或外掛輸入時，供外掛使用的檔案存取應透過
openclaw/plugin-sdk/*輔助函式，而非直接使用fs。 - 核心程式碼應使用
src/infra/*下的 fs-safe 包裝函式，確保一致套用 OpenClaw 的程序原則。 - 封存檔解壓縮應使用 fs-safe 封存檔輔助函式，並明確設定大小、項目數量、連結和目的地限制。
- 機密資料應使用 OpenClaw 機密資料輔助函式，或 fs-safe 的機密資料／私密狀態輔助函式；請勿自行在
fs.writeFile周圍實作模式檢查。 - 若要隔離具有敵意的本機使用者，請勿僅依賴 fs-safe。請以不同的作業系統使用者／主機執行獨立閘道，或使用沙箱機制。
Was this useful?
