Zum Hauptinhalt springen

​
Konfiguration

OpenClaw liest optional eine -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 einrichten (Cron, Hooks)
  • Sitzungen, Medien, Netzwerk oder UI abstimmen
Siehe die vollständige Referenz für jedes verfügbare Feld.
Neu bei der Konfiguration? Beginnen Sie mit openclaw onboard für die interaktive Einrichtung oder sehen Sie sich den Leitfaden Konfigurationsbeispiele 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 der Control UI und der Konfigurationsvalidierung verwendet wird.
  • Betrachten Sie diese Schema-Ausgabe als den kanonischen maschinenlesbaren Vertrag für openclaw.json; diese Übersicht und die Konfigurationsreferenz fassen ihn zusammen.
  • Die Feldwerte title und description werden in die Schema-Ausgabe für Editor- und Formular-Tools übernommen.
  • Verschachtelte Objekt-, Wildcard- (*) und Array-Element-Einträge ([]) übernehmen dieselben Dokumentationsmetadaten, wenn passende Felddokumentation vorhanden ist.
  • anyOf- / oneOf- / allOf-Kompositionszweige übernehmen diese Dokumentationsmetadaten ebenfalls, sodass Union-/Intersection-Varianten dieselbe Feldhilfe beibehalten.
  • config.schema.lookup gibt einen normalisierten Konfigurationspfad mit einem flachen Schemaknoten (title, description, type, enum, const, allgemeine Grenzen und ähnliche Validierungsfelder), passenden UI-Hinweismetadaten und Zusammenfassungen der direkten Unterelemente für Drill-down-Tools zurück.
  • Laufzeit-Plugin-/Kanalschemata werden zusammengeführt, wenn das Gateway die aktuelle Manifest-Registry laden kann.
  • pnpm config:docs:check erkennt Abweichungen zwischen dokumentationsbezogenen Konfigurations-Baseline-Artefakten und der aktuellen Schemaoberfläche.
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 seinen eigenen Konfigurationsabschnitt unter channels.<provider>. Schritte zur Einrichtung 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.
  • Modellreferenzen verwenden das Format provider/model (z. B. anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx steuert die Größenanpassung von Bildern in Transkripten/Tools (Standard 1200); niedrigere Werte reduzieren in der Regel die Vision-Token-Nutzung bei screenshotlastigen Abläufen.
  • 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 Benutzerdefinierte Provider in der Referenz.
Der DM-Zugriff wird pro Kanal über dmPolicy gesteuert:
  • "pairing" (Standard): unbekannte Absender erhalten einen einmaligen Pairing-Code zur Freigabe
  • "allowlist": nur Absender in allowFrom (oder im gepaarten Allow-Store)
  • "open": alle eingehenden DMs zulassen (erfordert allowFrom: ["*"])
  • "disabled": alle DMs ignorieren
Für Gruppen verwenden Sie groupPolicy + groupAllowFrom oder kanalspezifische Allowlists.Siehe die vollständige Referenz für Details pro Kanal.
Gruppen-Nachrichten 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 Überschreibungen pro Kanal und den Selbstchat-Modus.
Verwenden Sie agents.defaults.skills für eine gemeinsame Basis und überschreiben Sie dann bestimmte Agents 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, wenn Skills standardmäßig nicht eingeschränkt sein sollen.
  • Lassen Sie agents.list[].skills weg, um die Standardwerte zu übernehmen.
  • Setzen Sie agents.list[].skills: [] für keine Skills.
  • Siehe Skills, Skills-Konfiguration und die Konfigurationsreferenz.
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 die Gesundheitsüberwachung 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 Kanal oder ein Konto zu deaktivieren, ohne die globale Überwachung auszuschalten.
  • Siehe Health Checks für die operative Fehlersuche 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 (gemeinsam) | 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 Send-Richtlinien.
  • Siehe vollständige Referenz für alle Felder.
Führen Sie Agent-Sitzungen in isolierten Docker-Containern aus:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Erstellen Sie das Image zuerst: 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
Das bewirkt Folgendes:
  • 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 Relay-gestützte Registrierung an die Gateway-Identität, mit der die iOS-App gekoppelt wurde, sodass ein anderes Gateway die gespeicherte Registrierung nicht wiederverwenden kann.
  • Behält 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 Sendedatenverkehr dieselbe Relay-Bereitstellung erreicht.
End-to-End-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. Koppeln Sie die iOS-App mit dem Gateway und lassen Sie sowohl Node- als auch Operatorsitzungen verbinden.
  4. Die iOS-App ruft die Gateway-Identität ab, registriert sich mit dem Relay unter Verwendung von App Attest plus dem App-Beleg und veröffentlicht anschließend die Relay-gestützte push.apns.register-Payload an das gekoppelte 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 Relay-Registrierung veröffentlichen kann, die an dieses Gateway gebunden ist.
  • 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-Overrides.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true bleibt eine nur für loopback gedachte Entwicklungsausnahme; persistieren Sie keine HTTP-Relay-URLs in der Konfiguration.
Siehe iOS App für den End-to-End-Ablauf und Authentifizierungs- und Vertrauensablauf für das Relay-Sicherheitsmodell.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: Dauer-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: abgeschlossene isolierte Ausführungssitzungen aus sessions.json entfernen (Standard 24h; setzen Sie false, um zu deaktivieren).
  • runLog: cron/runs/<jobId>.jsonl nach Größe und beibehaltenen Zeilen kürzen.
  • Siehe Cron jobs für die Funktionsübersicht und CLI-Beispiele.
Aktivieren Sie HTTP-Webhook-Endpunkte auf dem 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 Eingaben.
  • Verwenden Sie ein dediziertes hooks.token; verwenden Sie nicht das gemeinsame Gateway-Token wieder.
  • Hook-Authentifizierung erfolgt nur per Header (Authorization: Bearer ... oder x-openclaw-token); Tokens in Query-Strings werden abgelehnt.
  • hooks.path darf nicht / sein; belassen Sie den Webhook-Eingang auf einem dedizierten Unterpfad wie /hooks.
  • Lassen Sie Unsicherer-Inhalt-Bypass-Flags deaktiviert (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), außer bei eng begrenztem Debugging.
  • Wenn Sie hooks.allowRequestSessionKey aktivieren, setzen Sie auch hooks.allowedSessionKeyPrefixes, um vom Aufrufer gewählte Sitzungsschlüssel zu begrenzen.
  • Für hookgesteuerte Agents sollten Sie starke moderne Modell-Tiers und eine strikte Tool-Richtlinie bevorzugen (zum Beispiel nur Messaging plus Sandboxing, wenn möglich).
Siehe die vollständige Referenz für alle Mapping-Optionen und die Gmail-Integration.
Führen Sie mehrere isolierte Agents mit getrennten 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 Zugriffsprofile pro Agent.
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 in Reihenfolge tief zusammengeführt (spätere gewinnt)
  • Nebenschlüssel: werden nach den Includes zusammengeführt (überschreiben eingeschlossene Werte)
  • Verschachtelte Includes: werden bis zu 10 Ebenen tief unterstützt
  • Relative Pfade: werden relativ zur einbindenden Datei aufgelöst
  • Fehlerbehandlung: klare Fehler bei fehlenden Dateien, Parse-Fehlern und zirkulären Includes

​
Konfigurations-Hot-Reload

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

​
Reload-Modi

ModusVerhalten
hybrid (Standard)Wendet sichere Änderungen sofort per Hot-Apply an. Startet bei kritischen Änderungen automatisch neu.
hotWendet nur sichere Änderungen per Hot-Apply 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 Dateiüberwachung. Änderungen werden beim nächsten manuellen Neustart wirksam.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Was per Hot-Apply übernommen wird und was einen Neustart erfordert

Die meisten Felder werden ohne Ausfallzeit per Hot-Apply übernommen. Im hybrid-Modus 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 — ihre Änderung löst keinen Neustart aus.

​
Config RPC (programmatische Aktualisierungen)

Control-Plane-Schreib-RPCs (config.apply, config.patch, update.run) sind auf 3 Anfragen pro 60 Sekunden pro deviceId+clientIp begrenzt. Bei Begrenzung gibt die RPC UNAVAILABLE mit retryAfterMs zurück.
Sicherer/standardmäßiger Ablauf:
  • config.schema.lookup: einen pfadbezogenen Konfigurations-Teilbaum mit einem flachen Schemaknoten, passenden Hinweismetadaten und Zusammenfassungen der direkten Unterelemente untersuchen
  • config.get: den aktuellen Snapshot + Hash abrufen
  • config.patch: bevorzugter Pfad für partielle Aktualisierungen
  • config.apply: nur vollständiger Ersatz der gesamten Konfiguration
  • update.run: explizites Self-Update + Neustart
Wenn Sie nicht die gesamte Konfiguration ersetzen, sollten Sie config.schema.lookup und dann config.patch bevorzugen.
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 partielle Aktualisierungen 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 den Neustart-Sentinel
  • restartDelayMs (optional) — Verzögerung vor dem Neustart (Standard 2000)
Neustartanfragen werden zusammengefasst, solange bereits eine Anfrage aussteht/in Bearbeitung ist, und zwischen Neustartzyklen gilt eine Abklingzeit 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 partielle Aktualisierung mit der vorhandenen Konfiguration zusammen (Semantik von JSON Merge Patch):
  • 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: Zusammenfassung ausstehender Neustarts plus eine Abklingzeit 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 übergeordneten Prozess 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-..." },
  },
}
Falls 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 },
  },
}
Env-Var-Äquivalent: OPENCLAW_LOAD_SHELL_ENV=1
Verweisen Sie in beliebigen Stringwerten 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ßgeschriebene Namen abgeglichen: [A-Z_][A-Z0-9_]*
  • Fehlende/leere Variablen werfen beim Laden einen Fehler
  • Mit $${VAR} für wörtliche Ausgabe maskieren
  • Funktioniert auch in $include-Dateien
  • Inline-Substitution: "${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 Credential-Pfade sind unter SecretRef Credential Surface aufgeführt.
Siehe Environment für vollständige Priorität und Quellen.

​
Vollständige Referenz

Für die vollständige Feld-für-Feld-Referenz siehe Configuration Reference.
Verwandt: Konfigurationsbeispiele · Configuration Reference · Doctor