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

OpenClaw liest seine optionale Gateway-Konfiguration als JSON5 aus ~/.openclaw/openclaw.json. Kommentare und ein Komma nach dem letzten Eintrag 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.

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

Das Onboarding fragt ab, was der Gateway zum Start braucht, und installiert auf Wunsch den Dienst:

openclaw onboard --install-daemon

Der Neustart in diesem Artikel setzt diesen installierten Dienst voraus. Anpassungen am Setup erreichst du mit:

openclaw configure

Die Shell-Beispiele in diesem Artikel richten sich an macOS und Linux. Unter Windows brauchst du die entsprechenden PowerShell- oder WSL-Befehle.

Für ein Channel-Beispiel gilt eine weitere Voraussetzung: Der Channel muss eingerichtet und angemeldet 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 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.

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. Frage verfügbare IDs deshalb über die CLI ab:

openclaw models list

Für den vollständigen Katalog:

openclaw models list --all

Die Datei sicher bearbeiten

1. Aktiven Pfad speichern

Führe die Befehle in derselben Shell aus:

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

Beide test-Befehle sollen ohne Ausgabe 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 geschützte Sicherung anlegen

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

Die Variable backup_path enthält den Pfad der Sicherung. Die Ausgabe von ls -l sollte für die Sicherungsdatei keine Gruppen- oder Welt-Leserechte zeigen. 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 das Gateway zu starten. Behebe gemeldete unbekannte Schlüssel, falsche Typen oder Syntaxfehler, bevor du den Dienst neu startest.

Für maschinenlesbare Ausgabe:

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. Der Ablauf setzt damit 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 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.

Welche Bereiche du später ergänzen kannst

Die Konfigurationsreferenz dokumentiert weitere Root-Bereiche für Channels, Sessions, Nachrichten, Gateway, Tools und Automatisierung. 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.

Der praktische Punkt

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, geschützte 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.