Konfiguration — Agenten

​

Agent-Standards

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // erbt github, weather
      { id: "docs", skills: ["docs-search"] }, // ersetzt Standards
      { id: "locked-down", skills: [] }, // keine Skills
    ],
  },
}

• Lassen Sie agents.defaults.skills weg, um Skills standardmäßig uneingeschränkt zu erlauben.
• Lassen Sie agents.list[].skills weg, um die Standards zu erben.
• Setzen Sie agents.list[].skills: [] für keine Skills.
• Eine nicht leere Liste agents.list[].skills ist die endgültige Menge für diesen Agent; sie wird nicht mit Standards zusammengeführt.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.skipOptionalBootstrapFiles

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

​

agents.defaults.contextInjection

• "continuation-skip": Sichere Fortsetzungs-Turns (nach einer abgeschlossenen Assistant-Antwort) überspringen das erneute Einfügen des Workspace-Bootstraps und reduzieren so die Prompt-Größe. Heartbeat-Läufe und Wiederholungen nach Compaction bauen den Kontext weiterhin neu auf.
• "never": Deaktiviert Workspace-Bootstrap und Kontextdatei-Injection bei jedem Turn. Verwenden Sie dies nur für Agents, die ihren Prompt-Lebenszyklus vollständig selbst verwalten (benutzerdefinierte Kontext-Engines, native Runtimes, die ihren eigenen Kontext erstellen, oder spezialisierte bootstrap-freie Workflows). Heartbeat- und Compaction-Recovery-Turns überspringen die Injection ebenfalls.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

​

Bootstrap-Profil-Overrides pro Agent

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": Fügt niemals Kürzungshinweistext in den System-Prompt ein.
• "once": Fügt einmal pro eindeutiger Kürzungssignatur einen knappen Hinweis ein.
• "always": Fügt bei jedem Lauf einen knappen Hinweis ein, wenn eine Kürzung vorliegt (empfohlen).

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "always" } }, // off | once | always
}

​

Zuständigkeitsübersicht für Kontextbudgets

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normale Workspace-Bootstrap-Injection.
• agents.defaults.startupContext.*: einmalige Reset-/Start-Modelllauf-Einleitung, einschließlich aktueller täglicher memory/*.md-Dateien. Reine Chat-Befehle /new und /reset werden bestätigt, ohne das Modell aufzurufen.
• skills.limits.*: die kompakte Skills-Liste, die in den System-Prompt eingefügt wird.
• agents.defaults.contextLimits.*: begrenzte Runtime-Auszüge und eingefügte runtime-eigene Blöcke.
• memory.qmd.limits.*: Snippet- und Injection-Größen für die indizierte Memory-Suche.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: Standardobergrenze für memory_get-Auszüge, bevor Kürzungs- Metadaten und Fortsetzungshinweis hinzugefügt werden.
• memoryGetDefaultLines: Standard-Zeilenfenster für memory_get, wenn lines weggelassen wird.
• toolResultMaxChars: fortgeschrittene Obergrenze für Live-Tool-Ergebnisse, die für persistierte Ergebnisse und Overflow-Wiederherstellung verwendet wird. Nicht setzen, um die automatische Modellkontext-Obergrenze zu verwenden: 16000 Zeichen unter 100K Tokens, 32000 Zeichen ab 100K Tokens und 64000 Zeichen ab 200K Tokens. Explizite Werte bis 1000000 werden für Long-Context-Modelle akzeptiert, aber die effektive Obergrenze bleibt auf etwa 30 % des Modellkontextfensters begrenzt. openclaw doctor --deep gibt die effektive Obergrenze aus, und doctor warnt nur, wenn ein expliziter Override veraltet ist oder keine Wirkung hat.
• postCompactionMaxChars: Obergrenze für AGENTS.md-Auszüge, die während der Aktualisierungs- Injection nach Compaction verwendet wird.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // fortgeschrittene Obergrenze für diesen Agent
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

​

agents.list[].skillsLimits.maxSkillsPromptChars

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.imageQuality

• auto: an Modellgrenzen und Bildanzahl anpassen.
• efficient: kleinere Bilder für geringere Token- und Byte-Nutzung bevorzugen.
• balanced: die standardmäßige Mittelweg-Stufe verwenden.
• high: mehr Details für Screenshots, Diagramme und Dokumentbilder bewahren.

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // globale Standard-Provider-Parameter
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Die String-Form setzt nur das primäre Modell.
  • Die Objektform setzt das primäre Modell plus geordnete Failover-Modelle.
• imageModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird vom image-Tool-Pfad als dessen Vision-Modellkonfiguration verwendet.
  • Wird auch als Fallback-Routing verwendet, wenn das ausgewählte oder Standardmodell keine Bildeingaben akzeptieren kann.
  • Bevorzugen Sie explizite provider/model-Referenzen. Reine IDs werden aus Kompatibilitätsgründen akzeptiert; wenn eine reine ID eindeutig einem konfigurierten bildeingabefähigen Eintrag in models.providers.*.models entspricht, qualifiziert OpenClaw sie für diesen Provider. Mehrdeutige konfigurierte Treffer erfordern ein explizites Provider-Präfix.
• imageGenerationModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Bildgenerierungsfunktion und jeder zukünftigen Tool-/Plugin-Oberfläche verwendet, die Bilder generiert.
  • Typische Werte: google/gemini-3.1-flash-image-preview für native Gemini-Bildgenerierung, fal/fal-ai/flux/dev für fal, openai/gpt-image-2 für OpenAI Images oder openai/gpt-image-1.5 für OpenAI-PNG-/WebP-Ausgabe mit transparentem Hintergrund.
  • Wenn Sie einen Provider/ein Modell direkt auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung (zum Beispiel GEMINI_API_KEY oder GOOGLE_API_KEY für google/*, OPENAI_API_KEY oder OpenAI Codex OAuth für openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY für fal/*).
  • Wenn ausgelassen, kann image_generate weiterhin einen authentifizierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die verbleibenden registrierten Bildgenerierungs-Provider in Reihenfolge der Provider-IDs.
• musicGenerationModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Musikgenerierungsfunktion und dem integrierten Tool music_generate verwendet.
  • Typische Werte: google/lyria-3-clip-preview, google/lyria-3-pro-preview oder minimax/music-2.6.
  • Wenn ausgelassen, kann music_generate weiterhin einen authentifizierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die verbleibenden registrierten Musikgenerierungs-Provider in Reihenfolge der Provider-IDs.
  • Wenn Sie einen Provider/ein Modell direkt auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den passenden API-Schlüssel.
• videoGenerationModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Videogenerierungsfunktion und dem integrierten Tool video_generate verwendet.
  • Typische Werte: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash oder qwen/wan2.7-r2v.
  • Wenn ausgelassen, kann video_generate weiterhin einen authentifizierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die verbleibenden registrierten Videogenerierungs-Provider in Reihenfolge der Provider-IDs.
  • Wenn Sie einen Provider/ein Modell direkt auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den passenden API-Schlüssel.
  • Das offizielle Qwen-Plugin für Videogenerierung unterstützt bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer sowie Provider-weite Optionen size, aspectRatio, resolution, audio und watermark.
• pdfModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird vom Tool pdf für Modell-Routing verwendet.
  • Wenn ausgelassen, fällt das PDF-Tool auf imageModel zurück und dann auf das aufgelöste Sitzungs-/Standardmodell.
• pdfMaxBytesMb: standardmäßige PDF-Größenbegrenzung für das Tool pdf, wenn maxBytesMb beim Aufruf nicht übergeben wird.
• pdfMaxPages: standardmäßige maximale Seitenzahl, die vom Extraktions-Fallback-Modus im Tool pdf berücksichtigt wird.
• verboseDefault: standardmäßige Ausführlichkeitsstufe für Agents. Werte: "off", "on", "full". Standard: "off".
• toolProgressDetail: Detailmodus für /verbose-Tool-Zusammenfassungen und Tool-Zeilen in Fortschrittsentwürfen. Werte: "explain" (Standard, kompakte menschliche Labels) oder "raw" (hängt den rohen Befehl/das rohe Detail an, wenn verfügbar). Agent-spezifisches agents.list[].toolProgressDetail überschreibt diesen Standard.
• reasoningDefault: standardmäßige Sichtbarkeit von Reasoning für Agents. Werte: "off", "on", "stream". Agent-spezifisches agents.list[].reasoningDefault überschreibt diesen Standard. Konfigurierte Reasoning-Standards werden nur für Owner, autorisierte Absender oder Operator-Admin-Gateway-Kontexte angewendet, wenn keine Reasoning-Überschreibung pro Nachricht oder Sitzung gesetzt ist.
• elevatedDefault: standardmäßige Stufe für erhöhte Ausgabe bei Agents. Werte: "off", "on", "ask", "full". Standard: "on".
• model.primary: Format provider/model (z. B. openai/gpt-5.5 für OpenAI-API-Schlüssel oder Codex-OAuth-Zugriff). Wenn Sie den Provider auslassen, versucht OpenClaw zuerst einen Alias, dann einen eindeutigen Treffer bei konfigurierten Providern für genau diese Modell-ID und fällt erst danach auf den konfigurierten Standard-Provider zurück (veraltetes Kompatibilitätsverhalten; bevorzugen Sie daher explizit provider/model). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw auf das erste konfigurierte Provider/Modell-Paar zurück, statt einen veralteten entfernten Provider-Standard anzuzeigen.
• models: der konfigurierte Modellkatalog und die Allowlist für /model. Jeder Eintrag kann alias (Kurzform) und params enthalten (Provider-spezifisch, zum Beispiel temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, OpenRouter-provider-Routing, chat_template_kwargs, extra_body/extraBody).
  • Verwenden Sie provider/*-Einträge wie "openai/*": {} oder "vllm/*": {}, um alle erkannten Modelle für ausgewählte Provider anzuzeigen, ohne jede Modell-ID manuell aufzulisten.
  • Fügen Sie einem provider/*-Eintrag agentRuntime hinzu, wenn jedes dynamisch erkannte Modell für diesen Provider dieselbe Laufzeit verwenden soll. Eine exakte provider/model-Laufzeitrichtlinie hat weiterhin Vorrang vor dem Wildcard-Eintrag.
  • Sichere Bearbeitungen: Verwenden Sie openclaw config set agents.defaults.models '<json>' --strict-json --merge, um Einträge hinzuzufügen. config set verweigert Ersetzungen, die vorhandene Allowlist-Einträge entfernen würden, sofern Sie nicht --replace übergeben.
  • Provider-bezogene Konfigurations-/Onboarding-Flows führen ausgewählte Provider-Modelle in diese Map zusammen und erhalten bereits konfigurierte nicht zugehörige Provider.
  • Für direkte OpenAI-Responses-Modelle ist serverseitige Compaction automatisch aktiviert. Verwenden Sie params.responsesServerCompaction: false, um das Injizieren von context_management zu stoppen, oder params.responsesCompactThreshold, um den Schwellenwert zu überschreiben. Siehe OpenAI server-side compaction.
• params: globale Standard-Provider-Parameter, die auf alle Modelle angewendet werden. Wird unter agents.defaults.params gesetzt (z. B. { cacheRetention: "long" }).
• Zusammenführungspriorität für params (Konfiguration): agents.defaults.params (globale Basis) wird von agents.defaults.models["provider/model"].params (pro Modell) überschrieben, danach überschreibt agents.list[].params (passende Agent-ID) schlüsselweise. Details finden Sie unter Prompt Caching.
• models.providers.openrouter.params.provider: OpenRouter-weiter Standard für die Provider-Routing-Richtlinie. OpenClaw leitet dies an das provider-Objekt der OpenRouter-Anfrage weiter; pro Modell überschreiben agents.defaults.models["openrouter/<model>"].params.provider und Agent-Parameter schlüsselweise. Siehe OpenRouter provider routing.
• params.extra_body/params.extraBody: erweitertes Pass-through-JSON, das in api: "openai-completions"-Anfragebodies für OpenAI-kompatible Proxys zusammengeführt wird. Wenn es mit generierten Anfrage-Schlüsseln kollidiert, gewinnt der zusätzliche Body; nicht-native Completions-Routen entfernen anschließend weiterhin OpenAI-only store.
• params.chat_template_kwargs: vLLM-/OpenAI-kompatible Chat-Template-Argumente, die in oberste api: "openai-completions"-Anfragebodies zusammengeführt werden. Für vllm/nemotron-3-* mit deaktiviertem Thinking sendet das gebündelte vLLM-Plugin automatisch enable_thinking: false und force_nonempty_content: true; explizite chat_template_kwargs überschreiben generierte Standards, und extra_body.chat_template_kwargs hat weiterhin letzte Priorität. Konfigurierte vLLM-Qwen- und Nemotron-Thinking-Modelle bieten binäre /think-Auswahlen (off, on) statt der mehrstufigen Aufwandsleiter.
• compat.thinkingFormat: OpenAI-kompatibler Thinking-Payload-Stil. Verwenden Sie "together" für Together-artiges reasoning.enabled, "qwen" für Qwen-artiges Top-Level-enable_thinking oder "qwen-chat-template" für chat_template_kwargs.enable_thinking auf Backends der Qwen-Familie, die Anfrageebenen-Chat-Template-Kwargs unterstützen, wie vLLM. OpenClaw ordnet deaktiviertes Thinking false und aktiviertes Thinking true zu, und konfigurierte vLLM-Qwen-Modelle bieten binäre /think-Auswahlen für diese Formate.
• compat.supportedReasoningEfforts: OpenAI-kompatible Reasoning-Aufwandliste pro Modell. Nehmen Sie "xhigh" für benutzerdefinierte Endpunkte auf, die es wirklich akzeptieren; OpenClaw zeigt dann /think xhigh in Befehlsmenüs, Gateway-Sitzungszeilen, Sitzungs-Patch-Validierung, Agent-CLI-Validierung und llm-task-Validierung für diesen konfigurierten Provider/dieses Modell an. Verwenden Sie compat.reasoningEffortMap, wenn das Backend für eine kanonische Stufe einen Provider-spezifischen Wert erwartet.
• params.preserveThinking: Z.AI-only Opt-in für beibehaltenes Thinking. Wenn aktiviert und Thinking eingeschaltet ist, sendet OpenClaw thinking.clear_thinking: false und spielt vorheriges reasoning_content erneut ab; siehe Z.AI thinking and preserved thinking.
• localService: optionaler Provider-weiter Prozessmanager für lokale/selbst gehostete Modellserver. Wenn das ausgewählte Modell zu diesem Provider gehört, prüft OpenClaw healthUrl (oder baseUrl + "/models"), startet command mit args, wenn der Endpunkt nicht erreichbar ist, wartet bis zu readyTimeoutMs und sendet dann die Modellanfrage. command muss ein absoluter Pfad sein. idleStopMs: 0 hält den Prozess bis zum Beenden von OpenClaw am Leben; ein positiver Wert stoppt den von OpenClaw gestarteten Prozess nach entsprechend vielen Millisekunden Leerlauf. Siehe Local model services.
• Laufzeitrichtlinien gehören zu Providern oder Modellen, nicht zu agents.defaults. Verwenden Sie models.providers.<provider>.agentRuntime für Provider-weite Regeln oder agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime für modellspezifische Regeln. OpenAI-Agent-Modelle beim offiziellen OpenAI-Provider wählen standardmäßig Codex aus.
• Konfigurationsschreiber, die diese Felder ändern (zum Beispiel /models set, /models set-image und Befehle zum Hinzufügen/Entfernen von Fallbacks), speichern die kanonische Objektform und erhalten vorhandene Fallback-Listen, wenn möglich.
• maxConcurrent: maximale parallele Agent-Ausführungen über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4.

​

Laufzeitrichtlinie

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      models: {
        "anthropic/claude-opus-4-8": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id: "auto", "openclaw", eine registrierte Plugin-Harness-ID oder ein unterstützter CLI-Backend-Alias. Das gebündelte Codex-Plugin registriert codex; das gebündelte Anthropic-Plugin stellt das CLI-Backend claude-cli bereit.
• id: "auto" lässt registrierte Plugin-Harnesses unterstützte Turns übernehmen und verwendet OpenClaw, wenn kein Harness passt. Eine explizite Plugin-Runtime wie id: "codex" erfordert dieses Harness und schlägt sicher fehl, wenn es nicht verfügbar ist oder fehlschlägt.
• id: "pi" wird nur als veralteter Alias für openclaw akzeptiert, um ausgelieferte Konfigurationen aus v2026.5.22 und früher zu erhalten. Neue Konfiguration sollte openclaw verwenden.
• Die Runtime-Priorität ist zuerst exakte Modellrichtlinie (agents.list[].models["provider/model"], agents.defaults.models["provider/model"] oder models.providers.<provider>.models[]), dann agents.list[] / agents.defaults.models["provider/*"], dann Provider-weite Richtlinie unter models.providers.<provider>.agentRuntime.
• Runtime-Schlüssel für ganze Agents sind Legacy. agents.defaults.agentRuntime, agents.list[].agentRuntime, Sitzungs-Runtime-Pins und OPENCLAW_AGENT_RUNTIME werden von der Runtime-Auswahl ignoriert. Führen Sie openclaw doctor --fix aus, um veraltete Werte zu entfernen.
• OpenAI-Agent-Modelle verwenden standardmäßig das Codex-Harness; Provider/Modell-agentRuntime.id: "codex" bleibt gültig, wenn Sie dies explizit machen möchten.
• Für Claude-CLI-Deployments bevorzugen Sie model: "anthropic/claude-opus-4-8" plus modellbezogenes agentRuntime.id: "claude-cli". Legacy-claude-cli/claude-opus-4-7-Modell-Refs funktionieren aus Kompatibilitätsgründen weiterhin, aber neue Konfiguration sollte die Provider/Modell-Auswahl kanonisch halten und das Ausführungs-Backend in die Provider/Modell-Runtime-Richtlinie legen.
• Dies steuert nur die Ausführung von Text-Agent-Turns. Mediengenerierung, Vision, PDF, Musik, Video und TTS verwenden weiterhin ihre Provider/Modell-Einstellungen.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI-Backends sind textorientiert; Tools sind immer deaktiviert.
• Sitzungen werden unterstützt, wenn sessionArg gesetzt ist.
• Bild-Durchleitung wird unterstützt, wenn imageArg Dateipfade akzeptiert.
• reseedFromRawTranscriptWhenUncompacted: true ermöglicht einem Backend, sichere ungültig gewordene Sitzungen aus einem begrenzten rohen OpenClaw-Transkriptende wiederherzustellen, bevor die erste Compaction-Zusammenfassung existiert. Änderungen an Auth-Profil oder Anmeldeinformations-Epoche führen weiterhin nie zu einem Raw-Reseed.

​

agents.defaults.promptOverlays

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• "friendly" (Standard) und "on" aktivieren die freundliche Ebene des Interaktionsstils.
• "off" deaktiviert nur die freundliche Ebene; der markierte GPT-5-Verhaltensvertrag bleibt aktiviert.
• Legacy-plugins.entries.openai.config.personality wird weiterhin gelesen, wenn diese gemeinsame Einstellung nicht gesetzt ist.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: Dauerzeichenfolge (ms/s/m/h). Standard: 30m (API-Schlüssel-Auth) oder 1h (OAuth-Auth). Setzen Sie dies auf 0m, um zu deaktivieren.
• includeSystemPromptSection: wenn false, wird der Heartbeat-Abschnitt aus dem System-Prompt ausgelassen und die Injektion von HEARTBEAT.md in den Bootstrap-Kontext übersprungen. Standard: true.
• suppressToolErrorWarnings: wenn true, werden Tool-Fehlerwarnungs-Payloads während Heartbeat-Läufen unterdrückt.
• timeoutSeconds: maximal zulässige Zeit in Sekunden für einen Heartbeat-Agent-Turn, bevor er abgebrochen wird. Lassen Sie dies nicht gesetzt, um agents.defaults.timeoutSeconds zu verwenden, falls gesetzt, andernfalls die auf 600 Sekunden begrenzte Heartbeat-Kadenz.
• directPolicy: Richtlinie für Direkt-/DM-Zustellung. allow (Standard) erlaubt die Zustellung an Direktziele. block unterdrückt die Zustellung an Direktziele und gibt reason=dm-blocked aus.
• lightContext: wenn true, verwenden Heartbeat-Läufe einen schlanken Bootstrap-Kontext und behalten aus den Workspace-Bootstrap-Dateien nur HEARTBEAT.md.
• isolatedSession: wenn true, läuft jeder Heartbeat in einer frischen Sitzung ohne vorherigen Konversationsverlauf. Dasselbe Isolationsmuster wie Cron sessionTarget: "isolated". Reduziert die Token-Kosten pro Heartbeat von ca. 100K auf ca. 2-5K Tokens.
• skipWhenBusy: wenn true, werden Heartbeat-Läufe bei zusätzlichen belegten Bahnen dieses Agents verschoben: seiner eigenen sitzungsschlüsselbasierten Subagent- oder verschachtelten Befehlsarbeit. Cron-Bahnen verschieben Heartbeats immer, auch ohne dieses Flag.
• Pro Agent: setzen Sie agents.list[].heartbeat. Wenn ein Agent heartbeat definiert, führen nur diese Agents Heartbeats aus.
• Heartbeats führen vollständige Agent-Turns aus — kürzere Intervalle verbrauchen mehr Tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default oder safeguard (segmentierte Zusammenfassung für lange Verläufe). Siehe Compaction.
• provider: ID eines registrierten Compaction-Provider-Plugins. Wenn festgelegt, wird die summarize() des Providers anstelle der integrierten LLM-Zusammenfassung aufgerufen. Fällt bei Fehlern auf die integrierte Zusammenfassung zurück. Das Festlegen eines Providers erzwingt mode: "safeguard". Siehe Compaction.
• timeoutSeconds: maximal zulässige Sekunden für einen einzelnen Compaction-Vorgang, bevor OpenClaw ihn abbricht. Standard: 180.
• keepRecentTokens: Agent-Cut-Point-Budget, um den neuesten Transkript-Auszug wortgetreu beizubehalten. Manuelles /compact berücksichtigt dies, wenn es ausdrücklich festgelegt ist; andernfalls ist manuelle Compaction ein harter Checkpoint.
• identifierPolicy: strict (Standard), off oder custom. strict stellt während der Compaction-Zusammenfassung integrierte Anleitung zur Beibehaltung undurchsichtiger Bezeichner voran.
• identifierInstructions: optionaler benutzerdefinierter Text zur Beibehaltung von Bezeichnern, der verwendet wird, wenn identifierPolicy=custom.
• qualityGuard: Prüfungen mit Wiederholung bei fehlerhaft formatierter Ausgabe für Safeguard-Zusammenfassungen. Im Safeguard-Modus standardmäßig aktiviert; setzen Sie enabled: false, um die Prüfung zu überspringen.
• midTurnPrecheck: optionale Tool-Loop-Druckprüfung. Wenn enabled: true, prüft OpenClaw den Kontextdruck, nachdem Tool-Ergebnisse angehängt wurden und bevor der nächste Modellaufruf erfolgt. Wenn der Kontext nicht mehr passt, bricht es den aktuellen Versuch vor dem Absenden des Prompts ab und verwendet den vorhandenen Precheck-Wiederherstellungspfad erneut, um Tool-Ergebnisse zu kürzen oder eine Compaction auszuführen und erneut zu versuchen. Funktioniert mit den Compaction-Modi default und safeguard. Standard: deaktiviert.
• postCompactionSections: optionale AGENTS.md-H2/H3-Abschnittsnamen, die nach der Compaction erneut eingefügt werden. Erneutes Einfügen ist deaktiviert, wenn nicht gesetzt oder auf [] gesetzt. Das ausdrückliche Festlegen von ["Session Startup", "Red Lines"] aktiviert dieses Paar und bewahrt den Legacy-Fallback Every Session/Safety. Aktivieren Sie dies nur, wenn der zusätzliche Kontext das Risiko wert ist, Projekthinweise zu duplizieren, die bereits in der Compaction-Zusammenfassung erfasst sind.
• model: optionales provider/model-id oder bloßer Alias aus agents.defaults.models nur für Compaction-Zusammenfassung. Bloße Aliase werden vor dem Dispatch aufgelöst; konfigurierte literale Modell-IDs behalten bei Kollisionen Vorrang. Verwenden Sie dies, wenn die Hauptsitzung ein Modell behalten soll, Compaction-Zusammenfassungen aber auf einem anderen ausgeführt werden sollen; wenn nicht gesetzt, verwendet Compaction das primäre Modell der Sitzung.
• maxActiveTranscriptBytes: optionaler Byte-Schwellenwert (number oder Zeichenfolgen wie "20mb"), der vor einem Lauf normale lokale Compaction auslöst, wenn das aktive JSONL über den Schwellenwert wächst. Erfordert truncateAfterCompaction, damit erfolgreiche Compaction zu einem kleineren Nachfolge-Transkript rotieren kann. Deaktiviert, wenn nicht gesetzt oder 0.
• notifyUser: wenn true, sendet kurze Hinweise an den Benutzer, wenn Compaction startet und wenn sie abgeschlossen ist (zum Beispiel „Kontext wird kompaktiert…“ und „Compaction abgeschlossen“). Standardmäßig deaktiviert, damit Compaction still bleibt.
• memoryFlush: stiller agentischer Turn vor Auto-Compaction, um dauerhafte Erinnerungen zu speichern. Setzen Sie model auf einen exakten Provider/ein exaktes Modell wie ollama/qwen3:8b, wenn dieser Verwaltungs-Turn auf einem lokalen Modell bleiben soll; die Überschreibung erbt nicht die Fallback-Kette der aktiven Sitzung. Wird übersprungen, wenn der Arbeitsbereich schreibgeschützt ist.

​

agents.defaults.runRetries

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // optionale agentenspezifische Überschreibungen
      },
    ],
  },
}

• base: Basisanzahl von Wiederholungsiterationen für die äußere Laufschleife. Standard: 24.
• perProfile: zusätzliche Wiederholungsiterationen, die pro Fallback-Profilkandidat gewährt werden. Standard: 8.
• min: absolutes Mindestlimit für Wiederholungsiterationen. Standard: 32.
• max: absolutes Höchstlimit für Wiederholungsiterationen, um ausufernde Ausführung zu verhindern. Standard: 160.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // Dauer (ms/s/m/h), Standardeinheit: Minuten
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Alter Tool-Ergebnisinhalt gelöscht]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Block-Streaming

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (minMs/maxMs verwenden)
    },
  },
}

• Nicht-Telegram-Kanäle erfordern ausdrücklich *.blockStreaming: true, um Blockantworten zu aktivieren.
• Kanalüberschreibungen: channels.<channel>.blockStreamingCoalesce (und kontospezifische Varianten). Signal/Slack/Discord/Google Chat verwenden standardmäßig minChars: 1500.
• humanDelay: zufällige Pause zwischen Blockantworten. natural = 800–2500 ms. Agentenspezifische Überschreibung: agents.list[].humanDelay.

​

Tippindikatoren

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Standards: instant für Direktchats/Erwähnungen, message für nicht erwähnte Gruppenchats.
• Sitzungsspezifische Überschreibungen: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / Inline-Inhalte werden ebenfalls unterstützt:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optional OpenShell policy id
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

​

agents.list (Overrides pro Agent)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: stabile Agent-ID (erforderlich).
• default: Wenn mehrere gesetzt sind, gewinnt der erste (Warnung wird protokolliert). Wenn keiner gesetzt ist, ist der erste Listeneintrag der Standard.
• model: Die String-Form setzt ein striktes agent-spezifisches Primärmodell ohne Modell-Fallback; die Objektform { primary } ist ebenfalls strikt, sofern Sie keine fallbacks hinzufügen. Verwenden Sie { primary, fallbacks: [...] }, um diesen Agent für Fallback zu aktivieren, oder { primary, fallbacks: [] }, um striktes Verhalten explizit zu machen. Cron-Jobs, die nur primary überschreiben, erben weiterhin Standard-Fallbacks, sofern Sie nicht fallbacks: [] setzen.
• params: pro Agent konfigurierte Stream-Parameter, die über den ausgewählten Modelleintrag in agents.defaults.models gelegt werden. Verwenden Sie dies für agent-spezifische Overrides wie cacheRetention, temperature oder maxTokens, ohne den gesamten Modellkatalog zu duplizieren.
• tts: optionale Text-to-Speech-Overrides pro Agent. Der Block wird per Deep-Merge über messages.tts gelegt; behalten Sie daher gemeinsame Provider-Zugangsdaten und Fallback-Richtlinien in messages.tts und setzen Sie hier nur persona-spezifische Werte wie Provider, Stimme, Modell, Stil oder Auto-Modus.
• skills: optionale Skill-Allowlist pro Agent. Wenn ausgelassen, erbt der Agent agents.defaults.skills, falls gesetzt; eine explizite Liste ersetzt die Standardwerte, statt sie zusammenzuführen, und [] bedeutet keine Skills.
• thinkingDefault: optionale standardmäßige Denkstufe pro Agent (off | minimal | low | medium | high | xhigh | adaptive | max). Überschreibt agents.defaults.thinkingDefault für diesen Agent, wenn kein Override pro Nachricht oder Sitzung gesetzt ist. Das ausgewählte Provider-/Modellprofil steuert, welche Werte gültig sind; bei Google Gemini behält adaptive Provider-eigenes dynamisches Denken bei (thinkingLevel bei Gemini 3/3.1 ausgelassen, thinkingBudget: -1 bei Gemini 2.5).
• reasoningDefault: optionale standardmäßige Reasoning-Sichtbarkeit pro Agent (on | off | stream). Überschreibt agents.defaults.reasoningDefault für diesen Agent, wenn kein Reasoning-Override pro Nachricht oder Sitzung gesetzt ist.
• fastModeDefault: optionaler Standardwert pro Agent für den Schnellmodus ("auto" | true | false). Gilt, wenn kein Schnellmodus-Override pro Nachricht oder Sitzung gesetzt ist.
• models: optionale Modellkatalog-/Runtime-Overrides pro Agent, nach vollständigen provider/model-IDs geschlüsselt. Verwenden Sie models["provider/model"].agentRuntime für Runtime-Ausnahmen pro Agent.
• runtime: optionaler Runtime-Deskriptor pro Agent. Verwenden Sie type: "acp" mit runtime.acp-Standardwerten (agent, backend, mode, cwd), wenn der Agent standardmäßig ACP-Harness-Sitzungen verwenden soll.
• identity.avatar: Workspace-relativer Pfad, http(s)-URL oder data:-URI.
• Lokale Workspace-relative identity.avatar-Bilddateien sind auf 2 MB begrenzt. http(s)-URLs und data:-URIs werden nicht gegen das lokale Dateigrößenlimit geprüft.
• identity leitet Standardwerte ab: ackReaction aus emoji, mentionPatterns aus name/emoji.
• subagents.allowAgents: Allowlist konfigurierter Agent-IDs für explizite sessions_spawn.agentId-Ziele (["*"] = jedes konfigurierte Ziel; Standard: nur derselbe Agent). Fügen Sie die Requester-ID ein, wenn selbstadressierte agentId-Aufrufe erlaubt sein sollen. Veraltete Einträge, deren Agent-Konfiguration gelöscht wurde, werden von sessions_spawn abgelehnt und aus agents_list ausgelassen; führen Sie openclaw doctor --fix aus, um sie zu bereinigen, oder fügen Sie einen minimalen agents.list[]-Eintrag hinzu, wenn dieses Ziel spawnbar bleiben und dabei Standardwerte erben soll.
• Sandbox-Vererbungsschutz: Wenn die Requester-Sitzung sandboxed ist, lehnt sessions_spawn Ziele ab, die unsandboxed laufen würden.
• subagents.requireAgentId: Wenn true, werden sessions_spawn-Aufrufe blockiert, die agentId auslassen (erzwingt explizite Profilauswahl; Standard: false).

​

Multi-Agent-Routing

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

​

Binding-Match-Felder

• type (optional): route für normales Routing (fehlender Typ ist standardmäßig route), acp für persistente ACP-Konversations-Bindings.
• match.channel (erforderlich)
• match.accountId (optional; * = beliebiges Konto; ausgelassen = Standardkonto)
• match.peer (optional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (optional; kanal-spezifisch)
• acp (optional; nur für type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exakt, kein Peer/Guild/Team)
5. match.accountId: "*" (kanalweit)
6. Standard-Agent

​

Zugriffsprofile pro Agent

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

Sitzung

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Nachrichten

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "followup", // steer | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Antwortpräfix

​

Ack-Reaktion

• Standardmäßig identity.emoji des aktiven Agenten, andernfalls "👀". Auf "" setzen, um sie zu deaktivieren.
• Überschreibungen pro Channel: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Auflösungsreihenfolge: Konto → Channel → messages.ackReaction → Identitäts-Fallback.
• Geltungsbereich: group-mentions (Standard), group-all, direct, all.
• removeAckAfterReply: entfernt die Ack-Reaktion nach der Antwort in reaktionsfähigen Channels wie Slack, Discord, Signal, Telegram, WhatsApp und iMessage.
• messages.statusReactions.enabled: aktiviert Lebenszyklus-Statusreaktionen in Slack, Discord, Signal, Telegram und WhatsApp. Bei Slack und Discord bleiben Statusreaktionen bei nicht gesetztem Wert aktiviert, wenn Ack-Reaktionen aktiv sind. Bei Signal, Telegram und WhatsApp setzen Sie den Wert explizit auf true, um Lebenszyklus-Statusreaktionen zu aktivieren.
• messages.statusReactions.emojis: überschreibt Lebenszyklus-Emoji-Schlüssel: queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft und stallHard. Telegram erlaubt nur eine feste Reaktionsauswahl, daher fallen nicht unterstützte konfigurierte Emoji auf die nächstgelegene unterstützte Statusvariante für diesen Chat zurück.

​

Eingangs-Debounce

​

TTS (Text-to-Speech)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-5.4-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          speakerVoiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
        microsoft: {
          speakerVoice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          speakerVoice: "alloy",
        },
      },
    },
  },
}

• auto steuert den standardmäßigen Auto-TTS-Modus: off, always, inbound oder tagged. /tts on|off kann lokale Einstellungen überschreiben, und /tts status zeigt den effektiven Zustand an.
• summaryModel überschreibt agents.defaults.model.primary für die automatische Zusammenfassung.
• modelOverrides ist standardmäßig aktiviert; modelOverrides.allowProvider ist standardmäßig false (Opt-in).
• API-Schlüssel fallen auf ELEVENLABS_API_KEY/XI_API_KEY und OPENAI_API_KEY zurück.
• Mitgelieferte Sprach-Provider sind Plugin-eigen. Wenn plugins.allow gesetzt ist, nehmen Sie jedes TTS-Provider-Plugin auf, das Sie verwenden möchten, zum Beispiel microsoft für Edge TTS. Die ältere Provider-ID edge wird als Alias für microsoft akzeptiert.
• providers.openai.baseUrl überschreibt den OpenAI-TTS-Endpunkt. Die Auflösungsreihenfolge ist Konfiguration, dann OPENAI_TTS_BASE_URL, dann https://api.openai.com/v1.
• Wenn providers.openai.baseUrl auf einen Nicht-OpenAI-Endpunkt verweist, behandelt OpenClaw ihn als OpenAI-kompatiblen TTS-Server und lockert die Modell-/Stimmenvalidierung.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider muss mit einem Schlüssel in talk.providers übereinstimmen, wenn mehrere Talk-Provider konfiguriert sind.
• Ältere flache Talk-Schlüssel (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) dienen nur der Kompatibilität. Führen Sie openclaw doctor --fix aus, um persistierte Konfiguration in talk.providers.<provider> umzuschreiben.
• Stimmen-IDs fallen auf ELEVENLABS_VOICE_ID oder SAG_VOICE_ID zurück.
• providers.*.apiKey akzeptiert Klartextzeichenfolgen oder SecretRef-Objekte.
• Der Fallback ELEVENLABS_API_KEY gilt nur, wenn kein Talk-API-Schlüssel konfiguriert ist.
• Mit providers.*.voiceAliases können Talk-Anweisungen benutzerfreundliche Namen verwenden.
• providers.mlx.modelId wählt das Hugging-Face-Repo aus, das vom lokalen macOS-MLX-Helfer verwendet wird. Wenn ausgelassen, verwendet macOS mlx-community/Soprano-80M-bf16.
• Die macOS-MLX-Wiedergabe läuft über den mitgelieferten Helfer openclaw-mlx-tts, wenn vorhanden, oder über eine ausführbare Datei in PATH; OPENCLAW_MLX_TTS_BIN überschreibt den Helferpfad für die Entwicklung.
• consultThinkingLevel steuert das Thinking-Level für den vollständigen OpenClaw-Agent-Lauf hinter Control-UI-Talk-Realtime-openclaw_agent_consult-Aufrufen. Nicht setzen, um normales Sitzungs-/Modellverhalten beizubehalten.
• consultFastMode legt eine einmalige Fast-Mode-Überschreibung für Control-UI-Talk-Realtime-Consults fest, ohne die normale Fast-Mode-Einstellung der Sitzung zu ändern.
• speechLocale legt die BCP-47-Locale-ID fest, die von der iOS/macOS-Talk-Spracherkennung verwendet wird. Nicht setzen, um die Gerätevoreinstellung zu verwenden.
• silenceTimeoutMs steuert, wie lange der Talk-Modus nach Stille der Benutzerin oder des Benutzers wartet, bevor er das Transkript sendet. Nicht gesetzt bleibt das standardmäßige Pausenfenster der Plattform erhalten (700 ms on macOS and Android, 900 ms on iOS).
• realtime.instructions hängt Provider-seitige Systemanweisungen an den integrierten Realtime-Prompt von OpenClaw an, sodass der Sprachstil konfiguriert werden kann, ohne die standardmäßige openclaw_agent_consult-Anleitung zu verlieren.
• realtime.consultRouting steuert den Gateway-Relay-Fallback, wenn der Realtime-Provider ein finales Benutzertranskript ohne openclaw_agent_consult erzeugt: provider-direct behält direkte Provider-Antworten bei, während force-agent-consult die finalisierte Anfrage durch OpenClaw leitet.

​

Verwandt

• Konfigurationsreferenz — alle anderen Konfigurationsschlüssel
• Konfiguration — häufige Aufgaben und schnelle Einrichtung
• Konfigurationsbeispiele