Zum Hauptinhalt springen

ZeroClaw Konfiguration und Sicherheit

1. Das grundlegende mentale Modell der Konfiguration​

Die Provider-Dokumentation beschreibt ein kanonisches Muster:

[providers.models.<type>.<alias>]

Das sagt dir sofort zwei Dinge:

  • Provider werden nach Familientyp gruppiert,
  • jede konkrete Instanz erhält einen vom Betreiber gewählten Alias.

ZeroClaw verdrahtet dann alles per Referenz. Ein Agent zeigt ĂĽber einen punktierten Alias auf einen Provider und referenziert separat ein Risikoprofil.

Deshalb sagt die Dokumentation, dass das kleinste funktionierende Setup vier Section-Header hat: einen Provider-Eintrag, einen Agent, der ihn referenziert, und ein Risikoprofil, das der Agent nutzt.

2. Worauf die Konfiguration optimieren will​

Das Konfigurationsmodell versucht, drei BedĂĽrfnisse auszubalancieren:

  • starke Struktur, damit die Runtime aggressiv validieren kann,
  • Betreiber-Flexibilität, damit du Instanzen sauber benennen und austauschen kannst,
  • sicheres Secret-Handling, damit Credentials nicht in einfaches TOML gezwungen werden.

Das ist eine ernsthaftere Konfigurationsgeschichte als "wirf einen API-Key in eine Env-Variable". Das ist gut fĂĽr echte Systeme, bedeutet aber auch, dass du frĂĽh Zeit darauf verwenden solltest, Aliase und Referenzen zu verstehen.

3. Provider-Konfiguration​

Die offizielle Dokumentation hebt einige Kernideen hervor.

Alias-basierte Provider-Einträge​

Du konfigurierst nicht "OpenAI global". Du konfigurierst einen oder mehrere konkrete Einträge wie:

[providers.models.openai.coding]
model = "gpt-5-codex"
wire_api = "responses"
requires_openai_auth = true

Das macht es leicht, mehrere Provider-Instanzen nebeneinander zu halten:

  • lokales Ollama,
  • produktives Anthropic,
  • einen OpenAI-kompatiblen Backup-Endpunkt,
  • verschiedene Regionen oder Auth-Modi.

Fallbacks​

ZeroClaw unterstützt zwei unabhängige Fallback-Konzepte:

  • Fallback-Modelle beim selben Provider
  • Fallback-Provider-Aliase

Das ist ein operativ starkes Design. Es lässt die Runtime gnädig degradieren, wenn ein Modell- oder Provider-Pfad ausfällt.

Environment- und Container-Overrides​

Die Provider-Dokumentation beschreibt auĂźerdem schema-gespiegelte Environment-Overrides, die besonders in Containern oder Deployment-Umgebungen nĂĽtzlich sind, in denen du die On-Disk-Konfiguration nicht mutieren willst.

4. Credentials und Secrets​

Die Dokumentation nennt vier Hauptwege, um Credentials bereitzustellen:

  1. inline api_key in der Konfiguration,
  2. 1Password-Referenzen ĂĽber op://...,
  3. ZeroClaws lokalen verschlĂĽsselten Secrets-Store,
  4. Environment-Overrides beim Prozessstart.

Die empfohlene operative Haltung ist eindeutig:

  • nutze den Secrets-Store oder Secret-Referenzen fĂĽr die normale Nutzung,
  • vermeide eingecheckte Inline-Keys,
  • nutze Env-Overrides fĂĽr Deployment-/Runtime-Substitution.

5. Channels werden separat konfiguriert​

Channels nutzen ihren eigenen alias-basierten Config-Baum:

[channels.<type>.<alias>]

Diese Trennung ist wichtig. Provider definieren, wie der Agent denkt; Channels definieren, wo er erreicht werden kann.

Die Channel-Dokumentation verweist auĂźerdem auf wiederkehrende Felder wie:

  • enabled
  • mention_only
  • proxy_url
  • excluded_tools
  • draft_update_interval_ms
  • approval_timeout_secs

So siehst du bereits die gemeinsame Betreiber-Form, noch bevor du eine bestimmte Channel-Integration lernst.

6. Sicherheitshaltung​

Der offizielle Sicherheitsüberblick beginnt mit einer einfachen Prämisse:

ein Agent, der Befehle ausführen, URLs öffnen und Dateien schreiben kann, ist ein privilegierter Prozess

Alles andere folgt daraus.

Die Dokumentation verweist auf vier Kernkonzepte:

  • Sicherheitsmodell
  • Autonomiestufen
  • Sandboxing
  • Tool-Receipts

Autonomie​

Die README beschreibt die Standardhaltung als beaufsichtigt:

  • Operationen mit mittlerem Risiko erfordern eine Freigabe,
  • Operationen mit hohem Risiko werden blockiert,
  • fĂĽr vertrauenswĂĽrdige Umgebungen existieren freizĂĽgigere Modi.

Sandboxing​

Die Dokumentation nennt OS-Level-Sandboxes wie:

  • Landlock
  • Bubblewrap
  • Seatbelt
  • Docker

Das ist wichtig, weil das Sicherheitsmodell von ZeroClaw nicht rein prompt-basiert ist. Es wird durch Kontrollen auf Systemebene gestĂĽtzt.

Tool-Receipts​

Receipts sind eine der markanteren Ideen im Projekt. Die README beschreibt sie als kryptografische Receipts für Tool-Aktionen. Das gibt dir eine stärkere Audit-Geschichte als gewöhnliches "der Agent hat das wahrscheinlich getan"-Logging.

7. Day-Two-Operations​

Sobald der Agent funktioniert, verschiebt sich der Betreiber-Workflow typischerweise zu:

zeroclaw service install
zeroclaw service start
zeroclaw daemon
zeroclaw auth status
zeroclaw config schema

Die genaue generierte Referenz ist fĂĽr Subcommands und Flags maĂźgeblich, aber konzeptionell decken diese ab:

  • Service-Modus installieren,
  • langlebige AusfĂĽhrung starten,
  • Auth-Status inspizieren,
  • Config-Schema inspizieren.

8. Praktischer Rat​

FĂĽr den echten Einsatz ist die sicherste Gewohnheit:

  1. halte die Config-Struktur explizit und alias-basiert,
  2. halte Secrets aus dem Klartext heraus,
  3. starte im beaufsichtigten Modus,
  4. fĂĽge Channels einzeln hinzu,
  5. behandle den Provider-Fallback als Zuverlässigkeits-Feature, nicht als nachträglichen Einfall.

Diese Denkweise passt viel besser zum Projekt, als zu versuchen, es wie einen Ein-Datei-Hobby-Bot zu betreiben.