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

Die OpenClaw Gateway-Konfiguration ist der Dreh- und Angelpunkt der Agenten-Pipeline. OpenClaw liest eine optionale JSON5-Konfiguration aus ~/.openclaw/openclaw.json. Fehlt diese Datei, startet das System mit sicheren Standardwerten. Für viele Nutzer kann die Vielzahl an Optionen und das Risiko von Fehlkonfigurationen anfangs überfordernd wirken.

Dieser Artikel beleuchtet die wichtigsten Abschnitte der Datei, zeigt praxisnahe Beispiele aus der offiziellen Dokumentation und hilft dabei, typische Stolpersteine zu umgehen.

Warum die openclaw.json so wichtig ist

OpenClaw unterscheidet sich von vielen KI-Frameworks durch seinen modularen Ansatz: Ein zentraler Gateway-Prozess verwaltet Channels, Modelle, Sessions und Automationen. Diese Architektur bietet hohe Flexibilität, verlagert jedoch viel Komplexität in eine einzige Konfigurationsdatei.

Ein konkretes Szenario: Ein Agent soll Telegram-Nachrichten empfangen, ein kosteneffizientes Modell nutzen und abends einen Cron-Job ausführen. Ohne eine saubere openclaw.json startet entweder der Channel nicht, das Modell wird nicht gefunden oder die Automation läuft ins Leere.

Die meisten Anwendungsfälle erfordern jedoch nur einen Bruchteil der verfügbaren Optionen. Da die Datei im JSON5-Format vorliegt, sind Kommentare und Trailing Commas problemlos möglich. Der Start gelingt bereits mit einer minimalen Konfiguration.

Absolute Minimal-Konfiguration

Nach offizieller Dokumentation genügen diese Zeilen:

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

Diese zwei Abschnitte bergen kaum Fehlerquellen. Für alle weiteren Parameter nutzt OpenClaw sichere Standardwerte.

Die Kernabschnitte im Detail

Identity: Das Erscheinungsbild des Agenten

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

Der optionale identity-Block bestimmt das äußere Erscheinungsbild des Agenten – Name, Stil und Emoji. Das ist besonders hilfreich, wenn mehrere Agenten parallel betrieben werden.

Unterschied zwischen agent und agents

OpenClaw unterscheidet zwischen dem spezifischen Gateway (agent) und den globalen Standardwerten für alle 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 (z. B. anthropic/claude-sonnet-4-6) gesteuert. Unter model.fallbacks lassen sich alternative Modelle für den Fall von Provider-Ausfällen definieren. Über models kann zudem ein Katalog mit lesbaren Alias-Namen angelegt werden.

Das Verhalten des Agenten wird durch weitere Parameter bestimmt: thinkingDefault regelt das Reasoning-Level, verboseDefault die Ausführlichkeit der Antworten und elevatedDefault legt fest, ob privilegierte Kommandos standardmäßig erlaubt sind. Ein häufiger Fehler ist es, thinkingDefault im Produktivbetrieb auf "high" zu belassen, was den Token-Verbrauch stark erhöht. Für die meisten Anwendungsfälle ist "low" der empfehlenswerte Standard.

Channels: Messaging-Dienste verbinden

Jeder Channel erhält einen eigenen Abschnitt unter channels.<provider>. Eine typische Telegram-Konfiguration sieht 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. Die Standardeinstellung pairing sendet unbekannten Absendern einen einmaligen Code. Mit allowlist werden nur explizit erlaubte Nutzer zugelassen, während open alle Direktnachrichten erlaubt. Über disabled lassen sich diese komplett blockieren.

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

Auth: API-Provider verwalten

Der auth-Block definiert die verfügbaren API-Credentials und deren Priorität. Die eigentlichen Secrets liegen aus Sicherheitsgründen 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"],
    },
  },
}

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" }],
      },
    },
  },
}

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 hier der scope (pro Absender oder global) sowie die Reset-Bedingungen. Ein Reset kann zeitbasiert (daily), bei Inaktivität (idle) oder durch spezifische Befehle (resetTriggers) erfolgen.

Env: Umgebungsvariablen

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

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 ist sicher, da keine privilegierten Kommandos erlaubt sind und Direktnachrichten auf eine Allowlist beschränkt bleiben. Sie ist zudem kosteneffizient und lässt sich bei Bedarf schrittweise erweitern.

Fehlerbehebung und Debugging

OpenClaw verweigert den Start konsequent, wenn die Konfiguration nicht exakt zum Schema passt. Unbekannte Schlüssel oder falsche Datentypen führen zu einem sofortigen Abbruch, da es keine stillschweigende Fallback-Validierung gibt.

Bei Startproblemen stehen diagnostische Befehle zur Verfügung. Mit openclaw doctor lassen sich Validierungsfehler anzeigen und durch den Zusatz --fix oft direkt beheben. Für detaillierte Start-Logs hilft openclaw gateway start --verbose, während openclaw config schema das aktuelle JSON-Schema ausgibt.

Falls ein Modell nicht antwortet, lohnt sich ein Blick auf die Limits der Provider. Die Verfügbarkeit lässt sich mit openclaw models prüfen. Zusätzlich bietet die Control UI unter der lokalen Adresse 127.0.0.1:18789 einen Config-Tab mit formularbasiertem Interface, Live-Schema-Hilfe und einem Raw-JSON-Editor.

Fazit

• Minimal starten: OpenClaw nutzt das JSON5-Format. Oft genügen der agent-Block und ein Channel. Die Konfiguration sollte nur bei konkretem Bedarf erweitert werden.
• Strikte Validierung: Die Datei muss exakt zum Schema passen. Bei Fehlern hilft openclaw doctor bei der Diagnose und automatischen Reparatur.
• Ausfallsicherheit: Die Definition von fallbacks stellt sicher, dass der Agent auch bei Provider-Ausfällen erreichbar bleibt.
• Sichere Kommunikation: Für den Einstieg empfiehlt sich die DM-Policy pairing, für den Produktivbetrieb bietet allowlist einen höheren Schutz.

Die openclaw.json wächst mit den Anforderungen der Pipeline. Eine einfache Basis, die regelmäßig validiert wird, bildet das stabilste Fundament für zuverlässige Agenten.

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