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

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

サンドボックス化

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

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

信頼できる送信者向けの昇格 exec。

設定例

例 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.entries.*.*）設定の両方が存在する場合：

サンドボックス設定

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

text
agents.entries.*.sandbox.mode > agents.defaults.sandbox.modeagents.entries.*.sandbox.scope > agents.defaults.sandbox.scopeagents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

ツール制限

フィルタリングの順序は次のとおりです。

  • ツールプロファイル

    tools.profile または agents.entries.*.tools.profile。

  • プロバイダーのツールプロファイル

    tools.byProvider[provider].profile または agents.entries.*.tools.byProvider[provider].profile。

  • グローバルツールポリシー

    tools.allow / tools.deny。

  • プロバイダーのツールポリシー

    tools.byProvider[provider].allow/deny。

  • エージェント固有のツールポリシー

    agents.entries.*.tools.allow/deny。

  • エージェントのプロバイダーポリシー

    agents.entries.*.tools.byProvider[provider].allow/deny。

  • サンドボックスのツールポリシー

    tools.sandbox.tools または agents.entries.*.tools.sandbox.tools。

  • サブエージェントのツールポリシー

    該当する場合は tools.subagents.tools。

    • 優先順位規則
    • 各レベルでツールをさらに制限できますが、それ以前のレベルで拒否されたツールを再び許可することはできません。
    • agents.entries.*.tools.sandbox.tools が設定されている場合、そのエージェントでは tools.sandbox.tools が置き換えられます。
    • agents.entries.*.tools.profile が設定されている場合、そのエージェントでは tools.profile が上書きされます。
    • プロバイダーのツールキーには、provider（例：google-antigravity）または provider/model（例：openai/gpt-5.4）のいずれかを使用できます。
    空の許可リストの動作

    このチェーン内の明示的な許可リストのいずれかにより、実行可能なツールがなくなった場合、OpenClaw はモデルにプロンプトを送信する前に停止します。これは意図された動作です。agents.entries.*.tools.allow: ["query_db"] のような存在しないツールを設定したエージェントは、query_db を登録する Plugin が有効になるまで明示的に失敗する必要があり、テキスト専用エージェントとして処理を継続してはなりません。

    ツールポリシーでは、複数のツールに展開される group:* の短縮表記をサポートしています。完全な一覧については、ツールグループを参照してください。

    エージェントごとの昇格オーバーライド（agents.entries.*.tools.elevated）により、特定のエージェントに対する昇格 exec をさらに制限できます。詳細については、昇格モードを参照してください。

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

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

    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.entries.*.sandbox.mode: "all" を設定します。
    拒否リストがあっても使用可能なツール
    • フィルタリングの全順序を確認してください：プロファイル → プロバイダープロファイル → グローバルポリシー → プロバイダーポリシー → エージェントポリシー → エージェントプロバイダーポリシー → サンドボックス → サブエージェント。
    • 各レベルでは制限をさらに追加できるだけで、権限を再付与することはできません。
    • 段階的なデバッグ方法については、サンドボックスとツールポリシーと昇格モードの比較を参照してください。
    エージェントごとにコンテナが分離されていない
    • デフォルトの scope は "agent"（エージェント ID ごとに 1 つのコンテナ）です。
    • セッションごとに 1 つのコンテナを使用するには scope: "session" を設定し、エージェント間で 1 つのコンテナを再利用するには scope: "shared" を設定します。

    関連項目

    Was this useful?
    On this page

    On this page