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

Die OpenClaw Gateway-Konfiguration ist der Dreh- und Angelpunkt der Agenten-Pipeline. OpenClaw liest nach offizieller Dokumentation eine optionale JSON5-Konfiguration aus ~/.openclaw/openclaw.json. Fehlt diese Datei, startet das System mit Standardwerten. Für viele Nutzer wirkt die Vielzahl an Optionen anfangs komplex, praktisch zählt aber vor allem ein sauberer Einstieg.

Dieser Artikel zeigt die wichtigsten Abschnitte der Datei, ordnet typische Stolpersteine ein und nutzt Beispiele aus der offiziellen OpenClaw-Dokumentation. Für sichere Secrets passt dazu der spätere Leitfaden Secrets und API-Keys sicher verwalten; für Rechte und Ausführungsgrenzen ergänzt Sandboxing & Exec-Approvals die Konfigurationsbasis.

Warum die openclaw.json so wichtig ist

OpenClaw bündelt zentrale Gateway-Aufgaben in einer Konfigurationsdatei: Channels, Modelle, Sessions, Authentifizierung und Automationen greifen dort ineinander. Diese Architektur macht das System flexibel, verlangt aber klare Entscheidungen bei den Basiseinstellungen.

Ein typisches Szenario: Ein Agent soll Telegram-Nachrichten empfangen, ein kosteneffizientes Modell nutzen und abends einen Cron-Job ausführen. Wenn die openclaw.json nicht sauber gesetzt ist, startet der Channel nicht, das Modell wird nicht gefunden oder die Automation läuft ohne brauchbares Ziel.

Die meisten Setups brauchen nur einen kleinen Teil der verfügbaren Optionen. Weil die Datei im JSON5-Format vorliegt, sind Kommentare und Trailing Commas möglich. Der Start gelingt bereits mit einer minimalen Konfiguration.

Absolute Minimal-Konfiguration

Nach offizieller OpenClaw-Dokumentation genügen für einen einfachen Start diese Zeilen:

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

Diese zwei Abschnitte definieren Arbeitsverzeichnis und Channel-Zugriff. Für weitere Parameter nutzt OpenClaw Standardwerte.

Die Kernabschnitte im Detail

Identity: Das Erscheinungsbild des Agenten

{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "🦞",
  },
}

Der optionale identity-Block bestimmt Name, Stil und Emoji des Agenten. Das hilft, wenn mehrere Agenten parallel betrieben werden oder ein Channel klar erkennen lassen soll, welcher Agent antwortet.

Unterschied zwischen agent und agents

OpenClaw unterscheidet zwischen Einstellungen für das konkrete Gateway (agent) und globalen Standardwerten für Sessions (agents).

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-6" },
  },
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      thinkingDefault: "low",
    },
  },
}

Die Modellauswahl wird über model.primary gesteuert. Unter model.fallbacks lassen sich alternative Modelle für Provider-Ausfälle definieren. Über models kann zusätzlich ein Katalog mit lesbaren Alias-Namen angelegt werden.

Weitere Parameter steuern das Verhalten des Agenten: thinkingDefault regelt das Reasoning-Level, verboseDefault die Ausführlichkeit der Antworten und elevatedDefault den Umgang mit privilegierten Kommandos. Für viele produktive Setups ist ein niedriges Reasoning-Level der sinnvollere Ausgangspunkt, weil höhere Stufen mehr Token verbrauchen.

Channels: Messaging-Dienste verbinden

Jeder Channel erhält einen eigenen Abschnitt unter channels.<provider>. Eine typische Telegram-Konfiguration sieht laut OpenClaw-Dokumentation so aus:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",    // pairing | allowlist | open | disabled
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

Die DM-Policies regeln den Zugang kanalübergreifend. pairing lässt unbekannte Absender über einen einmaligen Code koppeln. Mit allowlist werden nur explizit erlaubte Nutzer zugelassen, während open alle Direktnachrichten erlaubt. disabled blockiert Direktnachrichten vollständig.

Zugangsdaten wie Tokens sollten bei Nutzung von Versionskontrolle nicht direkt in der Konfigurationsdatei stehen. OpenClaw unterstützt die ${ENV_VAR}-Syntax, sodass Variablen über Shell-Umgebung oder ein Secrets-File geladen werden können.

Auth: API-Provider verwalten

Der auth-Block definiert verfügbare API-Credentials und deren Priorität. Die eigentlichen Secrets liegen nach OpenClaw-Konzept in einer separaten auth-profiles.json:

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:default"],
      openai: ["openai:default"],
    },
  },
}

So bleibt die Gateway-Konfiguration lesbar, ohne API-Schlüssel direkt im Hauptfile zu speichern.

Tools: Media, Audio und Video

Über den tools-Block wird der Umgang mit Medien gesteuert:

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,  // 20 MB
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,  // 50 MB
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

Die Werte begrenzen Dateigrößen, aktivieren einzelne Medienpfade und definieren passende Modelle. Für produktive Setups lohnt sich hier eine eher konservative Konfiguration, damit große Dateien nicht unkontrolliert Kosten oder Laufzeiten erhöhen.

Session: Verhalten pro Nachricht

Dieser Abschnitt bestimmt den Lebenszyklus von Sitzungen:

{
  session: {
    scope: "per-sender",
    dmScope: "per-channel-peer",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetTriggers: ["/new", "/reset"],
  },
}

Wichtige Parameter sind der scope sowie die Reset-Bedingungen. Ein Reset kann zeitbasiert, bei Inaktivität oder durch definierte Befehle wie /new und /reset erfolgen.

Env: Umgebungsvariablen

{
  env: {
    OPENROUTER_API_KEY: "<YOUR_API_KEY>",
    vars: {
      GROQ_API_KEY: "<YOUR_API_KEY>",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Der env-Block kann Umgebungsvariablen bereitstellen. Für echte Schlüssel gilt trotzdem: nicht ins Repository schreiben, sondern über lokale Secrets oder die Umgebung laden.

Mini-Szenario: Eine solide Starter-Konfiguration

Für einen Telegram-Bot, der Nachrichten mit einem kostenlosen Modell beantwortet und sich über /new zurücksetzen lässt, bietet sich folgendes Setup an:

// ~/.openclaw/openclaw.json
{
  identity: {
    name: "Nexus",
    theme: "helpful assistant",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "allowlist",
      allowFrom: ["921587194"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "openrouter/nvidia/nemotron-3-super-120b-a12b:free",
      },
      thinkingDefault: "low",
      elevatedDefault: "off",
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
  },
}

Diese Konfiguration begrenzt Direktnachrichten auf eine Allowlist, nutzt ein kostenloses Modell und lässt privilegierte Kommandos standardmäßig deaktiviert. Sie ist damit ein brauchbarer Startpunkt, der später schrittweise erweitert werden kann.

Fehlerbehebung und Debugging

OpenClaw validiert die Konfiguration gegen ein Schema. Unbekannte Schlüssel oder falsche Datentypen können deshalb den Start verhindern, statt stillschweigend ignoriert zu werden.

Bei Startproblemen helfen die Diagnosebefehle aus der OpenClaw-Dokumentation. openclaw doctor zeigt Validierungs- und Setup-Probleme an; je nach Fall kann --fix einfache Korrekturen unterstützen. Für detailliertere Gateway-Logs ist ein Start mit erhöhter Ausführlichkeit sinnvoll. Das aktuelle Schema lässt sich über die Config- beziehungsweise Schema-Hilfe von OpenClaw prüfen.

Wenn ein Modell nicht antwortet, sollte zuerst die Provider-Konfiguration geprüft werden: API-Key, Modellname, Limits und Fallbacks. Zusätzlich bietet die Control UI eine Oberfläche für Konfigurationsprüfung und Bearbeitung, sofern sie im lokalen Setup aktiviert ist.

Was wir daraus lernen

• Minimal starten: OpenClaw nutzt JSON5. Oft reichen zunächst der agent-Block und ein Channel. Weitere Optionen sollten bei konkretem Bedarf hinzukommen.
• Schema ernst nehmen: Die Datei muss zur erwarteten Struktur passen. Diagnosebefehle helfen, Typfehler und unbekannte Schlüssel schneller zu finden.
• Fallbacks bewusst setzen: Alternative Modelle halten den Agenten erreichbar, wenn ein Provider nicht antwortet oder Limits erreicht sind.
• Zugriff begrenzen: Für Tests ist pairing bequem; im produktiven Betrieb ist allowlist meist die kontrolliertere Wahl.

Die openclaw.json wächst mit den Anforderungen der Pipeline. Eine kleine, validierte Basis ist stabiler als ein großer Optionsblock, dessen Nebenwirkungen niemand mehr überblickt.

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