Strikte Konfigurations-Validierung und Doctor-Migrations

Kennst du das? Du änderst eine Kleinigkeit in einer großen Konfigurationsdatei und plötzlich verhält sich das System merkwürdig, ohne eine klare Fehlermeldung zu werfen. Oft werden Tippfehler oder veraltete Keys einfach ignoriert, anstatt den Start zu verhindern. Das führt zu stundenlanger Fehlersuche, nur um am Ende festzustellen, dass ein einzelner Buchstabe im Key falsch war oder ein Plugin-Parameter nicht mehr unterstützt wird.

Wir haben die Konfigurations-Logik umgestellt, damit solche Fehler sofort auffallen. Anstatt ungültige Keys stillschweigend zu ignorieren oder Migrationen automatisch im Hintergrund durchzuführen, setzt OpenClaw jetzt auf strikte Schemata und ein dediziertes Tool zur Fehlerbehebung.

Voraussetzungen

• Plugin-Manifeste (openclaw.plugin.json) für alle installierten Plugins
• JSON Schema Definitionen innerhalb der Plugin-Manifeste
• Zugriff auf die OpenClaw CLI

Schnellstart

Wenn du deine Konfiguration aktualisieren oder Fehler beheben willst, ist dies der schnellste Weg:

1. Gateway starten: OpenClaw führt bei jedem Start automatisch einen dry-run des doctor aus.
2. Fehler prüfen: Falls die Konfiguration ungültig ist, blockiert das System alle produktiven Befehle und zeigt dir die genauen Fehlerstellen.
3. Fehler beheben: Führe den Befehl openclaw doctor --fix aus.
4. Validierung abschließen: Das Tool wendet Migrationen an, entfernt unbekannte Keys und schreibt die aktualisierte Datei zurück.

Strikte Validierungsregeln

Die Konfiguration muss jetzt auf jeder Ebene exakt dem Schema entsprechen. Unbekannte Keys im Root oder in verschachtelten Objekten führen sofort zu einem Validierungsfehler. Es gibt keinen “Passthrough” mehr.

Plugin-Sicherheit

Jedes Plugin muss ein Manifest (openclaw.plugin.json) mit einem JSON Schema für seine Konfiguration bereitstellen. Wenn ein Plugin kein Schema besitzt oder die Konfiguration nicht valide ist, wird das Laden des Plugins blockiert. Die Fehlermeldung zeigt dir dabei direkt die Plugin-ID, den Grund und den fehlerhaften Pfad an.

Command Gating

Ist die Konfiguration ungültig, lässt OpenClaw nur noch Diagnose-Befehle zu. Alle anderen Operationen schlagen mit einem Hinweis auf openclaw doctor --fix fehl. Erlaubt bleiben:

• openclaw doctor
• openclaw status
• openclaw gateway status
• openclaw logs
• openclaw health
• openclaw help

Fehlerbehebung

Hier sind häufige Szenarien, die bei der Validierung auftreten:

Unbekannte Keys in der Konfiguration

• Problem: OpenClaw meldet “Unknown keys” im Root oder in channels.
• Lösung: Führe openclaw doctor --fix aus, um diese Keys automatisch zu entfernen, oder prüfe, ob ein Plugin-Manifest den Channel korrekt deklariert.

Plugin wird nicht geladen

• Problem: Das Gateway startet, aber ein spezifisches Plugin fehlt.
• Ursache: Entweder fehlt das JSON Schema im Manifest oder die Konfiguration unter plugins.entries.<id>.config ist ungültig. Prüfe die Logs auf die spezifische Pfadangabe des Fehlers.

Veraltete Konfigurations-Keys

• Problem: Du nutzt Keys aus einer älteren Version, die nicht mehr unterstützt werden.
• Lösung: Da OpenClaw keine automatischen Migrationen beim Laden mehr durchführt, musst du openclaw doctor --fix nutzen, um die Datei auf den aktuellen Stand zu bringen.

Hast du Fragen zur Konfiguration deines Gateways? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

• Plugin Manifest Referenz
• CLI Command Übersicht
• JSON Schema Guide für Entwickler
• Gateway Health Checks