Multi-Agent Sandbox & Tools設定

概要

マルチエージェントセットアップの各エージェントは、独自の以下を持つことができます：

  • サンドボックス設定（agents.list[].sandboxはagents.defaults.sandboxを上書き）
  • ツール制限（tools.allow / tools.deny、およびagents.list[].tools）

これにより、異なるセキュリティプロファイルを持つ複数のエージェントを実行できます：

  • フルアクセスを持つパーソナルアシスタント
  • 制限されたツールを持つ家族/仕事用エージェント
  • サンドボックス内の公開エージェント

setupCommandはsandbox.dockerの下に配置され（グローバルまたはエージェントごと）、コンテナの作成時に一度実行されます。

認証はエージェントごとです：各エージェントは、以下の独自のagentDir認証ストアから読み取ります：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

認証情報はエージェント間で共有されません。エージェント間でagentDirを再利用しないでください。認証情報を共有したい場合は、auth-profiles.jsonを他のエージェントのagentDirにコピーしてください。

ランタイムでのサンドボックス動作については、Sandboxingを参照してください。「なぜこれがブロックされているのか？」のデバッグについては、Sandbox vs Tool Policy vs Elevatedおよびopenclaw sandbox explainを参照してください。

設定例

例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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "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"  // オーバーライド：mainは決してサンドボックス化されない
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",  // オーバーライド：publicは常にサンドボックス化
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

設定の優先順位

グローバル（agents.defaults.*）とエージェント固有（agents.list[].*）の設定の両方が存在する場合：

サンドボックス設定

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

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

注意：

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

ツール制限

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

  1. ツールプロファイル（tools.profileまたはagents.list[].tools.profile）
  2. プロバイダーツールプロファイル（tools.byProvider[provider].profileまたはagents.list[].tools.byProvider[provider].profile）
  3. グローバルツールポリシー（tools.allow / tools.deny）
  4. プロバイダーツールポリシー（tools.byProvider[provider].allow/deny）
  5. エージェント固有ツールポリシー（agents.list[].tools.allow/deny）
  6. エージェントプロバイダーポリシー（agents.list[].tools.byProvider[provider].allow/deny）
  7. サンドボックスツールポリシー（tools.sandbox.toolsまたはagents.list[].tools.sandbox.tools）
  8. サブエージェントツールポリシー（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.2）のいずれかを受け入れます。

ツールグループ（ショートハンド）

ツールポリシー（グローバル、エージェント、サンドボックス）は、複数の具体的なツールに展開されるgroup:*エントリをサポートします：

  • group:runtime: exec, bash, process
  • group:fs: read, write, edit, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory: memory_search, memory_get
  • group:ui: browser, canvas
  • group:automation: cron, gateway
  • group:messaging: message
  • group:nodes: nodes
  • group:openclaw: すべての組み込みOpenClawツール（プロバイダープラグインを除く）

Elevatedモード

tools.elevatedはグローバルベースライン（送信者ベース許可リスト）です。agents.list[].tools.elevatedは、特定のエージェントに対してelevatedをさらに制限できます（両方が許可する必要があります）。

緩和パターン：

  • 信頼できないエージェントに対してexecを拒否（agents.list[].tools.deny: ["exec"]）
  • 制限されたエージェントにルーティングする送信者を許可リストに入れない
  • サンドボックス化された実行のみが必要な場合は、elevatedをグローバルに無効化（tools.elevated.enabled: false）
  • 機密プロファイルのためにエージェントごとにelevatedを無効化（agents.list[].tools.elevated.enabled: false）

シングルエージェントからの移行

以前（シングルエージェント）：

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

レガシーagent.*設定はopenclaw doctorによって移行されます。今後はagents.defaults + agents.listを優先してください。

ツール制限の例

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

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

安全な実行エージェント（ファイル変更なし）

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

コミュニケーション専用エージェント

{
  "tools": {
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

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

agents.defaults.sandbox.mode: "non-main"は、エージェントIDではなく、session.mainKey（デフォルト"main"）に基づいています。グループ/チャネルセッションは常に独自のキーを取得するため、非メインとして扱われ、サンドボックス化されます。エージェントを決してサンドボックス化しない場合は、agents.list[].sandbox.mode: "off"を設定してください。

テスト

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

  1. エージェント解決をチェック：

    openclaw agents list --bindings

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

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

  3. ツール制限をテスト：

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

  4. ログを監視：

    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"を設定

拒否リストにもかかわらずツールがまだ利用可能

  • ツールフィルタリングの順序をチェック：グローバル → エージェント → サンドボックス → サブエージェント
  • 各レベルはさらに制限することしかできず、戻すことはできない
  • ログで確認：[tools] filtering tools for agent:${agentId}

コンテナがエージェントごとに分離されない

  • エージェント固有のサンドボックス設定でscope: "agent"を設定
  • デフォルトは"session"で、セッションごとに1つのコンテナを作成

関連項目

← ドキュメントに戻る