Zum Inhalt springen
openclaw · 6 min Lesezeit

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

Wie OpenClaw seine JSON5-Konfiguration (openclaw.json) liest, welche Bereiche wirklich wichtig sind und welche Defaults für Hobby-Setups sinnvoll sind.

openclaw config gateway tutorial

Die OpenClaw Gateway-Konfiguration ist der Dreh- und Angelpunkt deiner Agenten-Pipeline. OpenClaw liest eine optionale JSON5-Konfiguration aus ~/.openclaw/openclaw.json. Falls die Datei fehlt, startet OpenClaw mit sicheren Defaults. Für viele Hobby-User ist das aber anfangs überfordernd: zu viele Optionen, unklare Defaults und riskante Fehlkonfigurationen.

Dieser Artikel erklärt die wichtigsten Abschnitte der openclaw.json, zeigt praxisnahe Beispiele aus der offiziellen Doku und hilft dir, typische Stolpersteine zu vermeiden.

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 ist flexibel, verlagert aber viel Komplexität in eine einzige Konfigurationsdatei.

Ein konkretes Szenario: Stell dir vor, du willst einen Agenten, der Telegram-Nachrichten empfängt, ein günstiges Modell nutzt und jeden Abend einen Cron-Job ausführt. Ohne eine saubere openclaw.json startet entweder der Channel nicht, das Modell wird nicht gefunden oder die Automation läuft ins Leere.

Die gute Nachricht: Die meisten Nutzer benötigen nur einen Bruchteil der verfügbaren Optionen. Die Datei ist JSON5 — also JSON mit Kommentaren und trailing commas. Starten kannst du mit einer minimalen Konfiguration, die aus zwei Zeilen besteht.

Absolute Minimal-Konfiguration

Nach offizieller Doku reicht das:

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

Zwei Abschnitte, keine Geheimnisse, keine Fehlerquellen. OpenClaw nutzt für alles andere sichere Defaults.

Die Kernabschnitte im Detail

identity: Gib deinem Agenten einen Namen

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

Der identity-Block ist optional, aber praktisch. Er bestimmt, wie sich dein Agent nach außen darstellt — Name, Stil und Emoji. Nützlich, wenn du mehrere Agents betreibst.

agent vs. agents: Nicht verwechseln

OpenClaw unterscheidet zwei Ebenen:

  • agent (singular): Workspace und Modell für diesen spezifischen Gateway.
  • agents (plural): Defaults, die für alle Agent-Sessions gelten — Modell, Fallbacks, Tool-Freigaben, Thinking-Level.

Empfohlener Starter:

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

Wichtige Felder in agents.defaults:

  • model.primary: Standardmodell. Im Format provider/model-id, z.B. anthropic/claude-sonnet-4-6.
  • model.fallbacks: Falls das Primary-Modell nicht verfügbar ist, greift OpenClaw automatisch auf diese zurück.
  • models: Definiert den Model-Katalog mit lesbaren Alias-Namen (z.B. "anthropic/claude-sonnet-4-6": { alias: "Sonnet" }).
  • thinkingDefault: Reasoning-Level ("low", "medium", "high", "off").
  • verboseDefault: Ausführlichkeit ("off" oder "on").
  • elevatedDefault: Ob privilegierte Kommandos standardmäßig erlaubt sind ("on" oder "off").

Typischer Fehler: thinkingDefault auf "high" zu lassen im Produktivbetrieb — das kostet deutlich mehr Tokens pro Anfrage. "low" ist der empfehlenswerte Default.

channels: Messaging-Dienste verbinden

Jeder Channel hat seinen eigenen Abschnitt unter channels.<provider>. So sieht eine Telegram-Konfiguration aus:

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

DM-Policies (für alle Channels gleich):

  • pairing (Default): Unbekannte Sender erhalten einen einmaligen Pairing-Code.
  • allowlist: Nur explizit erlaubte Absender.
  • open: Alle DMs erlaubt (erfordert allowFrom: ["*"]).
  • disabled: DMs komplett blockiert.

Credentials: Tokens gehören nie direkt ins Config-File, wenn du in ein Repo pushst. OpenClaw unterstützt ${ENV_VAR}-Syntax — setze die Variable in deiner Shell oder nutze ein Secrets-File.

auth: API-Provider verwalten

Der auth-Block definiert, welche API-Credentials verfügbar sind und in welcher Reihenfolge sie verwendet werden. Secrets liegen nicht in der openclaw.json, sondern in 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, Video

Über den tools-Block steuerst du, wie OpenClaw mit Medien umgeht:

{
  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

Der session-Block bestimmt, wie Sessions gehandhabt werden:

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

Wichtige Optionen:

  • scope: "per-sender" (pro Absender) oder "global" (alle nutzen dieselbe Session).
  • reset.mode: "daily" für täglichen Reset, "idle" für Inactivity-basiert.
  • resetTriggers: Welche Befehle einen Session-Reset auslösen.

env: Umgebungsvariablen

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

Mini-Szenario: Eine solide Starter-Konfiguration

Du startest mit OpenClaw und willst einen Telegram-Bot, der Nachrichten mit einem kostenlosen Modell beantwortet und den du über /new jederzeit resetten kannst:

// ~/.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 (keine privilegierten Commands, DMs nur von dir), kosteneffizient (kostenloses Modell) und praktisch (schneller Reset per Befehl). Von hier aus erweiterst du schrittweise.

Debugging: Wenn etwas nicht funktioniert

  1. Strict Validation: OpenClaw verweigert den Start, wenn die Config nicht vollständig zum Schema passt. Unbekannte Keys oder falsche Typen führen zu einem sofortigen Stop. Es gibt keine stillschweigende Fallback-Validierung.

  2. Diagnose-Befehle: Bei Startproblemen funktionieren nur noch diagnostische Commands. Starte mit:

    • openclaw doctor — zeigt exakte Validierungsfehler
    • openclaw doctor --fix (oder --yes) — repariert automatisch wo möglich
    • openclaw gateway start --verbose — detaillierte Logs beim Start
    • openclaw config schema — das aktuelle JSON-Schema ausgeben

  3. Model nicht verfügbar: Kostenlose Models haben Limits. Prüfe mit openclaw models die Verfügbarkeit.

  4. Control UI: Unter http://127.0.0.1:18789 öffnet sich die Control UI mit dem Config-Tab. Hier siehst du ein Form-basiertes Interface mit Live-Schema-Hilfe und einen Raw-JSON-Editor.

Key Takeaways

  • JSON5, nicht YAML: OpenClaw nutzt ~/.openclaw/openclaw.json im JSON5-Format.
  • Starte minimal: Zwei Abschnitte (agent + ein Channel) reichen oft. Erweitere nur bei Bedarf.
  • Strict Validation: Die Config muss vollständig zum Schema passen — unbekannte Keys blockieren den Start.
  • Model-Failover: Definiere immer fallbacks, damit dein Agent auch bei Provider-Downtime antwortet.
  • DM-Policies: pairing (Default) ist sicher für erste Schritte, allowlist für Produktivbetrieb.
  • openclaw doctor ist dein Freund: Der erste Befehl bei jedem Problem, der sogar automatisch reparieren kann.

Die openclaw.json ist kein statisches Dokument — sie wächst mit deinen Anforderungen. Beginne mit einer einfachen Basis, validiere mit openclaw doctor und erweitere nur bei Bedarf. So vermeidest du die häufigsten Fallstricke und baust eine stabile Grundlage für deine Agenten.

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

Quellen

Serie: OpenClaw Praxis-Serie

Teil 1 von 3

Das könnte dich auch interessieren

openclaw

OpenClaw Codex Provider: Native Auth, Threads, Model Discovery

Der gebündelte Codex Provider nutzt jetzt OpenClaw-native Authentifizierung, Threads und Model Discovery statt OpenAI-Wrapper. Starker Upgrade-Pfad.
openclaw

OpenClaw Security Hardening: Browser, Sandbox, CLI

OpenClaw 2026.4.10 bringt Security-Hardening für Browser, Sandbox und CLI. Stärkere Isolation und weniger Risiken.
openclaw

OpenClaw Task Flow im Core: Persistente Background-Orchestrierung

OpenClaw 2026.4.2 bringt Task Flow zurück in den Core: persistente Hintergrund-Orchestrierung mit durable state und klarer Plugin-Trennung.
Alle Beiträge