安全なファイル操作

OpenClaw は、セキュリティ上重要なローカルファイル操作（ルート範囲内に制限された読み書き、アトミックな置換、アーカイブ展開、一時ワークスペース、JSON 状態、シークレットファイルの処理）に @openclaw/fs-safe を使用します。

これは、信頼されていないパス名を受け取る信頼済み OpenClaw コード向けのライブラリによる安全策であり、サンドボックスではありません。実際の影響範囲は、ホストのファイルシステム権限、OS ユーザー、コンテナ、およびエージェント／ツールのポリシーによって引き続き決まります。

デフォルト：Python ヘルパーなし

OpenClaw は、fs-safe の POSIX Python ヘルパーをデフォルトでオフに設定します。

• オペレーターが明示的に有効化しない限り、Gateway は常駐 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 も使用できます。

ヘルパーがセキュリティ態勢の一部である場合は、auto ではなく require を使用してください。auto は、ヘルパーを起動できない場合に通知せず Node のみの動作へフォールバックします。

Python なしでも維持される保護

ヘルパーがオフでも、OpenClaw は引き続き fs-safe の Node のみの安全策を利用します。

• ベア名のみが許可される箇所では、相対パスによる範囲外への脱出（..）、絶対パス、パス区切り文字を拒否します。
• その場しのぎの path.resolve(...).startsWith(...) チェックではなく、信頼済みのルートハンドルを介して操作を解決します。
• そのポリシーを必要とする API では、シンボリックリンクおよびハードリンクのパターンを拒否します。
• API がファイル内容を返す、または受け取る場合、同一性チェックを行ってファイルを開きます。
• 状態／設定ファイルは、同じディレクトリ内の一時ファイルへの書き込みと名前変更によってアトミックに書き込みます。
• 読み取りとアーカイブ展開にバイト数制限を適用します。
• API が要求する場合、シークレットおよび状態ファイルに非公開のファイルモードを適用します。

これは、単一の信頼済みオペレーター境界内で、信頼済み Gateway コードが信頼されていないモデル／Plugin／チャネル由来のパス入力を処理するという、OpenClaw の通常の脅威モデルをカバーします。

Python によって追加される保護

POSIX では、任意のヘルパーが 1 つの Python プロセスを常駐させ、親ディレクトリを変更する操作（名前変更、削除、ディレクトリ作成、状態取得／一覧表示、一部の書き込みパス）にファイル記述子相対のファイルシステム操作を使用します。

これにより、検証から変更までの間に別のプロセスが親ディレクトリをすり替える、同一 UID 内の競合状態の余地が狭まります。これは、信頼されていないローカルプロセスが OpenClaw の操作対象と同じディレクトリを変更できるホストにおける多層防御です。

デプロイ環境にそのリスクがあり、Python が確実に存在する場合は、次のように設定します。

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Plugin とコアに関する指針

• メッセージ、モデル出力、設定、または Plugin 入力からパスを受け取る場合、Plugin 向けのファイルアクセスでは生の fs ではなく、openclaw/plugin-sdk/* ヘルパーを使用してください。
• コアコードでは、OpenClaw のプロセスポリシーが一貫して適用されるように、src/infra/* 配下の fs-safe ラッパーを使用してください。
• アーカイブ展開では、サイズ、エントリ数、リンク、展開先の制限を明示して fs-safe のアーカイブヘルパーを使用してください。
• シークレットには、OpenClaw のシークレットヘルパー、または fs-safe のシークレット／非公開状態ヘルパーを使用してください。fs.writeFile の周囲に独自のモードチェックを実装しないでください。
• 悪意のあるローカルユーザーから分離するために、fs-safe だけに依存しないでください。別々の OS ユーザー／ホストで個別の Gateway を実行するか、サンドボックスを使用してください。

関連項目：セキュリティ、サンドボックス、実行の承認、シークレット。