跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 使用 @openclaw/fs-safe 處理安全敏感的本機檔案操作：受根目錄限制的讀取/寫入、原子替換、封存檔解壓縮、暫存工作區、JSON 狀態，以及祕密檔案處理。 目標是為接收不受信任路徑名稱的受信任 OpenClaw 程式碼，提供一致的函式庫防護欄。它不是沙箱。主機檔案系統權限、OS 使用者、容器，以及代理程式/工具政策，仍然定義真正的影響範圍。

​
預設：不使用 Python 輔助程式

OpenClaw 預設將 fs-safe POSIX Python 輔助程式設為關閉。 原因：
  • Gateway 不應啟動常駐 Python sidecar，除非操作員明確選擇啟用；
  • 許多安裝不需要額外的父目錄變更強化；
  • 停用 Python 可讓套件/執行階段行為在桌面、Docker、CI 和 bundled app 環境中更可預測。
OpenClaw 只會變更預設值。如果你明確設定模式，fs-safe 會遵循該設定： 
# Default OpenClaw behavior: Node-only fs-safe fallbacks.
OPENCLAW_FS_SAFE_PYTHON_MODE=off

# Opt into the helper when available, falling back if unavailable.
OPENCLAW_FS_SAFE_PYTHON_MODE=auto

# Fail closed if the helper cannot start.
OPENCLAW_FS_SAFE_PYTHON_MODE=require

# Optional explicit interpreter.
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3
通用 fs-safe 名稱也可使用：FS_SAFE_PYTHON_MODE 和 FS_SAFE_PYTHON。

​
沒有 Python 時仍受保護的內容

在輔助程式關閉時，OpenClaw 仍會將 fs-safe 的 Node 路徑用於：
  • 拒絕相對路徑逸出，例如 ..、絕對路徑，以及在只允許名稱時出現的路徑分隔符；
  • 透過受信任的根目錄控制代碼解析操作，而不是使用臨時的 path.resolve(...).startsWith(...) 檢查；
  • 在要求該政策的 API 上拒絕符號連結和硬連結模式；
  • 在 API 回傳或取用檔案內容時，以身分檢查開啟檔案；
  • 對狀態/設定檔執行同層級暫存檔原子寫入；
  • 對讀取和封存檔解壓縮設定位元組限制；
  • 在 API 要求時，對祕密和狀態檔使用私人模式。
這些保護涵蓋一般 OpenClaw 威脅模型：在單一受信任操作員邊界內，受信任的 Gateway 程式碼處理不受信任的模型/Plugin/通道路徑輸入。

​
Python 增加的保護

在 POSIX 上，fs-safe 的選用輔助程式會維持一個常駐 Python 程序，並針對父目錄變更使用相對於 fd 的檔案系統操作，例如重新命名、移除、mkdir、stat/list，以及部分寫入路徑。 這會縮小同 UID 競態視窗，在該視窗中，另一個程序可在驗證與變更之間替換父目錄。對於不受信任的本機程序可修改 OpenClaw 正在操作的相同目錄的主機，這是縱深防禦。 如果你的部署有這項風險，且可保證 Python 存在，請使用： 
OPENCLAW_FS_SAFE_PYTHON_MODE=require
當輔助程式是安全態勢的一部分時，請使用 require 而不是 auto；如果輔助程式不可用，auto 會刻意退回僅 Node 的行為。

​
Plugin 與核心指引

  • 面向 Plugin 的檔案存取，在路徑來自訊息、模型輸出、設定或 Plugin 輸入時，應透過 openclaw/plugin-sdk/* 輔助函式，而不是原始 fs。
  • 核心程式碼應使用 src/infra/* 下的本機 fs-safe wrapper，讓 OpenClaw 的程序政策一致套用。
  • 封存檔解壓縮應使用 fs-safe 封存檔輔助函式，並明確設定大小、項目數、連結和目的地限制。
  • 祕密應使用 OpenClaw 祕密輔助函式，或 fs-safe 祕密/私人狀態輔助函式；不要圍繞 fs.writeFile 自行撰寫模式檢查。
  • 如果你需要對敵意本機使用者進行隔離，不要只依賴 fs-safe。請在不同 OS 使用者/主機下執行獨立 Gateway，或使用沙箱。
相關：安全性、沙箱、Exec 核准、祕密。