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

Die Gateway-Konfiguration ist der technische Kern von OpenClaw. Nach offizieller Dokumentation liest OpenClaw eine optionale JSON5-Datei unter ~/.openclaw/openclaw.json. Fehlt sie, startet das Gateway mit sicheren Standardwerten. Das klingt entspannt, wird aber schnell relevant, sobald du Modelle, Channels, Sessions oder Zugriffsregeln gezielt steuern willst.

Dieser Artikel zeigt die wichtigsten Blöcke der Datei, erklärt, welche davon für ein kleines Setup wirklich zählen, und ordnet typische Stolpersteine ein. Für Secrets passt dazu später 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

In openclaw.json laufen mehrere Ebenen zusammen:

• agents.defaults.* für Workspace, Modelle und Agent-Standards
• channels.* für Messenger-Anbindungen und Zugriffskontrolle
• session.* für Reset- und Sitzungslogik
• messages.* für sichtbare Antworten und Gruppenverhalten
• weitere Top-Level-Blöcke wie gateway, tools, auth, cron oder hooks

Ein typisches Praxisproblem: Ein Bot empfängt zwar Nachrichten, nutzt aber das falsche Modell, verliert Sessions zu früh oder antwortet im Gruppenchat sichtbarer als geplant. Genau diese Details landen nicht in einer verstreuten Tool-Konfiguration, sondern zentral in der openclaw.json.

Die gute Nachricht: Für ein kleines Setup brauchst du nur einen Bruchteil der verfügbaren Optionen. Weil OpenClaw JSON5 akzeptiert, sind Kommentare und Trailing Commas erlaubt. Das macht gerade den Einstieg deutlich entspannter als bei strengem JSON.

Absolute Minimal-Konfiguration

Die offizielle OpenClaw-Dokumentation zeigt als kleinstes Beispiel diese Struktur:

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

Wichtig ist hier vor allem ein Detail: Der Workspace hängt nicht unter agent.workspace, sondern unter agents.defaults.workspace.

Dieses Beispiel reicht bereits, damit ein WhatsApp-Absender aus der Allowlist dem Bot schreiben darf. Alles Weitere kommt aus Defaults.

Die Kernabschnitte im Detail

agents.defaults: Workspace und Modell-Standards

Der wichtigste Einstiegspunkt für die eigentliche Agent-Konfiguration ist agents.defaults.

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

Hier legst du fest:

• in welchem Workspace der Default-Agent arbeitet
• welches Modell primär verwendet wird
• welche Fallbacks bei Provider- oder Auth-Problemen greifen
• wie hoch das Standard-Reasoning ausfällt
• ob privilegierte Aktionen standardmäßig erlaubt sind

Für viele private oder semiproduktive Setups ist thinkingDefault: "low" ein guter Startpunkt, weil höhere Stufen mehr Latenz und Tokenverbrauch mitbringen.

agents.list: Identität und Agent-spezifische Overrides

Die sichtbare Identität eines Agenten sitzt nicht an der Root, sondern pro Agent in agents.list[].identity.

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-6" },
    },
    list: [
      {
        id: "main",
        default: true,
        identity: {
          name: "Clawd",
          theme: "helpful assistant",
          emoji: "🦞",
        },
      },
    ],
  },
}

Das ist vor allem dann sinnvoll, wenn du mehrere Agenten parallel betreibst oder einem Agenten eine klar erkennbare Rolle geben willst. Außerdem lassen sich an dieser Stelle einzelne Agenten gezielt von den Defaults abweichend konfigurieren.

Kein agent-Block: der wichtige Unterschied

Ein häufiger Denkfehler ist die Annahme, OpenClaw trenne zwischen einem Root-Block agent für das Gateway und agents für Sessions. Die aktuelle Doku beschreibt stattdessen diese Struktur:

• agents.* für Agent-Defaults und Agent-Listen
• session.* für Sitzungslogik
• messages.* für Antwort- und Gruppenverhalten
• gateway.* für Gateway-Runtime, Bindings und Control UI

Wenn du also Workspace, Modell oder Agent-Verhalten konfigurieren willst, landest du praktisch immer unter agents.defaults oder agents.list[] und nicht unter einem separaten agent-Objekt.

channels.<provider>: Messaging-Dienste anbinden

Jeder Messenger bekommt seinen eigenen Provider-Block unter channels.<provider>. Für Telegram sieht das laut offizieller Dokumentation zum Beispiel 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 wichtigsten Zugriffsmuster:

• pairing: unbekannte Nutzer koppeln sich erst per Einmal-Code
• allowlist: nur explizit erlaubte Nutzer oder Gruppen sind zugelassen
• open: alle DMs werden akzeptiert
• disabled: DMs sind komplett aus

Für Gruppen ergänzt groupPolicy die DM-Regeln. Mit requireMention: true lässt sich verhindern, dass der Bot in Gruppen ungefragt auf alles reagiert.

messages: sichtbare Antworten und Gruppenverhalten

Viele Einsteiger suchen Gruppenlogik im Channel-Block allein, aber OpenClaw trennt das zusätzlich über messages auf.

{
  messages: {
    visibleReplies: "automatic",
    groupChat: {
      visibleReplies: "message_tool",
      unmentionedInbound: "room_event",
    },
  },
}

Damit steuerst du unter anderem, ob Antworten in Gruppen automatisch sichtbar gepostet werden oder ob der Agent dafür explizit über das Message-Tool senden muss. Gerade in produktiveren Setups ist das relevant, wenn ein Agent Gruppenkontext mitlesen soll, aber nicht jeden halben Gedanken direkt nach außen tragen darf.

session: Lebenszyklus pro Unterhaltung

Der session-Block steuert, wie Gespräche getrennt, zurückgesetzt und aufbewahrt werden.

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

Praktisch wichtig sind dabei:

• scope für die Frage, was überhaupt als eigene Session zählt
• dmScope für Mehrkanal- oder Multi-User-Szenarien
• reset für automatische Rücksetzungen
• resetTriggers für manuelle Neustarts per Chat-Befehl

Wenn du einen Bot mit klar getrennten Einzelgesprächen willst, ist per-sender meist der naheliegende Start.

auth: Credential-Profile ohne rohe Secrets im Hauptfile

Die offizielle Doku trennt bewusst zwischen lesbarer Konfiguration und eigentlichen Geheimnissen. In auth definierst du die Profile und ihre Reihenfolge, nicht den Klartext-Schlüssel.

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

Die Secrets selbst gehören je nach Setup in Umgebungsvariablen, SecretRefs oder in die von OpenClaw getrennt verwalteten Auth-Daten. Das hält die Hauptdatei nachvollziehbar und senkt das Risiko, versehentlich Schlüssel ins Repository zu schieben.

tools.media: Audio und Video begrenzen

Für Medienpfade gibt es im tools-Block eigene Unterbereiche.

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

Hier lohnt sich fast immer eine konservative Haltung. Wer Maximalgrößen und Timeouts nicht begrenzt, baut sich schnell einen netten Weg, große Dateien mit unnötig viel Latenz und Kosten durch die Pipeline zu ziehen.

env: Variablen lokal bereitstellen

Die Doku zeigt außerdem einen env-Block für Umgebungsvariablen und Shell-Umgebung:

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

Technisch funktioniert das, aber für echte Schlüssel bleibt die bessere Praxis: keine Secrets direkt im gepflegten Config-File hinterlegen, sondern über lokale Secret-Mechanismen oder Umgebungsvariablen referenzieren.

Mini-Szenario: Eine solide Starter-Konfiguration

Wenn du einen Telegram-Bot mit klarer Allowlist, definierter Identität und manuellen Session-Resets willst, ist dieses Muster näher an der aktuellen Doku als eine fantasievolle Komplettdatei:

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
      },
      thinkingDefault: "low",
      elevatedDefault: "off",
    },
    list: [
      {
        id: "main",
        default: true,
        identity: {
          name: "Nexus",
          theme: "helpful assistant",
          emoji: "🦞",
        },
      },
    ],
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "allowlist",
      allowFrom: ["921587194"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["921587194"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
  },
  messages: {
    visibleReplies: "automatic",
  },
}

Das ist kein maximaler Ausbau, aber ein guter Startpunkt:

• klare Workspace-Zuordnung
• ein definiertes Primärmodell
• eingeschränkter Zugriff statt offener DMs
• sichtbare Identität am richtigen Ort
• einfache Session-Resets ohne Konfigurationsballast

Fehlerbehebung und Debugging

OpenClaw validiert die Datei strikt gegen das aktuelle Schema. Unbekannte Schlüssel oder falsche Typen werden nicht still geschluckt, sondern können den Start verhindern.

Für die Praxis sind vor allem diese Befehle nützlich:

openclaw config file
openclaw config get agents.defaults.workspace
openclaw config validate
openclaw config schema
openclaw doctor

Damit kannst du schnell prüfen:

• welche Config-Datei gerade aktiv ist
• welcher Wert effektiv an einem Pfad liegt
• ob die Datei schema-konform ist
• wie das Live-Schema aussieht
• welche Start- oder Validierungsfehler OpenClaw konkret meldet

Wenn du direkt editierst, ist außerdem relevant: Das Gateway beobachtet die Konfigurationsdatei und lädt gültige Änderungen automatisch nach. Ungültige Änderungen werden laut Doku abgewiesen, statt still das laufende Setup zu zerschießen.

Die Control UI kann zusätzlich helfen. Laut offizieller Doku erreichst du sie lokal unter http://127.0.0.1:18789; dort gibt es einen Config-Bereich mit Form-Ansicht und Raw-JSON-Editor.

Zusammenfassung

• Klein anfangen: Für den Einstieg reichen oft agents.defaults.workspace und ein Channel-Block.
• Schema zuerst ernst nehmen: OpenClaw akzeptiert keine Fantasie-Schlüssel. Gerade bei Copy-and-Paste-Beispielen lohnt ein schneller Validierungslauf.
• Agenten richtig einordnen: Workspace und Modell-Defaults leben unter agents.defaults, Identität unter agents.list[].identity.
• Zugriff bewusst begrenzen: allowlist und Mention-Gating sind für echte Nutzung fast immer die vernünftigere Wahl als ein offenes Setup.
• Debugging nicht raten: openclaw config validate, openclaw config schema und openclaw doctor sparen viel Sucherei.

Die openclaw.json sollte mit deinen Anforderungen wachsen, nicht mit deinem Ehrgeiz beim ersten Setup. Eine kleine, validierte Basis ist fast immer stabiler als ein riesiger Optionsblock, den du aus fünf Docs-Seiten zusammenkopiert hast und danach nie wieder anfassen willst.

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