Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Jeder Agent in einer Multi-Agent-Konfiguration kann die globale Sandbox- und Tool-Richtlinie überschreiben. Diese Seite behandelt die Konfiguration pro Agent, Vorrangregeln und Beispiele.

Sandboxing

Backends und Modi — vollständige Sandbox-Referenz.

Sandbox vs. Tool-Richtlinie vs. Elevated

Debugging von „warum ist das blockiert?“

Elevated-Modus

Elevated exec für vertrauenswürdige Absender.
Die Authentifizierung ist nach Agent abgegrenzt: Jeder Agent hat seinen eigenen agentDir-Authentifizierungsspeicher unter ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. Verwenden Sie agentDir niemals agentenübergreifend wieder. Agents können auf die Authentifizierungsprofile des Standard-/Haupt-Agent zugreifen, wenn sie kein lokales Profil haben, aber OAuth-Aktualisierungstoken werden nicht in sekundäre Agent-Speicher geklont. Wenn Sie Zugangsdaten manuell kopieren, kopieren Sie nur portable statische api_key- oder token-Profile.

​
Konfigurationsbeispiele

{
  "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"
        }
      }
    }
  ]
}
Ergebnis:
  • main-Agent: läuft auf dem Host, vollständiger Tool-Zugriff.
  • family-Agent: läuft in Docker (ein Container pro Agent), nur read und Nachrichtenversand in der aktuellen Unterhaltung.
{
  "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"]
        }
      }
    ]
  }
}

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}
Ergebnis:
  • Standard-Agents erhalten Coding-Tools.
  • Der support-Agent ist nur für Messaging vorgesehen (+ Slack-Tool).
{
  "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"]
        }
      }
    ]
  }
}

​
Konfigurationsvorrang

Wenn sowohl globale (agents.defaults.*) als auch agentenspezifische (agents.list[].*) Konfigurationen vorhanden sind:

​
Sandbox-Konfiguration

Agentenspezifische Einstellungen überschreiben globale Einstellungen: 
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}.* überschreibt agents.defaults.sandbox.{docker,browser,prune}.* für diesen Agent (wird ignoriert, wenn der Sandbox-Scope zu "shared" aufgelöst wird).

​
Tool-Einschränkungen

Die Filterreihenfolge lautet:
1

Tool-Profil

tools.profile oder agents.list[].tools.profile.
2

Provider-Tool-Profil

tools.byProvider[provider].profile oder agents.list[].tools.byProvider[provider].profile.
3

Globale Tool-Richtlinie

tools.allow / tools.deny.
4

Provider-Tool-Richtlinie

tools.byProvider[provider].allow/deny.
5

Agentenspezifische Tool-Richtlinie

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

Agent-Provider-Richtlinie

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

Sandbox-Tool-Richtlinie

tools.sandbox.tools oder agents.list[].tools.sandbox.tools.
8

Subagent-Tool-Richtlinie

tools.subagents.tools, falls zutreffend.
  • Jede Ebene kann Tools weiter einschränken, aber zuvor verweigerte Tools aus früheren Ebenen nicht wieder gewähren.
  • Wenn agents.list[].tools.sandbox.tools gesetzt ist, ersetzt es tools.sandbox.tools für diesen Agent.
  • Wenn agents.list[].tools.profile gesetzt ist, überschreibt es tools.profile für diesen Agent.
  • Provider-Tool-Schlüssel akzeptieren entweder provider (z. B. google-antigravity) oder provider/model (z. B. openai/gpt-5.4).
Wenn eine explizite Allowlist in dieser Kette dazu führt, dass für den Lauf keine aufrufbaren Tools übrig bleiben, stoppt OpenClaw, bevor der Prompt an das Modell übermittelt wird. Das ist beabsichtigt: Ein Agent, der mit einem fehlenden Tool wie agents.list[].tools.allow: ["query_db"] konfiguriert ist, sollte deutlich fehlschlagen, bis das Plugin aktiviert ist, das query_db registriert, und nicht als reiner Text-Agent fortfahren.
Tool-Richtlinien unterstützen group:*-Kurzformen, die zu mehreren Tools erweitert werden. Die vollständige Liste finden Sie unter Tool-Gruppen. Elevated-Überschreibungen pro Agent (agents.list[].tools.elevated) können Elevated exec für bestimmte Agents weiter einschränken. Details finden Sie unter Elevated-Modus.

​
Migration vom Einzelagenten

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}
Legacy-agent.*-Konfigurationen werden von openclaw doctor migriert; verwenden Sie künftig bevorzugt agents.defaults + agents.list.

​
Beispiele für Tool-Einschränkungen

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

​
Häufige Fehlerquelle: “non-main”

agents.defaults.sandbox.mode: "non-main" basiert auf session.mainKey (Standard "main"), nicht auf der Agent-ID. Gruppen-/Kanalsitzungen erhalten immer eigene Schlüssel, daher werden sie als non-main behandelt und in einer Sandbox ausgeführt. Wenn ein Agent niemals in einer Sandbox ausgeführt werden soll, setzen Sie agents.list[].sandbox.mode: "off".

​
Testen

Nach dem Konfigurieren von Multi-Agent-Sandbox und Tools:
1

Agent-Auflösung prüfen

openclaw agents list --bindings
2

Sandbox-Container verifizieren

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

Tool-Einschränkungen testen

  • Senden Sie eine Nachricht, die eingeschränkte Tools erfordert.
  • Verifizieren Sie, dass der Agent verweigerte Tools nicht verwenden kann.
4

Logs überwachen

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

​
Fehlerbehebung

  • Prüfen Sie, ob es ein globales agents.defaults.sandbox.mode gibt, das dies überschreibt.
  • Agent-spezifische Konfiguration hat Vorrang, setzen Sie daher agents.list[].sandbox.mode: "all".
  • Prüfen Sie die Reihenfolge der Tool-Filterung: global → Agent → Sandbox → Subagent.
  • Jede Ebene kann nur weiter einschränken, nicht erneut gewähren.
  • Verifizieren Sie dies mit Logs: [tools] filtering tools for agent:${agentId}.
  • Setzen Sie scope: "agent" in der Agent-spezifischen Sandbox-Konfiguration.
  • Standard ist "session", wodurch ein Container pro Sitzung erstellt wird.

​
Verwandte Themen