OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

マルチエージェントのサンドボックスとツール

Status: active

マルチエージェント構成では、各エージェントがグローバルなサンドボックスおよびツールポリシーを上書きできます。このページでは、エージェントごとの設定、優先順位ルール、例について説明します。

サンドボックス化

バックエンドとモード — サンドボックスの完全なリファレンス。
サンドボックス、ツールポリシー、昇格の違い

「なぜこれがブロックされるのか？」をデバッグします。
昇格モード

信頼済み送信者向けの昇格された実行。

設定例

例 1：個人用エージェントと制限付き家族用エージェント
json
{  "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": "120363424282127706@g.us"        }      }    }  ]}

結果：

  • main エージェント：ホスト上で実行され、すべてのツールにアクセスできます。
  • family エージェント：Docker 内で実行され（エージェントごとに 1 コンテナ）、read と現在の会話へのメッセージ送信のみを使用できます。
例 2：共有サンドボックスを使用する仕事用エージェント
json
{  "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：グローバルなコーディングプロファイルとメッセージ専用エージェント
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

結果：

  • デフォルトのエージェントにはコーディングツールが適用されます。
  • support エージェントはメッセージ専用です（Slack ツールを追加）。
例 3：エージェントごとに異なるサンドボックスモード
json
{  "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[].*）の両方が存在する場合：

サンドボックス設定

エージェント固有の設定がグローバル設定を上書きします。

text
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）により、特定のエージェントに対する昇格された実行をさらに制限できます。詳細については、昇格モードを参照してください。

    単一エージェントからの移行

    移行前（単一エージェント）

    json
    {  "agents": {    "defaults": {      "workspace": "~/.openclaw/workspace",      "sandbox": {        "mode": "non-main"      }    }  },  "tools": {    "sandbox": {      "tools": {        "allow": ["read", "write", "apply_patch", "exec"],        "deny": []      }    }  }}

    移行後（マルチエージェント）

    json
    {  "agents": {    "list": [      {        "id": "main",        "default": true,        "workspace": "~/.openclaw/workspace",        "sandbox": { "mode": "off" }      }    ]  }}

    ツール制限の例

    読み取り専用エージェント

    json
    {  "tools": {    "allow": ["read"],    "deny": ["exec", "write", "edit", "apply_patch", "process"]  }}

    ファイルシステムツールを無効にしたシェル実行

    json
    {  "tools": {    "allow": ["read", "exec", "process"],    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]  }}

    通信専用

    json
    {  "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"

    テスト

    マルチエージェントのサンドボックスとツールを設定した後：

  • エージェントの解決結果を確認

    bash
    openclaw agents list --bindings

  • サンドボックスコンテナを確認

    bash
    docker ps --filter "name=openclaw-sbx-"

  • ツール制限をテスト

    • 制限対象のツールを必要とするメッセージを送信します。
    • エージェントが拒否されたツールを使用できないことを確認します。

  • ログを監視

    bash
    openclaw logs --follow | grep -E "routing|sandbox|tools"

    • トラブルシューティング

    `mode: 'all'` にもかかわらずエージェントがサンドボックス化されない
    • それを上書きするグローバルな agents.defaults.sandbox.mode が存在しないか確認します。
    • エージェント固有の設定が優先されるため、agents.list[].sandbox.mode: "all" を設定します。
    拒否リストがあっても利用可能なツール
    • 完全なフィルタリング順序を確認してください：プロファイル → プロバイダープロファイル → グローバルポリシー → プロバイダーポリシー → エージェントポリシー → エージェントプロバイダーポリシー → サンドボックス → サブエージェント。
    • 各レベルでは制限をさらに強化できるだけで、権限を再付与することはできません。
    • 段階的なデバッグ手順については、サンドボックス、ツールポリシー、昇格の比較を参照してください。
    エージェントごとにコンテナが分離されていない
    • デフォルトの scope は "agent" です（エージェント ID ごとに 1 つのコンテナ）。
    • セッションごとに 1 つのコンテナを使用するには scope: "session" を設定し、複数のエージェントで 1 つのコンテナを再利用するには scope: "shared" を設定します。

    関連項目

    Was this useful?
    On this page

    On this page