Multi-Agent Sandbox & Tools

概要

マルチエージェント設定内の各エージェントは、独自のものを持つことができるようになりました。

サンドボックス構成 (agents.list[].sandbox は agents.defaults.sandbox をオーバーライドします)
ツールの制限 (tools.allow / tools.deny、および agents.list[].tools)

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

フルアクセスが可能なパーソナルアシスタント
制限されたツールを使用する家族/職場エージェント
サンドボックス内の一般向けエージェント

setupCommand は sandbox.docker (グローバルまたはエージェントごと) に属し、1 回実行されますコンテナが作成されたとき。認証はエージェントごとに行われます。各エージェントは、次の場所にある独自の agentDir 認証ストアから読み取ります。

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

資格情報はエージェント間で共有されません**。エージェント間で agentDir を再利用しないでください。認証情報を共有したい場合は、auth-profiles.json を他のエージェントの agentDir にコピーします。実行時のサンドボックスの動作については、サンドボックスを参照してください。「なぜこれがブロックされるのか?」のデバッグについては、サンドボックス vs ツールポリシー vs 昇格および 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": "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: グローバルコーディングプロファイル + メッセージング専用エージェント

```json
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

結果:

デフォルトのエージェントはコーディングツールを入手します
support エージェントはメッセージング専用です (+ Slack ツール)

例 3: エージェントごとに異なるサンドボックスモード

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main", // Global default
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off" // Override: main never sandboxed
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all", // Override: public always sandboxed
          "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" に解決される場合は無視されます)。

ツールの制限事項

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

ツールプロファイル (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.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 ツール (プロバイダープラグインを除く)

昇格モード

tools.elevated はグローバルベースライン (送信者ベースの許可リスト) です。 agents.list[].tools.elevated は、特定のエージェントの昇格をさらに制限できます (両方が許可する必要があります)。軽減パターン:- 信頼できないエージェントに対して exec を拒否する (agents.list[].tools.deny: ["exec"])

制限されたエージェントにルーティングする送信者を許可リストに登録しないようにします
サンドボックス実行のみが必要な場合は、昇格をグローバルに無効にします (tools.elevated.enabled: false)。
機密プロファイルのエージェントごとの昇格を無効にする (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": {
    "sessions": { "visibility": "tree" },
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

よくある落とし穴: 「非メイン」

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

テスト

マルチエージェントサンドボックスとツールを構成した後:

エージェントの解決策を確認します:
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" を設定します。

拒否リストにもかかわらずツールは引き続き利用可能

ツールのフィルタリング順序を確認します: グローバル → エージェント → サンドボックス → サブエージェント
各レベルはさらに制限することのみが可能であり、元に戻すことはできません
ログで確認: [tools] filtering tools for agent:${agentId}

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

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

概要

組み込みツール

ブラウザ

エージェント連携

スキル

拡張機能

自動化

メディアとデバイス

Multi-Agent Sandbox & Tools

概要

構成例

例 1: 個人 + 制限付き家族代理人

例 2: 共有サンドボックスを使用した作業エージェント

例 3: エージェントごとに異なるサンドボックスモード

構成の優先順位

サンドボックス構成

ツールの制限事項

ツールグループ (略記)

昇格モード

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

ツール制限の例

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

安全な実行エージェント (ファイルの変更なし)

通信専用エージェント

よくある落とし穴: 「非メイン」

テスト

`mode: "all"` にもかかわらず、エージェントはサンドボックス化されていません

拒否リストにもかかわらずツールは引き続き利用可能

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

関連項目

​概要

​構成例

​例 1: 個人 + 制限付き家族代理人

​例 2: 共有サンドボックスを使用した作業エージェント

​例 3: エージェントごとに異なるサンドボックス モード

​構成の優先順位

​サンドボックス構成

​ツールの制限事項

​ツールグループ (略記)

​昇格モード

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

​ツール制限の例

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

​安全な実行エージェント (ファイルの変更なし)

​通信専用エージェント

​よくある落とし穴: 「非メイン」

​テスト

​mode: "all" にもかかわらず、エージェントはサンドボックス化されていません

​拒否リストにもかかわらずツールは引き続き利用可能

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

​関連項目

概要

構成例

例 1: 個人 + 制限付き家族代理人

例 2: 共有サンドボックスを使用した作業エージェント

例 3: エージェントごとに異なるサンドボックスモード

構成の優先順位

サンドボックス構成

ツールの制限事項

ツールグループ (略記)

昇格モード

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

ツール制限の例

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

安全な実行エージェント (ファイルの変更なし)

通信専用エージェント

よくある落とし穴: 「非メイン」

テスト

`mode: "all"` にもかかわらず、エージェントはサンドボックス化されていません

拒否リストにもかかわらずツールは引き続き利用可能

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

関連項目