安全なファイル操作

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 プロセスを永続的に維持し、親ディレクトリを変更する操作（名前変更、削除、ディレクトリ作成、状態取得／一覧取得、および一部の書き込みパス）にファイルディスクリプター相対のファイルシステム操作を使用します。

これにより、OpenClaw が操作するものと同じディレクトリを信頼されていないローカルプロセスが変更できるホストで、別のプロセスが検証から変更までの間に親ディレクトリを差し替える、同一 UID の競合状態の発生可能時間が短縮されます。これは多層防御です。

デプロイ環境にそのリスクがあり、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 を実行するか、サンドボックスを使用してください。

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