Agent coordination

Sandbox en hulpmiddelen voor meerdere agenten

Elke agent in een multi-agent-configuratie kan de globale sandbox- en toolpolicy overschrijven. Deze pagina behandelt configuratie per agent, voorrangsregels en voorbeelden.

Sandboxing

Backends en modi — volledige sandboxreferentie.

Sandbox vs tool policy vs elevated

Debuggen: "waarom is dit geblokkeerd?"

Elevated mode

Elevated exec voor vertrouwde afzenders.

Configuratievoorbeelden

Voorbeeld 1: persoonlijke + beperkte gezinsagent

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

Resultaat:

main-agent: draait op host, volledige tooltoegang.
family-agent: draait in Docker (één container per agent), alleen de read-tool.

Voorbeeld 2: werkagent met gedeelde sandbox

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

Voorbeeld 2b: globaal codeerprofiel + agent alleen voor berichten

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

Resultaat:

standaardagents krijgen codeertools.
support-agent is alleen voor berichten (+ Slack-tool).

Voorbeeld 3: verschillende sandboxmodi per agent

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

Configuratievoorrang

Wanneer zowel globale (agents.defaults.*) als agentspecifieke (agents.list[].*) configuraties bestaan:

Sandboxconfiguratie

Agentspecifieke instellingen overschrijven globale instellingen:

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.*

Toolbeperkingen

De filtervolgorde is:

Toolprofiel

tools.profile of agents.list[].tools.profile.

Providertoolprofiel

tools.byProvider[provider].profile of agents.list[].tools.byProvider[provider].profile.

Globale toolpolicy

tools.allow / tools.deny.

Providertoolpolicy

tools.byProvider[provider].allow/deny.

Agentspecifieke toolpolicy

agents.list[].tools.allow/deny.

Agentproviderpolicy

agents.list[].tools.byProvider[provider].allow/deny.

Sandboxtoolpolicy

tools.sandbox.tools of agents.list[].tools.sandbox.tools.

Subagent-toolpolicy

tools.subagents.tools, indien van toepassing.

Voorrangsregels

Elk niveau kan tools verder beperken, maar kan eerder geweigerde tools niet opnieuw toestaan.
Als agents.list[].tools.sandbox.tools is ingesteld, vervangt dit tools.sandbox.tools voor die agent.
Als agents.list[].tools.profile is ingesteld, overschrijft dit tools.profile voor die agent.
Providertool-sleutels accepteren zowel provider (bijv. google-antigravity) als provider/model (bijv. openai/gpt-5.4).

Gedrag bij lege allowlist

Als een expliciete allowlist in die keten ervoor zorgt dat de run geen aanroepbare tools meer heeft, stopt OpenClaw voordat de prompt naar het model wordt gestuurd. Dit is opzettelijk: een agent die is geconfigureerd met een ontbrekende tool zoals agents.list[].tools.allow: ["query_db"] moet duidelijk falen totdat de Plugin die query_db registreert is ingeschakeld, en niet doorgaan als agent met alleen tekst.

Toolpolicy's ondersteunen group:*-verkortingen die uitvouwen naar meerdere tools. Zie Toolgroepen voor de volledige lijst.

Per-agent elevated-overschrijvingen (agents.list[].tools.elevated) kunnen elevated exec voor specifieke agents verder beperken. Zie Elevated mode voor details.

Migratie vanaf één agent

Voor (één agent)

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

Na (multi-agent)

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

Voorbeelden van toolbeperkingen

Alleen-lezen agent

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

Veilige uitvoering (geen bestandswijzigingen)

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

Alleen communicatie

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

sessions_history in dit profiel retourneert nog steeds een begrensde, opgeschoonde recall-weergave in plaats van een ruwe transcriptdump. Assistant-recall verwijdert denktags, <relevant-memories>-scaffolding, platte-tekst XML-payloads voor toolaanroepen (waaronder <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> en afgekorte toolaanroepblokken), gedegradeerde toolaanroep-scaffolding, gelekte ASCII-/full-width modelbesturingstokens en misvormde MiniMax-toolaanroep-XML vóór redactie/afkapping.

Veelvoorkomende valkuil: "non-main"

Testen

Na het configureren van multi-agent-sandbox en tools:

Agentresolutie controleren

openclaw agents list --bindings

Sandboxcontainers verifiëren

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

Toolbeperkingen testen

Stuur een bericht waarvoor beperkte tools nodig zijn.
Controleer of de agent geweigerde tools niet kan gebruiken.

Logs bewaken

tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

Probleemoplossing

Agent niet in sandbox ondanks `mode: 'all'`

Controleer of er een globale agents.defaults.sandbox.mode is die dit overschrijft.
Agentspecifieke configuratie heeft voorrang, dus stel agents.list[].sandbox.mode: "all" in.

Tools nog steeds beschikbaar ondanks denylist

Controleer de toolfiltervolgorde: globaal → agent → sandbox → subagent.
Elk niveau kan alleen verder beperken, niet opnieuw toestaan.
Verifieer met logs: [tools] filtering tools for agent:${agentId}.

Container niet per agent geïsoleerd

Stel scope: "agent" in de agentspecifieke sandboxconfiguratie in.
Standaard is "session", wat één container per sessie maakt.

Gerelateerd

Elevated mode
Multi-agent-routing
Sandboxconfiguratie
Sandbox vs tool policy vs elevated — debuggen: "waarom is dit geblokkeerd?"
Sandboxing — volledige sandboxreferentie (modi, bereiken, backends, images)
Sessiebeheer