Agent coordination
マルチエージェントのサンドボックスとツール
マルチエージェント設定内の各エージェントは、グローバルなサンドボックスとツールポリシーを上書きできます。このページでは、エージェントごとの設定、優先順位ルール、例について説明します。
バックエンドとモード — サンドボックスの完全なリファレンス。
「なぜこれはブロックされるのか?」をデバッグする。
信頼済み送信者向けの昇格済み exec。
設定例
例 1: 個人用 + 制限付きファミリーエージェント
{ "agents": { "list": [ { "id": "main", "default": true, "name": "Personal Assistant", "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } }, { "id": "family", "name": "Family Bot", "workspace": "~/.openclaw/workspace-family", "sandbox": { "mode": "all", "scope": "agent" }, "tools": { "allow": ["read", "message"], "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"], "message": { "crossContext": { "allowWithinProvider": false, "allowAcrossProviders": false } } } } ] }, "bindings": [ { "agentId": "family", "match": { "provider": "whatsapp", "accountId": "*", "peer": { "kind": "group", "id": "[email protected]" } } } ]}結果:
mainエージェント: ホスト上で実行され、すべてのツールにアクセスできます。familyエージェント: Docker 内で実行され (エージェントごとに 1 つのコンテナ)、readと現在の会話へのメッセージ送信のみが許可されます。
例 2: 共有サンドボックスを使う仕事用エージェント
{ "agents": { "list": [ { "id": "personal", "workspace": "~/.openclaw/workspace-personal", "sandbox": { "mode": "off" } }, { "id": "work", "workspace": "~/.openclaw/workspace-work", "sandbox": { "mode": "all", "scope": "shared", "workspaceRoot": "/tmp/work-sandboxes" }, "tools": { "allow": ["read", "write", "apply_patch", "exec"], "deny": ["browser", "gateway", "discord"] } } ] }}例 2b: グローバルなコーディングプロファイル + メッセージング専用エージェント
{ "tools": { "profile": "coding" }, "agents": { "list": [ { "id": "support", "tools": { "profile": "messaging", "allow": ["slack"] } } ] }}結果:
- デフォルトエージェントはコーディングツールを取得します。
supportエージェントはメッセージング専用です (+ Slack ツール)。
例 3: エージェントごとに異なるサンドボックスモード
{ "agents": { "defaults": { "sandbox": { "mode": "non-main", "scope": "session" } }, "list": [ { "id": "main", "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } }, { "id": "public", "workspace": "~/.openclaw/workspace-public", "sandbox": { "mode": "all", "scope": "agent" }, "tools": { "allow": ["read"], "deny": ["exec", "write", "edit", "apply_patch"] } } ] }}設定の優先順位
グローバル (agents.defaults.*) とエージェント固有 (agents.list[].*) の両方の設定が存在する場合:
サンドボックス設定
エージェント固有の設定がグローバル設定を上書きします。
agents.list[].sandbox.mode > agents.defaults.sandbox.modeagents.list[].sandbox.scope > agents.defaults.sandbox.scopeagents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*ツール制限
フィルタリング順序は次のとおりです。
ツールプロファイル
tools.profile または agents.list[].tools.profile。
プロバイダーツールプロファイル
tools.byProvider[provider].profile または agents.list[].tools.byProvider[provider].profile。
グローバルツールポリシー
tools.allow / tools.deny。
プロバイダーツールポリシー
tools.byProvider[provider].allow/deny。
エージェント固有のツールポリシー
agents.list[].tools.allow/deny。
エージェントプロバイダーポリシー
agents.list[].tools.byProvider[provider].allow/deny。
サンドボックスツールポリシー
tools.sandbox.tools または agents.list[].tools.sandbox.tools。
サブエージェントツールポリシー
該当する場合は tools.subagents.tools。
優先順位ルール
- 各レベルでツールをさらに制限できますが、前のレベルで拒否されたツールを再び許可することはできません。
agents.list[].tools.sandbox.toolsが設定されている場合、そのエージェントではtools.sandbox.toolsを置き換えます。agents.list[].tools.profileが設定されている場合、そのエージェントではtools.profileを上書きします。- プロバイダーツールキーには、
provider(例:google-antigravity) またはprovider/model(例:openai/gpt-5.4) を指定できます。
空の許可リストの動作
そのチェーン内の明示的な許可リストによって呼び出し可能なツールが 1 つも残らない場合、OpenClaw はプロンプトをモデルに送信する前に停止します。これは意図された動作です。agents.list[].tools.allow: ["query_db"] のように存在しないツールで設定されたエージェントは、query_db を登録する Plugin が有効化されるまで明確に失敗すべきであり、テキスト専用エージェントとして続行すべきではありません。
ツールポリシーは、複数のツールに展開される group:* 省略形をサポートします。完全な一覧は ツールグループ を参照してください。
エージェントごとの昇格上書き (agents.list[].tools.elevated) で、特定のエージェントの昇格済み exec をさらに制限できます。詳しくは 昇格モード を参照してください。
単一エージェントからの移行
移行前（単一エージェント）
{ "agents": { "defaults": { "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "non-main" } } }, "tools": { "sandbox": { "tools": { "allow": ["read", "write", "apply_patch", "exec"], "deny": [] } } }}移行後（マルチエージェント）
{ "agents": { "list": [ { "id": "main", "default": true, "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } } ] }}ツール制限の例
読み取り専用エージェント
{ "tools": { "allow": ["read"], "deny": ["exec", "write", "edit", "apply_patch", "process"] }}ファイルシステムツールを無効にしたシェル実行
{ "tools": { "allow": ["read", "exec", "process"], "deny": ["write", "edit", "apply_patch", "browser", "gateway"] }}通信のみ
{ "tools": { "sessions": { "visibility": "tree" }, "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"], "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"] }}このプロファイルの sessions_history は、生のトランスクリプトダンプではなく、境界が設定されサニタイズされたリコールビューを返します。アシスタントのリコールでは、思考タグ、<relevant-memories> の足場、プレーンテキストのツール呼び出し XML ペイロード（<tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls>、および切り詰められたツール呼び出しブロックを含む）、格下げされたツール呼び出しの足場、漏えいした ASCII/全角のモデル制御トークン、不正な MiniMax ツール呼び出し XML を、リダクション/切り詰めの前に除去します。
よくある落とし穴: "non-main"
テスト
マルチエージェントサンドボックスとツールを設定した後:
エージェント解決を確認する
openclaw agents list --bindingsサンドボックスコンテナを検証する
docker ps --filter "name=openclaw-sbx-"ツール制限をテストする
- 制限付きツールを必要とするメッセージを送信します。
- エージェントが拒否されたツールを使用できないことを確認します。
ログを監視する
tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"トラブルシューティング
`mode: 'all'` にもかかわらずエージェントがサンドボックス化されない
- それを上書きするグローバルな
agents.defaults.sandbox.modeがあるか確認します。 - エージェント固有の設定が優先されるため、
agents.list[].sandbox.mode: "all"を設定します。
deny list にもかかわらずツールがまだ利用可能
- ツールフィルタリングの順序を確認します: グローバル → エージェント → サンドボックス → サブエージェント。
- 各レベルではさらに制限することだけが可能で、許可を戻すことはできません。
- ログで確認します:
[tools] filtering tools for agent:${agentId}。
コンテナがエージェントごとに分離されていない
- エージェント固有のサンドボックス設定で
scope: "agent"を設定します。 - デフォルトは
"session"で、セッションごとに 1 つのコンテナを作成します。
関連
- 昇格モード
- マルチエージェントルーティング
- サンドボックス設定
- サンドボックス vs ツールポリシー vs 昇格 — 「これはなぜブロックされているのか？」のデバッグ
- サンドボックス化 — サンドボックスの完全なリファレンス（モード、スコープ、バックエンド、イメージ）
- セッション管理