Dokumentacja referencyjna konfiguracji

Podstawowa dokumentacja konfiguracji dla ~/.openclaw/openclaw.json. Przegląd zorientowany na zadania znajdziesz w Konfiguracja.

Obejmuje główne powierzchnie konfiguracji OpenClaw i odsyła dalej, gdy podsystem ma własną, bardziej szczegółową dokumentację. Katalogi poleceń należące do kanałów i pluginów oraz głębokie ustawienia pamięci/QMD znajdują się na osobnych stronach, a nie na tej.

Źródło prawdy w kodzie:

• openclaw config schema wypisuje aktualny JSON Schema używany do walidacji i Control UI, z metadanymi bundled/plugin/channel scalonymi, gdy są dostępne
• config.schema.lookup zwraca jeden węzeł schematu ograniczony do ścieżki dla narzędzi drill-down
• pnpm config:docs:check / pnpm config:docs:gen walidują bazowy hash dokumentacji konfiguracji względem aktualnej powierzchni schematu

Ścieżka wyszukiwania agenta: użyj akcji narzędzia gateway config.schema.lookup, aby uzyskać dokładną dokumentację i ograniczenia na poziomie pól przed edycjami. Użyj Konfiguracja do wskazówek zorientowanych na zadania, a tej strony do szerszej mapy pól, wartości domyślnych i linków do dokumentacji podsystemów.

Dedykowane, szczegółowe dokumentacje:

• Dokumentacja konfiguracji pamięci dla agents.defaults.memorySearch.*, memory.qmd.*, memory.citations i konfiguracji dreaming w plugins.entries.memory-core.config.dreaming
• Polecenia slash dla aktualnego wbudowanego + bundled katalogu poleceń
• strony właścicielskich kanałów/pluginów dla powierzchni poleceń specyficznych dla kanałów

Format konfiguracji to JSON5 (dozwolone komentarze i końcowe przecinki). Wszystkie pola są opcjonalne - OpenClaw używa bezpiecznych wartości domyślnych, gdy zostaną pominięte.

# Kanały

Klucze konfiguracji poszczególnych kanałów przeniesiono na dedykowaną stronę - zobacz Konfiguracja - kanały dla channels.*, w tym Slack, Discord, Telegram, WhatsApp, Matrix, iMessage oraz innych bundled kanałów (uwierzytelnianie, kontrola dostępu, wiele kont, bramkowanie wzmianek).

# Domyślne ustawienia agenta, multi-agent, sesje i wiadomości

Przeniesiono na dedykowaną stronę - zobacz Konfiguracja - agenci dla:

• agents.defaults.* (workspace, model, thinking, heartbeat, memory, media, skills, sandbox)
• multiAgent.* (routing i powiązania multi-agent)
• session.* (cykl życia sesji, compaction, przycinanie)
• messages.* (dostarczanie wiadomości, TTS, renderowanie markdown)
• talk.* (tryb Talk)
  • talk.speechLocale: opcjonalny identyfikator locale BCP 47 dla rozpoznawania mowy Talk na iOS/macOS
  • talk.silenceTimeoutMs: gdy nieustawione, Talk zachowuje domyślne okno pauzy platformy przed wysłaniem transkrypcji (700 ms on macOS and Android, 900 ms on iOS)

# Narzędzia i niestandardowi dostawcy

Polityka narzędzi, eksperymentalne przełączniki, konfiguracja narzędzi opartych na dostawcach oraz konfiguracja niestandardowego dostawcy / bazowego URL zostały przeniesione na dedykowaną stronę - zobacz Konfiguracja - narzędzia i niestandardowi dostawcy.

# Modele

Definicje dostawców, allowlisty modeli i konfiguracja niestandardowych dostawców znajdują się w Konfiguracja - narzędzia i niestandardowi dostawcy. Korzeń models odpowiada też za globalne zachowanie katalogu modeli.

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

• models.mode: zachowanie katalogu dostawcy (merge lub replace).
• models.providers: mapa niestandardowych dostawców indeksowana identyfikatorem dostawcy.
• models.pricing.enabled: kontroluje uruchamianie w tle cen, które startuje po osiągnięciu przez sidecary i kanały ścieżki gotowości Gateway. Gdy false, Gateway pomija pobieranie katalogów cen OpenRouter i LiteLLM; skonfigurowane wartości models.providers.*.models[].cost nadal działają dla lokalnych szacunków kosztów.

# MCP

Definicje serwerów MCP zarządzane przez OpenClaw znajdują się pod mcp.servers i są używane przez wbudowane Pi oraz inne adaptery runtime. Polecenia openclaw mcp list, show, set i unset zarządzają tym blokiem bez łączenia się z docelowym serwerem podczas edycji konfiguracji.

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

• mcp.servers: nazwane definicje serwerów MCP stdio lub zdalnych dla runtime'ów, które udostępniają skonfigurowane narzędzia MCP. Zdalne wpisy używają transport: "streamable-http" albo transport: "sse"; type: "http" to natywny alias CLI, który openclaw mcp set i openclaw doctor --fix normalizują do kanonicznego pola transport.
• mcp.sessionIdleTtlMs: idle TTL dla runtime'ów MCP bundled o zakresie sesji. Jednorazowe wbudowane uruchomienia żądają sprzątania po zakończeniu uruchomienia; ten TTL jest zabezpieczeniem dla długotrwałych sesji i przyszłych wywołujących.
• Zmiany pod mcp.* stosują się na gorąco przez usunięcie cache'owanych runtime'ów MCP sesji. Następne wykrycie/użycie narzędzia odtwarza je z nowej konfiguracji, więc usunięte wpisy mcp.servers są sprzątane natychmiast zamiast czekać na idle TTL.

Zobacz MCP i Backendy CLI, aby poznać zachowanie runtime.

# Skills

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

• allowBundled: opcjonalna allowlista tylko dla bundled skills (nie wpływa na skills zarządzane/workspace).
• load.extraDirs: dodatkowe współdzielone korzenie skill (najniższy priorytet).
• install.preferBrew: gdy true, preferuje instalatory Homebrew, gdy brew jest dostępny, zanim przejdzie do innych typów instalatorów.
• install.nodeManager: preferencja instalatora node dla specyfikacji metadata.openclaw.install (npm | pnpm | yarn | bun).
• entries.<skillKey>.enabled: false wyłącza skill, nawet jeśli jest bundled/zainstalowany.
• entries.<skillKey>.apiKey: udogodnienie dla skills deklarujących główną zmienną env (jawny string albo obiekt SecretRef).

# Pluginy

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

• Ładowane z ~/.openclaw/extensions, <workspace>/.openclaw/extensions oraz plugins.load.paths.
• Discovery akceptuje natywne pluginy OpenClaw oraz zgodne pakiety Codex i pakiety Claude, w tym pakiety Claude bez manifestu z domyślnym układem.
• Zmiany konfiguracji wymagają restartu Gateway.
• allow: opcjonalna allowlista (ładują się tylko wymienione pluginy). deny ma pierwszeństwo.
• bundledDiscovery: dla nowych konfiguracji domyślnie "allowlist", więc niepusta plugins.allow bramkuje też bundled pluginy dostawców, w tym dostawców runtime web-search. Doctor zapisuje "compat" dla zmigrowanych starszych konfiguracji allowlist, aby zachować istniejące zachowanie bundled dostawców do czasu świadomego włączenia.
• plugins.entries.<id>.apiKey: wygodne pole klucza API na poziomie pluginu (gdy obsługiwane przez plugin).
• plugins.entries.<id>.env: mapa zmiennych env ograniczona do pluginu.
• plugins.entries.<id>.hooks.allowPromptInjection: gdy false, core blokuje before_prompt_build i ignoruje pola modyfikujące prompt ze starszego before_agent_start, zachowując starsze modelOverride i providerOverride. Dotyczy natywnych hooków pluginów oraz obsługiwanych katalogów hooków dostarczanych przez pakiety.
• plugins.entries.<id>.hooks.allowConversationAccess: gdy true, zaufane pluginy spoza bundled mogą czytać surową treść rozmowy z typowanych hooków, takich jak llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize i agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: jawnie zaufaj temu pluginowi, aby mógł żądać nadpisań provider i model dla pojedynczych uruchomień subagentów w tle.
• plugins.entries.<id>.subagent.allowedModels: opcjonalna allowlista kanonicznych celów provider/model dla zaufanych nadpisań subagentów. Używaj "*" tylko wtedy, gdy celowo chcesz zezwolić na dowolny model.
• plugins.entries.<id>.config: obiekt konfiguracji zdefiniowany przez plugin (walidowany przez natywny schemat pluginu OpenClaw, gdy jest dostępny).
• Ustawienia konta/runtime pluginu kanału znajdują się pod channels.<id> i powinny być opisane przez metadane channelConfigs w manifeście właścicielskiego pluginu, a nie przez centralny rejestr opcji OpenClaw.
• plugins.entries.firecrawl.config.webFetch: ustawienia dostawcy web-fetch Firecrawl.
  • apiKey: klucz API Firecrawl (akceptuje SecretRef). Wraca do plugins.entries.firecrawl.config.webSearch.apiKey, starszego tools.web.fetch.firecrawl.apiKey albo zmiennej env FIRECRAWL_API_KEY.
  • baseUrl: bazowy URL API Firecrawl (domyślnie: https://api.firecrawl.dev; nadpisania self-hosted muszą wskazywać prywatne/wewnętrzne endpointy).
  • onlyMainContent: wyodrębnia tylko główną treść ze stron (domyślnie: true).
  • maxAgeMs: maksymalny wiek cache w milisekundach (domyślnie: 172800000 / 2 dni).
  • timeoutSeconds: timeout żądania scrape w sekundach (domyślnie: 60).
• plugins.entries.xai.config.xSearch: ustawienia xAI X Search (wyszukiwanie web Grok).
  • enabled: włącza dostawcę X Search.
  • model: model Grok używany do wyszukiwania (np. "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: ustawienia dreaming pamięci. Zobacz Dreaming, aby poznać fazy i progi.
  • enabled: główny przełącznik dreaming (domyślnie false).
  • frequency: rytm cron dla każdego pełnego przebiegu dreaming ("0 3 * * *" domyślnie).
  • model: opcjonalne nadpisanie modelu subagenta Dream Diary. Wymaga plugins.entries.memory-core.subagent.allowModelOverride: true; połącz z allowedModels, aby ograniczyć cele. Błędy niedostępności modelu są ponawiane raz z domyślnym modelem sesji; błędy zaufania lub allowlisty nie przechodzą po cichu do fallbacku.
  • polityka faz i progi są szczegółami implementacji (nie są kluczami konfiguracji dla użytkownika).
• Pełna konfiguracja pamięci znajduje się w Dokumentacja konfiguracji pamięci:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Włączone pluginy pakietów Claude mogą też dostarczać wbudowane wartości domyślne Pi z settings.json; OpenClaw stosuje je jako oczyszczone ustawienia agenta, a nie jako surowe poprawki konfiguracji OpenClaw.
• plugins.slots.memory: wybiera identyfikator aktywnego pluginu pamięci albo "none", aby wyłączyć pluginy pamięci.
• plugins.slots.contextEngine: wybiera identyfikator aktywnego pluginu silnika kontekstu; domyślnie "legacy", chyba że zainstalujesz i wybierzesz inny silnik.

Zobacz Pluginy.

# Zobowiązania

commitments kontroluje wywnioskowaną pamięć follow-up: OpenClaw może wykrywać check-iny z tur rozmowy i dostarczać je przez uruchomienia heartbeat.

• commitments.enabled: włącza ukryte wyodrębnianie LLM, przechowywanie i dostarczanie heartbeat dla wywnioskowanych zobowiązań follow-up. Domyślnie: false.
• commitments.maxPerDay: maksymalna liczba wywnioskowanych zobowiązań follow-up dostarczanych na sesję agenta w ruchomym dniu. Domyślnie: 3.

Zobacz Wywnioskowane zobowiązania.

# Przeglądarka

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

• evaluateEnabled: false wyłącza act:evaluate i wait --fn.
• tabCleanup odzyskuje śledzone karty głównego agenta po czasie bezczynności albo gdy sesja przekroczy swój limit. Ustaw idleMinutes: 0 lub maxTabsPerSession: 0, aby wyłączyć te poszczególne tryby czyszczenia.
• ssrfPolicy.dangerouslyAllowPrivateNetwork jest wyłączone, gdy nie jest ustawione, więc nawigacja przeglądarki domyślnie pozostaje rygorystyczna.
• Ustaw ssrfPolicy.dangerouslyAllowPrivateNetwork: true tylko wtedy, gdy celowo ufasz nawigacji przeglądarki w sieci prywatnej.
• W trybie rygorystycznym zdalne punkty końcowe profili CDP (profiles.*.cdpUrl) podlegają temu samemu blokowaniu sieci prywatnych podczas sprawdzania osiągalności/wykrywania.
• ssrfPolicy.allowPrivateNetwork pozostaje obsługiwane jako alias zgodności wstecznej.
• W trybie rygorystycznym użyj ssrfPolicy.hostnameAllowlist i ssrfPolicy.allowedHostnames dla jawnych wyjątków.
• Profile zdalne są tylko do podłączania (uruchamianie/zatrzymywanie/resetowanie wyłączone).
• profiles.*.cdpUrl akceptuje http://, https://, ws:// i wss://. Użyj HTTP(S), gdy chcesz, aby OpenClaw wykrył /json/version; użyj WS(S), gdy dostawca podaje bezpośredni adres URL DevTools WebSocket.
• remoteCdpTimeoutMs i remoteCdpHandshakeTimeoutMs dotyczą zdalnej oraz attachOnly osiągalności CDP, a także żądań otwierania kart. Zarządzane profile local loopback zachowują lokalne wartości domyślne CDP.
• Jeśli zewnętrznie zarządzana usługa CDP jest osiągalna przez loopback, ustaw dla tego profilu attachOnly: true; w przeciwnym razie OpenClaw traktuje port loopback jako lokalny zarządzany profil przeglądarki i może zgłaszać błędy własności lokalnego portu.
• Profile existing-session używają Chrome MCP zamiast CDP i mogą podłączać się na wybranym hoście albo przez podłączony węzeł przeglądarki.
• Profile existing-session mogą ustawić userDataDir, aby wskazać konkretny profil przeglądarki opartej na Chromium, takiej jak Brave lub Edge.
• Profile existing-session zachowują obecne limity tras Chrome MCP: działania oparte na migawkach/referencjach zamiast targetowania selektorami CSS, haki przesyłania jednego pliku, brak nadpisań limitu czasu dialogów, brak wait --load networkidle oraz brak responsebody, eksportu PDF, przechwytywania pobrań i działań wsadowych.
• Lokalne zarządzane profile openclaw automatycznie przypisują cdpPort i cdpUrl; ustawiaj cdpUrl jawnie tylko dla zdalnego CDP.
• Lokalne zarządzane profile mogą ustawić executablePath, aby nadpisać globalne browser.executablePath dla tego profilu. Użyj tego, aby uruchomić jeden profil w Chrome, a drugi w Brave.
• Lokalne zarządzane profile używają browser.localLaunchTimeoutMs dla wykrywania HTTP Chrome CDP po starcie procesu oraz browser.localCdpReadyTimeoutMs dla gotowości websocket CDP po uruchomieniu. Zwiększ je na wolniejszych hostach, gdzie Chrome uruchamia się poprawnie, ale kontrole gotowości ścigają się ze startem. Obie wartości muszą być dodatnimi liczbami całkowitymi do 120000 ms; nieprawidłowe wartości konfiguracji są odrzucane.
• Kolejność automatycznego wykrywania: domyślna przeglądarka, jeśli oparta na Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath i browser.profiles.<name>.executablePath akceptują zarówno ~, jak i ~/... jako katalog domowy systemu operacyjnego przed uruchomieniem Chromium. userDataDir per profil w profilach existing-session również rozwija tyldę.
• Usługa sterowania: tylko loopback (port wyprowadzony z gateway.port, domyślnie 18791).
• extraArgs dołącza dodatkowe flagi uruchomieniowe do lokalnego startu Chromium (na przykład --disable-gpu, rozmiar okna lub flagi debugowania).

# UI

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

• seamColor: kolor akcentu dla chromu UI aplikacji natywnej (odcień dymku trybu rozmowy itd.).
• assistant: nadpisanie tożsamości Control UI. W razie braku używana jest tożsamość aktywnego agenta.

# Gateway

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

# Punkty końcowe zgodne z OpenAI

• Chat Completions: domyślnie wyłączone. Włącz przez gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Wzmocnienie wejściowego URL dla Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Puste allowlisty są traktowane jako nieustawione; użyj gateway.http.endpoints.responses.files.allowUrl=false i/lub gateway.http.endpoints.responses.images.allowUrl=false, aby wyłączyć pobieranie URL.
• Opcjonalny nagłówek wzmacniający odpowiedź:
  • gateway.http.securityHeaders.strictTransportSecurity (ustawiaj tylko dla kontrolowanych przez siebie origin HTTPS; zobacz Uwierzytelnianie przez zaufane proxy)

# Izolacja wielu instancji

Uruchom wiele Gateway na jednym hoście z unikalnymi portami i katalogami stanu:

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

Wygodne flagi: --dev (używa ~/.openclaw-dev + portu 19001), --profile <name> (używa ~/.openclaw-<name>).

Zobacz Wiele Gateway.

# gateway.tls

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

• enabled: włącza terminację TLS na listenerze Gateway (HTTPS/WSS) (domyślnie: false).
• autoGenerate: automatycznie generuje lokalną parę samopodpisanego certyfikatu/klucza, gdy jawne pliki nie są skonfigurowane; tylko do użytku lokalnego/dev.
• certPath: ścieżka w systemie plików do pliku certyfikatu TLS.
• keyPath: ścieżka w systemie plików do pliku klucza prywatnego TLS; utrzymuj ograniczone uprawnienia.
• caPath: opcjonalna ścieżka pakietu CA do weryfikacji klienta lub niestandardowych łańcuchów zaufania.

# gateway.reload

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

• mode: kontroluje sposób stosowania edycji konfiguracji w czasie działania.
  • "off": ignoruj edycje na żywo; zmiany wymagają jawnego restartu.
  • "restart": zawsze restartuj proces Gateway po zmianie konfiguracji.
  • "hot": stosuj zmiany w procesie bez restartu.
  • "hybrid" (domyślnie): najpierw spróbuj hot reload; w razie potrzeby wróć do restartu.
• debounceMs: okno debounce w ms przed zastosowaniem zmian konfiguracji (nieujemna liczba całkowita).
• deferralTimeoutMs: opcjonalny maksymalny czas w ms oczekiwania na trwające operacje przed wymuszeniem restartu. Pomiń, aby użyć domyślnego ograniczonego oczekiwania (300000); ustaw 0, aby czekać bezterminowo i okresowo logować ostrzeżenia o nadal oczekujących operacjach.

# Hooki

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

Uwierzytelnianie: Authorization: Bearer <token> albo x-openclaw-token: <token>. Tokeny hooków w ciągu zapytania są odrzucane.

Uwagi dotyczące walidacji i bezpieczeństwa:

• hooks.enabled=true wymaga niepustego hooks.token.
• hooks.token musi być różny od gateway.auth.token; ponowne użycie tokena Gateway jest odrzucane.
• hooks.path nie może być /; użyj dedykowanej ścieżki podrzędnej, takiej jak /hooks.
• Jeśli hooks.allowRequestSessionKey=true, ogranicz hooks.allowedSessionKeyPrefixes (na przykład ["hook:"]).
• Jeśli mapowanie lub preset używa szablonowego sessionKey, ustaw hooks.allowedSessionKeyPrefixes i hooks.allowRequestSessionKey=true. Statyczne klucze mapowania nie wymagają tej zgody.

Punkty końcowe:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • sessionKey z treści żądania jest akceptowany tylko wtedy, gdy hooks.allowRequestSessionKey=true (domyślnie: false).
• POST /hooks/<name> → rozwiązywane przez hooks.mappings
  • Wartości sessionKey mapowania renderowane z szablonu są traktowane jako dostarczone zewnętrznie i również wymagają hooks.allowRequestSessionKey=true.

# Integracja Gmail

• Wbudowany preset Gmail używa sessionKey: "hook:gmail:{{messages[0].id}}".
• Jeśli zachowujesz to kierowanie per wiadomość, ustaw hooks.allowRequestSessionKey: true i ogranicz hooks.allowedSessionKeyPrefixes, aby pasowało do przestrzeni nazw Gmail, na przykład ["hook:", "hook:gmail:"].
• Jeśli potrzebujesz hooks.allowRequestSessionKey: false, nadpisz preset statycznym sessionKey zamiast domyślnej wartości szablonowej.

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

• Gateway automatycznie uruchamia gog gmail watch serve przy starcie, gdy jest skonfigurowany. Ustaw OPENCLAW_SKIP_GMAIL_WATCHER=1, aby wyłączyć.
• Nie uruchamiaj osobnego gog gmail watch serve obok Gateway.

# Host kanwy

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

• Udostępnia edytowalne przez agenta HTML/CSS/JS oraz A2UI przez HTTP pod portem Gateway:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Tylko lokalnie: pozostaw gateway.bind: "loopback" (domyślnie).
• Powiązania inne niż loopback: trasy kanwy wymagają uwierzytelnienia Gateway (token/hasło/zaufany serwer proxy), tak samo jak inne powierzchnie HTTP Gateway.
• Widoki WebView Node zwykle nie wysyłają nagłówków uwierzytelniania; po sparowaniu i połączeniu węzła Gateway ogłasza adresy URL możliwości zakresowane do węzła dla dostępu do kanwy/A2UI.
• Adresy URL możliwości są powiązane z aktywną sesją WS węzła i szybko wygasają. Rezerwowy mechanizm oparty na adresie IP nie jest używany.
• Wstrzykuje klienta przeładowania na żywo do udostępnianego HTML.
• Automatycznie tworzy startowy index.html, gdy katalog jest pusty.
• Udostępnia także A2UI pod /__openclaw__/a2ui/.
• Zmiany wymagają restartu Gateway.
• Wyłącz przeładowanie na żywo dla dużych katalogów lub błędów EMFILE.

# Wykrywanie

# mDNS (Bonjour)

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

• minimal (domyślnie, gdy dołączony Plugin bonjour jest włączony): pomija cliPath + sshPort z rekordów TXT.
• full: uwzględnia cliPath + sshPort; ogłaszanie multicastowe w sieci LAN nadal wymaga włączenia dołączonego Plugin bonjour.
• off: wyłącza ogłaszanie multicastowe w sieci LAN bez zmiany włączenia Plugin.
• Dołączony Plugin bonjour uruchamia się automatycznie na hostach macOS i jest opcjonalny na Linux, Windows oraz w konteneryzowanych wdrożeniach Gateway.
• Nazwa hosta domyślnie przyjmuje systemową nazwę hosta, gdy jest poprawną etykietą DNS, w przeciwnym razie wraca do openclaw. Nadpisz za pomocą OPENCLAW_MDNS_HOSTNAME.

# Szeroki obszar (DNS-SD)

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

Zapisuje strefę unicast DNS-SD w ~/.openclaw/dns/. Do wykrywania między sieciami połącz z serwerem DNS (zalecany CoreDNS) + Tailscale split DNS.

Konfiguracja: openclaw dns setup --apply.

# Środowisko

# env (wbudowane zmienne środowiskowe)

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

• Wbudowane zmienne środowiskowe są stosowane tylko wtedy, gdy w środowisku procesu brakuje danego klucza.
• Pliki .env: .env z CWD + ~/.openclaw/.env (żaden z nich nie nadpisuje istniejących zmiennych).
• shellEnv: importuje brakujące oczekiwane klucze z profilu logowania powłoki.
• Pełną kolejność pierwszeństwa znajdziesz w sekcji Środowisko.

# Podstawianie zmiennych środowiskowych

Odwołuj się do zmiennych środowiskowych w dowolnym ciągu konfiguracji za pomocą ${VAR_NAME}:

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

• Dopasowywane są tylko nazwy pisane wielkimi literami: [A-Z_][A-Z0-9_]*.
• Brakujące lub puste zmienne powodują błąd podczas ładowania konfiguracji.
• Użyj $${VAR}, aby zapisać literalne ${VAR}.
• Działa z $include.

# Sekrety

Odwołania do sekretów są addytywne: wartości w postaci tekstu jawnego nadal działają.

# SecretRef

Użyj jednego kształtu obiektu:

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

Walidacja:

• Wzorzec provider: ^[a-z][a-z0-9_-]{0,63}$
• Wzorzec identyfikatora source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• Identyfikator source: "file": bezwzględny wskaźnik JSON (na przykład "/providers/openai/apiKey")
• Wzorzec identyfikatora source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• Identyfikatory source: "exec" nie mogą zawierać segmentów ścieżki rozdzielanych ukośnikami . ani .. (na przykład a/../b jest odrzucane)

# Obsługiwany zakres poświadczeń

• Kanoniczna macierz: Zakres poświadczeń SecretRef
• secrets apply obsługuje docelowe ścieżki poświadczeń w openclaw.json.
• Odwołania w auth-profiles.json są uwzględniane w rozwiązywaniu w czasie działania i zakresie audytu.

# Konfiguracja dostawców sekretów

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

Uwagi:

• Dostawca file obsługuje mode: "json" i mode: "singleValue" (id musi mieć wartość "value" w trybie singleValue).
• Ścieżki dostawców file i exec kończą się bezpieczną odmową, gdy weryfikacja ACL systemu Windows jest niedostępna. Ustaw allowInsecurePath: true tylko dla zaufanych ścieżek, których nie można zweryfikować.
• Dostawca exec wymaga bezwzględnej ścieżki command i używa ładunków protokołu na stdin/stdout.
• Domyślnie ścieżki poleceń będące dowiązaniami symbolicznymi są odrzucane. Ustaw allowSymlinkCommand: true, aby zezwolić na ścieżki dowiązań symbolicznych przy jednoczesnym walidowaniu rozpoznanej ścieżki docelowej.
• Jeśli skonfigurowano trustedDirs, kontrola zaufanego katalogu jest stosowana do rozpoznanej ścieżki docelowej.
• Środowisko procesu potomnego exec jest domyślnie minimalne; jawnie przekaż wymagane zmienne za pomocą passEnv.
• Odwołania do sekretów są rozwiązywane podczas aktywacji do migawki w pamięci, a następnie ścieżki żądań odczytują wyłącznie tę migawkę.
• Filtrowanie aktywnego zakresu jest stosowane podczas aktywacji: nierozwiązane odwołania włączonych zakresów powodują niepowodzenie uruchomienia lub ponownego załadowania, a nieaktywne zakresy są pomijane z diagnostyką.

# Przechowywanie danych uwierzytelniania

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

• Profile poszczególnych agentów są przechowywane w <agentDir>/auth-profiles.json.
• auth-profiles.json obsługuje odwołania na poziomie wartości (keyRef dla api_key, tokenRef dla token) w statycznych trybach poświadczeń.
• Starsze płaskie mapy auth-profiles.json, takie jak { "provider": { "apiKey": "..." } }, nie są formatem czasu działania; openclaw doctor --fix przepisuje je do kanonicznych profili klucza API provider:default z kopią zapasową .legacy-flat.*.bak.
• Profile trybu OAuth (auth.profiles.<id>.mode = "oauth") nie obsługują poświadczeń profilu uwierzytelniania opartych na SecretRef.
• Statyczne poświadczenia czasu działania pochodzą z rozwiązanych migawek w pamięci; starsze statyczne wpisy auth.json są czyszczone po wykryciu.
• Starsze importy OAuth pochodzą z ~/.openclaw/credentials/oauth.json.
• Zobacz OAuth.
• Zachowanie sekretów w czasie działania oraz narzędzia audit/configure/apply: Zarządzanie sekretami.

# auth.cooldowns

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

• billingBackoffHours: bazowe opóźnienie ponawiania w godzinach, gdy profil zawiedzie z powodu rzeczywistych błędów rozliczeń/niewystarczających środków (domyślnie: 5). Jawny tekst dotyczący rozliczeń może nadal trafić tutaj nawet w odpowiedziach 401/403, ale dopasowania tekstu specyficzne dla dostawcy pozostają ograniczone do dostawcy, który je posiada (na przykład OpenRouter Key limit exceeded). Możliwe do ponowienia komunikaty HTTP 402 dotyczące okna użycia lub limitu wydatków organizacji/przestrzeni roboczej pozostają zamiast tego w ścieżce rate_limit.
• billingBackoffHoursByProvider: opcjonalne nadpisania godzin opóźnienia ponawiania rozliczeń dla poszczególnych dostawców.
• billingMaxHours: limit w godzinach dla wykładniczego wzrostu opóźnienia ponawiania rozliczeń (domyślnie: 24).
• authPermanentBackoffMinutes: bazowe opóźnienie ponawiania w minutach dla wysoce pewnych awarii auth_permanent (domyślnie: 10).
• authPermanentMaxMinutes: limit w minutach dla wzrostu opóźnienia ponawiania auth_permanent (domyślnie: 60).
• failureWindowHours: kroczące okno w godzinach używane dla liczników opóźnienia ponawiania (domyślnie: 24).
• overloadedProfileRotations: maksymalna liczba rotacji profili uwierzytelniania tego samego dostawcy dla błędów przeciążenia przed przełączeniem na rezerwowy model (domyślnie: 1). Kształty zajętości dostawcy, takie jak ModelNotReadyException, trafiają tutaj.
• overloadedBackoffMs: stałe opóźnienie przed ponowną próbą rotacji przeciążonego dostawcy/profilu (domyślnie: 0).
• rateLimitedProfileRotations: maksymalna liczba rotacji profili uwierzytelniania tego samego dostawcy dla błędów limitu szybkości przed przełączeniem na rezerwowy model (domyślnie: 1). Ten koszyk limitu szybkości obejmuje tekst o kształcie dostawcy, taki jak Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded i resource exhausted.

# Rejestrowanie

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

• Domyślny plik dziennika: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Ustaw logging.file, aby użyć stabilnej ścieżki.
• consoleLevel wzrasta do debug, gdy użyto --verbose.
• maxFileBytes: maksymalny rozmiar aktywnego pliku dziennika w bajtach przed rotacją (dodatnia liczba całkowita; domyślnie: 104857600 = 100 MB). OpenClaw zachowuje do pięciu numerowanych archiwów obok aktywnego pliku.
• redactSensitive / redactPatterns: najlepsze możliwe maskowanie danych dla wyjścia konsoli, dzienników plikowych, rekordów dziennika OTLP i utrwalonego tekstu transkrypcji sesji. redactSensitive: "off" wyłącza tylko tę ogólną zasadę dla dzienników/transkrypcji; powierzchnie bezpieczeństwa UI/narzędzi/diagnostyki nadal redagują sekrety przed emisją.

# Diagnostyka

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

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

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

• enabled: główny przełącznik wyjścia instrumentacji (domyślnie: true).
• flags: tablica ciągów flag włączających ukierunkowane wyjście dziennika (obsługuje symbole wieloznaczne, takie jak "telegram.*" lub "*").
• stuckSessionWarnMs: próg wieku bez postępu w ms do klasyfikowania długo działających sesji przetwarzania jako session.long_running, session.stalled lub session.stuck. Odpowiedź, narzędzie, status, blok i postęp ACP resetują licznik czasu; powtarzane diagnostyki session.stuck wycofują się, gdy nic się nie zmieniło.
• stuckSessionAbortMs: próg wieku bez postępu w ms, po którym kwalifikująca się zablokowana aktywna praca może zostać przerwana i opróżniona w celu odzyskania. Gdy nie ustawiono, OpenClaw używa bezpieczniejszego rozszerzonego okna uruchomienia osadzonego wynoszącego co najmniej 10 minut i 5x stuckSessionWarnMs.
• otel.enabled: włącza potok eksportu OpenTelemetry (domyślnie: false). Pełną konfigurację, katalog sygnałów i model prywatności znajdziesz w Eksport OpenTelemetry.
• otel.endpoint: adres URL kolektora dla eksportu OTel.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: opcjonalne punkty końcowe OTLP specyficzne dla sygnału. Po ustawieniu zastępują otel.endpoint tylko dla tego sygnału.
• otel.protocol: "http/protobuf" (domyślnie) lub "grpc".
• otel.headers: dodatkowe nagłówki metadanych HTTP/gRPC wysyłane z żądaniami eksportu OTel.
• otel.serviceName: nazwa usługi dla atrybutów zasobu.
• otel.traces / otel.metrics / otel.logs: włącza eksport śladów, metryk lub dzienników.
• otel.sampleRate: współczynnik próbkowania śladów 0-1.
• otel.flushIntervalMs: okresowy interwał opróżniania telemetrii w ms.
• otel.captureContent: dobrowolne przechwytywanie surowej treści dla atrybutów zakresu OTEL. Domyślnie wyłączone. Wartość logiczna true przechwytuje niesystemową treść wiadomości/narzędzi; forma obiektowa pozwala jawnie włączyć inputMessages, outputMessages, toolInputs, toolOutputs i systemPrompt.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: przełącznik środowiskowy dla najnowszych eksperymentalnych atrybutów dostawcy zakresów GenAI. Domyślnie zakresy zachowują starszy atrybut gen_ai.system dla zgodności; metryki GenAI używają ograniczonych atrybutów semantycznych.
• OPENCLAW_OTEL_PRELOADED=1: przełącznik środowiskowy dla hostów, które już zarejestrowały globalny SDK OpenTelemetry. OpenClaw pomija wtedy uruchamianie/zamykanie SDK należącego do Plugin, zachowując aktywne nasłuchiwanie diagnostyczne.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT i OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: zmienne środowiskowe punktów końcowych specyficznych dla sygnału używane, gdy pasujący klucz konfiguracji nie jest ustawiony.
• cacheTrace.enabled: zapisuj migawki śladu pamięci podręcznej dla uruchomień osadzonych (domyślnie: false).
• cacheTrace.filePath: ścieżka wyjściowa dla JSONL śladu pamięci podręcznej (domyślnie: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: kontrolują, co jest uwzględniane w wyjściu śladu pamięci podręcznej (wszystkie domyślnie: true).

# Aktualizacja

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

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

• channel: kanał wydania dla instalacji npm/git - "stable", "beta" lub "dev".
• checkOnStart: sprawdzaj aktualizacje npm przy starcie gateway (domyślnie: true).
• auto.enabled: włącz automatyczną aktualizację w tle dla instalacji pakietowych (domyślnie: false).
• auto.stableDelayHours: minimalne opóźnienie w godzinach przed automatycznym zastosowaniem w kanale stabilnym (domyślnie: 6; maks.: 168).
• auto.stableJitterHours: dodatkowe okno rozłożenia wdrożenia kanału stabilnego w godzinach (domyślnie: 12; maks.: 168).
• auto.betaCheckIntervalHours: jak często uruchamiane są sprawdzenia kanału beta, w godzinach (domyślnie: 1; maks.: 24).

# ACP

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

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

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

• enabled: globalna brama funkcji ACP (domyślnie: true; ustaw false, aby ukryć wysyłkę ACP i opcje tworzenia).
• dispatch.enabled: niezależna brama wysyłania tur sesji ACP (domyślnie: true). Ustaw false, aby pozostawić polecenia ACP dostępne, blokując wykonanie.
• backend: domyślny identyfikator backendu środowiska uruchomieniowego ACP (musi pasować do zarejestrowanego Plugin środowiska uruchomieniowego ACP). Najpierw zainstaluj Plugin backendu, a jeśli ustawiono plugins.allow, uwzględnij identyfikator Plugin backendu (na przykład acpx), inaczej backend ACP się nie załaduje.
• defaultAgent: zastępczy identyfikator docelowego agenta ACP, gdy tworzenia nie określają jawnego celu.
• allowedAgents: lista dozwolonych identyfikatorów agentów dopuszczonych do sesji środowiska uruchomieniowego ACP; pusta oznacza brak dodatkowego ograniczenia.
• maxConcurrentSessions: maksymalna liczba jednocześnie aktywnych sesji ACP.
• stream.coalesceIdleMs: okno opróżniania bezczynności w ms dla strumieniowanego tekstu.
• stream.maxChunkChars: maksymalny rozmiar fragmentu przed podziałem projekcji strumieniowanego bloku.
• stream.repeatSuppression: pomijaj powtarzane linie statusu/narzędzi na turę (domyślnie: true).
• stream.deliveryMode: "live" strumieniuje przyrostowo; "final_only" buforuje do terminalnych zdarzeń tury.
• stream.hiddenBoundarySeparator: separator przed widocznym tekstem po ukrytych zdarzeniach narzędzi (domyślnie: "paragraph").
• stream.maxOutputChars: maksymalna liczba znaków wyjścia asystenta projektowanych na turę ACP.
• stream.maxSessionUpdateChars: maksymalna liczba znaków dla projektowanych linii statusu/aktualizacji ACP.
• stream.tagVisibility: rekord nazw tagów na logiczne nadpisania widoczności dla zdarzeń strumieniowanych.
• runtime.ttlMinutes: TTL bezczynności w minutach dla pracowników sesji ACP przed kwalifikacją do czyszczenia.
• runtime.installCommand: opcjonalne polecenie instalacji uruchamiane podczas przygotowywania środowiska uruchomieniowego ACP.

# CLI

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

• cli.banner.taglineMode kontroluje styl sloganu banera:
  • "random" (domyślnie): rotujące zabawne/sezonowe slogany.
  • "default": stały neutralny slogan (All your chats, one OpenClaw.).
  • "off": brak tekstu sloganu (tytuł/wersja banera nadal są pokazywane).
• Aby ukryć cały baner (nie tylko slogany), ustaw zmienną środowiskową OPENCLAW_HIDE_BANNER=1.

# Kreator

Metadane zapisywane przez przepływy konfiguracji prowadzone przez CLI (onboard, configure, doctor):

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

# Tożsamość

Zobacz pola tożsamości agents.list w sekcji Domyślne ustawienia agentów.

# Most (starszy, usunięty)

Obecne kompilacje nie zawierają już mostu TCP. Węzły łączą się przez WebSocket Gateway. Klucze bridge.* nie są już częścią schematu konfiguracji (walidacja kończy się niepowodzeniem do czasu ich usunięcia; openclaw doctor --fix może usunąć nieznane klucze).

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

# Cron

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

• sessionRetention: jak długo przechowywać ukończone izolowane sesje uruchomień Cron przed usunięciem z sessions.json. Kontroluje też czyszczenie zarchiwizowanych transkrypcji usuniętych zadań Cron. Domyślnie: 24h; ustaw false, aby wyłączyć.
• runLog.maxBytes: maksymalny rozmiar pojedynczego pliku dziennika uruchomień (cron/runs/<jobId>.jsonl) przed przycinaniem. Domyślnie: 2_000_000 bajtów.
• runLog.keepLines: najnowsze wiersze zachowywane po wyzwoleniu przycinania dziennika uruchomień. Domyślnie: 2000.
• webhookToken: token bearer używany do dostarczania POST przez Webhook Cron (delivery.mode = "webhook"); jeśli zostanie pominięty, nagłówek uwierzytelniania nie jest wysyłany.
• webhook: przestarzały starszy awaryjny adres URL Webhook (http/https), używany tylko dla zapisanych zadań, które nadal mają notify: true.

# cron.retry

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

• maxAttempts: maksymalna liczba ponowień dla zadań jednorazowych przy błędach przejściowych (domyślnie: 3; zakres: 0-10).
• backoffMs: tablica opóźnień wycofywania w ms dla każdej próby ponowienia (domyślnie: [30000, 60000, 300000]; 1-10 wpisów).
• retryOn: typy błędów wyzwalające ponowienia - "rate_limit", "overloaded", "network", "timeout", "server_error". Pomiń, aby ponawiać wszystkie typy przejściowe.

Dotyczy tylko jednorazowych zadań Cron. Zadania cykliczne używają osobnej obsługi niepowodzeń.

# cron.failureAlert

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

• enabled: włącza alerty o niepowodzeniach dla zadań Cron (domyślnie: false).
• after: liczba kolejnych niepowodzeń przed wysłaniem alertu (dodatnia liczba całkowita, min: 1).
• cooldownMs: minimalna liczba milisekund między powtarzanymi alertami dla tego samego zadania (nieujemna liczba całkowita).
• includeSkipped: zliczanie kolejnych pominiętych uruchomień do progu alertu (domyślnie: false). Pominięte uruchomienia są śledzone osobno i nie wpływają na wycofywanie po błędzie wykonania.
• mode: tryb dostarczania - "announce" wysyła przez wiadomość kanału; "webhook" publikuje do skonfigurowanego Webhook.
• accountId: opcjonalne konto lub identyfikator kanału do ograniczenia zakresu dostarczania alertów.

# cron.failureDestination

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

• Domyślny cel powiadomień o niepowodzeniach Cron dla wszystkich zadań.
• mode: "announce" lub "webhook"; domyślnie "announce", gdy istnieje wystarczająco dużo danych celu.
• channel: nadpisanie kanału dla dostarczania announce. "last" ponownie używa ostatniego znanego kanału dostarczania.
• to: jawny cel announce lub adres URL Webhook. Wymagane dla trybu Webhook.
• accountId: opcjonalne nadpisanie konta dla dostarczania.
• delivery.failureDestination dla pojedynczego zadania nadpisuje tę globalną wartość domyślną.
• Gdy nie ustawiono ani globalnego, ani przypisanego do zadania celu niepowodzenia, zadania, które już dostarczają przez announce, w razie niepowodzenia wracają do tego głównego celu announce.
• delivery.failureDestination jest obsługiwane tylko dla zadań sessionTarget="isolated", chyba że główne delivery.mode zadania to "webhook".

Zobacz Zadania Cron. Izolowane wykonania Cron są śledzone jako zadania w tle.

# Zmienne szablonu modelu multimediów

Symbole zastępcze szablonu rozwijane w tools.media.models[].args:

# Dołączanie konfiguracji ($include)

Podziel konfigurację na wiele plików:

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

Zachowanie scalania:

• Pojedynczy plik: zastępuje zawierający go obiekt.
• Tablica plików: głęboko scalana w kolejności (późniejsze nadpisują wcześniejsze).
• Klucze równorzędne: scalane po dołączeniach (nadpisują dołączone wartości).
• Zagnieżdżone dołączenia: do 10 poziomów głębokości.
• Ścieżki: rozwiązywane względem pliku dołączającego, ale muszą pozostać w katalogu konfiguracji najwyższego poziomu (dirname pliku openclaw.json). Formy bezwzględne/../ są dozwolone tylko wtedy, gdy nadal rozwiązują się wewnątrz tej granicy.
• Zapisy należące do OpenClaw, które zmieniają tylko jedną sekcję najwyższego poziomu obsługiwaną przez dołączenie pojedynczego pliku, zapisują bezpośrednio do tego dołączonego pliku. Na przykład plugins install aktualizuje plugins: { $include: "./plugins.json5" } w plugins.json5 i pozostawia openclaw.json bez zmian.
• Dołączenia katalogu głównego, tablice dołączeń i dołączenia z nadpisaniami przez klucze równorzędne są tylko do odczytu dla zapisów należących do OpenClaw; takie zapisy kończą się niepowodzeniem zamiast spłaszczać konfigurację.
• Błędy: jasne komunikaty dla brakujących plików, błędów parsowania i cyklicznych dołączeń.

Powiązane: Konfiguracja · Przykłady konfiguracji · Doctor

# Powiązane

• Konfiguracja
• Przykłady konfiguracji