ネイティブ macOS 上で OpenClaw を出荷するオペレータはすぐに学びます。「ワークスペース専用のファイルシステム ツール」という YAML の一つのノブの裏に、エージェント側ツール フィルタ、ゲートウェイ解釈、任意の Docker bind マウントという三つの政策が隠れている、と。本 2026-05-06 マトリクスは tools.fs.workspaceOnly が Mac mini M4 のホスト パス正規化とどう相互作用するか、設定が広いアクセスを約束しても Path escapes workspace root が現れる理由、シークレットを漏らさず失敗を再現する方法を示します。表2つ、トリアージ 8 ステップ、FAQ JSON-LD、防御を深めるための可観測性とシークレット記事へのリンク付きです。
ゲートウェイ可観測性と編集 から続け、シークレット、環境変数、Keychain で資格情報姿勢を締め、ドレイン・再起動・スモークの運用ブック でアップグレードを検証すれば、ファイルシステムの退行が騒がしいデプロイ窓に隠れません。
現場では「モデルがファイルを書けない」と報告されがちですが、最初に疑うべきはモデルではなくパスの正規化です。Docker が絡むと、コンテナ内の /workspace とホストの実パスが一致しているように見えても、ゲートウェイが別の絶対パスで検証していることがあります。HK·JP·KR·SG·US のように地域を分けた場合でも、設定ファイルがコピーされるだけでボリューム UUID が変わらないとは限りません。バージョン・絶対パス・実行 UID の三点セットが揃えば、ほとんどの「謎の拒否」は再現可能になります。
なぜファイルシステム政策は Apple Silicon オペレータを惑わせるのか
macOS はシンボリックリンク、Firmlink、大文字小文字を区別しないボリュームを通じてパスを解決し、コンテナは別の根を見ます。エージェントは /workspace/out に書いているつもりでも、セキュリティ修正後のゲートウェイがより厳しいホスト規則を適用するかもしれません。Apple Silicon M4 では Activity Monitor 上の IO 遅延は「問題なし」に見えても、サンドボックス化ツールがメタデータ更新を直列化していることがあり、オペレータは政策の層ではなくモデルやネットを責めます。強制面を明示的に文書化すれば、その死角を防げます。
- 二重スタック マウント： Docker Desktop の bind パスは同一ホストの SSH セッション パスと微妙に異なります。
- 自動化と人間の試行： エンジニアが Terminal エイリアスで試すと、デーモンがヘッドレスで踏む制約を迂回します。
- 監査の緊張： SecOps はデフォルト拒否を望み、開発者の快適さは
~/Developer下の迅速な編集を望みます。
インシデント衛生： ログに Path escapes workspace root が出たら、絶対解決パス、所有 UID、ツールがサンドボックス内で実行されたかの三つを記録してください。上流メンテナが退行と意図した締め付けを切り分けるのに必要です。
マトリクス A — 強制層 対 オペレータの想定 対 検証の習慣
| 層 | よくある想定 | 検証方法 |
|---|---|---|
| エージェントの許可／拒否リスト | ファイル書き込みは YAML どおり | openclaw doctor と最小フィクスチャでツール呼び出しを再生 |
| ゲートウェイ ホスト ガード | workspaceOnly:false で根チェックが常に無効 |
リリースノートを比較し、アップグレード前後で設定を diff |
| Docker サンドボックス ボリューム マップ | コンテナ パスは macOS パスと等しい | マウント表を出力し、両方の根を数値で対応付け |
マトリクス B — 症状 対 疑わしい層 対 オーナー行動 対 緩和パターン
| 症状 | 疑わしい層 | オーナー | 緩和 |
|---|---|---|---|
| 読み取りは成功、ワークスペース外の書き込みはブロック | ホスト ガードレールの退行 | プラットフォーム | 政策がドキュメントと一致するまでゲートウェイ semver を固定し、最小再現を提出 |
| サンドボックス内だけランダムなパスが失敗 | bind マウントの欠落 | インフラ | 許可マウントを拡張するか、そのレーンではサンドボックスを外す |
| ツールがサブツリー全体を断続的に拒否 | ワークスペース移動とツール実行の競合 | 自動化 | ファイルロックでワークスペース provision を直列化し、2 秒 以上の安定窓 |
チームが実際に議論する定量的ノブ
- ワークスペース移動予算： 人間の確認なしにエージェント セッションあたり自動移動は多くても 1 回。
- ツール並列ファンアウト： Mac mini M4 ゲートウェイあたり同時ファイル変更ツールは 4 までに抑え、インデックス ジョブ中の APFS メタデータ嵐を避ける。
- 退行 SLA： 予期しないワークスペース拒否がリリース マージを 30 分 超ブロックしたら P1。
8 つのトリアージ手順（JSON-LD と対応）
- バージョン取得： CLI、ゲートウェイ プラグイン、OS ビルド番号。
- 解決済みワークスペース根を出力： ホスト デーモン対サンドボックス子プロセス。
- 設定を diff：
tools.fs.workspaceOnlyと付随する許可リスト。 - 失敗を分類： 脱出エラー、権限拒否、一時 IO。
- 最小プローブ： 制御された temp だけに触れる。
- Docker 隔離が有効ならネットとマウントを調整。
- ログを編集： 信頼境界の外に出す前に。
- 姿勢を文書化： ブレイクアウトがバグか政策かサポートが分かるように。
FAQ
開発者にデフォルトでホスト全体の書き込みを許すべきか
いいえ。狭くスコープしたステージング ホストか週次監査の一時ブレイクアウト レーンを発行し、本番ゲートウェイはワークスペース拘束のままにする。
シンボリックリンク脱出を安全に試すには
スクラッチ ボリューム下に捨てワークスペースを作り、無害ファイルへ symlink し、顧客データに触れる前に強制が横断をブロックすることを検証する。
専用 Mac mini M4 上で OpenClaw を動かすと、Apple のツールチェーン期待を守りつつサンドボックス境界を実験できます。Apple Silicon はファイル重いエージェントの遅延を予測しやすく、ネイティブ macOS は libc の驚きを減らし、NodeMac の SSH と任意の VNC はヘッドレスログが嘘をつくとき対話的にパス問題を証明できます。香港、日本、韓国、シンガポール、米国 のリージョンで「厳格ワークスペース」の本番ゲートウェイと研究ポッド専用の緩いサンドボックスを分離すれば、ブラスト半径と tools.fs リリース間の挙動変化への平均解明時間の両方を下げられます。
まとめると、OpenClaw のファイルツールは YAML を読んだそのままでは動きません。エージェント、ゲートウェイ、コンテナの三層が別々に合理的であることが重要で、矛盾が出たらまずバージョンとパス解決を固定し、次に allowlist を調整します。運用が成熟すると、研究者向けの広いパスと本番向けの狭いパスを組織として明示でき、サポート問い合わせも設定バグかポリシーかの二分探索に収束します。