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

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

サンドボックス化

バックエンドとモード — サンドボックスの完全なリファレンス。

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

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

昇格モード

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

認証はエージェント単位でスコープされます。各エージェントは ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite に独自の agentDir 認証ストアを持ちます。エージェント間で agentDir を再利用しないでください。ローカルプロファイルがない場合、エージェントはデフォルト／メインエージェントの認証プロファイルを参照できますが、OAuth リフレッシュトークンはセカンダリエージェントのストアに複製されません。認証情報を手動でコピーする場合は、移植可能な静的 api_key または token プロファイルのみをコピーしてください。

設定例

例 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": "120363424282127706@g.us"
        }
      }
    }
  ]
}

結果：

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

サンドボックス設定

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

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.sandbox.{docker,browser,prune}.* は、そのエージェントの agents.defaults.sandbox.{docker,browser,prune}.* を上書きします（サンドボックスのスコープが "shared" に解決される場合は無視されます）。

ツール制限

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

ツールプロファイル

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 をさらに制限できます。詳細については、昇格モードを参照してください。

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

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

{
  "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" }
      }
    ]
  }
}

従来の agents.defaults.*/agents.entries.*.* 設定キー（sandbox.perSession、agentRuntime、embeddedPi など）は openclaw doctor によって移行されます。今後は agents.defaults + agents.entries を使用してください。

ツール制限の例

読み取り専用エージェント
ファイルシステムツールを無効にしたシェル実行
通信専用

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

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

このポリシーは OpenClaw のファイルシステムツールを無効にしますが、exec は引き続きシェルであり、選択したホストまたはサンドボックスのファイルシステムで許可されている任意の場所にファイルを書き込めます。読み取り専用エージェントにするには、exec と process を拒否するか、シェルアクセスと agents.defaults.sandbox.workspaceAccess: "ro" または "none" などのサンドボックスファイルシステム制御を組み合わせてください。

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

agents.defaults.sandbox.mode: "non-main" は、エージェント ID ではなく、セッションキーをメインセッションキー（常に "main"。session.mainKey はユーザーが設定できず、他の値を指定すると OpenClaw が警告して無視します）と照合します。グループ／チャンネルセッションには常に独自のキーが割り当てられるため、non-main として扱われ、サンドボックス化されます。エージェントをサンドボックス化しない場合は、agents.entries.*.sandbox.mode: "off" を設定してください。

テスト

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

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

openclaw agents list --bindings

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

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

ツール制限をテスト

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

ログを監視

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" を設定します。

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

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

サンドボックス化

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

昇格モード

設定例

設定の優先順位

サンドボックス設定

ツール制限

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

ツール制限の例

よくある落とし穴：「non-main」

テスト

トラブルシューティング

関連項目

サンドボックス化

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

昇格モード

​設定例

​設定の優先順位

​サンドボックス設定

​ツール制限

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

​ツール制限の例

​よくある落とし穴：「non-main」

​テスト

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

​関連項目

設定例

設定の優先順位

サンドボックス設定

ツール制限

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

ツール制限の例

よくある落とし穴：「non-main」

テスト

トラブルシューティング

関連項目