OpenClaw Konfiguration

Jeder Entwickler kennt das: Du installierst ein neues Tool und verbringst die erste Stunde damit, kryptische Config-Dateien zu entschlüsseln. Oft reicht ein vergessenes Komma oder ein falscher Key, damit das ganze System streikt und du dich durch Log-Dateien wühlen musst.

OpenClaw macht das anders. Die Konfiguration ist flexibel, aber streng validiert, damit du Fehler sofort erkennst, bevor sie im Betrieb Probleme verursachen.

Voraussetzungen

• Eine installierte OpenClaw-Instanz
• Zugriff auf das Verzeichnis ~/.openclaw/

Schnellstart

OpenClaw liest eine optionale JSON5-Konfiguration aus der Datei ~/.openclaw/openclaw.json. Falls die Datei nicht existiert, nutzt OpenClaw sichere Standardwerte. JSON5 ist super, weil du Kommentare und hängende Kommas nutzen kannst.

Hier ist eine minimale Konfiguration, um direkt loszulegen:

~/.openclaw/openclaw.json

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

Wenn du neu bei der Konfiguration bist, empfehle ich dir openclaw onboard. Das ist ein interaktiver Setup-Assistent, der dich Schritt für Schritt durch die wichtigsten Einstellungen führt.

Konfiguration anpassen

Du hast vier Wege, um deine Einstellungen zu verwalten. Wähle den, der am besten zu deinem Workflow passt.

1. Interaktive Wizards

Für das erste Setup oder größere Änderungen sind die Wizards ideal:

• openclaw onboard: Der komplette Setup-Assistent.
• openclaw configure: Gezielter Wizard für die Konfiguration.

2. CLI (One-Liner)

Wenn du schnell einzelne Werte ändern willst, ohne eine Datei zu öffnen, nutze die CLI:

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey

3. Control UI

Öffne http://127.0.0.1:18789 in deinem Browser und wechsle zum Tab Config. Die UI generiert ein Formular basierend auf dem Schema der Konfiguration. Falls du lieber direkt im Code arbeitest, gibt es dort auch einen Raw JSON Editor.

4. Direktes Editieren

Du kannst die ~/.openclaw/openclaw.json direkt in deinem Editor bearbeiten. Das Gateway überwacht die Datei und wendet Änderungen automatisch an (Hot Reload).

Fehlerbehebung

OpenClaw ist bei der Validierung sehr streng. Unbekannte Keys oder falsche Datentypen führen dazu, dass das Gateway den Start verweigert. Das verhindert schwer findbare Fehler zur Laufzeit.

Wenn die Validierung fehlschlägt, passiert Folgendes:

• Das Gateway bootet nicht.
• Nur Diagnose-Befehle funktionieren noch.

Nutze diese Befehle, um Probleme zu finden und zu beheben:

• openclaw doctor: Zeigt dir genau an, wo der Fehler in der Config liegt.
• openclaw doctor --fix: Versucht, die Fehler automatisch zu reparieren.
• openclaw logs: Prüft die System-Logs auf Details.
• openclaw health: Checkt den allgemeinen Zustand des Systems.

AI Setup Assistant

Nächste Schritte

• Full Configuration Reference
• Configuration Examples

Kennst du das? Du möchtest nur schnell einen Bot für Telegram oder WhatsApp bauen, aber plötzlich hängst du in API-Dokumentationen fest oder kämpfst mit dem Session-Management. Es ist frustrierend, wenn die Logik für jeden Channel anders funktioniert und die Konfigurationsdatei immer unübersichtlicher wird.

Du willst eigentlich nur, dass dein Agent auf Nachrichten reagiert, das richtige Modell nutzt und sicher in einer isolierten Umgebung läuft. Hier erfährst du, wie du diese Standardaufgaben ohne Kopfschmerzen erledigst.

Voraussetzungen

Bevor du startest, stelle sicher, dass du folgende Dinge bereit hast (je nach Vorhaben):

• API-Zugangsdaten für deine Channels (z.B. botToken für Telegram).
• Zugriff auf die openclaw.json5 Konfigurationsdatei.
• Docker (falls du Sandboxing aktivieren möchtest).
• Die installierte CLI für Modell-Wechsel.

Schnellstart

In weniger als 5 Minuten setzt du einen funktionalen Channel mit Modell-Anbindung auf. Füge diesen Block in deine Konfiguration ein:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "DEIN_BOT_TOKEN",
      dmPolicy: "pairing",
    },
  },
}

Channels einrichten

Jeder Channel hat seinen eigenen Bereich unter channels.<provider>. Detaillierte Schritte findest du auf den jeweiligen Seiten:

• WhatsApp — channels.whatsapp
• Telegram — channels.telegram
• Discord — channels.discord
• Slack — channels.slack
• Signal — channels.signal
• iMessage — channels.imessage
• Google Chat — channels.googlechat
• Mattermost — channels.mattermost
• MS Teams — channels.msteams

Alle Channels nutzen das gleiche Muster für die dmPolicy:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // nur für allowlist/open
    },
  },
}

Modelle wählen und konfigurieren

Du legst ein primäres Modell und optionale Fallbacks fest:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models definiert den Katalog und dient als allowlist für /model.
• Modell-Referenzen nutzen das Format provider/model.
• Details findest du unter Models CLI und Model Failover.
• Für eigene Provider schau in die Custom providers Referenz.

Zugriffskontrolle (Wer darf schreiben?)

Der Zugriff auf DMs wird pro Channel via dmPolicy gesteuert:

• "pairing" (Standard): Unbekannte Absender erhalten einen Pairing-Code zur Freigabe.
• "allowlist": Nur Absender in allowFrom.
• "open": Erlaubt alle eingehenden DMs (erfordert allowFrom: ["*"]).
• "disabled": Ignoriert alle DMs.

Für Gruppen nutzt du groupPolicy + groupAllowFrom. Details gibt es in der Vollständigen Referenz.

Erwähnungen in Gruppen (Mention Gating)

In Gruppen erfordern Nachrichten standardmäßig eine Erwähnung. Das kannst du pro Agent anpassen:

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Metadata mentions: Native @-Erwähnungen (WhatsApp, Telegram).
• Text patterns: Regex-Muster in mentionPatterns.
• Siehe full reference.

Sessions und Resets

Sessions isolieren Gespräche und sorgen für Kontinuität:

{
  session: {
    dmScope: "per-channel-peer",  // Empfohlen für Multi-User
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: main, per-peer, per-channel-peer oder per-account-channel-peer.
• Details unter Session Management und in der Referenz.

Sandboxing aktivieren

Lass Agenten-Sessions in isolierten Docker-Containern laufen:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

Baue zuerst das Image: scripts/sandbox-setup.sh. Mehr dazu unter Sandboxing.

Heartbeat (Check-ins)

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

• every: Zeitangabe (z.B. 30m, 2h). 0m deaktiviert den Heartbeat.
• target: last, whatsapp, telegram, discord oder none.
• Siehe Heartbeat Guide.

Cron Jobs

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}

Übersicht unter Cron jobs.

Webhooks (Hooks)

Aktiviere HTTP-Endpunkte auf dem Gateway:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

Details zu Mappings findest du in der Referenz.

Multi-Agent Routing

Betreibe mehrere Agenten mit getrennten Workspaces:

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

Regeln findest du unter Multi-Agent.

Konfiguration aufteilen ($include)

Nutze $include, um große Dateien zu strukturieren:

~/.openclaw/openclaw.json

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

• Einzelne Datei: Ersetzt das Objekt.
• Array: Deep-merge in der angegebenen Reihenfolge.
• Relative Pfade: Beziehen sich auf die inkludierende Datei.
• Verschachtelung: Bis zu 10 Ebenen tief.

Fehlerbehebung

• Fehlende Dateien bei $include: Stelle sicher, dass die Pfade relativ zur Hauptdatei korrekt sind.
• Parse-Fehler: Überprüfe deine JSON5-Syntax, besonders bei Kommas und Klammern.
• Zirkuläre Includes: Achte darauf, dass sich Dateien nicht gegenseitig inkludieren.
• Sandboxing schlägt fehl: Hast du scripts/sandbox-setup.sh ausgeführt, um das Docker-Image zu bauen?

Hast du spezifische Fragen zu deinem Setup? Frag den AI Setup Assistant.

Nächste Schritte

• Models CLI
• Model Failover
• Session Management
• Sandboxing Guide
• Configuration Reference

Kennst du das? Du änderst eine Kleinigkeit in der Config, zum Beispiel einen Model-Parameter oder einen Channel-Namen, und musst danach den gesamten Prozess stoppen und neu starten. Das unterbricht deinen Flow und kostet jedes Mal Zeit.

Das Gateway nimmt dir diesen Prozess ab. Es beobachtet deine Konfigurationsdatei und übernimmt Änderungen im laufenden Betrieb. So kannst du direkt sehen, wie sich deine Anpassungen auswirken, ohne manuell einzugreifen.

Voraussetzungen

• Die Konfigurationsdatei unter ~/.openclaw/openclaw.json

Schnellstart

Das Gateway überwacht die Datei ~/.openclaw/openclaw.json automatisch. Für die meisten Einstellungen ist kein manueller Neustart erforderlich. Ich empfehle den Modus hybrid, da er die beste Balance zwischen Geschwindigkeit und Stabilität bietet.

So konfigurierst du das Reload-Verhalten in deiner Datei:

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

Reload-Modi

Du kannst zwischen vier verschiedenen Modi wählen, je nachdem, wie viel Kontrolle du behalten möchtest:

Modus	Verhalten
hybrid (Standard)	Wendet sichere Änderungen sofort per Hot-Apply an. Bei kritischen Änderungen erfolgt ein automatischer Neustart.
hot	Wendet nur sichere Änderungen sofort an. Wenn ein Neustart nötig ist, wird eine Warnung geloggt – du kümmerst dich selbst darum.
restart	Startet das Gateway bei jeder Änderung an der Config neu, egal ob die Änderung sicher ist oder nicht.
off	Deaktiviert die Dateiüberwachung. Änderungen werden erst beim nächsten manuellen Neustart aktiv.

Was per Hot-Apply geht und was einen Neustart braucht

Die meisten Felder werden ohne Downtime übernommen. Wenn du den hybrid Modus nutzt, werden die Änderungen, die einen Neustart erfordern, automatisch abgewickelt.

Kategorie	Felder	Neustart nötig?
Channels	channels.*, web (WhatsApp) — alle integrierten und Extension-Channels	Nein
Agent & models	agent, agents, models, routing	Nein
Automation	hooks, cron, agent.heartbeat	Nein
Sessions & messages	session, messages	Nein
Tools & media	tools, browser, skills, audio, talk	Nein
UI & misc	ui, logging, identity, bindings	Nein
Gateway server	gateway.* (port, bind, auth, tailscale, TLS, HTTP)	Ja
Infrastructure	discovery, canvasHost, plugins	Ja

[!NOTE] gateway.reload und gateway.remote sind Ausnahmen — Änderungen an diesen Feldern lösen keinen Neustart aus.

Fehlerbehebung

Falls Änderungen nicht wie erwartet übernommen werden, prüfe folgende Punkte:

• Modus hot aktiv: Wenn du im hot Modus arbeitest und eine Änderung an gateway.port vornimmst, wird das Gateway nur eine Warnung loggen. Du musst den Prozess dann manuell neu starten.
• Syntax-Fehler: Stelle sicher, dass die openclaw.json ein gültiges Format hat, bevor du speicherst.

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

• Gateway Remote-Konfiguration
• Channels einrichten

Kennst du das? Du möchtest deine Konfiguration automatisieren, aber manuelle Datei-Edits sind fehleranfällig und unterbrechen deinen Workflow. Wenn du Einstellungen direkt über Code oder Skripte ändern willst, ohne händisch in YAML- oder JSON-Dateien zu wühlen, sind programmatische Updates der richtige Weg.

Anstatt Dienste manuell neu zu starten oder Konfigurationsdateien zu überschreiben, nutzt du einfach RPC-Calls. Das ist sauberer, sicherer und lässt sich perfekt in deine CI/CD-Pipelines oder Admin-Tools integrieren.

Voraussetzungen

• Ein laufendes Gateway
• Zugriff auf das openclaw CLI

Schnellstart

Hier erfährst du, wie du die Konfiguration deines Gateways in wenigen Minuten über die API anpasst.

config.apply (Vollständiger Austausch)

Diese Methode validiert und schreibt die gesamte Konfiguration und startet das Gateway in einem einzigen Schritt neu.

Wichtig: config.apply ersetzt die komplette Konfiguration. Wenn du nur Teile ändern willst, solltest du config.patch nutzen oder für einzelne Keys openclaw config set verwenden.

Parameter:

• raw (string): JSON5-Payload für die gesamte Konfiguration.
• baseHash (optional): Der Konfigurations-Hash aus config.get (erforderlich, wenn bereits eine Konfiguration existiert).
• sessionKey (optional): Session-Key für den Wake-up-Ping nach dem Neustart.
• note (optional): Notiz für den Restart-Sentinel.
• restartDelayMs (optional): Verzögerung vor dem Neustart (Standard ist 2000).

openclaw gateway call config.get --params '{}'  # Sichere den payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123"
}'

config.patch (Teil-Update)

Wenn du nur bestimmte Werte ändern möchtest, ist config.patch die beste Wahl. Es führt ein Teil-Update mit der bestehenden Konfiguration zusammen (JSON merge patch Semantik):

• Objekte werden rekursiv zusammengeführt.
• null löscht einen Key.
• Arrays werden komplett ersetzt.

Parameter:

• raw (string): JSON5 mit genau den Keys, die du ändern möchtest.
• baseHash (erforderlich): Der Konfigurations-Hash aus config.get.
• sessionKey, note, restartDelayMs: Diese Parameter funktionieren identisch wie bei config.apply.

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

Fehlerbehebung

• Konfiguration wurde komplett gelöscht: Das passiert, wenn du config.apply statt config.patch verwendest. config.apply überschreibt alles, was nicht im raw-String enthalten ist.
• baseHash Fehler: Bei config.patch musst du zwingend den aktuellen Hash angeben. Rufe vorher config.get auf, um den aktuellen Status zu validieren.

Bei weiteren Fragen hilft dir der AI Setup Assistant jederzeit weiter.

Nächste Schritte

• Gateway API Reference
• CLI Command Overview

Man kennt das: Überall fliegen API-Keys herum. Mal stecken sie in der Shell, mal in einer versteckten Datei, die man vor drei Monaten angelegt hat. Das Management von Umgebungsvariablen nervt oft mehr als das eigentliche Setup der Tools.

OpenClaw versucht hier Ordnung zu schaffen, damit du nicht jedes Mal raten musst, wo welcher Key definiert ist. Hier ist der beste Weg, um deine Umgebung sauber zu halten.

Voraussetzungen

• Eine OpenClaw Konfigurationsdatei
• Eine .env-Datei (lokal oder global)

Schnellstart

OpenClaw liest Umgebungsvariablen standardmäßig aus dem Parent-Prozess. Falls dort nichts zu finden ist, werden folgende Orte geprüft:

1. .env im aktuellen Arbeitsverzeichnis
2. ~/.openclaw/.env als globaler Fallback

Wichtig: Diese Dateien überschreiben niemals bereits existierende Umgebungsvariablen. Du kannst Variablen auch direkt “inline” in deiner Konfiguration festlegen:

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Shell-Import (optional)

Falls bestimmte Keys fehlen, kann OpenClaw deine Login-Shell starten und nur die fehlenden Werte importieren. Das aktivierst du so:

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Alternativ nutzt du einfach die Variable OPENCLAW_LOAD_SHELL_ENV=1.

Variablen in der Konfiguration nutzen

Du kannst Umgebungsvariablen mit ${VAR_NAME} in jedem String innerhalb der Konfiguration referenzieren. Das ist besonders nützlich für das Gateway oder spezifische Provider:

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

Dabei gelten diese Regeln:

• Es werden nur Namen in Großbuchstaben erkannt: [A-Z_][A-Z0-9_]*
• Falls du ein literales ${VAR} ausgeben willst, nutze das Escaping: $${VAR}
• Das funktioniert auch innerhalb von $include-Dateien
• Inline-Ersetzung ist möglich: "${BASE}/v1" wird beispielsweise zu "https://api.example.com/v1"

Weitere Details zur Rangfolge findest du unter Environment.

Fehlerbehebung

• Fehlende Variablen: Wenn eine Variable in der Konfiguration mit ${VAR} referenziert wird, aber nicht existiert oder leer ist, wirft OpenClaw beim Laden einen Error. Stelle sicher, dass dein File oder dein Prozess die Variable wirklich bereitstellt.
• Precedence: Denke daran, dass bestehende System-Variablen Vorrang vor den Einträgen in deinen .env-Dateien haben.

Eine vollständige Übersicht aller Felder findest du in der Configuration Reference.

Du hast Fragen zum Setup? Frag den AI Setup Assistant.

Nächste Schritte

• Configuration Examples
• Configuration Reference
• Doctor