OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

Sandbox e strumenti multi-agente

Status: active

Ogni agente in una configurazione multi-agente può sostituire le impostazioni globali dell'ambiente isolato e dei criteri degli strumenti. Questa pagina illustra la configurazione per agente, le regole di precedenza e alcuni esempi.

Isolamento

Backend e modalità — riferimento completo per l'ambiente isolato.
Ambiente isolato, criteri degli strumenti e privilegi elevati

Esegui il debug di «perché questa operazione è bloccata?»
Modalità con privilegi elevati

Esecuzione con privilegi elevati per mittenti attendibili.

Esempi di configurazione

Esempio 1: agente personale e agente familiare con restrizioni
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"        }      }    }  ]}

Risultato:

  • Agente main: viene eseguito sull'host con accesso completo agli strumenti.
  • Agente family: viene eseguito in Docker (un contenitore per agente) e può usare solo read e inviare messaggi nella conversazione corrente.
Esempio 2: agente di lavoro con ambiente isolato condiviso
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"]        }      }    ]  }}
Esempio 2b: profilo globale di programmazione e agente dedicato esclusivamente alla messaggistica
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Risultato:

  • Gli agenti predefiniti ricevono gli strumenti di programmazione.
  • L'agente support è dedicato esclusivamente alla messaggistica (più lo strumento Slack).
Esempio 3: modalità dell'ambiente isolato diverse per ogni agente
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"]        }      }    ]  }}

Precedenza della configurazione

Quando sono presenti sia configurazioni globali (agents.defaults.*) sia configurazioni specifiche dell'agente (agents.list[].*):

Configurazione dell'ambiente isolato

Le impostazioni specifiche dell'agente sostituiscono quelle globali:

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

Restrizioni degli strumenti

L'ordine di applicazione dei filtri è il seguente:

  • Profilo degli strumenti

    tools.profile o agents.list[].tools.profile.

  • Profilo degli strumenti del provider

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

  • Criteri globali degli strumenti

    tools.allow / tools.deny.

  • Criteri degli strumenti del provider

    tools.byProvider[provider].allow/deny.

  • Criteri degli strumenti specifici dell'agente

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

  • Criteri del provider dell'agente

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

  • Criteri degli strumenti dell'ambiente isolato

    tools.sandbox.tools o agents.list[].tools.sandbox.tools.

  • Criteri degli strumenti dei sottoagenti

    tools.subagents.tools, se applicabile.

    • Regole di precedenza
    • Ogni livello può limitare ulteriormente gli strumenti, ma non può ripristinare strumenti negati dai livelli precedenti.
    • Se è impostato agents.list[].tools.sandbox.tools, questo sostituisce tools.sandbox.tools per quell'agente.
    • Se è impostato agents.list[].tools.profile, questo sostituisce tools.profile per quell'agente.
    • Le chiavi degli strumenti del provider accettano provider (ad esempio google-antigravity) oppure provider/model (ad esempio openai/gpt-5.4).
    Comportamento di una lista di elementi consentiti vuota

    Se una lista esplicita di strumenti consentiti nella catena non lascia alcuno strumento richiamabile per l'esecuzione, OpenClaw si arresta prima di inviare il prompt al modello. Questo comportamento è intenzionale: un agente configurato con uno strumento mancante, ad esempio agents.list[].tools.allow: ["query_db"], deve generare un errore evidente finché non viene abilitato il Plugin che registra query_db, anziché continuare come agente di solo testo.

    I criteri degli strumenti supportano abbreviazioni group:* che si espandono in più strumenti. Consulta Gruppi di strumenti per l'elenco completo.

    Le sostituzioni per agente relative ai privilegi elevati (agents.list[].tools.elevated) possono limitare ulteriormente l'esecuzione con privilegi elevati per agenti specifici. Consulta Modalità con privilegi elevati per i dettagli.

    Migrazione da un singolo agente

    Prima (agente singolo)

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

    Dopo (multi-agente)

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

    Esempi di restrizioni degli strumenti

    Agente di sola lettura

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

    Esecuzione della shell con gli strumenti del file system disabilitati

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

    Solo comunicazione

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

    In questo profilo, sessions_history restituisce comunque una vista di richiamo limitata e sanificata, anziché un dump della trascrizione non elaborata. Il richiamo dell'assistente rimuove i tag di ragionamento, la struttura <relevant-memories>, i payload XML in testo normale delle chiamate agli strumenti (inclusi <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> e i blocchi troncati delle chiamate agli strumenti), la struttura degradata delle chiamate agli strumenti, i token di controllo del modello ASCII/a larghezza intera trapelati e l'XML non valido delle chiamate agli strumenti MiniMax prima dell'oscuramento e del troncamento.

    Errore comune: "non-main"

    Verifica

    Dopo aver configurato l'ambiente isolato e gli strumenti multi-agente:

  • Controlla la risoluzione degli agenti

    bash
    openclaw agents list --bindings

  • Verifica i contenitori dell'ambiente isolato

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

  • Verifica le restrizioni degli strumenti

    • Invia un messaggio che richieda strumenti soggetti a restrizioni.
    • Verifica che l'agente non possa utilizzare gli strumenti negati.

  • Monitora i log

    bash
    openclaw logs --follow | grep -E "routing|sandbox|tools"

    • Risoluzione dei problemi

    L'agente non viene eseguito in un ambiente isolato nonostante `mode: 'all'`
    • Controlla se è presente un valore globale agents.defaults.sandbox.mode che lo sostituisce.
    • La configurazione specifica dell'agente ha la precedenza, quindi imposta agents.list[].sandbox.mode: "all".
    Strumenti ancora disponibili nonostante l'elenco di esclusione
    Container non isolato per agente
    • Il valore predefinito di scope è "agent" (un container per ID agente).
    • Imposta scope: "session" per avere un container per sessione oppure scope: "shared" per riutilizzare un container tra più agenti.

    Contenuti correlati

    Was this useful?
    On this page

    On this page