> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox vs. Tool-Richtlinie vs. erhöhte Berechtigungen

OpenClaw hat drei verwandte (aber unterschiedliche) Steuerungen:

1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) entscheidet, **wo Tools ausgeführt werden** (Sandbox-Backend oder Host).
2. **Tool-Richtlinie** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) entscheidet, **welche Tools verfügbar/erlaubt sind**.
3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) ist eine **nur für exec gedachte Ausweichmöglichkeit**, um außerhalb der Sandbox auszuführen, wenn Sie in einer Sandbox sind (standardmäßig `gateway`, oder `node`, wenn das exec-Ziel auf `node` konfiguriert ist).

## Schnelles Debugging

Verwenden Sie den Inspector, um zu sehen, was OpenClaw *tatsächlich* tut:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```

Er gibt Folgendes aus:

* effektiver Sandbox-Modus/-Scope und Workspace-Zugriff
* ob die Sitzung aktuell in einer Sandbox läuft (main vs. nicht-main)
* effektive Sandbox-Tool-Erlaubnis/-Ablehnung (und ob sie von Agent/global/default stammt)
* Elevated-Gates und Fix-it-Schlüsselpfade

## Sandbox: wo Tools ausgeführt werden

Sandboxing wird über `agents.defaults.sandbox.mode` gesteuert:

* `"off"`: Alles läuft auf dem Host.
* `"non-main"`: Nur nicht-main-Sitzungen laufen in einer Sandbox (häufige „Überraschung“ für Gruppen/Kanäle).
* `"all"`: Alles läuft in einer Sandbox.

Die vollständige Matrix (Scope, Workspace-Mounts, Images) finden Sie unter [Sandboxing](/de/gateway/sandboxing).

### Bind-Mounts (schneller Sicherheitscheck)

* `docker.binds` *durchdringt* das Sandbox-Dateisystem: Alles, was Sie mounten, ist im Container mit dem von Ihnen gesetzten Modus sichtbar (`:ro` oder `:rw`).
* Standard ist Lese-/Schreibzugriff, wenn Sie den Modus weglassen; bevorzugen Sie `:ro` für Source/Secrets.
* `scope: "shared"` ignoriert agentenspezifische Binds (nur globale Binds gelten).
* OpenClaw validiert Bind-Quellen zweimal: zuerst auf dem normalisierten Quellpfad, dann erneut nach der Auflösung über den tiefsten existierenden Vorfahren. Symlink-Parent-Escapes umgehen keine Prüfungen für blockierte Pfade oder erlaubte Roots.
* Nicht vorhandene Leaf-Pfade werden weiterhin sicher geprüft. Wenn `/workspace/alias-out/new-file` über einen verlinkten Parent zu einem blockierten Pfad oder außerhalb der konfigurierten erlaubten Roots aufgelöst wird, wird der Bind abgelehnt.
* Das Binden von `/var/run/docker.sock` übergibt der Sandbox effektiv die Kontrolle über den Host; tun Sie dies nur absichtlich.
* Workspace-Zugriff (`workspaceAccess: "ro"`/`"rw"`) ist unabhängig von Bind-Modi.

## Tool-Richtlinie: welche Tools existieren/aufrufbar sind

Zwei Ebenen sind wichtig:

* **Tool-Profil**: `tools.profile` und `agents.list[].tools.profile` (Basis-Allowlist)
* **Provider-Tool-Profil**: `tools.byProvider[provider].profile` und `agents.list[].tools.byProvider[provider].profile`
* **Globale/agentenspezifische Tool-Richtlinie**: `tools.allow`/`tools.deny` und `agents.list[].tools.allow`/`agents.list[].tools.deny`
* **Provider-Tool-Richtlinie**: `tools.byProvider[provider].allow/deny` und `agents.list[].tools.byProvider[provider].allow/deny`
* **Sandbox-Tool-Richtlinie** (gilt nur in einer Sandbox): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` und `agents.list[].tools.sandbox.tools.*`

Faustregeln:

* `deny` gewinnt immer.
* Wenn `allow` nicht leer ist, wird alles andere als blockiert behandelt.
* Die Tool-Richtlinie ist die harte Grenze: `/exec` kann ein abgelehntes `exec`-Tool nicht überschreiben.
* Die Tool-Richtlinie filtert die Tool-Verfügbarkeit nach Name; sie prüft keine Nebenwirkungen innerhalb von `exec`. Wenn `exec` erlaubt ist, macht das Ablehnen von `write`, `edit` oder `apply_patch` Shell-Befehle nicht schreibgeschützt.
* `/exec` ändert nur Sitzungsstandards für autorisierte Absender; es gewährt keinen Tool-Zugriff.
  Provider-Tool-Schlüssel akzeptieren entweder `provider` (z. B. `google-antigravity`) oder `provider/model` (z. B. `openai/gpt-5.4`).
* Gateway-Logs enthalten `agents/tool-policy`-Audit-Einträge, wenn ein Schritt der Tool-Richtlinie Tools entfernt oder eine Sandbox-Tool-Richtlinie einen Aufruf blockiert. Verwenden Sie `openclaw logs`, um das Regel-Label, den Konfigurationsschlüssel und die betroffenen Tool-Namen zu sehen.

### Tool-Gruppen (Kurzformen)

Tool-Richtlinien (global, Agent, Sandbox) unterstützen `group:*`-Einträge, die zu mehreren Tools erweitert werden:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}
```

Verfügbare Gruppen:

* `group:runtime`: `exec`, `process`, `code_execution` (`bash` wird als
  Alias für `exec` akzeptiert)
* `group:fs`: `read`, `write`, `edit`, `apply_patch`
  Für schreibgeschützte Agenten lehnen Sie `group:runtime` sowie mutierende Dateisystem-Tools ab, sofern die Sandbox-Dateisystemrichtlinie oder eine separate Host-Grenze die Schreibschutzbeschränkung nicht erzwingt.
* `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
* `group:memory`: `memory_search`, `memory_get`
* `group:web`: `web_search`, `x_search`, `web_fetch`
* `group:ui`: `browser`, `canvas`
* `group:automation`: `heartbeat_respond`, `cron`, `gateway`
* `group:messaging`: `message`
* `group:nodes`: `nodes`
* `group:agents`: `agents_list`, `update_plan`
* `group:media`: `image`, `image_generate`, `music_generate`, `video_generate`, `tts`
* `group:openclaw`: alle integrierten OpenClaw-Tools (ohne Provider-Plugins)
* `group:plugins`: alle geladenen Plugin-eigenen Tools, einschließlich konfigurierter MCP-Server, die über `bundle-mcp` verfügbar gemacht werden

Für MCP-Server in einer Sandbox ist die Sandbox-Tool-Richtlinie ein zweites Allow-Gate. Wenn `mcp.servers` konfiguriert ist, aber Sandbox-Turns nur integrierte Tools anzeigen, fügen Sie `bundle-mcp`, `group:plugins` oder einen serverpräfixierten MCP-Tool-Namen/-Glob wie `outlook__send_mail` oder `outlook__*` zu `tools.sandbox.tools.alsoAllow` hinzu, starten/laden Sie dann den Gateway neu und erfassen Sie die Tool-Liste erneut. Server-Globs verwenden den Provider-sicheren MCP-Server-Präfix: Nicht-`[A-Za-z0-9_-]`-Zeichen werden zu `-`, Namen, die nicht mit einem Buchstaben beginnen, erhalten ein `mcp-`-Präfix, und lange oder doppelte Präfixe können gekürzt oder mit einem Suffix versehen werden.

`openclaw doctor` prüft diese Form aktuell für von OpenClaw verwaltete Server in `mcp.servers`. MCP-Server, die aus gebündelten Plugin-Manifesten oder Claude `.mcp.json` geladen werden, verwenden dasselbe Sandbox-Gate, aber diese Diagnose listet diese Quellen noch nicht auf; verwenden Sie dieselben Allowlist-Einträge, wenn deren Tools in Sandbox-Turns verschwinden.

## Elevated: nur exec „auf dem Host ausführen“

Elevated gewährt **keine** zusätzlichen Tools; es wirkt sich nur auf `exec` aus.

* Wenn Sie in einer Sandbox sind, führt `/elevated on` (oder `exec` mit `elevated: true`) außerhalb der Sandbox aus (Genehmigungen können weiterhin gelten).
* Verwenden Sie `/elevated full`, um exec-Genehmigungen für die Sitzung zu überspringen.
* Wenn Sie bereits direkt ausführen, ist Elevated effektiv ein No-op (weiterhin gegated).
* Elevated ist **nicht** Skill-scoped und überschreibt **keine** Tool-Erlaubnis/-Ablehnung.
* Elevated gewährt keine beliebigen hostübergreifenden Overrides von `host=auto`; es folgt den normalen exec-Zielregeln und bewahrt `node` nur, wenn das konfigurierte/Sitzungsziel bereits `node` ist.
* `/exec` ist von Elevated getrennt. Es passt nur agentenspezifische exec-Standards für autorisierte Absender an.

Gates:

* Aktivierung: `tools.elevated.enabled` (und optional `agents.list[].tools.elevated.enabled`)
* Absender-Allowlists: `tools.elevated.allowFrom.<provider>` (und optional `agents.list[].tools.elevated.allowFrom.<provider>`)

Siehe [Elevated Mode](/de/tools/elevated).

## Häufige „Sandbox-Gefängnis“-Korrekturen

### „Tool X blocked by sandbox tool policy“

Fix-it-Schlüssel (wählen Sie einen):

* Sandbox deaktivieren: `agents.defaults.sandbox.mode=off` (oder agentenspezifisch `agents.list[].sandbox.mode=off`)
* Tool innerhalb der Sandbox erlauben:
  * entfernen Sie es aus `tools.sandbox.tools.deny` (oder agentenspezifisch `agents.list[].tools.sandbox.tools.deny`)
  * oder fügen Sie es zu `tools.sandbox.tools.allow` hinzu (oder agentenspezifische Erlaubnis)
* Prüfen Sie `openclaw logs` auf den Eintrag `agents/tool-policy`. Er zeichnet den Sandbox-Modus auf und ob die Allow- oder Deny-Regel das Tool blockiert hat.

### „Ich dachte, dies sei main, warum läuft es in einer Sandbox?“

Im Modus `"non-main"` sind Gruppen-/Kanalschlüssel *nicht* main. Verwenden Sie den main-Sitzungsschlüssel (angezeigt von `sandbox explain`) oder wechseln Sie den Modus zu `"off"`.

## Verwandt

* [Sandboxing](/de/gateway/sandboxing) -- vollständige Sandbox-Referenz (Modi, Scopes, Backends, Images)
* [Multi-Agent Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) -- agentenspezifische Overrides und Rangfolge
* [Elevated Mode](/de/tools/elevated)