Gateway
サンドボックス、ツールポリシー、昇格の違い
OpenClaw には、関連しているものの異なる3つの制御があります。
- サンドボックス（
agents.defaults.sandbox.*/agents.list[].sandbox.*）は、ツールをどこで実行するか（サンドボックスバックエンドまたはホスト）を決定します。 - ツールポリシー（
tools.*、tools.sandbox.tools.*、agents.list[].tools.*）は、どのツールを利用可能／許可するかを決定します。 - 昇格（
tools.elevated.*、agents.list[].tools.elevated.*）は、サンドボックス化されている場合に、サンドボックス外で実行するためのexec専用の脱出口です（デフォルトはgateway。execのターゲットがnodeに設定されている場合はnode）。
クイックデバッグ
OpenClaw が_実際に_何をしているか確認するには、インスペクターを使用します。
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json次の情報が出力されます。
- 有効なサンドボックスのモード／スコープ／ワークスペースアクセス
- セッションが現在サンドボックス化されているか（メインか非メインか）
- 有効なサンドボックスツールの許可／拒否（およびエージェント／グローバル／デフォルトのどこから取得されたか）
- 昇格ゲートと修正用キーのパス
サンドボックス：ツールの実行場所
サンドボックス化は agents.defaults.sandbox.mode で制御します。
"off"：すべてホスト上で実行します。"non-main"：非メインセッションのみサンドボックス化します（グループ／チャンネルでよくある「予想外」の原因です）。"all"：すべてサンドボックス化します。
agents.defaults.sandbox.workspaceAccess は、サンドボックスから参照できる範囲を制御します。指定値は "none"、"ro"、"rw" です。
完全な対応表（スコープ、ワークスペースのマウント、イメージ）については、サンドボックス化を参照してください。
バインドマウント（セキュリティのクイックチェック）
docker.bindsはサンドボックスのファイルシステムを_貫通_します。マウントしたものは、設定したモード（:roまたは:rw）でコンテナ内から参照できます。- モードを省略した場合、デフォルトは読み書き可能です。ソースやシークレットには
:roを推奨します。 scope: "shared"では、エージェント単位のバインドは無視されます（グローバルバインドのみ適用されます）。- OpenClaw はバインド元を2回検証します。最初に正規化されたソースパスを検証し、次に存在する最深の祖先を経由して解決した後に再度検証します。親ディレクトリのシンボリックリンクを利用した脱出では、ブロック対象パスや許可ルートのチェックを回避できません。
- 存在しない末端パスも安全にチェックされます。
/workspace/alias-out/new-fileがシンボリックリンクの親を経由してブロック対象パスまたは設定済みの許可ルート外へ解決される場合、そのバインドは拒否されます。 /var/run/docker.sockをバインドすると、実質的にサンドボックスへホストの制御権を渡すことになります。意図した場合にのみ行ってください。- ワークスペースアクセス（
workspaceAccess）は、バインドモードとは独立しています。
ツールポリシー：存在し、呼び出し可能なツール
次のレイヤーが重要です。
- ツールプロファイル：
tools.profileおよびagents.list[].tools.profile（基本許可リスト） - プロバイダーツールプロファイル：
tools.byProvider[provider].profileおよびagents.list[].tools.byProvider[provider].profile - グローバル／エージェント単位のツールポリシー：
tools.allow/tools.denyおよびagents.list[].tools.allow/agents.list[].tools.deny - プロバイダーツールポリシー：
tools.byProvider[provider].allow/denyおよびagents.list[].tools.byProvider[provider].allow/deny - サンドボックスツールポリシー（サンドボックス化されている場合のみ適用）：
tools.sandbox.tools.allow/tools.sandbox.tools.denyおよびagents.list[].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を使用してください。
ツールグループ（省略記法）
ツールポリシー（グローバル、エージェント、サンドボックス）は、複数のツールに展開される group:* エントリをサポートします。
{ tools: { sandbox: { tools: { allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"], }, }, },}利用可能なグループ：
| グループ | ツール |
|---|---|
group:runtime |
exec、process、code_execution（bash は exec の別名として受け付けられます） |
group:fs |
read、write、edit、apply_patch |
group:sessions |
sessions_list、sessions_history、sessions_send、sessions_spawn、sessions_yield、subagents、session_status |
group:memory |
memory_search、memory_get |
group:web |
web_search、x_search、web_fetch |
group:ui |
browser、canvas |
group:automation |
heartbeat_respond、cron、gateway |
group:messaging |
message |
group:nodes |
nodes、computer |
group:agents |
agents_list、get_goal、create_goal、update_goal、update_plan、skill_workshop |
group:media |
image、image_generate、music_generate、video_generate、tts |
group:openclaw |
OpenClaw の組み込みツールの大部分（ファイルシステムおよびランタイムのプリミティブである read/write/edit/apply_patch/exec/process、canvas、プロバイダーPluginを除く） |
group:plugins |
bundle-mcp を通じて公開される設定済み MCP サーバーを含む、ロード済みPlugin所有のすべてのツール |
読み取り専用エージェントでは、サンドボックスのファイルシステムポリシーまたは別のホスト境界によって読み取り専用制約が強制されていない限り、ファイルシステムを変更するツールに加えて group:runtime も拒否してください。
サンドボックス化された MCP サーバーでは、サンドボックスツールポリシーが2つ目の許可ゲートになります。mcp.servers が設定されているにもかかわらず、サンドボックス化されたターンに組み込みツールしか表示されない場合は、bundle-mcp、group:plugins、または outlook__send_mail や outlook__* のようなサーバープレフィックス付きの MCP ツール名／glob を tools.sandbox.tools.alsoAllow に追加し、Gateway を再起動／再読み込みしてツール一覧を再取得してください。サーバーの glob では、プロバイダーで安全に使用できる MCP サーバープレフィックスを使用します。[A-Za-z0-9_-] 以外の文字は - になり、英字で始まらない名前には mcp- プレフィックスが付き、長いプレフィックスや重複するプレフィックスは切り詰められたりサフィックスが付けられたりする場合があります。
現在、openclaw doctor は mcp.servers 内の OpenClaw 管理サーバーについて、この構成をチェックします。バンドルされたPluginマニフェストまたは Claude の .mcp.json から読み込まれた MCP サーバーにも同じサンドボックスゲートが使用されますが、この診断ではまだそれらのソースを列挙しません。サンドボックス化されたターンでツールが表示されなくなった場合は、同じ許可リストエントリを使用してください。
昇格：exec 専用の「ホスト上で実行」
昇格によって追加のツールが付与されることはありません。影響するのは exec のみです。
- サンドボックス化されている場合、
/elevated on（またはelevated: trueを指定したexec）はサンドボックス外で実行されます（承認が引き続き適用される場合があります）。 - セッションで
execの承認を省略するには、/elevated fullを使用します。 - すでに直接実行している場合、昇格は実質的に何も行いません（ゲートは引き続き適用されます）。
- 昇格は Skills 単位ではなく、ツールの許可／拒否を上書きすることもありません。
- 昇格では、
host=autoから任意の別ホストへ上書きすることはできません。通常のexecターゲットルールに従い、設定済み／セッションのターゲットがすでにnodeの場合にのみnodeを維持します。 /execは昇格とは別です。許可された送信者に対して、セッション単位のexecデフォルトを調整するだけです。
ゲート：
- 有効化：
tools.elevated.enabled（および必要に応じてagents.list[].tools.elevated.enabled） - 送信者の許可リスト：
tools.elevated.allowFrom.<provider>（および必要に応じてagents.list[].tools.elevated.allowFrom.<provider>）
昇格モードを参照してください。
よくある「サンドボックス監獄」の解決方法
「ツール X がサンドボックスツールポリシーによってブロックされた」
修正用キー（いずれか1つを選択）：
- サンドボックスを無効化：
agents.defaults.sandbox.mode=off（またはエージェント単位のagents.list[].sandbox.mode=off） - サンドボックス内でツールを許可：
tools.sandbox.tools.deny（またはエージェント単位のagents.list[].tools.sandbox.tools.deny）からそのツールを削除する- または
tools.sandbox.tools.allow（またはエージェント単位の許可リスト）に追加する
openclaw logsでagents/tool-policyエントリを確認してください。サンドボックスモードと、許可ルールまたは拒否ルールのどちらがツールをブロックしたかが記録されています。
「メインだと思っていたのに、なぜサンドボックス化されているのか？」
"non-main" モードでは、グループ／チャンネルのキーはメインでは_ありません_。メインセッションキー（sandbox explain に表示）を使用するか、モードを "off" に切り替えてください。
関連項目
- サンドボックス化 -- サンドボックスの完全なリファレンス（モード、スコープ、バックエンド、イメージ）
- マルチエージェントのサンドボックスとツール -- エージェント単位の上書きと優先順位
- 昇格モード
