@openclaw/fs-safe を使用します。ルート境界内の読み書き、アトミック置換、アーカイブ展開、一時ワークスペース、JSON 状態、シークレットファイル処理が対象です。
これは、信頼されていないパス名を受け取る信頼済み OpenClaw コード向けの ライブラリガードレールであり、サンドボックスではありません。実際の影響範囲を定義するのは、ホストのファイルシステム権限、OS ユーザー、コンテナ、エージェント/ツールポリシーです。
デフォルト: Python ヘルパーなし
OpenClaw は、fs-safe の POSIX Python ヘルパーをデフォルトで オフに設定します。- オペレーターが明示的に有効化しない限り、ゲートウェイは永続的な Python サイドカーを起動すべきではないため。
- ほとんどのインストールでは、追加の親ディレクトリ変更ハードニングを必要としないため。
- Python を無効化することで、デスクトップ、Docker、CI、バンドルアプリ環境全体でランタイム動作を予測しやすく保てるため。
FS_SAFE_PYTHON_MODE と FS_SAFE_PYTHON。
ヘルパーがセキュリティ体制の一部である場合は、auto ではなく require を使用してください。auto は、ヘルパーを起動できない場合に Node のみの動作へ静かにフォールバックします。
Python なしで保護される内容
ヘルパーがオフでも、OpenClaw は fs-safe の Node のみのガードレールを引き続き利用します。- 相対パスの脱出 (
..)、絶対パス、素の名前だけが許可される場所でのパス区切り文字を拒否する。 - その場限りの
path.resolve(...).startsWith(...)チェックではなく、信頼済みルートハンドルを通じて操作を解決する。 - そのポリシーを必要とする API で、シンボリックリンクとハードリンクのパターンを拒否する。
- API がファイル内容を返す、または消費する場合に、ID チェック付きでファイルを開く。
- 状態/設定ファイルを、アトミックな兄弟一時ファイル + リネームで書き込む。
- 読み取りとアーカイブ展開にバイト制限を適用する。
- API が要求する場合に、シークレットと状態ファイルへプライベートなファイルモードを適用する。
Python が追加するもの
POSIX では、任意のヘルパーが 1 つの永続 Python プロセスを維持し、親ディレクトリの変更に fd 相対のファイルシステム操作を使用します。対象は、リネーム、削除、mkdir、stat/list、および一部の書き込みパスです。 これにより、同じ UID の別プロセスが検証と変更の間に親ディレクトリを差し替える競合ウィンドウが狭まります。OpenClaw が操作する同じディレクトリを、信頼されていないローカルプロセスが変更できるホストでの多層防御です。 デプロイにそのリスクがあり、Python が存在することが保証されている場合は、次を設定してください。Plugin とコアのガイダンス
- Plugin 向けのファイルアクセスでは、パスがメッセージ、モデル出力、設定、または Plugin 入力に由来する場合、生の
fsではなくopenclaw/plugin-sdk/*ヘルパーを通すべきです。 - コアコードでは、
src/infra/*配下の fs-safe ラッパーを使用し、OpenClaw のプロセスポリシーが一貫して適用されるようにするべきです。 - アーカイブ展開では、明示的なサイズ、エントリ数、リンク、宛先の制限を指定して、fs-safe のアーカイブヘルパーを使用するべきです。
- シークレットでは、OpenClaw のシークレットヘルパー、または fs-safe のシークレット/プライベート状態ヘルパーを使用するべきです。
fs.writeFileの周りでモードチェックを自作しないでください。 - 敵対的なローカルユーザーの分離では、fs-safe だけに依存しないでください。別々の OS ユーザー/ホストで別々のゲートウェイを実行するか、サンドボックスを使用してください。