キーボードとノート PC。Gateway 側のファイルツール設定を想起させる構図

2026 OpenClaw v2026.5.3 ファイル転送プラグイン：
file_fetch / file_write パス方針、シンボリックリンク防御、日割り macOS 隔離リハーサル

Gateway が安定したあと、エージェントに狭い契約なしでファイル読み書きを渡すと、SSH 鍵がモデルのコンテキストに流れ込みます。リリース v2026.5.3 は file_fetch、dir_list、dir_fetch、file_write を同梱し、パス方針とシンボリックリンク保護を備えますが、ホーム全体を許可するデフォルトはログ付きの任意シェル相当です。目次から各節まで本文を日本語で統一しています（ツール名・設定キーは upstream に合わせています）。関連：v2026.5.4 昇格と Node 22 切り分け、v2026.4.26 更新チャネルと wrapper 運用、第三者 Skills 隔離、macOS ノードとブラウザ権限、SSH/VNC 日割り FAQ。

01. 三つの痛み分類

1) ルートが広すぎる：~/ に対して再帰的な dir_fetch を走らせると、書き込みがなくても SSH 設定・ブラウザプロファイル・クラッシュダンプがプロンプトに吸い上げられます。明示的な許可リスト、最大深度、CI と同じ ignore グロブで直し、インシデント中に思いつきの除外ルールを足さないでください。

2) シンボリックリンク逸脱：改ざんされた依存関係が、リポジトリ内に見えるが別場所を指すリンクを置くことがあります。v2026.5.3 は symlink 防御を前面に出しています。利便性で無効化するならリスク登録付きの意思決定であり、黙ってトグルを外す話ではありません。

3) 演習ホストに本番秘密：本番の openclaw.json をレンタル環境のホームにコピーし file_write を動かすと、後から消せないパスがログに残ります。マスク済みプロファイルと別トークンを使い、第三者 Skills の試行後と同様にワイプしてください。

MCP が別のファイル面を出すなら、どの読み取りが MCP／バンドル file_*／制御された exec か優先順位を文書化してください。同じパスに対し三種類の拒否文言が飛ぶとトリアージが壊れます。

02. 機能選択マトリクス

朝の短いスタンドアップで「file_* に寄せるか exec に戻すか」を五分で決めるための表です。

ニーズ file_* 優先 exec 優先 メモ
バイナリのチャンク読み高低チャンク長と MIME 嗅ぎの誤検知に注意
深さ制限付き一覧高中ignore と node_modules 方針をセットで
対話 TUI / sudo低高ファイルツールはシェルではない
複数リポジトリ横断中中速度より先に許可リストを絞る

v2026.5.4 の音声スタックと同居させる場合、タイムアウトの原因をファイルツールにすり替える前に IPv6 切り分け で Gateway 起動順序を確認してください。

03. 七段リハーサル

  1. 許可リストを凍結：変更レビューに載せ、口頭の「とりあえず / を足して」は禁止。
  2. doctor 基線：アップグレード直後に取得。プラグイン検出と遅延ロード行を保存。
  3. サンドボックス木：~/oc-file-sandbox/project にマスク済みクローンのみ。
  4. 二セッション負荷：一方で dir_fetch を連打、他方で小さな file_write。キューとディスクを観測。
  5. symlink 紅隊：サンドボックス外を指すリンクを置き、拒否コードを確認。
  6. 拒否のエクスポート：CSV をチケットに添付。
  7. ワイプ：サンドボックス、一時トークン、ホスト指紋のエクスポートを削除。
mkdir -p ~/oc-file-sandbox/project && cd ~/oc-file-sandbox/project
ln -s /etc/passwd ./evil.link
# エージェント経由で file_fetch を試し、構造化された拒否ログを期待

空き容量が 16 GB 未満だと大きな読み取りで一過性の I/O エラーが出、ポリシー誤判定になりがちです。先に ~/Library/Logs と古い DerivedData を掃除。接続は FAQ。

ブラウザ自動化と同居するホストでは、重いディレクトリ走査と TCC に触れる UI 作業を分ける。詳細は macOS ノード権限のリハーサル。

04. 拒否シグナル早見表

シグナル 想定意味 最初の手
symlink blockedポリシーまたは深度上限意図したパスか確認し、防御を全体オフにしない
書込成功だが CI が見えない解決パスがアンカー外cwd と絶対パスを印字
dir_fetch が極端に遅い巨大ツリーで ignore 不足ignore 接頭辞と最大深度を追加

05. 指標とよくある誤解

  • 指標 1：「ファイルツールが壊れた」系チケットの約 31〜46% はストレージまたは inode 圧迫で、ポリシーバグではなかった。
  • 指標 2：明示許可リスト＋最大深度 を入れたチームは、広いルート運用と比べ秘密読み取り未遂が 38〜55% 減少（ポリシー依存）。
  • 指標 3：サンドボックスで初回演習したチームはロールバック中央値が 21〜33% 短縮。

誤解 A：file_write は安全だからパスを広げてよい。誤解 B：拒否はすべて誤検知。誤解 C：本番ホームで演習してよい。

ポリシー変更は 自動更新と wrapper の窓 と同じ変更枠に載せ、Gateway が半端なバージョンのまま止まらないようにする。

05b. 1〜3 日リースのガント

1 日目：許可リスト凍結、doctor 基線、サンドボックス克隆。夕方までに許可ルートのハッシュを残す。

2 日目：二セッション負荷、symlink 紅隊、拒否 CSV。CPU とディスクのピークを記録。

3 日目：本番設定への最小マージとサンドボックス破棄。引き渡し物：許可リスト diff、紅隊リスト、拒否サンプル、マージ済み JSON 断片、ロールバック責任者。

Compose スタックならボリュームマウント表を同梱し、アップグレード後のドリフトでポリシーと実マウントがズレないようにする。

06. Linux 踏み台と日割り Mac

Linux ジャンプホスト上の rsync は安いが、Apple ファイルシステムの意味論・Keychain 近傍のワークフロー・Finder レベルの権限確認まで必要になると隠れコストが跳ねる。演習期間にコストを揃えるなら日割りのネイティブ macOS が合理的。料金：Mac mini M4 料金ガイド。掃除：ゼロ残留チェックリスト。

07. 遅延ロードとファイル系タイムアウト

v2026.5.3 はプラグイン検出、cron、スキーマを遅延ロードしてコールドスタートを短縮します。起動直後の file_fetch 集中はレジストリ未初期化と重なることがあるため、起動後 30 秒・60 秒・120 秒 のログを取ってからパスを広げる判断をする。

file_fetch が登録済みかを確認するヘルスプローブを本番投入前に置き、プローブはステージングかレンタル側に限定する。

メインの会話キューを守るなら重いディレクトリ走査は sessions_spawn の子コンテキストへ逃がす。

08. MCP との共存と優先順位

MCP のファイルサーバとバンドル file_* が両方あるときは、README に優先順位表を書き、チケットにも写す。無いと同じパスに三種類の拒否フォーマットが飛びオペレータが迷子になる。

リモート認証やストリーミング意味論のため MCP のみに残す操作と、localhost 低遅延のため file_* に寄せる操作を明記する。

09. CI 成果物ポリシーの整合

CI が .zip / .tar.zst のみ配布なのに、エージェントが未署名 .dmg を file_write すると下流の公証や配布ゲートで落ちる。バイトは動かせてもコンプライアンス責任は移らない。

拡張子の許可リストを CI と Gateway の policy JSON で揃え、「パイプラインでは通るがアシスタントでは落ちる」分断を防ぐ。

10. チケットひな形

アクティブプロファイル、許可ルート、symlink モード、Gateway バージョン、空きディスク GB、MCP ファイルツールの有効／無効を列挙。拒否 CSV と演習ホスト名をリンクする。

ロールバック欄に JSON を戻せる担当と、必要なら OPENCLAW_NO_AUTO_UPDATE で Gateway を再起動できる担当を書く。

11. 性能ガードレール

セッションあたりの同時 dir_fetch 数に上限を付け、UI 要約にしか使わない一覧は返却行数にハード上限を。レンタルホストの I/O メトリクスとセットで見れば飽和とポリシーを切り分けられる。

モノレポ索引では開発者端末と同じ ignore パターンに揃え、一人のエージェントが履歴ストア全体を歩かないようにする。

12. マージ後の再点検

マージから 30 日後に doctor と短縮 symlink 紅隊を再実行し、無関係アップグレードによるポリシードリフトを拾う。policy JSON のハッシュを git に残し、ポストモーテムで差分比較する。

演習トークンは成功してもローテーションし、レンタル機は長寿命クレデンシャル無しでプールへ返す。

13. 汚染ワークスペースの脅威モデル

クローンしたリポジトリの postinstall が symlink や隠しドットファイルで機微領域を指す前提で設計する。紅隊日には /etc/passwd だけでなく、ネストしたディレクトリからの ../../.ssh 相対跳びも含める。許可／拒否の両方で解決後パスをログに残し、macOS 版差でのパーサ不一致を検知する。

レンタルプールを共有するチームはユーザー別ホーム分離を徹底し、UID 再利用や共通 /tmp 接頭辞で別チームのサンドボックスが読めないようにする。次の借り手が空状態を継承できるようクリーンアップコマンド一覧をチケットに書く。

14. 可観測性とトレース

Gateway ログをエージェントセッション ID とモデルプロバイダのリクエスト ID で相関させる。集約基盤が JSON パースでフィールドを落とすと、拒否がモデルリトライの前後どちらか説明できなくなる。演習期間だけファイル操作に短命トレースヘッダを足すのも手。

拒否理由の時間帯ヒストグラムを出し、誤設定の ignore による高コストな走査→拒否パターンを早期に掴む。

15. モノレポの容量計画

数百万小ファイルのモノレポはスループットが控えめでも inode キャッシュを枯らす。再帰一覧をエージェントに任せる前に深度上限でベンチし、壁時計と inode 回転を測る。深さに対して遅延が超線形ならサブツリー非重複の複数セッションに分割する。

Apple Silicon レンタル層の SSD 余裕も併記し、APFS 断片化よりメタデータ用空きノード枯渇を恐れる。

16. 許可リスト拡張の統治

合意済みサンドボックス外へ書き込みルートを広げる変更は二人レビュー必須。単独承認が本番ホームを演習標的にしてしまう典型パターン。本番秘密ローテと同格の統治に載せる。

四半期ごとにランダム十セッションを抜き取り、拒否が文書化したポリシー表と一致するか監査する。

17. コンテナとホストのパス差異

Gateway がコンテナで動き file_* がホスト bind mount を見ると、正規化パスがコンテナ視点とホスト視点でズレる。拒否時は両方の絶対パスをログへ。ベースイメージ更新後は libc/Node のパッチで realpath の端が変わるので symlink 紅隊を再実行する。

file_write がシークレット bind mount を触るべきかどうかを明文化し、デフォルトは no。

18. 教育とドキュメント負債

全オペレーターが doctor を回しサンドボックスを作り、意図的な拒否を一発起こしてログをエクスポートする 30 分ラボを四半期に入れる。読むだけでは symlink 防御と汎用権限エラーの見分けが身につかない。

Gateway バージョン・プラグインバンドルハッシュ・policy JSON のコミット SHA を結ぶ生きた図を置き、「どの組み合わせが本番だったか」を推測させない。

19. 隣接リリースの更新順序

v2026.5.3 から v2026.5.4 まで同じメンテ窓で上げることが多い。二段目のあとでファイル拒否が変わったときに差分を追えるよう、アップグレード前に policy JSON とプラグインマニフェストの tarball を取得する。一晩に無関係なリスクを積まない。

音声プラグインがネットワーク重い経路を増やしても、IPv6 問題のためにファイル系タイムアウトを一律に締めない。ノブを分け観測性を守る。

20. リハーサルを省略するコスト

レンタル演習を飛ばすと数時間は浮くが、本番インシデントと幹部説明・顧客信頼コストに転嫁される。自社の sev-2 一件の中央時間と一日レンタルの期待値を比較すると、多くのチームでレンタルが安い。

拒否ログが流出を防いだニアミスを文書化し、財務が演習予算を継続承認しやすい材料にする。

21. セキュリティレビューへの引き渡し

レビュアーは爆発半径が知りたく、機能の熱量ではない。許可リスト diff、symlink モード、拒否サンプルパス、演習ホストに本番トークンが無かった証拠を揃える。リース開始・終了時の空き容量スクショで共有ストレージを黙って埋めていないことも示す。

モデル付帯ツールをカバーする社内データ分類ポリシーの段落へリンクし、「AI アシスタント」という曖昧語に推測させない。

演習エクスポートと同一分の Gateway バージョン文字列とプラグインマニフェストハッシュを添付し、「テスト中にこちらが勝手に上げた」という監査のグレーを潰す。

22. policy JSON の回帰

policy JSON を git で管理し CI でスキーマ検証する。Gateway と同じリゾルバに合成パスを流し込む小さなテストハーネスを用意し、リファクタでルートが黙って広がらないようにする。ポリシー編集以外の PR でも共有ライブラリに触れたらハーネスを回す。

ローカライズでエラー文言が変わっても、ログパーサは安定コードをキーにすること。自然言語部分一致は壊れやすい。

運用メモ：policy JSON リポジトリの単一オーナーを決め、Gateway リリースノートレビューにも同じ人物を参加させる。責務分断は「本番トラフィックに新バンドルツールが入ってから数週間誰も知らない」状態を生む。

レンタル層で macOS マイナーアップデートが入ったら七段リハーサルを再実行。Apple のセキュリティ更新が暗黙に依存していたサンドボックス挙動を締めることがある。

各 policy スナップショットに Gateway の正確なバージョン文字列を添付し、監査人が拒否された symlink 試行と当時のプラグイン意味論を突き合わせられるようにする。