Agent coordination

Sandbox e strumenti multi-agente

Ogni agente in una configurazione multi-agente può sovrascrivere la sandbox globale e la policy degli strumenti. Questa pagina descrive la configurazione per agente, le regole di precedenza e alcuni esempi.

Sandboxing

Backend e modalità — riferimento completo per la sandbox.

Sandbox vs tool policy vs elevated

Debug di "perché è bloccato?"

Elevated mode

Exec elevato per mittenti attendibili.

Esempi di configurazione

Esempio 1: agente personale + agente famiglia limitato

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

Risultato:

Agente main: viene eseguito sull'host, con accesso completo agli strumenti.
Agente family: viene eseguito in Docker (un container per agente), solo strumento read.

Esempio 2: agente di lavoro con sandbox condivisa

{
  "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 di codifica globale + agente solo messaggistica

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

Risultato:

gli agenti predefiniti ricevono gli strumenti di codifica.
l'agente support è solo messaggistica (+ strumento Slack).

Esempio 3: modalità sandbox diverse per agente

{
  "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 esistono sia configurazioni globali (agents.defaults.*) sia configurazioni specifiche dell'agente (agents.list[].*):

Configurazione della sandbox

Le impostazioni specifiche dell'agente sovrascrivono quelle globali:

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

Restrizioni degli strumenti

L'ordine di filtraggio è:

Profilo strumenti

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

Profilo strumenti del provider

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

Policy globale degli strumenti

tools.allow / tools.deny.

Policy strumenti del provider

tools.byProvider[provider].allow/deny.

Policy strumenti specifica dell'agente

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

Policy provider dell'agente

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

Policy strumenti della sandbox

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

Policy strumenti del sottoagente

tools.subagents.tools, se applicabile.

Regole di precedenza

Ogni livello può restringere ulteriormente gli strumenti, ma non può riabilitare strumenti negati dai livelli precedenti.
Se agents.list[].tools.sandbox.tools è impostato, sostituisce tools.sandbox.tools per quell'agente.
Se agents.list[].tools.profile è impostato, sovrascrive tools.profile per quell'agente.
Le chiavi degli strumenti del provider accettano provider (ad es. google-antigravity) oppure provider/model (ad es. openai/gpt-5.4).

Comportamento della allowlist vuota

Se una allowlist esplicita in questa catena lascia l'esecuzione senza strumenti chiamabili, OpenClaw si arresta prima di inviare il prompt al modello. È intenzionale: un agente configurato con uno strumento mancante come agents.list[].tools.allow: ["query_db"] deve fallire in modo evidente finché il Plugin che registra query_db non viene abilitato, invece di continuare come agente solo testo.

Le policy degli strumenti supportano abbreviazioni group:* che si espandono in più strumenti. Vedi Gruppi di strumenti per l'elenco completo.

Le sovrascritture elevated per agente (agents.list[].tools.elevated) possono limitare ulteriormente l'exec elevato per agenti specifici. Vedi Modalità elevated per i dettagli.

Migrazione da agente singolo

Prima (agente singolo)

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

Dopo (multi-agente)

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

Esempi di restrizione degli strumenti

Agente in sola lettura

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

Esecuzione sicura (nessuna modifica ai file)

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

Solo comunicazione

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

sessions_history in questo profilo restituisce comunque una vista di richiamo limitata e sanificata, invece di un dump grezzo della trascrizione. Il richiamo dell'assistente rimuove tag di ragionamento, impalcature <relevant-memories>, payload XML di chiamate a strumenti in testo semplice (inclusi <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> e blocchi di chiamate a strumenti troncati), impalcature di chiamate a strumenti declassate, token di controllo del modello trapelati ASCII/a larghezza intera e XML di chiamate a strumenti MiniMax malformato prima della redazione/troncamento.

Errore comune: "non-main"

Test

Dopo aver configurato sandbox e strumenti multi-agente:

Controlla la risoluzione degli agenti

openclaw agents list --bindings

Verifica i container della sandbox

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

Testa le restrizioni degli strumenti

Invia un messaggio che richiede strumenti limitati.
Verifica che l'agente non possa usare strumenti negati.

Monitora i log

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

Risoluzione dei problemi

Agente non in sandbox nonostante `mode: 'all'`

Controlla se esiste un agents.defaults.sandbox.mode globale che lo sovrascrive.
La configurazione specifica dell'agente ha la precedenza, quindi imposta agents.list[].sandbox.mode: "all".

Strumenti ancora disponibili nonostante la deny list

Controlla l'ordine di filtraggio degli strumenti: globale → agente → sandbox → sottoagente.
Ogni livello può solo restringere ulteriormente, non riabilitare.
Verifica con i log: [tools] filtering tools for agent:${agentId}.

Container non isolato per agente

Imposta scope: "agent" nella configurazione sandbox specifica dell'agente.
Il valore predefinito è "session", che crea un container per sessione.

Correlati

Modalità elevated
Routing multi-agente
Configurazione della sandbox
Sandbox vs tool policy vs elevated — debug di "perché è bloccato?"
Sandboxing — riferimento completo della sandbox (modalità, ambiti, backend, immagini)
Gestione delle sessioni

# Esempi di configurazione

# Precedenza della configurazione

# Configurazione della sandbox

# Restrizioni degli strumenti

Profilo strumenti

Profilo strumenti del provider

Policy globale degli strumenti

Policy strumenti del provider

Policy strumenti specifica dell'agente

Policy provider dell'agente

Policy strumenti della sandbox

Policy strumenti del sottoagente

# Migrazione da agente singolo

Prima (agente singolo)

Dopo (multi-agente)

# Esempi di restrizione degli strumenti

Agente in sola lettura

Esecuzione sicura (nessuna modifica ai file)

Solo comunicazione

# Errore comune: "non-main"

# Test

Controlla la risoluzione degli agenti

Verifica i container della sandbox

Testa le restrizioni degli strumenti

Monitora i log

# Risoluzione dei problemi

# Correlati

Esempi di configurazione

Precedenza della configurazione

Configurazione della sandbox

Restrizioni degli strumenti

Migrazione da agente singolo

Esempi di restrizione degli strumenti

Errore comune: "non-main"

Test

Risoluzione dei problemi

Correlati