Konfiguration — Agenten

​

Agent-Standardeinstellungen

​

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 die Standards
      { id: "locked-down", skills: [] }, // keine Skills
    ],
  },
}

• Lassen Sie agents.defaults.skills weg, um standardmäßig uneingeschränkte Skills zuzulassen.
• Lassen Sie agents.list[].skills weg, um die Standardwerte zu erben.
• Setzen Sie agents.list[].skills: [], um keine Skills zuzulassen.
• Eine nicht leere Liste in agents.list[].skills ist die endgültige Menge für diesen Agenten; sie wird nicht mit den Standardwerten zusammengeführt.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.contextInjection

• "continuation-skip": Sichere Fortsetzungsturns (nach einer abgeschlossenen Assistant-Antwort) überspringen die erneute Injektion des Workspace-Bootstraps, wodurch die Größe des Prompts reduziert wird. Heartbeat-Läufe und Wiederholungen nach Compaction bauen den Kontext weiterhin neu auf.

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

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": niemals Warntext in den System-Prompt injizieren.
• "once": Warnung einmal pro eindeutiger Abschneidesignatur injizieren (empfohlen).
• "always": bei jedem Lauf Warnung injizieren, wenn Abschneidung vorliegt.

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

​

Zuordnung der Zuständigkeit für Kontextbudgets

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normale Injektion des Workspace-Bootstraps.
• agents.defaults.startupContext.*: einmaliges Startprelude für /new und /reset, einschließlich aktueller täglicher Dateien aus memory/*.md.
• skills.limits.*: die kompakte Skills-Liste, die in den System-Prompt injiziert wird.
• agents.defaults.contextLimits.*: begrenzte Laufzeitauszüge und injizierte runtimeeigene Blöcke.
• memory.qmd.limits.*: Snippet- und Injektionsgrößen für indizierte Memory-Suche.

• agents.list[].skillsLimits.maxSkillsPromptChars
• 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,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: standardmäßige Begrenzung von memory_get-Auszügen, bevor Metadaten zur Abschneidung und der Hinweis auf Fortsetzung hinzugefügt werden.
• memoryGetDefaultLines: standardmäßiges Zeilenfenster für memory_get, wenn lines weggelassen wird.
• toolResultMaxChars: Begrenzung für Tool-Ergebnisse im Live-Betrieb, die für persistierte Ergebnisse und Wiederherstellung bei Überläufen verwendet wird.
• postCompactionMaxChars: Begrenzung für AGENTS.md-Auszüge, die während der Injektion beim Refresh nach Compaction verwendet wird.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

​

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.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-Providerparameter
      embeddedHarness: {
        runtime: "auto", // auto | pi | registrierte Harness-ID, z. B. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "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 Objekt-Form setzt das primäre Modell plus geordnete Failover-Modelle.
• imageModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird vom Tool-Pfad image als Konfiguration für das Vision-Modell verwendet.
  • Wird auch als Fallback-Routing verwendet, wenn das ausgewählte/standardmäßige Modell keine Bildeingaben akzeptieren kann.
• imageGenerationModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Funktion zur Bildgenerierung und jeder zukünftigen Tool-/Plugin-Oberfläche verwendet, die Bilder erzeugt.
  • Typische Werte: google/gemini-3.1-flash-image-preview für native Gemini-Bildgenerierung, fal/fal-ai/flux/dev für fal oder openai/gpt-image-2 für OpenAI Images.
  • Wenn Sie direkt ein Provider-/Modellpaar 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, FAL_KEY für fal/*).
  • Wenn weggelassen, kann image_generate trotzdem einen auth-gestützten Standardprovider ableiten. Es versucht zuerst den aktuellen Standardprovider und danach die übrigen registrierten Bildgenerierungsprovider in der Reihenfolge ihrer Provider-ID.
• musicGenerationModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Funktion zur Musikgenerierung und vom eingebauten Tool music_generate verwendet.
  • Typische Werte: google/lyria-3-clip-preview, google/lyria-3-pro-preview oder minimax/music-2.5+.
  • Wenn weggelassen, kann music_generate trotzdem einen auth-gestützten Standardprovider ableiten. Es versucht zuerst den aktuellen Standardprovider und danach die übrigen registrierten Musikgenerierungsprovider in der Reihenfolge ihrer Provider-ID.
  • Wenn Sie direkt ein Provider-/Modellpaar auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key.
• videoGenerationModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Funktion zur Videogenerierung und vom eingebauten 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 weggelassen, kann video_generate trotzdem einen auth-gestützten Standardprovider ableiten. Es versucht zuerst den aktuellen Standardprovider und danach die übrigen registrierten Videogenerierungsprovider in der Reihenfolge ihrer Provider-ID.
  • Wenn Sie direkt ein Provider-/Modellpaar auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key.
  • Der gebündelte Qwen-Provider für Videogenerierung unterstützt bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer sowie die Optionen auf Providerebene size, aspectRatio, resolution, audio und watermark.
• pdfModel: akzeptiert entweder einen String ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird vom Tool pdf für das Modell-Routing verwendet.
  • Wenn weggelassen, fällt das PDF-Tool auf imageModel und dann auf das aufgelöste Sitzungs-/Standardmodell zurück.
• pdfMaxBytesMb: standardmäßiges PDF-Größenlimit für das Tool pdf, wenn maxBytesMb zur Aufrufzeit nicht übergeben wird.
• pdfMaxPages: standardmäßige maximale Seitenanzahl, die vom Extraktions-Fallback-Modus im Tool pdf berücksichtigt wird.
• verboseDefault: Standard-Verbose-Level für Agenten. Werte: "off", "on", "full". Standard: "off".
• elevatedDefault: Standardlevel für erhöhte Ausgabe bei Agenten. Werte: "off", "on", "ask", "full". Standard: "on".
• model.primary: Format provider/model (z. B. openai/gpt-5.4 für Zugriff per API-Key oder openai-codex/gpt-5.5 für Codex OAuth). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann ein eindeutiges Match mit einem konfigurierten Provider für genau diese Modell-ID und greift erst dann auf den konfigurierten Standardprovider zurück (veraltetes Kompatibilitätsverhalten, daher bevorzugen Sie explizites provider/model). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw auf das erste konfigurierte Provider-/Modellpaar zurück, anstatt einen veralteten Standard eines entfernten Providers anzuzeigen.
• models: der konfigurierte Modellkatalog und die Allowlist für /model. Jeder Eintrag kann alias (Abkürzung) und params (providerspezifisch, z. B. temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold) enthalten.
  • Sichere Bearbeitungen: Verwenden Sie openclaw config set agents.defaults.models '<json>' --strict-json --merge, um Einträge hinzuzufügen. config set verweigert Ersetzungen, die bestehende Allowlist-Einträge entfernen würden, sofern Sie nicht --replace übergeben.
  • Providerbezogene Abläufe für configure/Onboarding führen ausgewählte Providermodelle in diese Zuordnung ein und erhalten bereits konfigurierte nicht zusammenhängende Provider.
  • Für direkte OpenAI-Responses-Modelle ist serverseitige Compaction automatisch aktiviert. Verwenden Sie params.responsesServerCompaction: false, um die Injektion von context_management zu stoppen, oder params.responsesCompactThreshold, um den Schwellenwert zu überschreiben. Siehe OpenAI server-side compaction.
• params: globale Standard-Providerparameter, die auf alle Modelle angewendet werden. Werden unter agents.defaults.params gesetzt (z. B. { cacheRetention: "long" }).
• Priorität beim Zusammenführen von params (Konfiguration): agents.defaults.params (globale Basis) wird von agents.defaults.models["provider/model"].params (pro Modell) überschrieben, danach überschreibt agents.list[].params (mit passender Agent-ID) nach Schlüssel. Siehe Prompt Caching für Details.
• embeddedHarness: Standardrichtlinie für die Low-Level-Runtime eingebetteter Agenten. Verwenden Sie runtime: "auto", damit registrierte Plugin-Harnesses unterstützte Modelle übernehmen können, runtime: "pi" zum Erzwingen des eingebauten PI-Harness oder eine registrierte Harness-ID wie runtime: "codex". Setzen Sie fallback: "none", um den automatischen PI-Fallback zu deaktivieren.
• Konfigurationsschreiber, die diese Felder verändern (zum Beispiel /models set, /models set-image und Befehle zum Hinzufügen/Entfernen von Fallbacks), speichern die kanonische Objektform und erhalten nach Möglichkeit vorhandene Fallback-Listen.
• maxConcurrent: maximale Anzahl paralleler Agent-Läufe über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: "auto", "pi" oder eine registrierte Plugin-Harness-ID. Das gebündelte Codex-Plugin registriert codex.
• fallback: "pi" oder "none". "pi" behält das eingebaute PI-Harness als Kompatibilitätsfallback bei, wenn kein Plugin-Harness ausgewählt ist. "none" sorgt dafür, dass eine fehlende oder nicht unterstützte Auswahl eines Plugin-Harness fehlschlägt, statt stillschweigend PI zu verwenden. Fehler des ausgewählten Plugin-Harness werden immer direkt angezeigt.
• Umgebungsüberschreibungen: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> überschreibt runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none deaktiviert den PI-Fallback für diesen Prozess.
• Für reine Codex-Bereitstellungen setzen Sie model: "openai/gpt-5.5", embeddedHarness.runtime: "codex" und embeddedHarness.fallback: "none".
• Die Wahl des Harness wird pro Sitzungs-ID nach dem ersten eingebetteten Lauf festgeschrieben. Änderungen in Konfiguration/Umgebung wirken sich auf neue oder zurückgesetzte Sitzungen aus, nicht auf ein bestehendes Transcript. Legacy-Sitzungen mit Transcript-Verlauf, aber ohne aufgezeichnete Festlegung, werden als auf PI festgelegt behandelt. /status zeigt Nicht-PI-Harness-IDs wie codex neben Fast an.
• Dies steuert nur das eingebettete Chat-Harness. Mediengenerierung, Vision, PDF, Musik, Video und TTS verwenden weiterhin ihre Provider-/Modell-Einstellungen.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI-Backends sind textorientiert; Tools sind immer deaktiviert.
• Sitzungen werden unterstützt, wenn sessionArg gesetzt ist.
• Bilddurchreichung wird unterstützt, wenn imageArg Dateipfade akzeptiert.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.promptOverlays

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

• "friendly" (Standard) und "on" aktivieren die freundliche Interaktionsschicht.
• "off" deaktiviert nur die freundliche Schicht; der getaggte GPT-5-Verhaltensvertrag bleibt aktiv.
• Das ältere plugins.entries.openai.config.personality wird weiterhin gelesen, wenn diese gemeinsame Einstellung nicht gesetzt ist.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m deaktiviert
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // Standard: true; false lässt den Abschnitt Heartbeat im System-Prompt weg
        lightContext: false, // Standard: false; true behält aus den Workspace-Bootstrap-Dateien nur HEARTBEAT.md
        isolatedSession: false, // Standard: false; true führt jeden Heartbeat in einer neuen Sitzung aus (kein Gesprächsverlauf)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (Standard) | block
        target: "none", // Standard: none | Optionen: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: Dauer-String (ms/s/m/h). Standard: 30m (API-Key-Authentifizierung) oder 1h (OAuth-Authentifizierung). Setzen Sie 0m, um zu deaktivieren.
• includeSystemPromptSection: wenn false, wird der Heartbeat-Abschnitt aus dem System-Prompt weggelassen und die Injektion von HEARTBEAT.md in den Bootstrap-Kontext übersprungen. Standard: true.
• suppressToolErrorWarnings: wenn true, werden Nutzlasten für Tool-Fehlerwarnungen während Heartbeat-Läufen unterdrückt.
• timeoutSeconds: maximale Zeit in Sekunden, die ein Heartbeat-Agent-Turn ausführen darf, bevor er abgebrochen wird. Nicht gesetzt verwendet agents.defaults.timeoutSeconds.
• directPolicy: Richtlinie für direkte/DM-Zustellung. allow (Standard) erlaubt direkte Zielzustellung. block unterdrückt direkte Zielzustellung und erzeugt reason=dm-blocked.
• lightContext: wenn true, verwenden Heartbeat-Läufe einen leichtgewichtigen Bootstrap-Kontext und behalten aus den Workspace-Bootstrap-Dateien nur HEARTBEAT.md.
• isolatedSession: wenn true, wird jeder Heartbeat in einer frischen Sitzung ohne vorherigen Gesprächsverlauf ausgeführt. Dasselbe Isolationsmuster wie bei Cron sessionTarget: "isolated". Reduziert die Tokenkosten pro Heartbeat von etwa ~100K auf ~2–5K Tokens.
• Pro Agent: setzen Sie agents.list[].heartbeat. Wenn irgendein Agent heartbeat definiert, führen nur diese Agenten 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 eines registrierten Compaction-Provider-Plugins (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // verwendet, wenn identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] deaktiviert Re-Injektion
        model: "openrouter/anthropic/claude-sonnet-4-6", // optionale nur für Compaction geltende Modellüberschreibung
        notifyUser: true, // kurze Hinweise senden, wenn Compaction beginnt und abgeschlossen wird (Standard: false)
        memoryFlush: {
          enabled: true,
          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 (stückweise Zusammenfassung für lange Verläufe). Siehe Compaction.
• provider: ID eines registrierten Compaction-Provider-Plugins. Wenn gesetzt, wird summarize() dieses Providers anstelle der eingebauten LLM-Zusammenfassung aufgerufen. Bei Fehlern fällt es auf das eingebaute Verhalten zurück. Das Setzen eines Providers erzwingt mode: "safeguard". Siehe Compaction.
• timeoutSeconds: maximale Anzahl an Sekunden, die für eine einzelne Compaction-Operation erlaubt sind, bevor OpenClaw sie abbricht. Standard: 900.
• identifierPolicy: strict (Standard), off oder custom. strict stellt bei der Zusammenfassung während der Compaction eingebaute Anweisungen zur Beibehaltung undurchsichtiger Bezeichner voran.
• identifierInstructions: optionaler benutzerdefinierter Text zur Beibehaltung von Bezeichnern, der verwendet wird, wenn identifierPolicy=custom.
• postCompactionSections: optionale Namen von H2-/H3-Abschnitten in AGENTS.md, die nach der Compaction erneut injiziert werden. Standard ist ["Session Startup", "Red Lines"]; setzen Sie [], um die Re-Injektion zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften Every Session/Safety auch als Legacy-Fallback akzeptiert.
• model: optionale Überschreibung provider/model-id nur für die Zusammenfassung während der Compaction. Verwenden Sie dies, wenn die Hauptsitzung ein Modell behalten soll, Compaction-Zusammenfassungen aber auf einem anderen Modell laufen sollen; wenn nicht gesetzt, verwendet Compaction das primäre Modell der Sitzung.
• notifyUser: wenn true, sendet kurze Hinweise an den Benutzer, wenn die Compaction beginnt und wenn sie abgeschlossen ist (zum Beispiel „Compacting context…“ und „Compaction complete“). Standardmäßig deaktiviert, damit Compaction still bleibt.
• memoryFlush: stiller agentischer Turn vor automatischer Compaction, um dauerhafte Erinnerungen zu speichern. Wird übersprungen, wenn der Workspace schreibgeschützt ist.

​

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: "[Old tool result content cleared]" },
        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 (verwenden Sie minMs/maxMs)
    },
  },
}

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

​

Tippindikatoren

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

• Standardwerte: instant für direkte Chats/Erwähnungen, message für Gruppenchats ohne Erwähnung.
• Überschreibungen pro Sitzung: 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", // optionale OpenShell-Policy-ID
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # Haupt-Sandbox-Image
scripts/sandbox-browser-setup.sh   # optionales Browser-Image

​

agents.list (Überschreibungen 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", // oder { primary, fallbacks }
        thinkingDefault: "high", // Überschreibung des Thinking-Levels pro Agent
        reasoningDefault: "on", // Überschreibung der Sichtbarkeit von Reasoning pro Agent
        fastModeDefault: false, // Überschreibung des Fast-Modus pro Agent
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // überschreibt passende defaults.models-Parameter nach Schlüssel
        skills: ["docs-search"], // ersetzt agents.defaults.skills, wenn gesetzt
        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 die erste (Warnung wird protokolliert). Wenn keine gesetzt ist, ist der erste Listeneintrag der Standard.
• model: Die String-Form überschreibt nur primary; die Objekt-Form { primary, fallbacks } überschreibt beides ([] deaktiviert globale Fallbacks). Cron-Jobs, die nur primary überschreiben, erben weiterhin Standard-Fallbacks, sofern Sie nicht fallbacks: [] setzen.
• params: Stream-Parameter pro Agent, die über den ausgewählten Modelleintrag in agents.defaults.models zusammengeführt werden. Verwenden Sie dies für agentenspezifische Überschreibungen wie cacheRetention, temperature oder maxTokens, ohne den gesamten Modellkatalog zu duplizieren.
• skills: optionale Skill-Allowlist pro Agent. Wenn weggelassen, erbt der Agent agents.defaults.skills, sofern gesetzt; eine explizite Liste ersetzt die Standards statt sie zusammenzuführen, und [] bedeutet keine Skills.
• thinkingDefault: optionale Standard-Thinking-Stufe pro Agent (off | minimal | low | medium | high | xhigh | adaptive | max). Überschreibt agents.defaults.thinkingDefault für diesen Agenten, wenn kein Override pro Nachricht oder Sitzung gesetzt ist.
• reasoningDefault: optionale Standardsichtbarkeit für Reasoning pro Agent (on | off | stream). Gilt, wenn kein Override für Reasoning pro Nachricht oder Sitzung gesetzt ist.
• fastModeDefault: optionaler Standard für den Fast-Modus pro Agent (true | false). Gilt, wenn kein Override für den Fast-Modus pro Nachricht oder Sitzung gesetzt ist.
• embeddedHarness: optionale Überschreibung der Low-Level-Harness-Richtlinie pro Agent. Verwenden Sie { runtime: "codex", fallback: "none" }, um einen Agenten nur mit Codex auszuführen, während andere Agenten den Standard-PI-Fallback behalten.
• runtime: optionaler Runtime-Deskriptor pro Agent. Verwenden Sie type: "acp" mit den Standardwerten in runtime.acp (agent, backend, mode, cwd), wenn der Agent standardmäßig ACP-Harness-Sitzungen verwenden soll.
• identity.avatar: relativer Pfad zum Workspace, http(s)-URL oder data:-URI.
• identity leitet Standardwerte ab: ackReaction aus emoji, mentionPatterns aus name/emoji.
• subagents.allowAgents: Allowlist von Agent-IDs für sessions_spawn (["*"] = beliebig; Standard: nur derselbe Agent).
• Schutz bei Vererbung der Sandbox: Wenn die anfragende Sitzung sandboxed ist, lehnt sessions_spawn Ziele ab, die unsandboxed ausgeführt würden.
• subagents.requireAgentId: wenn true, werden Aufrufe von sessions_spawn blockiert, die agentId weglassen (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" } },
  ],
}

​

Match-Felder für Bindungen

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

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

​

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",
    parentForkMaxTokens: 100000, // Parent-Thread-Fork oberhalb dieser Tokenanzahl überspringen (0 deaktiviert)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // Dauer oder false
      maxDiskBytes: "500mb", // optionales hartes Budget
      highWaterBytes: "400mb", // optionales Bereinigungsziel
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // Standardwert für automatisches Entfokussieren nach Inaktivität in Stunden (`0` deaktiviert)
      maxAgeHours: 0, // Standardwert für harte Maximaldauer in Stunden (`0` deaktiviert)
    },
    mainKey: "main", // Legacy (Runtime verwendet immer "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Nachrichten

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

​

Antwortpräfix

​

Bestätigungsreaktion

• Standard ist das identity.emoji des aktiven Agenten, andernfalls "👀". Setzen Sie "", um zu deaktivieren.
• Überschreibungen pro Kanal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Auflösungsreihenfolge: Konto → Kanal → messages.ackReaction → Fallback über Identität.
• Scope: group-mentions (Standard), group-all, direct, all.
• removeAckAfterReply: entfernt die Bestätigungsreaktion nach der Antwort auf Slack, Discord und Telegram.
• messages.statusReactions.enabled: aktiviert Lifecycle-Statusreaktionen auf Slack, Discord und Telegram. Auf Slack und Discord bleiben Statusreaktionen bei fehlender Einstellung aktiviert, wenn Bestätigungsreaktionen aktiv sind. Auf Telegram setzen Sie dies explizit auf true, um Lifecycle-Statusreaktionen zu aktivieren.

​

Inbound-Debounce

​

TTS (Text-to-Speech)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "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,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• auto steuert den Standardmodus für Auto-TTS: off, always, inbound oder tagged. /tts on|off kann lokale Einstellungen überschreiben, und /tts status zeigt den effektiven Status.
• 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-Keys fallen auf ELEVENLABS_API_KEY/XI_API_KEY und OPENAI_API_KEY zurück.
• openai.baseUrl überschreibt den OpenAI-TTS-Endpunkt. Die Auflösungsreihenfolge ist Konfiguration, dann OPENAI_TTS_BASE_URL, dann https://api.openai.com/v1.
• Wenn openai.baseUrl auf einen Nicht-OpenAI-Endpunkt verweist, behandelt OpenClaw dies als OpenAI-kompatiblen TTS-Server und lockert die Validierung von Modell/Stimme.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• talk.provider muss zu einem Schlüssel in talk.providers passen, wenn mehrere Talk-Provider konfiguriert sind.
• Legacy-Schlüssel für Talk in flacher Form (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) dienen nur der Kompatibilität und werden automatisch nach talk.providers.<provider> migriert.
• Voice-IDs fallen auf ELEVENLABS_VOICE_ID oder SAG_VOICE_ID zurück.
• providers.*.apiKey akzeptiert Klartext-Strings oder SecretRef-Objekte.
• Der Fallback ELEVENLABS_API_KEY gilt nur, wenn kein API-Key für Talk konfiguriert ist.
• providers.*.voiceAliases erlaubt es Talk-Direktiven, freundliche Namen zu verwenden.
• silenceTimeoutMs steuert, wie lange der Talk-Modus nach Benutzerschweigen wartet, bevor das Transcript gesendet wird. Nicht gesetzt verwendet das Standard-Pausenfenster der Plattform (700 ms auf macOS und Android, 900 ms auf iOS).

​

Verwandt

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