Zum Hauptinhalt springen

​
Konfiguration

OpenClaw liest eine optionale -Konfiguration aus ~/.openclaw/openclaw.json. Wenn die Datei fehlt, verwendet OpenClaw sichere Standardwerte. Häufige Gründe, eine Konfiguration hinzuzufügen:
  • Kanäle verbinden und steuern, wer dem Bot Nachrichten senden kann
  • Modelle, Tools, Sandboxing oder Automatisierung festlegen (Cron, Hooks)
  • Sitzungen, Medien, Netzwerk oder UI anpassen
In der vollständigen Referenz finden Sie jedes verfügbare Feld.
Neu bei der Konfiguration? Beginnen Sie mit openclaw onboard für die interaktive Einrichtung oder sehen Sie sich die Anleitung Configuration Examples für vollständige Copy-and-paste-Konfigurationen an.

​
Minimale Konfiguration

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

​
Konfiguration bearbeiten

openclaw onboard       # vollständiger Onboarding-Ablauf
openclaw configure     # Konfigurationsassistent

​
Strikte Validierung

OpenClaw akzeptiert nur Konfigurationen, die vollständig dem Schema entsprechen. Unbekannte Schlüssel, fehlerhafte Typen oder ungültige Werte führen dazu, dass das Gateway den Start verweigert. Die einzige Ausnahme auf Root-Ebene ist $schema (string), damit Editoren JSON-Schema-Metadaten anhängen können.
Hinweise zu Schema-Tools:
  • openclaw config schema gibt dieselbe JSON-Schema-Familie aus, die von Control UI und der Konfigurationsvalidierung verwendet wird.
  • Feldwerte für title und description werden in die Schema-Ausgabe für Editor- und Formular-Tools übernommen.
  • Verschachtelte Objekt-, Wildcard- (*) und Array-Item- ([]) Einträge übernehmen dieselben Docs-Metadaten, wenn passende Felddokumentation vorhanden ist.
  • Auch Kompositionszweige mit anyOf / oneOf / allOf übernehmen dieselben Docs- Metadaten, sodass Union-/Intersection-Varianten dieselbe Feldhilfe behalten.
  • config.schema.lookup gibt einen normalisierten Konfigurationspfad mit einem flachen Schemaknoten (title, description, type, enum, const, häufige Grenzen und ähnliche Validierungsfelder), zugeordneten UI-Hinweis-Metadaten sowie unmittelbaren Zusammenfassungen der Unterelemente für Drill-down-Tools zurück.
  • Runtime-Plugin-/Kanalschemata werden zusammengeführt, wenn das Gateway die aktuelle Manifest-Registry laden kann.
Wenn die Validierung fehlschlägt:
  • Das Gateway startet nicht
  • Nur Diagnosebefehle funktionieren (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Führen Sie openclaw doctor aus, um die genauen Probleme zu sehen
  • Führen Sie openclaw doctor --fix (oder --yes) aus, um Reparaturen anzuwenden

​
Häufige Aufgaben

Jeder Kanal hat einen eigenen Konfigurationsabschnitt unter channels.<provider>. Die Einrichtungsschritte finden Sie auf der jeweiligen Kanalseite:Alle Kanäle verwenden dasselbe DM-Richtlinienmuster:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // nur für allowlist/open
    },
  },
}
Legen Sie das primäre Modell und optionale Fallbacks fest:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models definiert den Modellkatalog und dient als Allowlist für /model.
  • Modell-Refs verwenden das Format provider/model (z. B. anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx steuert das Downscaling von Bildern in Transkripten/Tools (Standard 1200); niedrigere Werte reduzieren in der Regel den Verbrauch von Vision-Tokens bei screenshotlastigen Ausführungen.
  • Siehe Models CLI zum Wechseln von Modellen im Chat und Model Failover für Auth-Rotation und Fallback-Verhalten.
  • Für benutzerdefinierte/selbst gehostete Provider siehe Custom providers in der Referenz.
Der DM-Zugriff wird pro Kanal über dmPolicy gesteuert:
  • "pairing" (Standard): unbekannte Absender erhalten einen einmaligen Pairing-Code zur Genehmigung
  • "allowlist": nur Absender in allowFrom (oder im gepaarten Allow-Store)
  • "open": erlaubt alle eingehenden DMs (erfordert allowFrom: ["*"])
  • "disabled": ignoriert alle DMs
Für Gruppen verwenden Sie groupPolicy + groupAllowFrom oder kanalspezifische Allowlists.In der vollständigen Referenz finden Sie kanalspezifische Details.
Gruppennachrichten erfordern standardmäßig eine Erwähnung. Konfigurieren Sie Muster pro Agent:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Metadaten-Erwähnungen: native @-Erwähnungen (WhatsApp Tap-to-mention, Telegram @bot usw.)
  • Textmuster: sichere Regex-Muster in mentionPatterns
  • Siehe vollständige Referenz für kanalspezifische Überschreibungen und den Self-Chat-Modus.
Verwenden Sie agents.defaults.skills für eine gemeinsame Baseline und überschreiben Sie dann bestimmte Agenten mit agents.list[].skills:
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // übernimmt github, weather
      { id: "docs", skills: ["docs-search"] }, // ersetzt Standardwerte
      { id: "locked-down", skills: [] }, // keine Skills
    ],
  },
}
  • Lassen Sie agents.defaults.skills weg, damit Skills standardmäßig nicht eingeschränkt sind.
  • Lassen Sie agents.list[].skills weg, um die Standardwerte zu übernehmen.
  • Setzen Sie agents.list[].skills: [], um keine Skills zu erlauben.
  • Siehe Skills, Skills config und die Configuration Reference.
Steuern Sie, wie aggressiv das Gateway Kanäle neu startet, die veraltet wirken:
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • Setzen Sie gateway.channelHealthCheckMinutes: 0, um Neustarts durch den Health Monitor global zu deaktivieren.
  • channelStaleEventThresholdMinutes sollte größer oder gleich dem Prüfintervall sein.
  • Verwenden Sie channels.<provider>.healthMonitor.enabled oder channels.<provider>.accounts.<id>.healthMonitor.enabled, um automatische Neustarts für einen einzelnen Kanal oder ein einzelnes Konto zu deaktivieren, ohne den globalen Monitor auszuschalten.
  • Siehe Health Checks für operative Fehlerbehebung und die vollständige Referenz für alle Felder.
Sitzungen steuern Gesprächskontinuität und Isolation:
{
  session: {
    dmScope: "per-channel-peer",  // empfohlen für mehrere Benutzer
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (geteilt) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: globale Standardwerte für threadgebundenes Sitzungsrouting (Discord unterstützt /focus, /unfocus, /agents, /session idle und /session max-age).
  • Siehe Session Management für Scoping, Identitätsverknüpfungen und Sende-Richtlinien.
  • Siehe vollständige Referenz für alle Felder.
Führen Sie Agentensitzungen in isolierten Docker-Containern aus:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Erstellen Sie zuerst das Image: scripts/sandbox-setup.shSiehe Sandboxing für die vollständige Anleitung und die vollständige Referenz für alle Optionen.
Relay-gestützter Push wird in openclaw.json konfiguriert.Legen Sie dies in der Gateway-Konfiguration fest:
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Standard: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
CLI-Äquivalent:
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
Was dies bewirkt:
  • Ermöglicht dem Gateway, push.test, Wake-Nudges und Reconnect-Wakes über das externe Relay zu senden.
  • Verwendet eine registrierungsbezogene Sendeberechtigung, die von der gepaarten iOS-App weitergeleitet wird. Das Gateway benötigt kein Relay-Token für die gesamte Bereitstellung.
  • Bindet jede relaygestützte Registrierung an die Gateway-Identität, mit der die iOS-App gepaart wurde, sodass ein anderes Gateway die gespeicherte Registrierung nicht wiederverwenden kann.
  • Lässt lokale/manuelle iOS-Builds bei direktem APNs. Relay-gestützte Sendungen gelten nur für offiziell verteilte Builds, die sich über das Relay registriert haben.
  • Muss mit der Relay-Basis-URL übereinstimmen, die in den offiziellen/TestFlight-iOS-Build eingebettet ist, damit Registrierungs- und Sendetraffic dieselbe Relay-Bereitstellung erreichen.
Ende-zu-Ende-Ablauf:
  1. Installieren Sie einen offiziellen/TestFlight-iOS-Build, der mit derselben Relay-Basis-URL kompiliert wurde.
  2. Konfigurieren Sie gateway.push.apns.relay.baseUrl auf dem Gateway.
  3. Pairen Sie die iOS-App mit dem Gateway und lassen Sie sowohl Node- als auch Operator-Sitzungen verbinden.
  4. Die iOS-App ruft die Gateway-Identität ab, registriert sich beim Relay mit App Attest plus dem App-Receipt und veröffentlicht dann die relaygestützte push.apns.register-Payload an das gepaarte Gateway.
  5. Das Gateway speichert den Relay-Handle und die Sendeberechtigung und verwendet sie dann für push.test, Wake-Nudges und Reconnect-Wakes.
Betriebshinweise:
  • Wenn Sie die iOS-App auf ein anderes Gateway umstellen, verbinden Sie die App erneut, damit sie eine neue, an dieses Gateway gebundene Relay-Registrierung veröffentlichen kann.
  • Wenn Sie einen neuen iOS-Build ausliefern, der auf eine andere Relay-Bereitstellung verweist, aktualisiert die App ihre zwischengespeicherte Relay-Registrierung, anstatt den alten Relay-Ursprung wiederzuverwenden.
Kompatibilitätshinweis:
  • OPENCLAW_APNS_RELAY_BASE_URL und OPENCLAW_APNS_RELAY_TIMEOUT_MS funktionieren weiterhin als temporäre Env-Überschreibungen.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true bleibt eine nur für loopback gedachte Entwicklungs-Ausweichmöglichkeit; speichern Sie keine HTTP-Relay-URLs dauerhaft in der Konfiguration.
Siehe iOS App für den Ende-zu-Ende-Ablauf und Authentication and trust flow für das Relay-Sicherheitsmodell.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: Duration-String (30m, 2h). Setzen Sie 0m, um zu deaktivieren.
  • target: last | none | <channel-id> (zum Beispiel discord, matrix, telegram oder whatsapp)
  • directPolicy: allow (Standard) oder block für DM-artige Heartbeat-Ziele
  • Siehe Heartbeat für die vollständige Anleitung.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: bereinigt abgeschlossene isolierte Ausführungssitzungen aus sessions.json (Standard 24h; setzen Sie false, um zu deaktivieren).
  • runLog: bereinigt cron/runs/<jobId>.jsonl nach Größe und beibehaltenen Zeilen.
  • Siehe Cron jobs für Funktionsüberblick und CLI-Beispiele.
Aktivieren Sie HTTP-Webhook-Endpunkte im Gateway:
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
Sicherheitshinweis:
  • Behandeln Sie alle Hook-/Webhook-Payload-Inhalte als nicht vertrauenswürdige Eingabe.
  • Verwenden Sie ein dediziertes hooks.token; verwenden Sie nicht das gemeinsame Gateway-Token erneut.
  • Hook-Authentifizierung ist nur Header-basiert (Authorization: Bearer ... oder x-openclaw-token); Tokens in Query-Strings werden abgelehnt.
  • hooks.path darf nicht / sein; halten Sie den Webhook-Eingang auf einem dedizierten Unterpfad wie /hooks.
  • Lassen Sie Bypass-Flags für unsichere Inhalte deaktiviert (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), außer für eng begrenztes Debugging.
  • Wenn Sie hooks.allowRequestSessionKey aktivieren, setzen Sie auch hooks.allowedSessionKeyPrefixes, um vom Aufrufer gewählte Sitzungsschlüssel zu begrenzen.
  • Für Hook-gesteuerte Agenten bevorzugen Sie starke moderne Modellstufen und eine strikte Tool-Richtlinie (zum Beispiel nur Messaging plus nach Möglichkeit Sandboxing).
Siehe vollständige Referenz für alle Mapping-Optionen und die Gmail-Integration.
Führen Sie mehrere isolierte Agenten mit separaten Workspaces und Sitzungen aus:
{
  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" } },
  ],
}
Siehe Multi-Agent und die vollständige Referenz für Binding-Regeln und agentenspezifische Zugriffsprofile.
Verwenden Sie $include, um große Konfigurationen zu organisieren:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • Einzelne Datei: ersetzt das enthaltende Objekt
  • Array von Dateien: wird der Reihe nach tief zusammengeführt (spätere gewinnt)
  • Nebenschlüssel: werden nach Includes zusammengeführt (überschreiben inkludierte Werte)
  • Verschachtelte Includes: werden bis zu 10 Ebenen tief unterstützt
  • Relative Pfade: werden relativ zur inkludierenden Datei aufgelöst
  • Fehlerbehandlung: klare Fehler bei fehlenden Dateien, Parse-Fehlern und zirkulären Includes

​
Hot Reload der Konfiguration

Das Gateway überwacht ~/.openclaw/openclaw.json und wendet Änderungen automatisch an — für die meisten Einstellungen ist kein manueller Neustart erforderlich.

​
Reload-Modi

ModusVerhalten
hybrid (Standard)Wendet sichere Änderungen sofort hot an. Startet bei kritischen Änderungen automatisch neu.
hotWendet nur sichere Änderungen hot an. Protokolliert eine Warnung, wenn ein Neustart erforderlich ist — Sie kümmern sich darum.
restartStartet das Gateway bei jeder Konfigurationsänderung neu, sicher oder nicht.
offDeaktiviert die Dateibeobachtung. Änderungen werden beim nächsten manuellen Neustart wirksam.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Was hot angewendet wird und was einen Neustart erfordert

Die meisten Felder werden ohne Ausfallzeit hot angewendet. Im Modus hybrid werden Änderungen, die einen Neustart erfordern, automatisch verarbeitet.
KategorieFelderNeustart erforderlich?
Kanälechannels.*, web (WhatsApp) — alle integrierten und ErweiterungskanäleNein
Agent & Modelleagent, agents, models, routingNein
Automatisierunghooks, cron, agent.heartbeatNein
Sitzungen & Nachrichtensession, messagesNein
Tools & Medientools, browser, skills, audio, talkNein
UI & Sonstigesui, logging, identity, bindingsNein
Gateway-Servergateway.* (Port, Bind, Auth, Tailscale, TLS, HTTP)Ja
Infrastrukturdiscovery, canvasHost, pluginsJa
gateway.reload und gateway.remote sind Ausnahmen — Änderungen daran lösen keinen Neustart aus.

​
Config-RPC (programmatische Updates)

Control-Plane-Schreib-RPCs (config.apply, config.patch, update.run) sind auf 3 Anfragen pro 60 Sekunden pro deviceId+clientIp begrenzt. Bei Begrenzung gibt der RPC UNAVAILABLE mit retryAfterMs zurück.
Sicherer/standardmäßiger Ablauf:
  • config.schema.lookup: untersucht einen pfadbezogenen Konfigurationsunterbaum mit einem flachen Schemaknoten, zugeordneten Hinweis-Metadaten und unmittelbaren Zusammenfassungen der Unterelemente
  • config.get: ruft den aktuellen Snapshot + Hash ab
  • config.patch: bevorzugter Pfad für Teilaktualisierungen
  • config.apply: nur für vollständigen Konfigurationsersatz
  • update.run: explizites Selbst-Update + Neustart
Wenn Sie nicht die gesamte Konfiguration ersetzen, bevorzugen Sie config.schema.lookup und dann config.patch.
Validiert + schreibt die vollständige Konfiguration und startet das Gateway in einem Schritt neu.
config.apply ersetzt die gesamte Konfiguration. Verwenden Sie config.patch für Teilaktualisierungen oder openclaw config set für einzelne Schlüssel.
Parameter:
  • raw (string) — JSON5-Payload für die gesamte Konfiguration
  • baseHash (optional) — Konfigurations-Hash aus config.get (erforderlich, wenn Konfiguration vorhanden ist)
  • sessionKey (optional) — Sitzungsschlüssel für den Wake-up-Ping nach dem Neustart
  • note (optional) — Hinweis für das Neustart-Sentinel
  • restartDelayMs (optional) — Verzögerung vor dem Neustart (Standard 2000)
Neustartanfragen werden zusammengefasst, während bereits eine aussteht/läuft, und zwischen Neustartzyklen gilt eine Abkühlzeit von 30 Sekunden.
openclaw gateway call config.get --params '{}'  # payload.hash erfassen
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
Führt eine Teilaktualisierung in die bestehende Konfiguration zusammen (JSON-Merge-Patch-Semantik):
  • Objekte werden rekursiv zusammengeführt
  • null löscht einen Schlüssel
  • Arrays werden ersetzt
Parameter:
  • raw (string) — JSON5 nur mit den zu ändernden Schlüsseln
  • baseHash (erforderlich) — Konfigurations-Hash aus config.get
  • sessionKey, note, restartDelayMs — wie bei config.apply
Das Neustartverhalten entspricht config.apply: zusammengefasste ausstehende Neustarts plus eine Abkühlzeit von 30 Sekunden zwischen Neustartzyklen.
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

​
Umgebungsvariablen

OpenClaw liest Umgebungsvariablen aus dem Elternprozess sowie aus:
  • .env aus dem aktuellen Arbeitsverzeichnis (falls vorhanden)
  • ~/.openclaw/.env (globaler Fallback)
Keine der beiden Dateien überschreibt bestehende Umgebungsvariablen. Sie können auch Inline-Umgebungsvariablen in der Konfiguration setzen: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Wenn aktiviert und erwartete Schlüssel nicht gesetzt sind, führt OpenClaw Ihre Login-Shell aus und importiert nur die fehlenden Schlüssel:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Entsprechende Env-Variable: OPENCLAW_LOAD_SHELL_ENV=1
Verweisen Sie in jedem Stringwert der Konfiguration mit ${VAR_NAME} auf Umgebungsvariablen:
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
Regeln:
  • Es werden nur Großbuchstabennamen abgeglichen: [A-Z_][A-Z0-9_]*
  • Fehlende/leere Variablen lösen beim Laden einen Fehler aus
  • Escapen Sie mit $${VAR} für eine wörtliche Ausgabe
  • Funktioniert auch in $include-Dateien
  • Inline-Ersetzung: "${BASE}/v1" → "https://api.example.com/v1"
Für Felder, die SecretRef-Objekte unterstützen, können Sie Folgendes verwenden:
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
Details zu SecretRef (einschließlich secrets.providers für env/file/exec) finden Sie unter Secrets Management. Unterstützte Anmeldedatenpfade sind unter SecretRef Credential Surface aufgeführt.
Siehe Environment für vollständige Vorrangregeln und Quellen.

​
Vollständige Referenz

Die vollständige Referenz für alle Felder finden Sie unter Configuration Reference.
Verwandt: Configuration Examples · Configuration Reference · Doctor