Gateway-Konfiguration: openclaw.json (JSON5) verständlich erklärt

OpenClaw liest seine optionale Gateway-Konfiguration als JSON5 aus ~/.openclaw/openclaw.json. Kommentare und Trailing Commas sind erlaubt. Fehlt die Datei, verwendet OpenClaw sichere Standardwerte.

Sobald du Workspace, Modell oder Channel-Zugriff gezielt festlegen willst, wird die Datei relevant. Dieser Teil der OpenClaw-Praxis-Serie zeigt eine kleine, nachvollziehbare Konfiguration und einen sicheren Ablauf für manuelle Änderungen.

Für Zugangsdaten ergänzt später OpenClaw SecretRef richtig einsetzen diesen Einstieg. Rechte und Ausführungsgrenzen behandelt OpenClaw Approvals erklärt.

Stand der technischen Prüfung: 14. August 2026.

Voraussetzungen

Bevor du die Datei bearbeitest, brauchst du eine funktionierende OpenClaw-Installation. Laut offizieller Getting-started-Dokumentation unterstützt OpenClaw Node.js 22.22.3+, 24.15+ oder 25.9+; Node 26 wird dort als Runtime empfohlen.

Prüfe deine Version:

node --version

Richte anschließend Modellanbieter, Authentifizierung und Gateway über das Onboarding ein:

openclaw onboard --install-daemon

Der Wizard fragt die erforderlichen Zugangsdaten ab und installiert auf Wunsch den Gateway-Dienst. Der spätere Neustartschritt in diesem Artikel setzt diesen installierten Dienst voraus. Anpassungen am Setup erreichst du mit:

openclaw configure

Für ein Channel-Beispiel gilt eine zusätzliche Voraussetzung: Der betreffende Channel muss installiert, angemeldet und erreichbar sein. Eine Allowlist allein stellt keine WhatsApp- oder Telegram-Verbindung her.

Welche Datei OpenClaw tatsächlich liest

Der Standardpfad lautet:

~/.openclaw/openclaw.json

Er kann jedoch durch OPENCLAW_CONFIG_PATH abweichen. Ermittle deshalb vor jeder manuellen Änderung den aktiven Pfad:

openclaw config file

Der ausgegebene Pfad muss auf eine reguläre Datei zeigen. Die offizielle Dokumentation rät von einer verlinkten openclaw.json ab, weil OpenClaw-eigene Schreibvorgänge die Datei atomar ersetzen können. Wenn du einen abweichenden Speicherort verwendest, sollte OPENCLAW_CONFIG_PATH direkt auf die reale Datei zeigen.

Existiert die ausgegebene Datei noch nicht, führe zunächst openclaw onboard oder openclaw configure aus. Eine leere Datei anzulegen ist nicht nötig, da OpenClaw auch ohne Konfigurationsdatei starten kann.

Wie die Konfiguration aufgebaut ist

OpenClaw unterscheidet grob zwischen zwei Ebenen:

• Root-Blöcke wie channels, gateway, session, messages oder tools betreffen Infrastruktur und übergreifendes Verhalten.
• agents.defaults enthält Standards für den Agent-Lauf, etwa Workspace und Modell.

Einzelne Agenten können diese Vorgaben überschreiben, sofern das Schema der installierten Version den jeweiligen Pfad unterstützt. Verlasse dich bei Detailfeldern nicht auf ältere Beispiele: Das laufende Schema ist die verbindliche Referenz.

Du kannst es ausgeben mit:

openclaw config schema

Eine kleine, belegte Basiskonfiguration

Die offizielle Dokumentation zeigt dieses Muster:

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
    },
  },
}

agents.defaults.workspace legt den Standard-Workspace fest. Der Pfad lautet nicht agent.workspace.

channels.whatsapp.allowFrom begrenzt den Zugriff auf die eingetragenen Absender. Ersetze die Beispielnummer durch die Nummer, die in deinem Setup zugelassen werden soll. Dieser Eintrag konfiguriert nur den Zugriff: WhatsApp muss vorher eingerichtet und angemeldet worden sein.

Wenn du keinen WhatsApp-Channel verwendest, übernimm den Block nicht. Eine Basiskonfiguration darf auch nur den Workspace enthalten.

Ein Modell festlegen

Das aktuelle Schema bestätigt agents.defaults.model; die offizielle Beispielkonfiguration verwendet darin primary:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "<provider/model>",
      },
    },
  },
}

Ersetze <provider/model> durch eine Modell-ID, die deine Installation tatsächlich kennt. Verfügbare IDs ändern sich und können vom eingerichteten Provider abhängen. Frage sie deshalb über die CLI ab:

openclaw models list

Für den vollständigen Katalog:

openclaw models list --all

Ein festes Modellbeispiel im Artikel wäre schnell unpassend, wenn der Provider nicht eingerichtet ist oder seine Modellnamen ändert.

Die Datei sicher bearbeiten

1. Aktiven Pfad speichern

Führe die folgenden Befehle in derselben Shell aus:

config_path="$(openclaw config file)"
test -f "$config_path"
test ! -L "$config_path"

Beide test-Befehle sollen ohne Ausgabe und mit Exit-Code 0 enden. Schlägt der zweite Test fehl, ist der Pfad ein Symlink. Lege die Konfiguration dann als reguläre Datei ab und richte OPENCLAW_CONFIG_PATH bei Bedarf direkt auf sie.

2. Eine Sicherung anlegen

backup_path="${config_path}.backup.$(date +%Y%m%d-%H%M%S)"
cp -- "$config_path" "$backup_path"

Die Variable backup_path enthält anschließend den Pfad der Sicherung. Bewahre die Shell offen, bis die Änderung geprüft ist.

3. Nur die benötigten Felder ändern

Öffne $config_path in deinem Editor. JSON5 erlaubt Kommentare, nicht quotierte Objektschlüssel und ein Komma nach dem letzten Eintrag.

Füge keine Felder aus beliebigen Beispielkonfigurationen ein. Prüfe unbekannte Pfade vorher im Live-Schema:

openclaw config schema

Für einzelne vorhandene Werte eignet sich:

openclaw config get agents.defaults.workspace

Der Befehl akzeptiert Pfade in Punkt- oder Bracket-Notation.

4. Konfiguration validieren

openclaw config validate

Die Prüfung validiert die aktive Datei gegen das installierte Schema, ohne dafür das Gateway zu starten. Behebe gemeldete unbekannte Schlüssel, falsche Typen oder Syntaxfehler, bevor du den Dienst neu startest.

Für maschinenlesbare Ausgabe steht zusätzlich diese Variante bereit:

openclaw config validate --json

5. Gateway mit der validierten Datei neu starten

Prüfe zunächst, ob deine installierte CLI den sicheren Neustart anbietet:

openclaw gateway restart --help

Die aktuelle CLI beschreibt --safe als OpenClaw-gesteuerten Neustart, der auf laufende Gateway-Arbeit Rücksicht nimmt. Starte den über das Onboarding installierten Dienst nach erfolgreicher Validierung neu:

openclaw gateway restart --safe

Der Befehl soll ohne Fehler enden. Damit verlässt sich der Ablauf nicht auf einen unbestätigten automatischen Reload: Der neu gestartete Gateway-Prozess liest die aktive, zuvor validierte Konfigurationsdatei.

6. Gespeicherten Wert und Laufzeit prüfen

Prüfe den konfigurierten Workspace:

openclaw config get agents.defaults.workspace

Die Ausgabe soll dem Wert aus deiner Datei entsprechen.

Prüfe anschließend den neu gestarteten Gateway-Dienst:

openclaw gateway status

Der Status soll einen laufenden Gateway melden. Ein laufender Prozess bestätigt noch nicht, dass Channel-Anmeldung und Modellzugriff funktionieren. Öffne deshalb die Control UI:

openclaw dashboard

Sende dort eine Testnachricht. Eine Modellantwort bestätigt, dass Gateway, Authentifizierung und Modellzugriff nach dem Neustart zusammenarbeiten. Wenn du einen Channel geändert hast, teste zusätzlich mit einem zugelassenen Absender. Ein nicht zugelassener Absender darf durch die Allowlist keinen Zugriff erhalten.

Fehlerdiagnose

Für eine lesende Systemprüfung dient:

openclaw doctor --lint

Der Lint-Modus meldet Befunde, ohne die Reparaturoptionen von doctor --fix oder doctor --repair aufzurufen.

Bei einem Fehler gehst du in dieser Reihenfolge vor:

1. openclaw config file bestätigt, dass du die aktive Datei bearbeitet hast.
2. openclaw config validate trennt Syntax- und Schemafehler von Laufzeitproblemen.
3. openclaw config get <pfad> zeigt den gespeicherten Wert eines konkreten Pfads.
4. openclaw gateway restart --safe startet den installierten Dienst mit der aktiven Datei neu.
5. openclaw gateway status prüft, ob der Neustart erfolgreich war.
6. openclaw doctor --lint liefert zusätzliche Diagnosehinweise.
7. Eine Testnachricht prüft Channel, Authentifizierung und Modell gemeinsam.

Konfiguration zurückrollen

Wenn die Änderung nicht funktioniert, kopiere die zuvor erzeugte Sicherung zurück und validiere sie:

cp -- "$backup_path" "$config_path"
openclaw config validate

Starte anschließend den Gateway-Dienst mit der wiederhergestellten Datei neu:

openclaw gateway restart --safe
openclaw config get agents.defaults.workspace
openclaw gateway status

Die Wiederherstellung ist abgeschlossen, wenn die Validierung erfolgreich endet, config get wieder den erwarteten Workspace ausgibt und der Status einen laufenden Gateway meldet. Sende danach erneut eine Testnachricht. So prüfst du, ob Authentifizierung und Modellzugriff auch mit der zurückgespielten Konfiguration funktionieren.

Welche Bereiche du später ergänzen kannst

Die Konfigurationsreferenz dokumentiert weitere Root-Bereiche für Channels, Sessions, Nachrichten, Gateway, Tools und Automatisierung. Ihre Unterfelder entwickeln sich weiter und werden teilweise von Plugins oder Channels ergänzt.

Prüfe deshalb jeden konkreten Pfad gegen die installierte Runtime, bevor du ihn übernimmst. Das gilt besonders für Session-Resets, Gruppenverhalten, Medienlimits, Auth-Profile und privilegierte Werkzeuge. Ein kurzer Schematest ist belastbarer als ein großer, ungeprüfter Copy-and-Paste-Block.

Zusammenfassung

openclaw.json ist eine optionale JSON5-Datei. Für ein kleines Setup genügt eine knappe Konfiguration unter agents.defaults; Channel-Blöcke kommen nur hinzu, wenn der Channel bereits eingerichtet ist.

Der Ablauf lautet: aktiven Pfad ermitteln, reguläre Datei bestätigen, Sicherung anlegen, wenige Felder ändern, Schema validieren, Gateway sicher neu starten und die Funktion prüfen. Zugangsdaten gehören nicht als Klartext in ein öffentliches oder versioniertes Konfigurationsbeispiel.

Dies ist Teil 1 der OpenClaw Praxis-Serie auf agentenlog.de. Alle Teile findest du in der Tutorials-Übersicht.