Konfigurationsreferenz

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• openclaw config schema gibt das Live-JSON-Schema aus, das für Validierung und Control UI verwendet wird, mit zusammengeführten gebündelten/Plugin-/Kanal-Metadaten, sofern verfügbar
• config.schema.lookup gibt einen pfadbezogenen Schemaknoten für Drill-down-Werkzeuge zurück
• pnpm config:docs:check / pnpm config:docs:gen validieren den Baseline-Hash der Konfigurationsdokumentation gegen die aktuelle Schemaoberfläche

• Referenz zur Speicherkonfiguration für agents.defaults.memorySearch.*, memory.qmd.*, memory.citations und Dreaming-Konfiguration unter plugins.entries.memory-core.config.dreaming
• Slash-Befehle für den aktuellen integrierten + gebündelten Befehlskatalog
• zuständige Kanal-/Plugin-Seiten für kanalspezifische Befehlsoberflächen

​

Kanäle

​

Agent-Standardwerte, Multi-Agent, Sitzungen und Nachrichten

• agents.defaults.* (Arbeitsbereich, Modell, Denken, Heartbeat, Speicher, Medien, Skills, Sandbox)
• multiAgent.* (Multi-Agent-Routing und Bindungen)
• session.* (Sitzungslebenszyklus, Compaction, Pruning)
• messages.* (Nachrichtenzustellung, TTS, Markdown-Rendering)
• talk.* (Talk-Modus)
  • talk.consultThinkingLevel: Override der Denkstufe für den vollständigen OpenClaw-Agent-Lauf hinter Control UI Talk-Echtzeitkonsultationen
  • talk.consultFastMode: einmaliger Fast-Mode-Override für Control UI Talk-Echtzeitkonsultationen
  • talk.speechLocale: optionale BCP-47-Locale-ID für Talk-Spracherkennung unter iOS/macOS
  • talk.silenceTimeoutMs: wenn nicht gesetzt, behält Talk das plattformseitige Standard-Pausenfenster vor dem Senden des Transkripts bei (700 ms on macOS and Android, 900 ms on iOS)

​

Tools und benutzerdefinierte Provider

​

Modelle

{
  models: {
    // Optional. Default: true. Requires a Gateway restart when changed.
    pricing: { enabled: false },
  },
}

• models.mode: Provider-Katalogverhalten (merge oder replace).
• models.providers: Zuordnung benutzerdefinierter Provider, geschlüsselt nach Provider-ID.
• models.providers.*.localService: optionaler On-Demand-Prozessmanager für lokale Modellserver. OpenClaw prüft den konfigurierten Health-Endpunkt, startet bei Bedarf den absoluten command, wartet auf Bereitschaft und sendet dann die Modellanfrage. Siehe Lokale Modelldienste.
• models.pricing.enabled: steuert den Hintergrund-Preis-Bootstrap, der startet, nachdem Sidecars und Kanäle den Gateway-Bereit-Pfad erreicht haben. Wenn false, überspringt der Gateway OpenRouter- und LiteLLM-Preiskatalogabrufe; konfigurierte models.providers.*.models[].cost-Werte funktionieren weiterhin für lokale Kostenschätzungen.

​

MCP

{
  mcp: {
    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
      },
    },
  },
}

• mcp.servers: benannte stdio- oder Remote-MCP-Serverdefinitionen für Runtimes, die konfigurierte MCP-Tools bereitstellen. Remote-Einträge verwenden transport: "streamable-http" oder transport: "sse"; type: "http" ist ein CLI-nativer Alias, den openclaw mcp set und openclaw doctor --fix in das kanonische Feld transport normalisieren.
• mcp.sessionIdleTtlMs: Leerlauf-TTL für sitzungsbezogene gebündelte MCP-Runtimes. Einmalige eingebettete Läufe fordern Bereinigung am Laufende an; diese TTL ist die Rückfallebene für langlebige Sitzungen und zukünftige Aufrufer.
• Änderungen unter mcp.* werden durch Entsorgen zwischengespeicherter Sitzungs-MCP-Runtimes direkt angewendet. Die nächste Tool-Erkennung/-Nutzung erstellt sie aus der neuen Konfiguration neu, sodass entfernte mcp.servers-Einträge sofort bereinigt werden, statt auf die Leerlauf-TTL zu warten.

​

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled: optionale Allowlist nur für gebündelte Skills (verwaltete/Arbeitsbereich-Skills nicht betroffen).
• load.extraDirs: zusätzliche gemeinsame Skill-Wurzeln (niedrigste Priorität).
• load.allowSymlinkTargets: vertrauenswürdige echte Zielwurzeln, in die Skill-Symlinks auflösen dürfen, wenn sich der Link außerhalb seiner konfigurierten Quellwurzel befindet.
• install.preferBrew: wenn true, Homebrew-Installer bevorzugen, sofern brew verfügbar ist, bevor auf andere Installer-Arten zurückgefallen wird.
• install.nodeManager: Node-Installer-Präferenz für metadata.openclaw.install- Spezifikationen (npm | pnpm | yarn | bun).
• install.allowUploadedArchives: vertrauenswürdigen operator.admin-Gateway- Clients erlauben, private ZIP-Archive zu installieren, die über skills.upload.* bereitgestellt wurden (Standard: false). Dies aktiviert nur den Pfad für hochgeladene Archive; normale ClawHub- Installationen benötigen dies nicht.
• entries.<skillKey>.enabled: false deaktiviert einen Skill, selbst wenn er gebündelt/installiert ist.
• entries.<skillKey>.apiKey: Komfortfeld für Skills, die eine primäre Umgebungsvariable deklarieren (Klartextzeichenfolge oder SecretRef-Objekt).

​

Plugins

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    bundledDiscovery: "allowlist",
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• Geladen aus ~/.openclaw/extensions, <workspace>/.openclaw/extensions sowie plugins.load.paths.
• Die Erkennung akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles im Standardlayout.
• Konfigurationsänderungen erfordern einen Gateway-Neustart.
• allow: optionale Allowlist (nur aufgeführte Plugins werden geladen). deny hat Vorrang.
• bundledDiscovery: standardmäßig "allowlist" für neue Konfigurationen, sodass eine nicht leere plugins.allow auch gebündelte Provider-Plugins einschließt, einschließlich Websuche- Runtime-Providern. Doctor schreibt "compat" für migrierte Legacy-Allowlist- Konfigurationen, um bestehendes Verhalten gebündelter Provider beizubehalten, bis Sie sich dafür entscheiden.
• plugins.entries.<id>.apiKey: Komfortfeld für API-Schlüssel auf Plugin-Ebene (wenn vom Plugin unterstützt).
• plugins.entries.<id>.env: Plugin-spezifische Zuordnung von Umgebungsvariablen.
• plugins.entries.<id>.hooks.allowPromptInjection: wenn false, blockiert Core before_prompt_build und ignoriert Prompt-mutierende Felder aus Legacy-before_agent_start, während Legacy-modelOverride und providerOverride beibehalten werden. Gilt für native Plugin-Hooks und unterstützte, von Bundles bereitgestellte Hook-Verzeichnisse.
• plugins.entries.<id>.hooks.allowConversationAccess: wenn true, dürfen vertrauenswürdige nicht gebündelte Plugins rohe Konversationsinhalte aus typisierten Hooks wie llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize und agent_end lesen.
• plugins.entries.<id>.subagent.allowModelOverride: diesem Plugin ausdrücklich vertrauen, pro Lauf provider- und model-Overrides für Hintergrund-Subagent-Läufe anzufordern.
• plugins.entries.<id>.subagent.allowedModels: optionale Allowlist kanonischer provider/model-Ziele für vertrauenswürdige Subagent-Overrides. Verwenden Sie "*" nur, wenn Sie bewusst jedes Modell zulassen möchten.
• plugins.entries.<id>.llm.allowModelOverride: diesem Plugin ausdrücklich vertrauen, Modell-Overrides für api.runtime.llm.complete anzufordern.
• plugins.entries.<id>.llm.allowedModels: optionale Allowlist kanonischer provider/model-Ziele für vertrauenswürdige Plugin-LLM-Completion-Overrides. Verwenden Sie "*" nur, wenn Sie bewusst jedes Modell zulassen möchten.
• plugins.entries.<id>.llm.allowAgentIdOverride: diesem Plugin ausdrücklich vertrauen, api.runtime.llm.complete gegen eine nicht standardmäßige Agent-ID auszuführen.
• plugins.entries.<id>.config: vom Plugin definiertes Konfigurationsobjekt (validiert durch natives OpenClaw-Plugin-Schema, sofern verfügbar).
• Konto-/Runtime-Einstellungen von Kanal-Plugins befinden sich unter channels.<id> und sollten durch die Manifest-Metadaten channelConfigs des zuständigen Plugins beschrieben werden, nicht durch eine zentrale OpenClaw-Optionsregistrierung.

​

Codex-Harness-Plugin-Konfiguration

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
                allow_destructive_actions: false,
              },
            },
          },
        },
      },
    },
  },
}

• plugins.entries.codex.config.codexPlugins.enabled: aktiviert native Codex Plugin-/App-Unterstützung für das Codex-Harness. Standard: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: standardmäßige Richtlinie für destruktive Aktionen bei migrierten Plugin-App-Elicitations. Standard: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: aktiviert einen migrierten Plugin-Eintrag, wenn global codexPlugins.enabled ebenfalls true ist. Standard: true für explizite Einträge.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: stabile Marketplace-Identität. V1 unterstützt nur "openai-curated".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: stabile Codex-Plugin-Identität aus der Migration, zum Beispiel "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: Plugin-spezifische Überschreibung für destruktive Aktionen. Wenn ausgelassen, wird der globale Wert allow_destructive_actions verwendet.

• plugins.entries.firecrawl.config.webFetch: Firecrawl-Web-Fetch-Provider-Einstellungen.
  • apiKey: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt zurück auf plugins.entries.firecrawl.config.webSearch.apiKey, das Legacy-tools.web.fetch.firecrawl.apiKey oder die Env-Var FIRECRAWL_API_KEY.
  • baseUrl: Firecrawl-API-Basis-URL (Standard: https://api.firecrawl.dev; selbst gehostete Überschreibungen müssen auf private/interne Endpunkte zielen).
  • onlyMainContent: nur den Hauptinhalt aus Seiten extrahieren (Standard: true).
  • maxAgeMs: maximales Cache-Alter in Millisekunden (Standard: 172800000 / 2 Tage).
  • timeoutSeconds: Timeout für Scrape-Anfragen in Sekunden (Standard: 60).
• plugins.entries.xai.config.xSearch: Einstellungen für xAI X Search (Grok-Websuche).
  • enabled: den X-Search-Provider aktivieren.
  • model: Grok-Modell, das für die Suche verwendet werden soll (z. B. "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: Einstellungen für Memory-Dreaming. Siehe Dreaming für Phasen und Schwellenwerte.
  • enabled: Hauptschalter für Dreaming (Standard false).
  • frequency: Cron-Takt für jeden vollständigen Dreaming-Durchlauf (standardmäßig "0 3 * * *").
  • model: optionale Modellüberschreibung für den Dream-Diary-Subagenten. Erfordert plugins.entries.memory-core.subagent.allowModelOverride: true; kombinieren Sie dies mit allowedModels, um Ziele einzuschränken. Fehler wegen nicht verfügbarer Modelle werden einmal mit dem Standardmodell der Sitzung erneut versucht; Trust- oder Allowlist-Fehler fallen nicht stillschweigend zurück.
  • Phasenrichtlinie und Schwellenwerte sind Implementierungsdetails (keine benutzerseitigen Konfigurationsschlüssel).
• Die vollständige Memory-Konfiguration befindet sich in der Memory-Konfigurationsreferenz:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Aktivierte Claude-Bundle-Plugins können außerdem eingebettete Pi-Standardwerte aus settings.json beisteuern; OpenClaw wendet diese als bereinigte Agent-Einstellungen an, nicht als rohe OpenClaw-Konfigurationspatches.
• plugins.slots.memory: wählen Sie die aktive Memory-Plugin-ID oder "none", um Memory-Plugins zu deaktivieren.
• plugins.slots.contextEngine: wählen Sie die aktive Kontext-Engine-Plugin-ID; standardmäßig "legacy", sofern Sie keine andere Engine installieren und auswählen.

​

Zusagen

• commitments.enabled: aktiviert versteckte LLM-Extraktion, Speicherung und Heartbeat-Auslieferung für abgeleitete Nachfasszusagen. Standard: false.
• commitments.maxPerDay: maximale Anzahl abgeleiteter Nachfasszusagen, die pro Agent-Sitzung innerhalb eines rollierenden Tages ausgeliefert werden. Standard: 3.

​

Browser

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
      sweepMinutes: 5,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• evaluateEnabled: false deaktiviert act:evaluate und wait --fn.
• tabCleanup gibt verfolgte Tabs des primären Agenten nach Leerlaufzeit oder wenn eine Sitzung ihr Limit überschreitet wieder frei. Setzen Sie idleMinutes: 0 oder maxTabsPerSession: 0, um diese einzelnen Bereinigungsmodi zu deaktivieren.
• ssrfPolicy.dangerouslyAllowPrivateNetwork ist deaktiviert, wenn nicht gesetzt, sodass Browser-Navigation standardmäßig strikt bleibt.
• Setzen Sie ssrfPolicy.dangerouslyAllowPrivateNetwork: true nur, wenn Sie Browser-Navigation in privaten Netzwerken absichtlich vertrauen.
• Im strikten Modus unterliegen Remote-CDP-Profilendpunkte (profiles.*.cdpUrl) bei Erreichbarkeits-/Erkennungsprüfungen derselben Blockierung privater Netzwerke.
• ssrfPolicy.allowPrivateNetwork bleibt als Legacy-Alias unterstützt.
• Verwenden Sie im strikten Modus ssrfPolicy.hostnameAllowlist und ssrfPolicy.allowedHostnames für explizite Ausnahmen.
• Remote-Profile sind nur zum Anhängen vorgesehen (Start/Stopp/Reset deaktiviert).
• profiles.*.cdpUrl akzeptiert http://, https://, ws:// und wss://. Verwenden Sie HTTP(S), wenn OpenClaw /json/version ermitteln soll; verwenden Sie WS(S), wenn Ihr Provider Ihnen eine direkte DevTools-WebSocket-URL bereitstellt.
• remoteCdpTimeoutMs und remoteCdpHandshakeTimeoutMs gelten für Remote- und attachOnly-CDP-Erreichbarkeit sowie Tab-Öffnungsanfragen. Verwaltete loopback- Profile behalten lokale CDP-Standardwerte.
• Wenn ein extern verwalteter CDP-Dienst über loopback erreichbar ist, setzen Sie für dieses Profil attachOnly: true; andernfalls behandelt OpenClaw den loopback-Port als lokal verwaltetes Browser-Profil und kann lokale Portbesitzfehler melden.
• existing-session-Profile verwenden Chrome MCP statt CDP und können auf dem ausgewählten Host oder über einen verbundenen Browser-Knoten anhängen.
• existing-session-Profile können userDataDir setzen, um ein bestimmtes Chromium-basiertes Browser-Profil wie Brave oder Edge anzusteuern.
• existing-session-Profile behalten die aktuellen Chrome-MCP-Routenlimits: snapshot-/ref-gesteuerte Aktionen statt CSS-Selektor-Targeting, Ein-Datei-Upload- Hooks, keine Dialog-Timeout-Überschreibungen, kein wait --load networkidle und kein responsebody, PDF-Export, Download-Interception oder Batch-Aktionen.
• Lokal verwaltete openclaw-Profile weisen cdpPort und cdpUrl automatisch zu; setzen Sie cdpUrl nur explizit für Remote-CDP.
• Lokal verwaltete Profile können executablePath setzen, um das globale browser.executablePath für dieses Profil zu überschreiben. Verwenden Sie dies, um ein Profil in Chrome und ein anderes in Brave auszuführen.
• Lokal verwaltete Profile verwenden browser.localLaunchTimeoutMs für die HTTP- Erkennung von Chrome CDP nach dem Prozessstart und browser.localCdpReadyTimeoutMs für die CDP-WebSocket-Bereitschaft nach dem Start. Erhöhen Sie diese Werte auf langsameren Hosts, bei denen Chrome erfolgreich startet, Bereitschaftsprüfungen aber mit dem Start konkurrieren. Beide Werte müssen positive Ganzzahlen bis 120000 ms sein; ungültige Konfigurationswerte werden abgelehnt.
• Reihenfolge der automatischen Erkennung: Standardbrowser, wenn Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath und browser.profiles.<name>.executablePath akzeptieren beide ~ und ~/... für Ihr OS-Home-Verzeichnis vor dem Chromium-Start. Profilbezogenes userDataDir in existing-session-Profilen wird ebenfalls mit Tilde expandiert.
• Steuerdienst: nur loopback (Port abgeleitet aus gateway.port, Standard 18791).
• extraArgs hängt zusätzliche Start-Flags an den lokalen Chromium-Start an (zum Beispiel --disable-gpu, Fenstergrößen oder Debug-Flags).

​

UI

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor: Akzentfarbe für die Chrome-Elemente der nativen App-UI (Talk-Mode-Bubble-Färbung usw.).
• assistant: Überschreibung der Control-UI-Identität. Fällt auf die aktive Agent-Identität zurück.

​

Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

​

OpenAI-kompatible Endpunkte

• Chat Completions: standardmäßig deaktiviert. Aktivieren mit gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Responses-URL-Eingabehärtung:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Leere Allowlists werden als nicht gesetzt behandelt; verwenden Sie gateway.http.endpoints.responses.files.allowUrl=false und/oder gateway.http.endpoints.responses.images.allowUrl=false, um URL-Abrufe zu deaktivieren.
• Optionaler Response-Härtungs-Header:
  • gateway.http.securityHeaders.strictTransportSecurity (nur für HTTPS-Origins setzen, die Sie kontrollieren; siehe Trusted-Proxy-Authentifizierung)

​

Multi-Instanz-Isolierung

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

​

gateway.tls

{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

• enabled: aktiviert TLS-Terminierung am Gateway-Listener (HTTPS/WSS) (Standard: false).
• autoGenerate: erzeugt automatisch ein lokales selbstsigniertes Zertifikat/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokale/Dev-Nutzung.
• certPath: Dateisystempfad zur TLS-Zertifikatsdatei.
• keyPath: Dateisystempfad zur privaten TLS-Schlüsseldatei; Berechtigungen restriktiv halten.
• caPath: optionaler CA-Bundle-Pfad für Client-Verifizierung oder benutzerdefinierte Trust Chains.

​

gateway.reload

{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

• mode: steuert, wie Konfigurationsänderungen zur Laufzeit angewendet werden.
  • "off": Live-Änderungen ignorieren; Änderungen erfordern einen expliziten Neustart.
  • "restart": Gateway-Prozess bei Konfigurationsänderung immer neu starten.
  • "hot": Änderungen im Prozess ohne Neustart anwenden.
  • "hybrid" (Standard): zuerst Hot Reload versuchen; bei Bedarf auf Neustart zurückfallen.
• debounceMs: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nichtnegative ganze Zahl).
• deferralTimeoutMs: optionale maximale Wartezeit in ms für laufende Operationen, bevor ein Neustart oder Channel-Hot-Reload erzwungen wird. Weglassen, um die standardmäßige begrenzte Wartezeit (300000) zu verwenden; auf 0 setzen, um unbegrenzt zu warten und regelmäßig Warnungen zu noch ausstehenden Vorgängen zu protokollieren.

​

Hooks

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.4-mini",
      },
    ],
  },
}

• hooks.enabled=true erfordert ein nicht leeres hooks.token.
• hooks.token muss sich von gateway.auth.token unterscheiden; die Wiederverwendung des Gateway-Tokens wird abgelehnt.
• hooks.path darf nicht / sein; verwenden Sie einen dedizierten Unterpfad wie /hooks.
• Wenn hooks.allowRequestSessionKey=true ist, beschränken Sie hooks.allowedSessionKeyPrefixes (zum Beispiel ["hook:"]).
• Wenn eine Zuordnung oder Voreinstellung einen vorlagenbasierten sessionKey verwendet, setzen Sie hooks.allowedSessionKeyPrefixes und hooks.allowRequestSessionKey=true. Statische Zuordnungsschlüssel erfordern diese Aktivierung nicht.

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • sessionKey aus der Anfrage-Payload wird nur akzeptiert, wenn hooks.allowRequestSessionKey=true ist (Standard: false).
• POST /hooks/<name> → wird über hooks.mappings aufgelöst
  • Durch Vorlagen gerenderte Zuordnungswerte für sessionKey werden als extern bereitgestellt behandelt und erfordern ebenfalls hooks.allowRequestSessionKey=true.

​

Gmail-Integration

• Die integrierte Gmail-Voreinstellung verwendet sessionKey: "hook:gmail:{{messages[0].id}}".
• Wenn Sie dieses Routing pro Nachricht beibehalten, setzen Sie hooks.allowRequestSessionKey: true und beschränken Sie hooks.allowedSessionKeyPrefixes so, dass es zum Gmail-Namespace passt, zum Beispiel ["hook:", "hook:gmail:"].
• Wenn Sie hooks.allowRequestSessionKey: false benötigen, überschreiben Sie die Voreinstellung mit einem statischen sessionKey statt mit dem vorlagenbasierten Standard.

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• Gateway startet beim Booten automatisch gog gmail watch serve, wenn es konfiguriert ist. Setzen Sie OPENCLAW_SKIP_GMAIL_WATCHER=1, um dies zu deaktivieren.
• Führen Sie kein separates gog gmail watch serve parallel zum Gateway aus.

​

Canvas-Plugin-Host

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            root: "~/.openclaw/workspace/canvas",
            liveReload: true,
            // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}

• Stellt agentenbearbeitbares HTML/CSS/JS und A2UI per HTTP unter dem Gateway-Port bereit:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Nur lokal: Behalten Sie gateway.bind: "loopback" bei (Standard).
• Nicht-Loopback-Bindings: Canvas-Routen erfordern Gateway-Authentifizierung (Token/Passwort/vertrauenswürdiger Proxy), genau wie andere Gateway-HTTP-Oberflächen.
• Node-WebViews senden in der Regel keine Auth-Header; nachdem ein Node gekoppelt und verbunden ist, gibt der Gateway node-spezifische Capability-URLs für den Canvas-/A2UI-Zugriff bekannt.
• Capability-URLs sind an die aktive Node-WS-Sitzung gebunden und laufen schnell ab. IP-basierter Fallback wird nicht verwendet.
• Fügt den bereitgestellten HTML-Dateien einen Live-Reload-Client hinzu.
• Erstellt automatisch eine Starterdatei index.html, wenn das Verzeichnis leer ist.
• Stellt A2UI außerdem unter /__openclaw__/a2ui/ bereit.
• Änderungen erfordern einen Neustart des Gateway.
• Deaktivieren Sie Live-Reload für große Verzeichnisse oder bei EMFILE-Fehlern.

​

Discovery

​

mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal (Standard, wenn das gebündelte bonjour-Plugin aktiviert ist): lässt cliPath + sshPort aus TXT-Records weg.
• full: schließt cliPath + sshPort ein; LAN-Multicast-Ankündigung erfordert weiterhin, dass das gebündelte bonjour-Plugin aktiviert ist.
• off: unterdrückt LAN-Multicast-Ankündigung, ohne die Plugin-Aktivierung zu ändern.
• Das gebündelte bonjour-Plugin startet automatisch auf macOS-Hosts und ist auf Linux, Windows und containerisierten Gateway-Bereitstellungen optional aktivierbar.
• Der Hostname ist standardmäßig der System-Hostname, wenn er ein gültiges DNS-Label ist; andernfalls wird openclaw verwendet. Überschreiben Sie ihn mit OPENCLAW_MDNS_HOSTNAME.

​

Weitbereich (DNS-SD)

{
  discovery: {
    wideArea: { enabled: true },
  },
}

​

Umgebung

​

env (Inline-Umgebungsvariablen)

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

• Inline-Umgebungsvariablen werden nur angewendet, wenn in der Prozessumgebung der Schlüssel fehlt.
• .env-Dateien: CWD .env + ~/.openclaw/.env (keine davon überschreibt vorhandene Variablen).
• shellEnv: importiert fehlende erwartete Schlüssel aus Ihrem Login-Shell-Profil.
• Vollständige Vorrangregeln finden Sie unter Umgebung.

​

Umgebungsvariablen-Ersetzung

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• Nur Namen in Großbuchstaben werden abgeglichen: [A-Z_][A-Z0-9_]*.
• Fehlende/leere Variablen lösen beim Laden der Konfiguration einen Fehler aus.
• Mit $${VAR} für ein literales ${VAR} escapen.
• Funktioniert mit $include.

​

Secrets

​

SecretRef

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

• provider-Muster: ^[a-z][a-z0-9_-]{0,63}$
• source: "env"-id-Muster: ^[A-Z][A-Z0-9_]{0,127}$
• source: "file"-id: absoluter JSON-Pointer (zum Beispiel "/providers/openai/apiKey")
• source: "exec"-id-Muster: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• source: "exec"-ids dürfen keine durch Schrägstriche getrennten Pfadsegmente . oder .. enthalten (zum Beispiel wird a/../b abgelehnt)

​

Unterstützte Zugangsdatenoberfläche

• Kanonische Matrix: SecretRef-Zugangsdatenoberfläche
• secrets apply zielt auf unterstützte openclaw.json-Zugangsdatenpfade ab.
• auth-profiles.json-Referenzen sind in Runtime-Auflösung und Audit-Abdeckung enthalten.

​

Konfiguration der Secret-Provider

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

• Der file-Provider unterstützt mode: "json" und mode: "singleValue" (id muss im singleValue-Modus "value" sein).
• Datei- und exec-Provider-Pfade schlagen geschlossen fehl, wenn die Windows-ACL-Verifizierung nicht verfügbar ist. Setzen Sie allowInsecurePath: true nur für vertrauenswürdige Pfade, die nicht verifiziert werden können.
• Der exec-Provider erfordert einen absoluten command-Pfad und verwendet Protokoll-Payloads über stdin/stdout.
• Standardmäßig werden Symlink-Befehlspfade abgelehnt. Setzen Sie allowSymlinkCommand: true, um Symlink-Pfade zuzulassen, während der aufgelöste Zielpfad validiert wird.
• Wenn trustedDirs konfiguriert ist, wird die Prüfung vertrauenswürdiger Verzeichnisse auf den aufgelösten Zielpfad angewendet.
• Die exec-Kindumgebung ist standardmäßig minimal; übergeben Sie erforderliche Variablen explizit mit passEnv.
• Secret-Referenzen werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst; anschließend lesen Anfragepfade nur den Snapshot.
• Während der Aktivierung wird eine Filterung aktiver Oberflächen angewendet: Nicht aufgelöste Referenzen auf aktivierten Oberflächen lassen Start/Neuladen fehlschlagen, während inaktive Oberflächen mit Diagnosen übersprungen werden.

​

Auth-Speicher

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      "openai-codex": ["openai-codex:personal"],
    },
  },
}

• Agent-spezifische Profile werden unter <agentDir>/auth-profiles.json gespeichert.
• auth-profiles.json unterstützt Referenzen auf Wertebene (keyRef für api_key, tokenRef für token) für statische Zugangsdatenmodi.
• Legacy-flache auth-profiles.json-Maps wie { "provider": { "apiKey": "..." } } sind kein Runtime-Format; openclaw doctor --fix schreibt sie mit einem .legacy-flat.*.bak-Backup in kanonische provider:default-API-Schlüsselprofile um.
• OAuth-Modus-Profile (auth.profiles.<id>.mode = "oauth") unterstützen keine SecretRef-gestützten Auth-Profil-Zugangsdaten.
• Statische Runtime-Zugangsdaten stammen aus im Arbeitsspeicher aufgelösten Snapshots; alte statische auth.json-Einträge werden bereinigt, wenn sie gefunden werden.
• Legacy-OAuth-Importe aus ~/.openclaw/credentials/oauth.json.
• Siehe OAuth.
• Secrets-Runtime-Verhalten und audit/configure/apply-Werkzeuge: Secrets-Verwaltung.

​

auth.cooldowns

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      authPermanentBackoffMinutes: 10,
      authPermanentMaxMinutes: 60,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

• billingBackoffHours: Basis-Backoff in Stunden, wenn ein Profil aufgrund echter Abrechnungs-/Guthaben-nicht-ausreichend-Fehler fehlschlägt (Standard: 5). Expliziter Abrechnungstext kann auch bei 401-/403-Antworten hier landen, aber Provider-spezifische Text- Matcher bleiben auf den Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter Key limit exceeded). Wiederholbare HTTP-402-Meldungen zum Nutzungsfenster oder zu Ausgabenlimits für Organisation/Workspace bleiben stattdessen im rate_limit-Pfad.
• billingBackoffHoursByProvider: optionale Overrides pro Provider für Abrechnungs-Backoff-Stunden.
• billingMaxHours: Obergrenze in Stunden für das exponentielle Wachstum des Abrechnungs-Backoffs (Standard: 24).
• authPermanentBackoffMinutes: Basis-Backoff in Minuten für hochverlässliche auth_permanent-Fehler (Standard: 10).
• authPermanentMaxMinutes: Obergrenze in Minuten für das auth_permanent-Backoff-Wachstum (Standard: 60).
• failureWindowHours: rollierendes Zeitfenster in Stunden, das für Backoff-Zähler verwendet wird (Standard: 24).
• overloadedProfileRotations: maximale Rotationen von Auth-Profilen desselben Providers bei Überlastungsfehlern, bevor auf Modell-Fallback gewechselt wird (Standard: 1). Provider-Auslastungsformen wie ModelNotReadyException landen hier.
• overloadedBackoffMs: feste Verzögerung vor dem erneuten Versuch einer Rotation für überlasteten Provider/überlastetes Profil (Standard: 0).
• rateLimitedProfileRotations: maximale Rotationen von Auth-Profilen desselben Providers bei Rate-Limit-Fehlern, bevor auf Modell-Fallback gewechselt wird (Standard: 1). Dieser Rate-Limit-Bucket umfasst Provider-geprägten Text wie Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded und resource exhausted.

​

Protokollierung

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• Standard-Logdatei: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Setzen Sie logging.file für einen stabilen Pfad.
• consoleLevel wird bei --verbose auf debug angehoben.
• maxFileBytes: maximale Größe der aktiven Logdatei in Byte vor der Rotation (positive Ganzzahl; Standard: 104857600 = 100 MB). OpenClaw behält bis zu fünf nummerierte Archive neben der aktiven Datei.
• redactSensitive / redactPatterns: Best-Effort-Maskierung für Konsolenausgabe, Datei-Logs, OTLP-Logdatensätze und persistierten Sitzungstranskripttext. redactSensitive: "off" deaktiviert nur diese allgemeine Log-/Transkript-Richtlinie; UI-/Tool-/Diagnose-Sicherheitsflächen redigieren Geheimnisse weiterhin vor der Ausgabe.

​

Diagnose

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,
    stuckSessionAbortMs: 600000,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

• enabled: Hauptschalter für Instrumentierungsausgabe (Standard: true).
• flags: Array von Flag-Strings, die gezielte Logausgabe aktivieren (unterstützt Wildcards wie "telegram.*" oder "*").
• stuckSessionWarnMs: Altersschwelle ohne Fortschritt in ms, um lang laufende Verarbeitungssitzungen als session.long_running, session.stalled oder session.stuck zu klassifizieren. Antwort, Tool, Status, Block und ACP-Fortschritt setzen den Timer zurück; wiederholte session.stuck-Diagnosen verwenden Backoff, solange unverändert.
• stuckSessionAbortMs: Altersschwelle ohne Fortschritt in ms, bevor geeignete angehaltene aktive Arbeit zur Wiederherstellung abbruch-entleert werden darf. Wenn nicht gesetzt, verwendet OpenClaw das sicherere erweiterte Fenster für eingebettete Ausführung von mindestens 10 Minuten und 5x stuckSessionWarnMs.
• otel.enabled: aktiviert die OpenTelemetry-Export-Pipeline (Standard: false). Die vollständige Konfiguration, den Signalkatalog und das Datenschutzmodell finden Sie unter OpenTelemetry-Export.
• otel.endpoint: Collector-URL für OTel-Export.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: optionale signalspezifische OTLP-Endpunkte. Wenn gesetzt, überschreiben sie otel.endpoint nur für dieses Signal.
• otel.protocol: "http/protobuf" (Standard) oder "grpc".
• otel.headers: zusätzliche HTTP-/gRPC-Metadaten-Header, die mit OTel-Exportanforderungen gesendet werden.
• otel.serviceName: Dienstname für Ressourcenattribute.
• otel.traces / otel.metrics / otel.logs: Trace-, Metrik- oder Logexport aktivieren.
• otel.sampleRate: Trace-Sampling-Rate 0-1.
• otel.flushIntervalMs: periodisches Telemetrie-Flush-Intervall in ms.
• otel.captureContent: Opt-in-Erfassung von Rohinhalten für OTEL-Span-Attribute. Standardmäßig deaktiviert. Boolesches true erfasst Nicht-System-Nachrichten-/Tool-Inhalte; die Objektform lässt Sie inputMessages, outputMessages, toolInputs, toolOutputs und systemPrompt explizit aktivieren.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: Umgebungsumschalter für neueste experimentelle GenAI-Span-Provider-Attribute. Standardmäßig behalten Spans aus Kompatibilitätsgründen das Legacy-Attribut gen_ai.system; GenAI-Metriken verwenden begrenzte semantische Attribute.
• OPENCLAW_OTEL_PRELOADED=1: Umgebungsumschalter für Hosts, die bereits ein globales OpenTelemetry-SDK registriert haben. OpenClaw überspringt dann Start/Shutdown des Plugin-eigenen SDK, während Diagnose-Listener aktiv bleiben.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT und OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: signalspezifische Endpunkt-Umgebungsvariablen, die verwendet werden, wenn der passende Konfigurationsschlüssel nicht gesetzt ist.
• cacheTrace.enabled: Cache-Trace-Snapshots für eingebettete Ausführungen protokollieren (Standard: false).
• cacheTrace.filePath: Ausgabepfad für Cache-Trace-JSONL (Standard: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: steuern, was in der Cache-Trace-Ausgabe enthalten ist (alle Standard: true).

​

Update

{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

• channel: Release-Kanal für npm-/git-Installationen - "stable", "beta" oder "dev".
• checkOnStart: beim Start des Gateways auf npm-Updates prüfen (Standard: true).
• auto.enabled: automatische Hintergrundaktualisierung für Paketinstallationen aktivieren (Standard: false).
• auto.stableDelayHours: Mindestverzögerung in Stunden vor automatischer Anwendung im Stable-Kanal (Standard: 6; Maximum: 168).
• auto.stableJitterHours: zusätzliches Ausrollfenster für den Stable-Kanal in Stunden (Standard: 12; Maximum: 168).
• auto.betaCheckIntervalHours: wie oft Prüfungen im Beta-Kanal in Stunden ausgeführt werden (Standard: 1; Maximum: 24).

​

ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

• enabled: globales ACP-Feature-Gate (Standard: true; setzen Sie false, um ACP-Dispatch- und Spawn-Bedienelemente auszublenden).
• dispatch.enabled: unabhängiges Gate für ACP-Sitzungs-Turn-Dispatch (Standard: true). Setzen Sie false, um ACP-Befehle verfügbar zu halten, aber die Ausführung zu blockieren.
• backend: Standard-ACP-Runtime-Backend-ID (muss mit einem registrierten ACP-Runtime-Plugin übereinstimmen). Installieren Sie zuerst das Backend-Plugin, und wenn plugins.allow gesetzt ist, nehmen Sie die Backend-Plugin-ID auf (zum Beispiel acpx), sonst wird das ACP-Backend nicht geladen.
• defaultAgent: Fallback-ACP-Ziel-Agent-ID, wenn Spawns kein explizites Ziel angeben.
• allowedAgents: Allowlist von Agent-IDs, die für ACP-Runtime-Sitzungen zulässig sind; leer bedeutet keine zusätzliche Einschränkung.
• maxConcurrentSessions: maximale Anzahl gleichzeitig aktiver ACP-Sitzungen.
• stream.coalesceIdleMs: Idle-Flush-Fenster in ms für gestreamten Text.
• stream.maxChunkChars: maximale Chunk-Größe vor dem Aufteilen der gestreamten Blockprojektion.
• stream.repeatSuppression: wiederholte Status-/Tool-Zeilen pro Turn unterdrücken (Standard: true).
• stream.deliveryMode: "live" streamt inkrementell; "final_only" puffert bis zu terminalen Turn-Ereignissen.
• stream.hiddenBoundarySeparator: Trennzeichen vor sichtbarem Text nach verborgenen Tool-Ereignissen (Standard: "paragraph").
• stream.maxOutputChars: maximale Zeichenanzahl der Assistentenausgabe, die pro ACP-Turn projiziert wird.
• stream.maxSessionUpdateChars: maximale Zeichenanzahl für projizierte ACP-Status-/Update-Zeilen.
• stream.tagVisibility: Datensatz von Tag-Namen zu booleschen Sichtbarkeits-Overrides für gestreamte Ereignisse.
• runtime.ttlMinutes: Idle-TTL in Minuten für ACP-Sitzungs-Worker vor möglicher Bereinigung.
• runtime.installCommand: optionaler Installationsbefehl, der beim Bootstrapping einer ACP-Runtime-Umgebung ausgeführt wird.

​

CLI

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• cli.banner.taglineMode steuert den Stil der Banner-Tagline:
  • "random" (Standard): rotierende humorvolle/saisonale Taglines.
  • "default": feste neutrale Tagline (All your chats, one OpenClaw.).
  • "off": kein Tagline-Text (Banner-Titel/-Version werden weiterhin angezeigt).
• Um das gesamte Banner auszublenden (nicht nur Taglines), setzen Sie die Umgebungsvariable OPENCLAW_HIDE_BANNER=1.

​

Assistent

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

​

Identität

​

Bridge (Legacy, entfernt)

{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

​

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• sessionRetention: wie lange abgeschlossene isolierte Cron-Laufsitzungen aufbewahrt werden, bevor sie aus sessions.json entfernt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: 24h; auf false setzen, um dies zu deaktivieren.
• runLog.maxBytes: maximale Größe pro Laufprotokolldatei (cron/runs/<jobId>.jsonl) vor dem Entfernen. Standard: 2_000_000 Byte.
• runLog.keepLines: neueste Zeilen, die beibehalten werden, wenn das Entfernen des Laufprotokolls ausgelöst wird. Standard: 2000.
• webhookToken: Bearer-Token, der für die Cron-Webhook-POST-Zustellung (delivery.mode = "webhook") verwendet wird; wenn er ausgelassen wird, wird kein Auth-Header gesendet.
• webhook: veraltete Legacy-Fallback-Webhook-URL (http/https), die nur für gespeicherte Jobs verwendet wird, die noch notify: true haben.

​

cron.retry

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

• maxAttempts: maximale Wiederholungen für einmalige Jobs bei transienten Fehlern (Standard: 3; Bereich: 0-10).
• backoffMs: Array von Backoff-Verzögerungen in ms für jeden Wiederholungsversuch (Standard: [30000, 60000, 300000]; 1-10 Einträge).
• retryOn: Fehlertypen, die Wiederholungen auslösen - "rate_limit", "overloaded", "network", "timeout", "server_error". Weglassen, um alle transienten Typen zu wiederholen.

​

cron.failureAlert

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      accountId: "main",
    },
  },
}

• enabled: Fehleralarme für Cron-Jobs aktivieren (Standard: false).
• after: aufeinanderfolgende Fehler, bevor ein Alarm ausgelöst wird (positive Ganzzahl, min.: 1).
• cooldownMs: Mindestanzahl von Millisekunden zwischen wiederholten Alarmen für denselben Job (nicht negative Ganzzahl).
• includeSkipped: aufeinanderfolgende übersprungene Läufe auf den Alarmschwellenwert anrechnen (Standard: false). Übersprungene Läufe werden separat verfolgt und beeinflussen den Backoff bei Ausführungsfehlern nicht.
• mode: Zustellmodus - "announce" sendet über eine Kanalnachricht; "webhook" postet an den konfigurierten Webhook.
• accountId: optionale Konto- oder Kanal-ID zur Eingrenzung der Alarmzustellung.

​

cron.failureDestination

{
  cron: {
    failureDestination: {
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

• Standardziel für Cron-Fehlerbenachrichtigungen über alle Jobs hinweg.
• mode: "announce" oder "webhook"; standardmäßig "announce", wenn genügend Zieldaten vorhanden sind.
• channel: Kanalüberschreibung für die Announce-Zustellung. "last" verwendet den zuletzt bekannten Zustellkanal wieder.
• to: explizites Announce-Ziel oder Webhook-URL. Für den Webhook-Modus erforderlich.
• accountId: optionale Kontoüberschreibung für die Zustellung.
• delivery.failureDestination pro Job überschreibt diesen globalen Standard.
• Wenn weder ein globales noch ein jobspezifisches Fehlerziel festgelegt ist, fallen Jobs, die bereits über announce zustellen, bei Fehlern auf dieses primäre Announce-Ziel zurück.
• delivery.failureDestination wird nur für Jobs mit sessionTarget="isolated" unterstützt, es sei denn, das primäre delivery.mode des Jobs ist "webhook".

​

Medienmodell-Template-Variablen

​

Config-Includes ($include)

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

• Einzelne Datei: ersetzt das enthaltende Objekt.
• Array von Dateien: wird in der Reihenfolge tief zusammengeführt (spätere überschreiben frühere).
• Geschwisterschlüssel: werden nach Includes zusammengeführt (überschreiben enthaltene Werte).
• Verschachtelte Includes: bis zu 10 Ebenen tief.
• Pfade: werden relativ zur einschließenden Datei aufgelöst, müssen aber innerhalb des obersten Config-Verzeichnisses (dirname von openclaw.json) bleiben. Absolute/../-Formen sind nur erlaubt, wenn sie weiterhin innerhalb dieser Grenze aufgelöst werden.
• Schreibvorgänge im Besitz von OpenClaw, die nur einen obersten Abschnitt ändern, der durch ein Single-File-Include gestützt wird, schreiben in diese eingeschlossene Datei durch. Beispielsweise aktualisiert plugins install plugins: { $include: "./plugins.json5" } in plugins.json5 und lässt openclaw.json unverändert.
• Root-Includes, Include-Arrays und Includes mit Geschwisterüberschreibungen sind für Schreibvorgänge im Besitz von OpenClaw schreibgeschützt; diese Schreibvorgänge schlagen geschlossen fehl, statt die Config zu verflachen.
• Fehler: klare Meldungen für fehlende Dateien, Parse-Fehler und zirkuläre Includes.

​

Verwandt

• Konfiguration
• Konfigurationsbeispiele