Konfiguracja — agenci

​

Ustawienia domyślne agenta

​

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" }, // dziedziczy github, weather
      { id: "docs", skills: ["docs-search"] }, // zastępuje wartości domyślne
      { id: "locked-down", skills: [] }, // brak Skills
    ],
  },
}

• Pomiń agents.defaults.skills, aby domyślnie nie ograniczać Skills.
• Pomiń agents.list[].skills, aby dziedziczyć wartości domyślne.
• Ustaw agents.list[].skills: [], aby nie mieć żadnych Skills.
• Niepusta lista agents.list[].skills jest ostatecznym zestawem dla tego agenta; nie łączy się z wartościami domyślnymi.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.contextInjection

• "continuation-skip": bezpieczne tury kontynuacji (po zakończonej odpowiedzi asystenta) pomijają ponowne wstrzyknięcie bootstrap obszaru roboczego, zmniejszając rozmiar promptu. Uruchomienia Heartbeat i ponowienia po Compaction nadal odbudowują kontekst.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": nigdy nie wstrzykuj tekstu ostrzeżenia do promptu systemowego.
• "once": wstrzyknij ostrzeżenie raz dla każdego unikalnego podpisu obcięcia (zalecane).
• "always": wstrzykuj ostrzeżenie przy każdym uruchomieniu, gdy istnieje obcięcie.

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

​

Mapa własności budżetu kontekstu

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: zwykłe wstrzykiwanie bootstrap obszaru roboczego.
• agents.defaults.startupContext.*: jednorazowe preludium startowe dla /new i /reset, w tym ostatnie dzienne pliki memory/*.md.
• skills.limits.*: kompaktowa lista Skills wstrzykiwana do promptu systemowego.
• agents.defaults.contextLimits.*: ograniczone fragmenty runtime i wstrzykiwane bloki należące do runtime.
• memory.qmd.limits.*: rozmiar fragmentów indeksowanego wyszukiwania pamięci i ich wstrzykiwania.

• 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: domyślny limit fragmentu memory_get przed dodaniem metadanych obcięcia i informacji o kontynuacji.
• memoryGetDefaultLines: domyślne okno wierszy memory_get, gdy pominięto lines.
• toolResultMaxChars: limit aktywnego wyniku narzędzia używany dla zapisanych wyników i odzyskiwania po przepełnieniu.
• postCompactionMaxChars: limit fragmentu AGENTS.md używany podczas wstrzykiwania odświeżenia po Compaction.

​

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" }, // globalne domyślne parametry providera
      embeddedHarness: {
        runtime: "auto", // auto | pi | registered harness id, np. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: akceptuje albo ciąg ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Forma ciągu ustawia tylko model podstawowy.
  • Forma obiektu ustawia model podstawowy oraz uporządkowane modele failover.
• imageModel: akceptuje albo ciąg ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez ścieżkę narzędzia image jako konfiguracja modelu vision.
  • Używany także jako routowanie rezerwowe, gdy wybrany/dom yślny model nie może przyjąć obrazu jako wejścia.
• imageGenerationModel: akceptuje albo ciąg ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną możliwość generowania obrazów oraz każdą przyszłą powierzchnię narzędzia/Pluginu generującą obrazy.
  • Typowe wartości: google/gemini-3.1-flash-image-preview dla natywnego generowania obrazów Gemini, fal/fal-ai/flux/dev dla fal albo openai/gpt-image-2 dla OpenAI Images.
  • Jeśli wybierzesz provider/model bezpośrednio, skonfiguruj też pasujące uwierzytelnianie providera (na przykład GEMINI_API_KEY lub GOOGLE_API_KEY dla google/*, OPENAI_API_KEY lub OpenAI Codex OAuth dla openai/gpt-image-2, FAL_KEY dla fal/*).
  • Jeśli to pole zostanie pominięte, image_generate nadal może wywnioskować domyślnego providera z obsługą uwierzytelniania. Najpierw próbuje bieżącego domyślnego providera, a potem pozostałych zarejestrowanych providerów generowania obrazów w kolejności identyfikatorów providerów.
• musicGenerationModel: akceptuje albo ciąg ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną możliwość generowania muzyki oraz wbudowane narzędzie music_generate.
  • Typowe wartości: google/lyria-3-clip-preview, google/lyria-3-pro-preview albo minimax/music-2.5+.
  • Jeśli to pole zostanie pominięte, music_generate nadal może wywnioskować domyślnego providera z obsługą uwierzytelniania. Najpierw próbuje bieżącego domyślnego providera, a potem pozostałych zarejestrowanych providerów generowania muzyki w kolejności identyfikatorów providerów.
  • Jeśli wybierzesz provider/model bezpośrednio, skonfiguruj też pasujące uwierzytelnianie providera/klucz API.
• videoGenerationModel: akceptuje albo ciąg ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną możliwość generowania wideo oraz wbudowane narzędzie video_generate.
  • Typowe wartości: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash albo qwen/wan2.7-r2v.
  • Jeśli to pole zostanie pominięte, video_generate nadal może wywnioskować domyślnego providera z obsługą uwierzytelniania. Najpierw próbuje bieżącego domyślnego providera, a potem pozostałych zarejestrowanych providerów generowania wideo w kolejności identyfikatorów providerów.
  • Jeśli wybierzesz provider/model bezpośrednio, skonfiguruj też pasujące uwierzytelnianie providera/klucz API.
  • Bundled provider generowania wideo Qwen obsługuje maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe wideo, długość 10 sekund oraz opcje poziomu providera size, aspectRatio, resolution, audio i watermark.
• pdfModel: akceptuje albo ciąg ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez narzędzie pdf do routowania modeli.
  • Jeśli zostanie pominięty, narzędzie PDF przechodzi rezerwowo do imageModel, a następnie do rozwiązanego modelu sesji/dom yślnego.
• pdfMaxBytesMb: domyślny limit rozmiaru PDF dla narzędzia pdf, gdy podczas wywołania nie przekazano maxBytesMb.
• pdfMaxPages: domyślna maksymalna liczba stron uwzględnianych przez tryb rezerwowego wyodrębniania w narzędziu pdf.
• verboseDefault: domyślny poziom verbose dla agentów. Wartości: "off", "on", "full". Domyślnie: "off".
• elevatedDefault: domyślny poziom elevated-output dla agentów. Wartości: "off", "on", "ask", "full". Domyślnie: "on".
• model.primary: format provider/model (np. openai/gpt-5.4 dla dostępu przez klucz API albo openai-codex/gpt-5.5 dla Codex OAuth). Jeśli pominiesz providera, OpenClaw najpierw próbuje aliasu, potem jednoznacznego dopasowania skonfigurowanego providera dla dokładnego identyfikatora modelu, a dopiero potem wraca do skonfigurowanego domyślnego providera (przestarzałe zachowanie zgodności, więc preferuj jawne provider/model). Jeśli ten provider nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw przechodzi do pierwszego skonfigurowanego provider/model zamiast ujawniać nieaktualny domyślny model usuniętego providera.
• models: skonfigurowany katalog modeli i allowlist dla /model. Każdy wpis może zawierać alias (skrót) i params (specyficzne dla providera, na przykład temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold).
  • Bezpieczne edycje: użyj openclaw config set agents.defaults.models '<json>' --strict-json --merge, aby dodać wpisy. config set odmawia zastąpień, które usunęłyby istniejące wpisy allowlist, chyba że przekażesz --replace.
  • Przepływy configure/onboarding ograniczone do providera scalają wybrane modele providera z tą mapą i zachowują niepowiązanych providerów już skonfigurowanych.
  • Dla bezpośrednich modeli OpenAI Responses server-side Compaction jest włączane automatycznie. Użyj params.responsesServerCompaction: false, aby przestać wstrzykiwać context_management, albo params.responsesCompactThreshold, aby nadpisać próg. Zobacz OpenAI server-side compaction.
• params: globalne domyślne parametry providera stosowane do wszystkich modeli. Ustawiane w agents.defaults.params (np. { cacheRetention: "long" }).
• Pierwszeństwo scalania params (konfiguracja): agents.defaults.params (globalna baza) jest nadpisywane przez agents.defaults.models["provider/model"].params (per model), a następnie agents.list[].params (pasujący identyfikator agenta) nadpisuje według klucza. Zobacz Prompt Caching, aby poznać szczegóły.
• embeddedHarness: domyślne zasady niskopoziomowego runtime osadzonego agenta. Użyj runtime: "auto", aby zarejestrowane Plugin harnesses mogły przejąć obsługiwane modele, runtime: "pi", aby wymusić wbudowany harness PI, albo zarejestrowanego identyfikatora harness, takiego jak runtime: "codex". Ustaw fallback: "none", aby wyłączyć automatyczny fallback PI.
• Konfiguratory zapisujące te pola (na przykład /models set, /models set-image oraz polecenia add/remove dla fallback) zapisują kanoniczną formę obiektu i, gdy to możliwe, zachowują istniejące listy fallback.
• maxConcurrent: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4.

​

agents.defaults.embeddedHarness

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

• runtime: "auto", "pi" albo identyfikator zarejestrowanego Plugin harness. Bundled plugin Codex rejestruje codex.
• fallback: "pi" albo "none". "pi" zachowuje wbudowany harness PI jako fallback zgodności, gdy nie wybrano żadnego Plugin harness. "none" powoduje, że brakujący albo nieobsługiwany wybór Plugin harness kończy się błędem zamiast cichego użycia PI. Błędy wybranego Plugin harness są zawsze ujawniane bezpośrednio.
• Nadpisania środowiskowe: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> nadpisuje runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none wyłącza fallback PI dla tego procesu.
• W przypadku wdrożeń tylko z Codex ustaw model: "openai/gpt-5.5", embeddedHarness.runtime: "codex" i embeddedHarness.fallback: "none".
• Wybór harness jest przypinany per identyfikator sesji po pierwszym osadzonym uruchomieniu. Zmiany konfiguracji/env wpływają na nowe lub zresetowane sesje, a nie na istniejący transkrypt. Starsze sesje z historią transkryptu, ale bez zapisanego przypięcia, są traktowane jako przypięte do PI. /status pokazuje identyfikatory harness inne niż PI, takie jak codex, obok Fast.
• To kontroluje tylko osadzony harness czatu. Generowanie multimediów, vision, PDF, muzyka, wideo i TTS nadal używają swoich ustawień provider/model.

​

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

• Backendy CLI są tekstowe w pierwszej kolejności; narzędzia są zawsze wyłączone.
• Sesje są obsługiwane, gdy ustawiono sessionArg.
• Przekazywanie obrazów jest obsługiwane, gdy imageArg akceptuje ścieżki plików.

​

agents.defaults.systemPromptOverride

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

​

agents.defaults.promptOverlays

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

• "friendly" (domyślnie) i "on" włączają warstwę przyjaznego stylu interakcji.
• "off" wyłącza tylko warstwę przyjazną; oznaczony kontrakt zachowania GPT-5 pozostaje włączony.
• Starsze plugins.entries.openai.config.personality jest nadal odczytywane, gdy to współdzielone ustawienie nie jest ustawione.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m wyłącza
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // domyślnie: true; false pomija sekcję Heartbeat w promptcie systemowym
        lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap obszaru roboczego
        isolatedSession: false, // domyślnie: false; true uruchamia każdy Heartbeat w świeżej sesji (bez historii rozmowy)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (domyślnie) | block
        target: "none", // domyślnie: none | opcje: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: ciąg czasu trwania (ms/s/m/h). Domyślnie: 30m (uwierzytelnianie kluczem API) albo 1h (uwierzytelnianie OAuth). Ustaw 0m, aby wyłączyć.
• includeSystemPromptSection: gdy ma wartość false, pomija sekcję Heartbeat w promptcie systemowym i pomija wstrzyknięcie HEARTBEAT.md do kontekstu bootstrap. Domyślnie: true.
• suppressToolErrorWarnings: gdy ma wartość true, ukrywa ładunki ostrzeżeń o błędach narzędzi podczas uruchomień Heartbeat.
• timeoutSeconds: maksymalny czas w sekundach dozwolony dla tury agenta Heartbeat, po którym zostaje przerwana. Pozostaw nieustawione, aby użyć agents.defaults.timeoutSeconds.
• directPolicy: zasady dostarczania bezpośredniego/DM. allow (domyślnie) zezwala na dostarczanie do celu bezpośredniego. block blokuje dostarczanie do celu bezpośredniego i emituje reason=dm-blocked.
• lightContext: gdy ma wartość true, uruchomienia Heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko HEARTBEAT.md z plików bootstrap obszaru roboczego.
• isolatedSession: gdy ma wartość true, każdy Heartbeat działa w świeżej sesji bez wcześniejszej historii rozmowy. Ten sam wzorzec izolacji co Cron sessionTarget: "isolated". Zmniejsza koszt tokenów per Heartbeat z około ~100K do ~2-5K tokenów.
• Per agent: ustaw agents.list[].heartbeat. Gdy jakikolwiek agent definiuje heartbeat, tylko ci agenci uruchamiają Heartbeat.
• Heartbeat uruchamia pełne tury agenta — krótsze interwały spalają więcej tokenów.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id zarejestrowanego Pluginu providera Compaction (opcjonalnie)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // używane, gdy identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] wyłącza ponowne wstrzykiwanie
        model: "openrouter/anthropic/claude-sonnet-4-6", // opcjonalne nadpisanie modelu tylko dla Compaction
        notifyUser: true, // wysyłaj krótkie powiadomienia, gdy Compaction się zaczyna i kończy (domyślnie: 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 albo safeguard (podsumowanie w fragmentach dla długich historii). Zobacz Compaction.
• provider: identyfikator zarejestrowanego Pluginu providera Compaction. Gdy ustawiony, wywoływane jest summarize() providera zamiast wbudowanego podsumowania LLM. W przypadku błędu następuje fallback do wbudowanego rozwiązania. Ustawienie providera wymusza mode: "safeguard". Zobacz Compaction.
• timeoutSeconds: maksymalna liczba sekund dozwolona dla pojedynczej operacji Compaction, po której OpenClaw ją przerywa. Domyślnie: 900.
• identifierPolicy: strict (domyślnie), off albo custom. strict dodaje wbudowane wskazówki zachowania nieprzezroczystych identyfikatorów podczas podsumowywania Compaction.
• identifierInstructions: opcjonalny własny tekst zachowania identyfikatorów używany, gdy identifierPolicy=custom.
• postCompactionSections: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po Compaction. Domyślnie ["Session Startup", "Red Lines"]; ustaw [], aby wyłączyć ponowne wstrzykiwanie. Gdy nieustawione albo jawnie ustawione na tę domyślną parę, starsze nagłówki Every Session/Safety są również akceptowane jako starszy fallback.
• model: opcjonalne nadpisanie provider/model-id tylko dla podsumowania Compaction. Użyj tego, gdy główna sesja powinna zachować jeden model, ale podsumowania Compaction powinny działać na innym; gdy nieustawione, Compaction używa modelu podstawowego sesji.
• notifyUser: gdy true, wysyła użytkownikowi krótkie powiadomienia, gdy Compaction się zaczyna i kończy (na przykład „Compacting context…” i „Compaction complete”). Domyślnie wyłączone, aby Compaction pozostało ciche.
• memoryFlush: cicha tura agentowa przed automatycznym Compaction w celu zapisania trwałych wspomnień. Pomijane, gdy obszar roboczy jest tylko do odczytu.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // czas trwania (ms/s/m/h), domyślna jednostka: minuty
        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 (użyj minMs/maxMs)
    },
  },
}

• Kanały inne niż Telegram wymagają jawnego *.blockStreaming: true, aby włączyć odpowiedzi blokowe.
• Nadpisania kanałów: channels.<channel>.blockStreamingCoalesce (oraz warianty per konto). Signal/Slack/Discord/Google Chat mają domyślnie minChars: 1500.
• humanDelay: losowa przerwa między odpowiedziami blokowymi. natural = 800–2500 ms. Nadpisanie per agent: agents.list[].humanDelay.

​

Wskaźniki pisania

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

• Domyślnie: instant dla czatów bezpośrednich/wzmianek, message dla niewspomnianych czatów grupowych.
• Nadpisania per sesja: 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",
          // SecretRef / treści inline również są obsługiwane:
          // 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", // opcjonalnie
          gatewayEndpoint: "https://lab.example", // opcjonalnie
          policy: "strict", // opcjonalny identyfikator zasad OpenShell
          providers: ["openai"], // opcjonalnie
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # główny obraz sandbox
scripts/sandbox-browser-setup.sh   # opcjonalny obraz przeglądarki

​

agents.list (nadpisania per agent)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // albo { primary, fallbacks }
        thinkingDefault: "high", // nadpisanie poziomu thinking per agent
        reasoningDefault: "on", // nadpisanie widoczności reasoning per agent
        fastModeDefault: false, // nadpisanie trybu fast per agent
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // nadpisuje pasujące defaults.models params według klucza
        skills: ["docs-search"], // zastępuje agents.defaults.skills, gdy ustawione
        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: stabilny identyfikator agenta (wymagany).
• default: gdy ustawiono wiele, wygrywa pierwszy (zapisywane jest ostrzeżenie). Jeśli żaden nie jest ustawiony, domyślny jest pierwszy wpis listy.
• model: forma ciągu nadpisuje tylko primary; forma obiektu { primary, fallbacks } nadpisuje oba ([] wyłącza globalne fallback). Zadania Cron, które nadpisują tylko primary, nadal dziedziczą domyślne fallback, chyba że ustawisz fallbacks: [].
• params: parametry strumienia per agent scalane nad wybranym wpisem modelu w agents.defaults.models. Używaj tego do nadpisań specyficznych dla agenta, takich jak cacheRetention, temperature lub maxTokens, bez duplikowania całego katalogu modeli.
• skills: opcjonalna allowlist Skills per agent. Jeśli pominięta, agent dziedziczy agents.defaults.skills, gdy jest ustawione; jawna lista zastępuje wartości domyślne zamiast je scalać, a [] oznacza brak Skills.
• thinkingDefault: opcjonalny domyślny poziom thinking per agent (off | minimal | low | medium | high | xhigh | adaptive | max). Nadpisuje agents.defaults.thinkingDefault dla tego agenta, gdy nie ustawiono nadpisania per wiadomość ani per sesja.
• reasoningDefault: opcjonalna domyślna widoczność reasoning per agent (on | off | stream). Obowiązuje, gdy nie ustawiono nadpisania reasoning per wiadomość ani per sesja.
• fastModeDefault: opcjonalna domyślna wartość trybu fast per agent (true | false). Obowiązuje, gdy nie ustawiono nadpisania per wiadomość ani per sesja.
• embeddedHarness: opcjonalne nadpisanie zasad niskopoziomowego harness per agent. Użyj { runtime: "codex", fallback: "none" }, aby jeden agent był tylko dla Codex, podczas gdy inni agenci zachowują domyślny fallback PI.
• runtime: opcjonalny deskryptor runtime per agent. Użyj type: "acp" z domyślnymi ustawieniami runtime.acp (agent, backend, mode, cwd), gdy agent powinien domyślnie używać sesji harness ACP.
• identity.avatar: ścieżka względna do obszaru roboczego, adres URL http(s) albo URI data:.
• identity wyprowadza wartości domyślne: ackReaction z emoji, mentionPatterns z name/emoji.
• subagents.allowAgents: allowlist identyfikatorów agentów dla sessions_spawn (["*"] = dowolny; domyślnie: tylko ten sam agent).
• Ochrona dziedziczenia sandbox: jeśli sesja żądająca jest sandboxed, sessions_spawn odrzuca cele, które działałyby bez sandbox.
• subagents.requireAgentId: gdy ma wartość true, blokuje wywołania sessions_spawn, które pomijają agentId (wymusza jawny wybór profilu; domyślnie: false).

​

Routowanie wielu agentów

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

​

Pola dopasowania powiązań

• type (opcjonalnie): route dla zwykłego routowania (brak typu domyślnie oznacza route), acp dla trwałych powiązań rozmów ACP.
• match.channel (wymagane)
• match.accountId (opcjonalnie; * = dowolne konto; pominięte = konto domyślne)
• match.peer (opcjonalnie; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opcjonalnie; specyficzne dla kanału)
• acp (opcjonalnie; tylko dla type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (dokładne, bez peer/guild/team)
5. match.accountId: "*" (dla całego kanału)
6. Agent domyślny

​

Profile dostępu per 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",
          ],
        },
      },
    ],
  },
}

​

Sesja

{
  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, // pomiń fork z wątku nadrzędnego powyżej tej liczby tokenów (0 wyłącza)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // czas trwania albo false
      maxDiskBytes: "500mb", // opcjonalny twardy budżet
      highWaterBytes: "400mb", // opcjonalny cel czyszczenia
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // domyślne automatyczne odwiązanie po bezczynności w godzinach (`0` wyłącza)
      maxAgeHours: 0, // domyślny twardy maksymalny wiek w godzinach (`0` wyłącza)
    },
    mainKey: "main", // starsze pole (runtime zawsze używa "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Wiadomości

{
  messages: {
    responsePrefix: "🦞", // albo "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 wyłącza
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefiks odpowiedzi

​

Reakcja potwierdzająca

• Domyślnie używa identity.emoji aktywnego agenta, w przeciwnym razie "👀". Ustaw "", aby wyłączyć.
• Nadpisania per kanał: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Kolejność rozwiązywania: konto → kanał → messages.ackReaction → fallback tożsamości.
• Zakres: group-mentions (domyślnie), group-all, direct, all.
• removeAckAfterReply: usuwa potwierdzenie po odpowiedzi w Slack, Discord i Telegram.
• messages.statusReactions.enabled: włącza reakcje statusu cyklu życia w Slack, Discord i Telegram. W Slack i Discord pozostawienie nieustawionego pola utrzymuje reakcje statusu włączone, gdy aktywne są reakcje potwierdzające. W Telegram ustaw to jawnie na true, aby włączyć reakcje statusu cyklu życia.

​

Debounce wejściowy

​

TTS (zamiana tekstu na mowę)

{
  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 kontroluje domyślny tryb auto-TTS: off, always, inbound albo tagged. /tts on|off może nadpisywać lokalne preferencje, a /tts status pokazuje stan efektywny.
• summaryModel nadpisuje agents.defaults.model.primary dla auto-summary.
• modelOverrides jest domyślnie włączone; modelOverrides.allowProvider ma domyślnie wartość false (opcja opt-in).
• Klucze API mają fallback do ELEVENLABS_API_KEY/XI_API_KEY oraz OPENAI_API_KEY.
• openai.baseUrl nadpisuje endpoint OpenAI TTS. Kolejność rozwiązywania to konfiguracja, potem OPENAI_TTS_BASE_URL, a na końcu https://api.openai.com/v1.
• Gdy openai.baseUrl wskazuje endpoint inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i łagodzi walidację modelu/głosu.

​

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 musi pasować do klucza w talk.providers, gdy skonfigurowano wielu providerów Talk.
• Starsze płaskie klucze Talk (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) służą wyłącznie zgodności i są automatycznie migrowane do talk.providers.<provider>.
• Identyfikatory głosów mają fallback do ELEVENLABS_VOICE_ID lub SAG_VOICE_ID.
• providers.*.apiKey akceptuje zwykłe ciągi tekstowe albo obiekty SecretRef.
• Fallback ELEVENLABS_API_KEY działa tylko wtedy, gdy nie skonfigurowano klucza API Talk.
• providers.*.voiceAliases pozwala dyrektywom Talk używać przyjaznych nazw.
• silenceTimeoutMs kontroluje, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypt. Pozostawienie nieustawionego pola zachowuje domyślne okno pauzy platformy (700 ms na macOS i Android, 900 ms na iOS).

​

Powiązane

• Dokumentacja konfiguracji — wszystkie pozostałe klucze konfiguracji
• Konfiguracja — typowe zadania i szybka konfiguracja
• Przykłady konfiguracji