Konfiguracja — agenci

​

Domyślne ustawienia 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" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Pomiń agents.defaults.skills, aby domyślnie zezwolić na nieograniczone Skills.
• Pomiń agents.list[].skills, aby odziedziczyć wartości domyślne.
• Ustaw agents.list[].skills: [], aby nie używać Skills.
• Niepusta lista agents.list[].skills jest ostatecznym zestawem dla danego agenta; nie jest scalana z wartościami domyślnymi.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": bezpieczne tury kontynuacji (po ukończonej odpowiedzi asystenta) pomijają ponowne wstrzyknięcie inicjalizacji obszaru roboczego, zmniejszając rozmiar promptu. Uruchomienia Heartbeat i ponowienia po Compaction nadal odbudowują kontekst.
• "never": wyłącza wstrzykiwanie inicjalizacji obszaru roboczego i plików kontekstu w każdej turze. Używaj tego tylko dla agentów, którzy w pełni zarządzają cyklem życia własnego promptu (niestandardowe silniki kontekstu, natywne środowiska uruchomieniowe budujące własny kontekst lub wyspecjalizowane przepływy pracy bez inicjalizacji). Tury Heartbeat i odzyskiwania po Compaction również pomijają wstrzykiwanie.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

Nadpisania profilu inicjalizacji dla agenta

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": nigdy nie wstrzykuj tekstu powiadomienia o obcięciu do promptu systemowego.
• "once": wstrzyknij zwięzłe powiadomienie raz dla każdej unikalnej sygnatury obcięcia.
• "always": wstrzykuj zwięzłe powiadomienie przy każdym uruchomieniu, gdy występuje obcięcie (zalecane).

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

​

Mapa właścicielstwa budżetów kontekstu

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: zwykłe wstrzykiwanie inicjalizacji obszaru roboczego.
• agents.defaults.startupContext.*: jednorazowy wstęp uruchomienia modelu po resecie/starcie, w tym ostatnie codzienne pliki memory/*.md. Surowe polecenia czatu /new i /reset są potwierdzane bez wywoływania modelu.
• skills.limits.*: zwarta lista Skills wstrzykiwana do promptu systemowego.
• agents.defaults.contextLimits.*: ograniczone wycinki środowiska uruchomieniowego i wstrzykiwane bloki należące do środowiska uruchomieniowego.
• memory.qmd.limits.*: rozmiary fragmentu indeksowanego wyszukiwania pamięci i wstrzyknięcia.

• 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: domyślny limit wycinka memory_get przed dodaniem metadanych obcięcia i powiadomienia o kontynuacji.
• memoryGetDefaultLines: domyślne okno wierszy memory_get, gdy lines jest pominięte.
• toolResultMaxChars: zaawansowany sufit wyników narzędzi na żywo używany dla utrwalonych wyników i odzyskiwania po przepełnieniu. Pozostaw nieustawione, aby użyć automatycznego limitu kontekstu modelu: 16000 znaków poniżej 100 tys. tokenów, 32000 znaków przy 100 tys.+ tokenów i 64000 znaków przy 200 tys.+ tokenów. Jawne wartości do 1000000 są akceptowane dla modeli długiego kontekstu, ale efektywny limit nadal jest ograniczony do około 30% okna kontekstu modelu. openclaw doctor --deep wypisuje efektywny limit, a doctor ostrzega tylko wtedy, gdy jawne nadpisanie jest nieaktualne lub nie ma efektu.
• postCompactionMaxChars: limit wycinka AGENTS.md używany podczas wstrzykiwania odświeżenia po Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // advanced ceiling for this 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: dostosuj do limitów modelu i liczby obrazów.
• efficient: preferuj mniejsze obrazy, aby obniżyć użycie tokenów i bajtów.
• balanced: użyj standardowej drabinki środka.
• high: zachowaj więcej szczegółów dla zrzutów ekranu, diagramów i obrazów dokumentów.

{
  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" }, // global default provider params
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: akceptuje ciąg znaków ("provider/model") albo obiekt ({ primary, fallbacks }).
  • Forma ciągu znaków ustawia tylko model podstawowy.
  • Forma obiektu ustawia model podstawowy oraz uporządkowane modele przełączania awaryjnego.
• imageModel: akceptuje ciąg znaków ("provider/model") albo obiekt ({ primary, fallbacks }).
  • Używany przez ścieżkę narzędzia image jako konfiguracja modelu wizyjnego.
  • Używany także jako routing awaryjny, gdy wybrany/domyślny model nie może przyjmować wejścia obrazowego.
  • Preferuj jawne referencje provider/model. Same identyfikatory są akceptowane dla zgodności; jeśli sam identyfikator jednoznacznie pasuje do skonfigurowanego wpisu obsługującego obrazy w models.providers.*.models, OpenClaw kwalifikuje go do tego dostawcy. Niejednoznaczne skonfigurowane dopasowania wymagają jawnego prefiksu dostawcy.
• imageGenerationModel: akceptuje ciąg znaków ("provider/model") albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną zdolność generowania obrazów oraz każdą przyszłą powierzchnię narzędzia/Plugin, która generuje obrazy.
  • Typowe wartości: google/gemini-3.1-flash-image-preview dla natywnego generowania obrazów Gemini, fal/fal-ai/flux/dev dla fal, openai/gpt-image-2 dla OpenAI Images albo openai/gpt-image-1.5 dla wyjścia PNG/WebP OpenAI z przezroczystym tłem.
  • Jeśli wybierasz dostawcę/model bezpośrednio, skonfiguruj także pasujące uwierzytelnienie dostawcy (na przykład GEMINI_API_KEY albo GOOGLE_API_KEY dla google/*, OPENAI_API_KEY albo OpenAI Codex OAuth dla openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY dla fal/*).
  • Jeśli pominięto, image_generate nadal może wywnioskować domyślnego dostawcę z uwierzytelnieniem. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania obrazów w kolejności identyfikatorów dostawcy.
• musicGenerationModel: akceptuje ciąg znaków ("provider/model") albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną zdolność 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.6.
  • Jeśli pominięto, music_generate nadal może wywnioskować domyślnego dostawcę z uwierzytelnieniem. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania muzyki w kolejności identyfikatorów dostawcy.
  • Jeśli wybierasz dostawcę/model bezpośrednio, skonfiguruj także pasujące uwierzytelnienie/klucz API dostawcy.
• videoGenerationModel: akceptuje ciąg znaków ("provider/model") albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną zdolność 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 pominięto, video_generate nadal może wywnioskować domyślnego dostawcę z uwierzytelnieniem. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania wideo w kolejności identyfikatorów dostawcy.
  • Jeśli wybierasz dostawcę/model bezpośrednio, skonfiguruj także pasujące uwierzytelnienie/klucz API dostawcy.
  • Oficjalny Plugin generowania wideo Qwen obsługuje do 1 wyjściowego wideo, 1 obrazu wejściowego, 4 wejściowych wideo, 10 sekund czasu trwania oraz opcje na poziomie dostawcy: size, aspectRatio, resolution, audio i watermark.
• pdfModel: akceptuje ciąg znaków ("provider/model") albo obiekt ({ primary, fallbacks }).
  • Używany przez narzędzie pdf do routingu modelu.
  • Jeśli pominięto, narzędzie PDF cofa się do imageModel, a następnie do rozwiązanego modelu sesji/domyślnego.
• pdfMaxBytesMb: domyślny limit rozmiaru PDF dla narzędzia pdf, gdy maxBytesMb nie zostanie przekazane w czasie wywołania.
• pdfMaxPages: domyślna maksymalna liczba stron branych pod uwagę przez tryb awaryjnego wyodrębniania w narzędziu pdf.
• verboseDefault: domyślny poziom szczegółowości dla agentów. Wartości: "off", "on", "full". Domyślnie: "off".
• toolProgressDetail: tryb szczegółowości dla podsumowań narzędzi /verbose i wierszy wersji roboczych postępu narzędzi. Wartości: "explain" (domyślna, zwięzłe etykiety czytelne dla człowieka) albo "raw" (dołącza surowe polecenie/szczegóły, gdy są dostępne). agents.list[].toolProgressDetail dla agenta zastępuje tę wartość domyślną.
• reasoningDefault: domyślna widoczność rozumowania dla agentów. Wartości: "off", "on", "stream". agents.list[].reasoningDefault dla agenta zastępuje tę wartość domyślną. Skonfigurowane domyślne ustawienia rozumowania są stosowane tylko dla właścicieli, autoryzowanych nadawców albo kontekstów Gateway administratora-operatora, gdy nie ustawiono nadpisania rozumowania dla wiadomości ani sesji.
• elevatedDefault: domyślny poziom podwyższonego wyjścia dla agentów. Wartości: "off", "on", "ask", "full". Domyślnie: "on".
• model.primary: format provider/model (np. openai/gpt-5.5 dla dostępu przez klucz API OpenAI albo Codex OAuth). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania skonfigurowanego dostawcy dla dokładnie tego identyfikatora modelu, a dopiero potem cofa się do skonfigurowanego domyślnego dostawcy (przestarzałe zachowanie zgodności, więc preferuj jawne provider/model). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw cofa się do pierwszego skonfigurowanego dostawcy/modelu zamiast ujawniać nieaktualną wartość domyślną usuniętego dostawcy.
• models: skonfigurowany katalog modeli i lista dozwolonych dla /model. Każdy wpis może zawierać alias (skrót) i params (specyficzne dla dostawcy, na przykład temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, routing provider OpenRouter, chat_template_kwargs, extra_body/extraBody).
  • Użyj wpisów provider/*, takich jak "openai/*": {} albo "vllm/*": {}, aby pokazać wszystkie odkryte modele dla wybranych dostawców bez ręcznego wypisywania każdego identyfikatora modelu.
  • Dodaj agentRuntime do wpisu provider/*, gdy każdy dynamicznie odkryty model dla tego dostawcy powinien używać tego samego środowiska uruchomieniowego. Dokładna polityka środowiska uruchomieniowego provider/model nadal ma pierwszeństwo przed wieloznacznikiem.
  • Bezpieczne edycje: użyj openclaw config set agents.defaults.models '<json>' --strict-json --merge, aby dodać wpisy. config set odrzuca zastąpienia, które usunęłyby istniejące wpisy listy dozwolonych, chyba że przekażesz --replace.
  • Przepływy konfiguracji/wdrażania ograniczone do dostawcy scalają wybrane modele dostawcy z tą mapą i zachowują niepowiązanych dostawców, którzy są już skonfigurowani.
  • Dla bezpośrednich modeli OpenAI Responses Compaction po stronie serwera jest włączana automatycznie. Użyj params.responsesServerCompaction: false, aby przestać wstrzykiwać context_management, albo params.responsesCompactThreshold, aby nadpisać próg. Zobacz Compaction po stronie serwera OpenAI.
• params: globalne domyślne parametry dostawcy stosowane do wszystkich modeli. Ustawiane w agents.defaults.params (np. { cacheRetention: "long" }).
• Kolejność pierwszeństwa scalania params (konfiguracja): agents.defaults.params (globalna baza) jest zastępowane przez agents.defaults.models["provider/model"].params (dla modelu), a następnie agents.list[].params (pasujący identyfikator agenta) zastępuje według klucza. Szczegóły w Prompt Caching.
• models.providers.openrouter.params.provider: domyślna polityka routingu dostawców dla całego OpenRouter. OpenClaw przekazuje ją do obiektu provider żądania OpenRouter; agents.defaults.models["openrouter/<model>"].params.provider dla modelu oraz parametry agenta zastępują według klucza. Zobacz routing dostawców OpenRouter.
• params.extra_body/params.extraBody: zaawansowany przepuszczany JSON scalany z treściami żądań api: "openai-completions" dla proxy zgodnych z OpenAI. Jeśli koliduje z wygenerowanymi kluczami żądania, dodatkowa treść wygrywa; nienatywne trasy completions nadal później usuwają właściwe tylko dla OpenAI store.
• params.chat_template_kwargs: argumenty szablonu czatu zgodne z vLLM/OpenAI scalane z treściami żądań najwyższego poziomu api: "openai-completions". Dla vllm/nemotron-3-* przy wyłączonym myśleniu dołączony Plugin vLLM automatycznie wysyła enable_thinking: false i force_nonempty_content: true; jawne chat_template_kwargs zastępują wygenerowane wartości domyślne, a extra_body.chat_template_kwargs nadal ma ostateczne pierwszeństwo. Skonfigurowane modele myślące vLLM Qwen i Nemotron udostępniają binarne wybory /think (off, on) zamiast wielopoziomowej drabiny wysiłku.
• compat.thinkingFormat: styl ładunku myślenia zgodny z OpenAI. Użyj "together" dla stylu Together reasoning.enabled, "qwen" dla stylu Qwen najwyższego poziomu enable_thinking albo "qwen-chat-template" dla chat_template_kwargs.enable_thinking w backendach z rodziny Qwen, które obsługują kwargs szablonu czatu na poziomie żądania, takich jak vLLM. OpenClaw mapuje wyłączone myślenie na false, a włączone myślenie na true, a skonfigurowane modele vLLM Qwen udostępniają binarne wybory /think dla tych formatów.
• compat.supportedReasoningEfforts: lista poziomów wysiłku rozumowania zgodna z OpenAI dla modelu. Uwzględnij "xhigh" dla niestandardowych punktów końcowych, które naprawdę go akceptują; wtedy OpenClaw udostępnia /think xhigh w menu poleceń, wierszach sesji Gateway, walidacji poprawek sesji, walidacji CLI agenta i walidacji llm-task dla tego skonfigurowanego dostawcy/modelu. Użyj compat.reasoningEffortMap, gdy backend oczekuje wartości specyficznej dla dostawcy dla kanonicznego poziomu.
• params.preserveThinking: opcjonalne włączenie zachowanego myślenia tylko dla Z.AI. Gdy jest włączone i myślenie jest włączone, OpenClaw wysyła thinking.clear_thinking: false i odtwarza wcześniejsze reasoning_content; zobacz myślenie Z.AI i zachowane myślenie.
• localService: opcjonalny menedżer procesów na poziomie dostawcy dla lokalnych/samodzielnie hostowanych serwerów modeli. Gdy wybrany model należy do tego dostawcy, OpenClaw sonduje healthUrl (albo baseUrl + "/models"), uruchamia command z args, jeśli punkt końcowy nie działa, czeka do readyTimeoutMs, a następnie wysyła żądanie modelu. command musi być ścieżką bezwzględną. idleStopMs: 0 utrzymuje proces przy życiu do wyjścia OpenClaw; wartość dodatnia zatrzymuje proces uruchomiony przez OpenClaw po tylu milisekundach bezczynności. Zobacz lokalne usługi modeli.
• Polityka środowiska uruchomieniowego należy do dostawców albo modeli, nie do agents.defaults. Użyj models.providers.<provider>.agentRuntime dla reguł obejmujących dostawcę albo agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime dla reguł specyficznych dla modelu. Modele agentów OpenAI u oficjalnego dostawcy OpenAI domyślnie wybierają Codex.
• Pisarze konfiguracji, którzy mutują te pola (na przykład /models set, /models set-image i polecenia dodawania/usuwania rozwiązań awaryjnych), zapisują kanoniczną formę obiektu i zachowują istniejące listy awaryjne, gdy to możliwe.
• maxConcurrent: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4.

​

Polityka środowiska uruchomieniowego

{
  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", zarejestrowany identyfikator harnessu pluginu albo obsługiwany alias backendu CLI. Dołączony Plugin Codex rejestruje codex; dołączony Plugin Anthropic udostępnia backend CLI claude-cli.
• id: "auto" pozwala zarejestrowanym harnessom pluginów przejmować obsługiwane tury i używa OpenClaw, gdy żaden harness nie pasuje. Jawne środowisko uruchomieniowe pluginu, takie jak id: "codex", wymaga tego harnessu i kończy się błędem w trybie zamkniętym, jeśli jest niedostępny lub zawiedzie.
• id: "pi" jest akceptowane tylko jako przestarzały alias openclaw, aby zachować dostarczone konfiguracje z v2026.5.22 i wcześniejszych. Nowa konfiguracja powinna używać openclaw.
• Kolejność pierwszeństwa środowiska uruchomieniowego to najpierw dokładna polityka modelu (agents.list[].models["provider/model"], agents.defaults.models["provider/model"] albo models.providers.<provider>.models[]), potem agents.list[] / agents.defaults.models["provider/*"], a następnie polityka całego dostawcy w models.providers.<provider>.agentRuntime.
• Klucze środowiska uruchomieniowego całego agenta są przestarzałe. agents.defaults.agentRuntime, agents.list[].agentRuntime, przypięcia środowiska sesji i OPENCLAW_AGENT_RUNTIME są ignorowane przy wyborze środowiska uruchomieniowego. Uruchom openclaw doctor --fix, aby usunąć nieaktualne wartości.
• Modele agentów OpenAI domyślnie używają harnessu Codex; provider/model agentRuntime.id: "codex" pozostaje prawidłowe, gdy chcesz wskazać to jawnie.
• Dla wdrożeń Claude CLI preferuj model: "anthropic/claude-opus-4-8" oraz model-scoped agentRuntime.id: "claude-cli". Starsze odwołania do modeli claude-cli/claude-opus-4-7 nadal działają dla zgodności, ale nowa konfiguracja powinna utrzymywać kanoniczny wybór provider/model i umieszczać backend wykonawczy w polityce środowiska uruchomieniowego provider/model.
• To steruje tylko wykonywaniem tekstowych tur agenta. Generowanie mediów, wizja, PDF, muzyka, wideo i TTS nadal używają swoich ustawień provider/model.

​

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

• Backendy CLI są przede wszystkim tekstowe; 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.
• reseedFromRawTranscriptWhenUncompacted: true pozwala backendowi odzyskać bezpieczne unieważnione sesje z ograniczonego ogona surowej transkrypcji OpenClaw, zanim powstanie pierwsze podsumowanie Compaction. Zmiany profilu uwierzytelniania lub epoki poświadczeń nadal nigdy nie wykonują raw-reseed.

​

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 przyjazną warstwę; oznaczony kontrakt zachowania GPT-5 pozostaje włączony.
• Starsze plugins.entries.openai.config.personality jest nadal odczytywane, gdy to wspólne ustawienie nie jest ustawione.

​

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: ciąg czasu trwania (ms/s/m/h). Domyślnie: 30m (uwierzytelnianie kluczem API) albo 1h (uwierzytelnianie OAuth). Ustaw na 0m, aby wyłączyć.
• includeSystemPromptSection: gdy false, pomija sekcję Heartbeat w prompcie systemowym i pomija wstrzykiwanie HEARTBEAT.md do kontekstu bootstrap. Domyślnie: true.
• suppressToolErrorWarnings: gdy true, wycisza ładunki ostrzeżeń o błędach narzędzi podczas uruchomień Heartbeat.
• timeoutSeconds: maksymalny czas w sekundach dozwolony dla tury agenta Heartbeat przed jej przerwaniem. Pozostaw nieustawione, aby użyć agents.defaults.timeoutSeconds, gdy jest ustawione, w przeciwnym razie kadencja Heartbeat ograniczona do 600 sekund.
• directPolicy: polityka dostarczania bezpośredniego/DM. allow (domyślnie) zezwala na dostarczanie do celu bezpośredniego. block wycisza dostarczanie do celu bezpośredniego i emituje reason=dm-blocked.
• lightContext: gdy true, uruchomienia Heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko HEARTBEAT.md z plików bootstrap przestrzeni roboczej.
• isolatedSession: gdy true, każdy Heartbeat działa w świeżej sesji bez wcześniejszej historii konwersacji. Ten sam wzorzec izolacji co Cron sessionTarget: "isolated". Zmniejsza koszt tokenów na Heartbeat z ~100K do ~2-5K tokenów.
• skipWhenBusy: gdy true, uruchomienia Heartbeat są odraczane na dodatkowych zajętych ścieżkach tego agenta: jego własnej ścieżce subagenta kluczowanej sesją albo zagnieżdżonej pracy polecenia. Ścieżki Cron zawsze odraczają Heartbeat, nawet bez tej flagi.
• Per-agent: ustaw agents.list[].heartbeat. Gdy dowolny agent definiuje heartbeat, tylko ci agenci uruchamiają Heartbeat.
• Heartbeat uruchamia pełne tury agenta — krótsze interwały zużywają więcej tokenów.

​

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 lub safeguard (fragmentaryczne podsumowywanie długich historii). Zobacz Compaction.
• provider: identyfikator zarejestrowanego pluginu dostawcy Compaction. Gdy jest ustawiony, wywoływane jest summarize() dostawcy zamiast wbudowanego podsumowywania LLM. W razie niepowodzenia następuje powrót do wbudowanego mechanizmu. Ustawienie dostawcy wymusza mode: "safeguard". Zobacz Compaction.
• timeoutSeconds: maksymalna liczba sekund dozwolona dla pojedynczej operacji Compaction, zanim OpenClaw ją przerwie. Domyślnie: 180.
• keepRecentTokens: budżet punktu odcięcia agenta na zachowanie dosłownego najnowszego końca transkrypcji. Ręczne /compact uwzględnia tę wartość, gdy jest jawnie ustawiona; w przeciwnym razie ręczna Compaction jest twardym punktem kontrolnym.
• identifierPolicy: strict (domyślnie), off lub custom. strict dodaje na początku wbudowane wskazówki dotyczące zachowania nieprzezroczystych identyfikatorów podczas podsumowywania Compaction.
• identifierInstructions: opcjonalny niestandardowy tekst zachowywania identyfikatorów używany, gdy identifierPolicy=custom.
• qualityGuard: kontrole ponawiania przy nieprawidłowo sformatowanym wyniku dla podsumowań safeguard. Domyślnie włączone w trybie safeguard; ustaw enabled: false, aby pominąć audyt.
• midTurnPrecheck: opcjonalna kontrola obciążenia pętli narzędzi. Gdy enabled: true, OpenClaw sprawdza presję kontekstu po dołączeniu wyników narzędzi i przed następnym wywołaniem modelu. Jeśli kontekst już się nie mieści, przerywa bieżącą próbę przed przesłaniem promptu i ponownie używa istniejącej ścieżki odzyskiwania po kontroli wstępnej, aby przyciąć wyniki narzędzi albo wykonać Compaction i spróbować ponownie. Działa z trybami Compaction default i safeguard. Domyślnie: wyłączone.
• postCompactionSections: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po Compaction. Ponowne wstrzykiwanie jest wyłączone, gdy wartość nie jest ustawiona albo jest ustawiona na []. Jawne ustawienie ["Session Startup", "Red Lines"] włącza tę parę i zachowuje starszy fallback Every Session/Safety. Włączaj to tylko wtedy, gdy dodatkowy kontekst jest wart ryzyka zduplikowania wskazówek projektowych już ujętych w podsumowaniu Compaction.
• model: opcjonalne provider/model-id albo czysty alias z agents.defaults.models tylko dla podsumowywania Compaction. Czyste aliasy są rozwiązywane przed wysłaniem; skonfigurowane dosłowne identyfikatory modeli zachowują pierwszeństwo przy kolizjach. Użyj tego, gdy główna sesja ma zachować jeden model, ale podsumowania Compaction mają działać na innym; gdy nie ustawiono, Compaction używa głównego modelu sesji.
• maxActiveTranscriptBytes: opcjonalny próg w bajtach (number albo ciągi takie jak "20mb"), który uruchamia zwykłą lokalną Compaction przed uruchomieniem, gdy aktywny JSONL przekroczy próg. Wymaga truncateAfterCompaction, aby udana Compaction mogła obrócić transkrypcję na mniejszego następcę. Wyłączone, gdy nie ustawiono albo ustawiono 0.
• notifyUser: gdy true, wysyła użytkownikowi krótkie powiadomienia, gdy Compaction się zaczyna i gdy się kończy (na przykład „Kompaktowanie kontekstu…” i „Compaction zakończona”). Domyślnie wyłączone, aby Compaction pozostała cicha.
• memoryFlush: cicha agentowa tura przed automatyczną Compaction do zapisywania trwałych wspomnień. Ustaw model na dokładnego dostawcę/model, takiego jak ollama/qwen3:8b, gdy ta tura porządkowa ma pozostać na modelu lokalnym; nadpisanie nie dziedziczy aktywnego łańcucha fallbacków sesji. Pomijane, gdy obszar roboczy jest tylko do odczytu.

​

agents.defaults.runRetries

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // optional per-agent overrides
      },
    ],
  },
}

• base: bazowa liczba iteracji ponowień uruchomienia dla zewnętrznej pętli uruchomieniowej. Domyślnie: 24.
• perProfile: dodatkowe iteracje ponowień uruchomienia przyznawane każdemu kandydatowi profilu fallback. Domyślnie: 8.
• min: minimalny bezwzględny limit iteracji ponowień uruchomienia. Domyślnie: 32.
• max: maksymalny bezwzględny limit iteracji ponowień uruchomienia, zapobiegający niekontrolowanemu wykonaniu. Domyślnie: 160.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        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"] },
      },
    },
  },
}

​

Strumieniowanie blokowe

{
  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 (use minMs/maxMs)
    },
  },
}

• Kanały inne niż Telegram wymagają jawnego *.blockStreaming: true, aby włączyć odpowiedzi blokowe.
• Nadpisania kanałów: channels.<channel>.blockStreamingCoalesce (oraz warianty dla kont). Signal/Slack/Discord/Google Chat domyślnie używają minChars: 1500.
• humanDelay: losowa pauza między odpowiedziami blokowymi. natural = 800–2500 ms. Nadpisanie dla agenta: 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 czatów grupowych bez wzmianki.
• Nadpisania dla sesji: 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 contents also supported:
          // 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 (nadpisania dla poszczególnych agentów)

{
  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: stabilny identyfikator agenta (wymagany).
• default: gdy ustawiono wiele, wygrywa pierwszy (logowane jest ostrzeżenie). Jeśli nie ustawiono żadnego, domyślny jest pierwszy wpis listy.
• model: forma tekstowa ustawia ścisły model główny dla agenta bez zapasowego modelu; forma obiektowa { primary } również jest ścisła, chyba że dodasz fallbacks. Użyj { primary, fallbacks: [...] }, aby włączyć dla tego agenta przełączanie awaryjne, albo { primary, fallbacks: [] }, aby jawnie wymusić ścisłe zachowanie. Zadania Cron, które nadpisują tylko primary, nadal dziedziczą domyślne modele zapasowe, chyba że ustawisz fallbacks: [].
• params: parametry strumienia dla agenta scalane z wybranym wpisem modelu w agents.defaults.models. Użyj tego dla nadpisań specyficznych dla agenta, takich jak cacheRetention, temperature lub maxTokens, bez duplikowania całego katalogu modeli.
• tts: opcjonalne nadpisania text-to-speech dla agenta. Blok jest głęboko scalany z messages.tts, więc trzymaj współdzielone poświadczenia dostawcy i politykę zapasową w messages.tts, a tutaj ustawiaj tylko wartości specyficzne dla persony, takie jak dostawca, głos, model, styl lub tryb automatyczny.
• skills: opcjonalna lista dozwolonych Skills dla agenta. 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 myślenia dla agenta (off | minimal | low | medium | high | xhigh | adaptive | max). Nadpisuje agents.defaults.thinkingDefault dla tego agenta, gdy nie ustawiono nadpisania dla wiadomości ani sesji. Wybrany profil dostawcy/modelu kontroluje, które wartości są prawidłowe; dla Google Gemini adaptive zachowuje dynamiczne myślenie zarządzane przez dostawcę (thinkingLevel pominięte w Gemini 3/3.1, thinkingBudget: -1 w Gemini 2.5).
• reasoningDefault: opcjonalna domyślna widoczność rozumowania dla agenta (on | off | stream). Nadpisuje agents.defaults.reasoningDefault dla tego agenta, gdy nie ustawiono nadpisania rozumowania dla wiadomości ani sesji.
• fastModeDefault: opcjonalna wartość domyślna trybu szybkiego dla agenta ("auto" | true | false). Stosowana, gdy nie ustawiono nadpisania trybu szybkiego dla wiadomości ani sesji.
• models: opcjonalne nadpisania katalogu modeli/środowiska uruchomieniowego dla agenta, kluczowane pełnymi identyfikatorami provider/model. Użyj models["provider/model"].agentRuntime dla wyjątków środowiska uruchomieniowego danego agenta.
• runtime: opcjonalny deskryptor środowiska uruchomieniowego dla agenta. Użyj type: "acp" z wartościami domyślnymi runtime.acp (agent, backend, mode, cwd), gdy agent ma domyślnie używać sesji uprzęży ACP.
• identity.avatar: ścieżka względna wobec obszaru roboczego, URL http(s) lub URI data:.
• Lokalne pliki obrazów identity.avatar ze ścieżką względną wobec obszaru roboczego są ograniczone do 2 MB. URL-e http(s) i URI data: nie są sprawdzane lokalnym limitem rozmiaru pliku.
• identity wyprowadza wartości domyślne: ackReaction z emoji, mentionPatterns z name/emoji.
• subagents.allowAgents: lista dozwolonych skonfigurowanych identyfikatorów agentów dla jawnych celów sessions_spawn.agentId (["*"] = dowolny skonfigurowany cel; domyślnie: tylko ten sam agent). Uwzględnij identyfikator żądającego, gdy wywołania agentId celujące w samego siebie mają być dozwolone. Nieaktualne wpisy, których konfiguracja agenta została usunięta, są odrzucane przez sessions_spawn i pomijane w agents_list; uruchom openclaw doctor --fix, aby je wyczyścić, albo dodaj minimalny wpis agents.list[], jeśli ten cel ma pozostać możliwy do uruchomienia przy dziedziczeniu wartości domyślnych.
• Ochrona dziedziczenia piaskownicy: jeśli sesja żądającego działa w piaskownicy, sessions_spawn odrzuca cele, które działałyby bez piaskownicy.
• subagents.requireAgentId: gdy true, blokuje wywołania sessions_spawn, które pomijają agentId (wymusza jawny wybór profilu; domyślnie: false).

​

Routing wieloagentowy

{
  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ązania

• type (opcjonalne): route dla normalnego routingu (brak typu domyślnie oznacza route), acp dla trwałych powiązań konwersacji ACP.
• match.channel (wymagane)
• match.accountId (opcjonalne; * = dowolne konto; pominięte = konto domyślne)
• match.peer (opcjonalne; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opcjonalne; specyficzne dla kanału)
• acp (opcjonalne; 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: "*" (w całym kanale)
6. Agent domyślny

​

Profile dostępu dla poszczególnych agentów

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

​

Wiadomości

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

​

Prefiks odpowiedzi

​

Reakcja potwierdzenia

• Domyślnie używa identity.emoji aktywnego agenta, w przeciwnym razie "👀". Ustaw "", aby wyłączyć.
• Nadpisania według kanału: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Kolejność rozstrzygania: konto → kanał → messages.ackReaction → awaryjna wartość tożsamości.
• Zakres: group-mentions (domyślnie), group-all, direct, all.
• removeAckAfterReply: usuwa potwierdzenie po odpowiedzi w kanałach obsługujących reakcje, takich jak Slack, Discord, Signal, Telegram, WhatsApp i iMessage.
• messages.statusReactions.enabled: włącza reakcje statusu cyklu życia w Slack, Discord, Signal, Telegram i WhatsApp. W Slack i Discord brak ustawienia pozostawia reakcje statusu włączone, gdy reakcje potwierdzenia są aktywne. W Signal, Telegram i WhatsApp ustaw jawnie na true, aby włączyć reakcje statusu cyklu życia.
• messages.statusReactions.emojis: nadpisuje klucze emoji cyklu życia: queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft i stallHard. Telegram zezwala tylko na stały zestaw reakcji, więc nieobsługiwane skonfigurowane emoji wracają do najbliższego obsługiwanego wariantu statusu dla danego czatu.

​

Debounce przychodzących wiadomości

​

TTS (tekst na mowę)

{
  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 kontroluje domyślny tryb automatycznego TTS: off, always, inbound lub tagged. /tts on|off może nadpisać lokalne preferencje, a /tts status pokazuje stan efektywny.
• summaryModel zastępuje agents.defaults.model.primary dla automatycznego podsumowania.
• modelOverrides jest domyślnie włączone; modelOverrides.allowProvider ma domyślną wartość false (wymaga włączenia).
• Klucze API korzystają awaryjnie z ELEVENLABS_API_KEY/XI_API_KEY oraz OPENAI_API_KEY.
• Dołączone dostawcy mowy są własnością pluginów. Jeśli ustawiono plugins.allow, uwzględnij każdy plugin dostawcy TTS, którego chcesz używać, na przykład microsoft dla Edge TTS. Starszy identyfikator dostawcy edge jest akceptowany jako alias dla microsoft.
• providers.openai.baseUrl zastępuje punkt końcowy OpenAI TTS. Kolejność rozwiązywania to konfiguracja, następnie OPENAI_TTS_BASE_URL, a następnie https://api.openai.com/v1.
• Gdy providers.openai.baseUrl wskazuje punkt końcowy inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i rozluźnia walidację modelu/głosu.

​

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 musi pasować do klucza w talk.providers, gdy skonfigurowano wielu dostawców Talk.
• Starsze płaskie klucze Talk (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) służą wyłącznie do zgodności. Uruchom openclaw doctor --fix, aby przepisać utrwaloną konfigurację do talk.providers.<provider>.
• Identyfikatory głosów korzystają awaryjnie z ELEVENLABS_VOICE_ID lub SAG_VOICE_ID.
• providers.*.apiKey przyjmuje ciągi tekstowe jawnym tekstem lub obiekty SecretRef.
• Awaryjne użycie ELEVENLABS_API_KEY ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk.
• providers.*.voiceAliases pozwala dyrektywom Talk używać przyjaznych nazw.
• providers.mlx.modelId wybiera repozytorium Hugging Face używane przez lokalnego pomocnika MLX na macOS. Jeśli zostanie pominięte, macOS używa mlx-community/Soprano-80M-bf16.
• Odtwarzanie MLX na macOS działa przez dołączonego pomocnika openclaw-mlx-tts, gdy jest obecny, albo przez plik wykonywalny w PATH; OPENCLAW_MLX_TTS_BIN zastępuje ścieżkę pomocnika podczas programowania.
• consultThinkingLevel kontroluje poziom myślenia dla pełnego uruchomienia agenta OpenClaw stojącego za wywołaniami Control UI Talk realtime openclaw_agent_consult. Pozostaw nieustawione, aby zachować normalne zachowanie sesji/modelu.
• consultFastMode ustawia jednorazowe nadpisanie trybu szybkiego dla konsultacji Control UI Talk realtime bez zmiany normalnego ustawienia trybu szybkiego sesji.
• speechLocale ustawia identyfikator lokalizacji BCP 47 używany przez rozpoznawanie mowy Talk w iOS/macOS. Pozostaw nieustawione, aby użyć domyślnego ustawienia urządzenia.
• silenceTimeoutMs kontroluje, jak długo tryb Talk czeka po ciszy użytkownika, zanim wyśle transkrypcję. Brak ustawienia zachowuje domyślne okno pauzy platformy (700 ms on macOS and Android, 900 ms on iOS).
• realtime.instructions dołącza skierowane do dostawcy instrukcje systemowe do wbudowanego promptu realtime OpenClaw, dzięki czemu styl głosu można skonfigurować bez utraty domyślnych wskazówek openclaw_agent_consult.
• realtime.consultRouting kontroluje awaryjne przekazywanie Gateway, gdy dostawca realtime tworzy finalną transkrypcję użytkownika bez openclaw_agent_consult: provider-direct zachowuje bezpośrednie odpowiedzi dostawcy, a force-agent-consult kieruje sfinalizowane żądanie przez OpenClaw.

​

Powiązane

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