サンドボックス、ツールポリシー、昇格の違い

1. サンドボックス（agents.defaults.sandbox.* / agents.entries.*.sandbox.*）は、ツールをどこで実行するか（サンドボックスバックエンドまたはホスト）を決定します。
2. ツールポリシー（tools.*、tools.sandbox.tools.*、agents.entries.*.tools.*）は、どのツールを利用可能／許可するかを決定します。
3. 昇格（tools.elevated.*、agents.entries.*.tools.elevated.*）は、サンドボックス化されている場合にサンドボックス外で実行するための exec 専用のエスケープハッチです（デフォルトでは gateway、または exec ターゲットが node に設定されている場合は node）。

​

クイックデバッグ

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

• 有効なサンドボックスのモード／スコープ／ワークスペースアクセス
• セッションが現在サンドボックス化されているかどうか（メインか非メインか）
• 有効なサンドボックスツールの許可／拒否（およびエージェント／グローバル／デフォルトのどれに由来するか）
• 昇格のゲートと修正用キーのパス

​

サンドボックス：ツールを実行する場所

• "off"：すべてがホスト上で実行されます。
• "non-main"：非メインセッションのみがサンドボックス化されます（グループ／チャンネルでよくある「予想外」の挙動）。
• "all"：すべてがサンドボックス化されます。

​

バインドマウント（セキュリティのクイックチェック）

• docker.binds はサンドボックスのファイルシステムを_貫通_します。マウントしたものはすべて、設定したモード（:ro または :rw）でコンテナ内から参照できます。
• モードを省略した場合、デフォルトは読み書き可能です。ソース／シークレットには :ro を推奨します。
• scope: "shared" はエージェントごとのバインドを無視します（グローバルバインドのみが適用されます）。
• OpenClaw はバインド元を 2 回検証します。最初に正規化されたソースパスを検証し、次に最も深い既存の祖先を経由して解決した後で再度検証します。親ディレクトリのシンボリックリンクを利用した脱出によって、ブロック対象パスまたは許可ルートのチェックを回避することはできません。
• 存在しない末端パスも安全にチェックされます。/workspace/alias-out/new-file がシンボリックリンクされた親を経由してブロック対象パスまたは設定済みの許可ルート外に解決される場合、バインドは拒否されます。
• /var/run/docker.sock をバインドすると、実質的にサンドボックスへホストの制御権を渡すことになります。意図している場合にのみ実行してください。
• ワークスペースアクセス（workspaceAccess）はバインドモードとは独立しています。

​

ツールポリシー：存在し、呼び出し可能なツール

• ツールプロファイル：tools.profile および agents.entries.*.tools.profile（基本許可リスト）
• プロバイダーツールプロファイル：tools.byProvider[provider].profile および agents.entries.*.tools.byProvider[provider].profile
• グローバル／エージェントごとのツールポリシー：tools.allow／tools.deny および agents.entries.*.tools.allow／agents.entries.*.tools.deny
• プロバイダーツールポリシー：tools.byProvider[provider].allow/deny および agents.entries.*.tools.byProvider[provider].allow/deny
• サンドボックスツールポリシー（サンドボックス化されている場合にのみ適用）：tools.sandbox.tools.allow／tools.sandbox.tools.deny および agents.entries.*.tools.sandbox.tools.*

• deny が常に優先されます。
• allow が空でない場合、それ以外はすべてブロック対象として扱われます。
• ツールポリシーは最終的な制限です。/exec で拒否された exec ツールを上書きすることはできません。
• ツールポリシーは名前によってツールの可用性をフィルタリングします。exec 内部の副作用は検査しません。exec が許可されている場合、write、edit、または apply_patch を拒否しても、シェルコマンドは読み取り専用にはなりません。
• /exec は、承認済み送信者のセッションデフォルトを変更するだけであり、ツールへのアクセス権は付与しません。
• プロバイダーツールキーでは、provider（例：google-antigravity）または provider/model（例：openai/gpt-5.4）のいずれかを使用できます。
• ツールポリシーのステップでツールが除外された場合、またはサンドボックスツールポリシーによって呼び出しがブロックされた場合、Gateway のログには agents/tool-policy 監査エントリが含まれます。ルールラベル、設定キー、および影響を受けるツール名を確認するには、openclaw logs を使用してください。

​

ツールグループ（短縮表記）

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

​

昇格：exec 専用の「ホスト上で実行」

• サンドボックス化されている場合、/elevated on（または elevated: true を伴う exec）はサンドボックス外で実行されます（引き続き承認が必要な場合があります）。
• セッションで exec の承認を省略するには、/elevated full を使用します。
• すでに直接実行されている場合、昇格は実質的に何もしません（ただし、引き続きゲートの制約を受けます）。
• 昇格は Skills 単位ではなく、ツールの許可／拒否を上書きすることもありません。
• 昇格によって host=auto から任意のクロスホスト上書きが許可されることはありません。通常の exec ターゲットルールに従い、設定済み／セッションのターゲットがすでに node である場合にのみ node を維持します。
• /exec は昇格とは別のものです。承認済み送信者について、セッションごとの exec デフォルトを調整するだけです。

• 有効化：tools.elevated.enabled（および必要に応じて agents.entries.*.tools.elevated.enabled）
• 送信者の許可リスト：tools.elevated.allowFrom.<provider>（および必要に応じて agents.entries.*.tools.elevated.allowFrom.<provider>）

​

よくある「サンドボックスへの閉じ込め」の修正

​

「ツール X がサンドボックスツールポリシーによってブロックされました」

• サンドボックスを無効化: agents.defaults.sandbox.mode=off（またはエージェントごとの agents.entries.*.sandbox.mode=off）
• サンドボックス内でツールを許可:
  • tools.sandbox.tools.deny から削除する（またはエージェントごとの agents.entries.*.tools.sandbox.tools.deny）
  • または tools.sandbox.tools.allow に追加する（またはエージェントごとに許可）
• openclaw logs で agents/tool-policy エントリを確認してください。このエントリには、サンドボックスモードと、許可ルールまたは拒否ルールのどちらによってツールがブロックされたかが記録されます。

​

「main だと思っていたのに、なぜサンドボックス化されているのですか？」

​

関連項目

• サンドボックス化 — サンドボックスの完全なリファレンス（モード、スコープ、バックエンド、イメージ）
• マルチエージェントのサンドボックスとツール — エージェントごとの上書きと優先順位
• 昇格モード