Przejdź do głównej treści

​
Konfiguracja

OpenClaw odczytuje opcjonalną konfigurację z pliku ~/.openclaw/openclaw.json. Jeśli plik nie istnieje, OpenClaw używa bezpiecznych ustawień domyślnych. Typowe powody dodania konfiguracji:
  • Podłączenie kanałów i określenie, kto może wysyłać wiadomości do bota
  • Ustawienie modeli, narzędzi, sandboxingu lub automatyzacji (cron, hooki)
  • Dostosowanie sesji, multimediów, sieci lub interfejsu użytkownika
Zobacz pełną dokumentację referencyjną, aby poznać wszystkie dostępne pola.
Dopiero zaczynasz z konfiguracją? Zacznij od openclaw onboard, aby przejść przez interaktywną konfigurację, albo zajrzyj do przewodnika Przykłady konfiguracji, aby zobaczyć kompletne konfiguracje do skopiowania i wklejenia.

​
Minimalna konfiguracja

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

​
Edytowanie konfiguracji

openclaw onboard       # pełny proces wdrożenia
openclaw configure     # kreator konfiguracji

​
Ścisła walidacja

OpenClaw akceptuje tylko konfiguracje, które w pełni odpowiadają schematowi. Nieznane klucze, nieprawidłowe typy lub niepoprawne wartości powodują, że Gateway odmawia uruchomienia. Jedynym wyjątkiem na poziomie głównym jest $schema (string), dzięki czemu edytory mogą dołączać metadane JSON Schema.
Uwagi dotyczące narzędzi schematu:
  • openclaw config schema wypisuje tę samą rodzinę JSON Schema, której używają Control UI i walidacja konfiguracji.
  • Traktuj wynik tego schematu jako kanoniczny kontrakt w formacie czytelnym maszynowo dla pliku openclaw.json; ten przegląd i dokumentacja referencyjna konfiguracji go podsumowują.
  • Wartości pól title i description są przenoszone do wyjścia schematu na potrzeby edytorów i narzędzi formularzy.
  • Wpisy zagnieżdżonych obiektów, wieloznaczników (*) i elementów tablic ([]) dziedziczą te same metadane dokumentacyjne tam, gdzie istnieje pasująca dokumentacja pól.
  • Gałęzie kompozycji anyOf / oneOf / allOf również dziedziczą te same metadane dokumentacyjne, dzięki czemu warianty unii/przecięcia zachowują tę samą pomoc dla pól.
  • config.schema.lookup zwraca jedną znormalizowaną ścieżkę konfiguracji z płytkim węzłem schematu (title, description, type, enum, const, wspólne ograniczenia i podobne pola walidacji), dopasowanymi metadanymi wskazówek UI oraz podsumowaniami bezpośrednich elementów podrzędnych dla narzędzi szczegółowego przechodzenia.
  • Schematy pluginów/kanałów w czasie działania są scalane, gdy gateway może załadować bieżący rejestr manifestów.
  • pnpm config:docs:check wykrywa rozbieżności między artefaktami bazowymi konfiguracji używanymi w dokumentacji a bieżącą powierzchnią schematu.
Gdy walidacja się nie powiedzie:
  • Gateway się nie uruchamia
  • Działają tylko polecenia diagnostyczne (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Uruchom openclaw doctor, aby zobaczyć dokładne problemy
  • Uruchom openclaw doctor --fix (lub --yes), aby zastosować poprawki

​
Typowe zadania

Każdy kanał ma własną sekcję konfiguracji w channels.<provider>. Zobacz dedykowaną stronę kanału, aby poznać kroki konfiguracji:Wszystkie kanały współdzielą ten sam wzorzec zasad dla wiadomości DM:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // tylko dla allowlist/open
    },
  },
}
Ustaw model podstawowy i opcjonalne modele zapasowe:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models definiuje katalog modeli i działa jako lista dozwolonych dla /model.
  • Referencje modeli używają formatu provider/model (np. anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx kontroluje skalowanie obrazów w transkryptach/narzędziach (domyślnie 1200); niższe wartości zwykle zmniejszają zużycie tokenów vision przy zadaniach z dużą liczbą zrzutów ekranu.
  • Zobacz Models CLI, aby przełączać modele na czacie, oraz Przełączanie awaryjne modeli, aby poznać rotację uwierzytelniania i zachowanie modeli zapasowych.
  • W przypadku niestandardowych/samodzielnie hostowanych providerów zobacz Niestandardowi providerzy w dokumentacji referencyjnej.
Dostęp do wiadomości DM jest kontrolowany osobno dla każdego kanału przez dmPolicy:
  • "pairing" (domyślnie): nieznani nadawcy otrzymują jednorazowy kod parowania do zatwierdzenia
  • "allowlist": tylko nadawcy z allowFrom (lub sparowanego magazynu listy dozwolonych)
  • "open": zezwalaj na wszystkie przychodzące wiadomości DM (wymaga allowFrom: ["*"])
  • "disabled": ignoruj wszystkie wiadomości DM
W przypadku grup użyj groupPolicy + groupAllowFrom lub list dozwolonych specyficznych dla kanału.Zobacz pełną dokumentację referencyjną, aby poznać szczegóły dla poszczególnych kanałów.
Domyślnie wiadomości grupowe wymagają wzmianki. Skonfiguruj wzorce dla każdego agenta:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Wzmianki w metadanych: natywne wzmianki @ (WhatsApp tap-to-mention, Telegram @bot itp.)
  • Wzorce tekstowe: bezpieczne wzorce regex w mentionPatterns
  • Zobacz pełną dokumentację referencyjną, aby poznać zastąpienia dla poszczególnych kanałów i tryb self-chat.
Użyj agents.defaults.skills jako współdzielonej bazy, a następnie zastąp ustawienia konkretnych agentów za pomocą agents.list[].skills:
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // dziedziczy github, weather
      { id: "docs", skills: ["docs-search"] }, // zastępuje ustawienia domyślne
      { id: "locked-down", skills: [] }, // brak Skills
    ],
  },
}
Kontroluj, jak agresywnie gateway restartuje kanały, które wyglądają na nieaktywne:
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • Ustaw gateway.channelHealthCheckMinutes: 0, aby globalnie wyłączyć restarty monitora kondycji.
  • channelStaleEventThresholdMinutes powinno być większe lub równe interwałowi sprawdzania.
  • Użyj channels.<provider>.healthMonitor.enabled lub channels.<provider>.accounts.<id>.healthMonitor.enabled, aby wyłączyć automatyczne restarty dla jednego kanału lub konta bez wyłączania monitora globalnego.
  • Zobacz Kontrole kondycji, aby poznać operacyjne debugowanie, oraz pełną dokumentację referencyjną, aby zobaczyć wszystkie pola.
Sesje kontrolują ciągłość i izolację rozmów:
{
  session: {
    dmScope: "per-channel-peer",  // zalecane dla wielu użytkowników
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (wspólna) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: globalne ustawienia domyślne routingu sesji powiązanych z wątkiem (Discord obsługuje /focus, /unfocus, /agents, /session idle i /session max-age).
  • Zobacz Zarządzanie sesjami, aby poznać zakresy, powiązania tożsamości i zasady wysyłania.
  • Zobacz pełną dokumentację referencyjną, aby zobaczyć wszystkie pola.
Uruchamiaj sesje agentów w izolowanych kontenerach Docker:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Najpierw zbuduj obraz: scripts/sandbox-setup.shZobacz Sandboxing, aby przeczytać pełny przewodnik, oraz pełną dokumentację referencyjną, aby poznać wszystkie opcje.
Push oparty na relay konfiguruje się w openclaw.json.Ustaw to w konfiguracji gateway:
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Opcjonalne. Domyślnie: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
Odpowiednik w CLI:
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
Co to robi:
  • Umożliwia gateway wysyłanie push.test, sygnałów wybudzania i wybudzeń przy ponownym połączeniu przez zewnętrzny relay.
  • Używa uprawnienia wysyłki ograniczonego do rejestracji, przekazanego dalej przez sparowaną aplikację iOS. Gateway nie potrzebuje tokena relay dla całego wdrożenia.
  • Wiąże każdą rejestrację opartą na relay z tożsamością gateway, z którą sparowano aplikację iOS, dzięki czemu inny gateway nie może ponownie użyć zapisanej rejestracji.
  • Pozostawia lokalne/ręczne kompilacje iOS przy bezpośrednim APNs. Wysyłki oparte na relay dotyczą tylko oficjalnie dystrybuowanych kompilacji, które zarejestrowały się przez relay.
  • Musi odpowiadać bazowemu URL relay osadzonemu w oficjalnej/wersji TestFlight kompilacji iOS, aby ruch rejestracji i wysyłki trafiał do tego samego wdrożenia relay.
Przepływ end-to-end:
  1. Zainstaluj oficjalną/wersję TestFlight aplikacji iOS skompilowaną z tym samym bazowym URL relay.
  2. Skonfiguruj gateway.push.apns.relay.baseUrl w gateway.
  3. Sparuj aplikację iOS z gateway i pozwól połączyć się zarówno sesjom węzła, jak i operatora.
  4. Aplikacja iOS pobiera tożsamość gateway, rejestruje się w relay przy użyciu App Attest oraz potwierdzenia odbioru aplikacji, a następnie publikuje ładunek push.apns.register oparty na relay do sparowanego gateway.
  5. Gateway zapisuje uchwyt relay i uprawnienie wysyłki, a następnie używa ich do push.test, sygnałów wybudzania i wybudzeń przy ponownym połączeniu.
Uwagi operacyjne:
  • Jeśli przełączysz aplikację iOS na inny gateway, połącz ponownie aplikację, aby mogła opublikować nową rejestrację relay powiązaną z tym gateway.
  • Jeśli wydasz nową kompilację iOS wskazującą inne wdrożenie relay, aplikacja odświeży zapisaną w pamięci podręcznej rejestrację relay zamiast ponownie używać starego źródła relay.
Uwaga dotycząca zgodności:
  • OPENCLAW_APNS_RELAY_BASE_URL i OPENCLAW_APNS_RELAY_TIMEOUT_MS nadal działają jako tymczasowe nadpisania przez zmienne środowiskowe.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true pozostaje wyłącznie pętlą zwrotną dla środowiska programistycznego; nie utrwalaj adresów URL relay HTTP w konfiguracji.
Zobacz Aplikacja iOS, aby poznać przepływ end-to-end, oraz Przepływ uwierzytelniania i zaufania, aby zrozumieć model bezpieczeństwa relay.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: ciąg czasu trwania (30m, 2h). Ustaw 0m, aby wyłączyć.
  • target: last | none | <channel-id> (na przykład discord, matrix, telegram lub whatsapp)
  • directPolicy: allow (domyślnie) lub block dla celów heartbeat w stylu DM
  • Zobacz Heartbeat, aby przeczytać pełny przewodnik.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: usuwaj ukończone izolowane sesje uruchomień z sessions.json (domyślnie 24h; ustaw false, aby wyłączyć).
  • runLog: przycinaj cron/runs/<jobId>.jsonl według rozmiaru i liczby zachowanych linii.
  • Zobacz Zadania cron, aby poznać przegląd funkcji i przykłady CLI.
Włącz punkty końcowe webhooków HTTP w Gateway:
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
Uwaga dotycząca bezpieczeństwa:
  • Traktuj całą zawartość ładunków hooków/webhooków jako niezaufane dane wejściowe.
  • Używaj dedykowanego hooks.token; nie używaj ponownie współdzielonego tokena Gateway.
  • Uwierzytelnianie hooków działa tylko przez nagłówki (Authorization: Bearer ... lub x-openclaw-token); tokeny w ciągu zapytania są odrzucane.
  • hooks.path nie może być /; trzymaj ruch przychodzący webhooków na dedykowanej podścieżce, takiej jak /hooks.
  • Pozostaw flagi obejścia niebezpiecznej zawartości wyłączone (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), chyba że prowadzisz ściśle ograniczone debugowanie.
  • Jeśli włączysz hooks.allowRequestSessionKey, ustaw także hooks.allowedSessionKeyPrefixes, aby ograniczyć klucze sesji wybierane przez wywołującego.
  • W przypadku agentów sterowanych przez hooki preferuj mocne nowoczesne klasy modeli oraz ścisłe zasady dotyczące narzędzi (na przykład tylko wiadomości plus sandboxing, gdzie to możliwe).
Zobacz pełną dokumentację referencyjną, aby poznać wszystkie opcje mapowania i integrację z Gmail.
Uruchamiaj wielu izolowanych agentów z oddzielnymi obszarami roboczymi i sesjami:
{
  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" } },
  ],
}
Zobacz Multi-Agent oraz pełną dokumentację referencyjną, aby poznać reguły powiązań i profile dostępu dla poszczególnych agentów.
Użyj $include, aby uporządkować duże konfiguracje:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • Pojedynczy plik: zastępuje obiekt zawierający
  • Tablica plików: scalana głęboko w kolejności (późniejsze wygrywają)
  • Klucze równorzędne: scalane po include’ach (nadpisują dołączone wartości)
  • Zagnieżdżone include’y: obsługiwane do 10 poziomów głębokości
  • Ścieżki względne: rozwiązywane względem pliku dołączającego
  • Obsługa błędów: czytelne błędy dla brakujących plików, błędów parsowania i cyklicznych include’ów

​
Hot reload konfiguracji

Gateway obserwuje ~/.openclaw/openclaw.json i automatycznie stosuje zmiany — dla większości ustawień nie jest wymagany ręczny restart.

​
Tryby przeładowania

TrybZachowanie
hybrid (domyślnie)Natychmiast stosuje bezpieczne zmiany na gorąco. W przypadku krytycznych zmian automatycznie restartuje.
hotStosuje na gorąco tylko bezpieczne zmiany. Gdy wymagany jest restart, zapisuje ostrzeżenie w logach — zajmujesz się tym ręcznie.
restartRestartuje Gateway przy każdej zmianie konfiguracji, bezpiecznej lub nie.
offWyłącza obserwowanie pliku. Zmiany zaczną obowiązywać przy następnym ręcznym restarcie.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Co stosuje się na gorąco, a co wymaga restartu

Większość pól stosuje się na gorąco bez przestoju. W trybie hybrid zmiany wymagające restartu są obsługiwane automatycznie.
KategoriaPolaWymagany restart?
Kanałychannels.*, web (WhatsApp) — wszystkie wbudowane i rozszerzeniowe kanałyNie
Agent i modeleagent, agents, models, routingNie
Automatyzacjahooks, cron, agent.heartbeatNie
Sesje i wiadomościsession, messagesNie
Narzędzia i multimediatools, browser, skills, audio, talkNie
UI i inneui, logging, identity, bindingsNie
Serwer gatewaygateway.* (port, bind, auth, tailscale, TLS, HTTP)Tak
Infrastrukturadiscovery, canvasHost, pluginsTak
gateway.reload i gateway.remote są wyjątkami — ich zmiana nie powoduje restartu.

​
RPC konfiguracji (aktualizacje programistyczne)

Operacje zapisu RPC płaszczyzny sterowania (config.apply, config.patch, update.run) są ograniczane do 3 żądań na 60 sekund dla każdego deviceId+clientIp. Po osiągnięciu limitu RPC zwraca UNAVAILABLE z retryAfterMs.
Bezpieczny/domyślny przepływ:
  • config.schema.lookup: sprawdź jedno poddrzewo konfiguracji ograniczone do ścieżki z płytkim węzłem schematu, dopasowanymi metadanymi wskazówek i podsumowaniami bezpośrednich elementów podrzędnych
  • config.get: pobierz bieżący snapshot + hash
  • config.patch: preferowana ścieżka częściowej aktualizacji
  • config.apply: tylko pełne zastąpienie konfiguracji
  • update.run: jawna samodzielna aktualizacja + restart
Jeśli nie zastępujesz całej konfiguracji, preferuj config.schema.lookup, a następnie config.patch.
Waliduje + zapisuje pełną konfigurację i restartuje Gateway w jednym kroku.
config.apply zastępuje całą konfigurację. Użyj config.patch do częściowych aktualizacji albo openclaw config set dla pojedynczych kluczy.
Parametry:
  • raw (string) — ładunek JSON5 dla całej konfiguracji
  • baseHash (opcjonalnie) — hash konfiguracji z config.get (wymagany, gdy konfiguracja istnieje)
  • sessionKey (opcjonalnie) — klucz sesji dla sygnału wybudzenia po restarcie
  • note (opcjonalnie) — notatka dla znacznika restartu
  • restartDelayMs (opcjonalnie) — opóźnienie przed restartem (domyślnie 2000)
Żądania restartu są łączone, gdy jedno jest już oczekujące/w toku, a między cyklami restartu obowiązuje 30-sekundowy czas odnowienia.
openclaw gateway call config.get --params '{}'  # przechwyć payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
Scala częściową aktualizację z istniejącą konfiguracją (semantyka JSON merge patch):
  • Obiekty są scalane rekurencyjnie
  • null usuwa klucz
  • Tablice są zastępowane
Parametry:
  • raw (string) — JSON5 zawierający tylko klucze do zmiany
  • baseHash (wymagany) — hash konfiguracji z config.get
  • sessionKey, note, restartDelayMs — takie same jak w config.apply
Zachowanie restartu odpowiada config.apply: oczekujące restarty są łączone, a między cyklami restartu obowiązuje 30-sekundowy czas odnowienia.
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

​
Zmienne środowiskowe

OpenClaw odczytuje zmienne środowiskowe z procesu nadrzędnego oraz z:
  • .env z bieżącego katalogu roboczego (jeśli istnieje)
  • ~/.openclaw/.env (globalne ustawienie zapasowe)
Żaden z tych plików nie nadpisuje istniejących zmiennych środowiskowych. Możesz także ustawić w konfiguracji wbudowane zmienne środowiskowe: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Jeśli ta funkcja jest włączona, a oczekiwane klucze nie są ustawione, OpenClaw uruchamia twoją powłokę logowania i importuje tylko brakujące klucze:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Odpowiednik jako zmienna środowiskowa: OPENCLAW_LOAD_SHELL_ENV=1
Odwołuj się do zmiennych środowiskowych w dowolnej wartości tekstowej konfiguracji za pomocą ${VAR_NAME}:
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
Zasady:
  • Dopasowywane są tylko nazwy pisane wielkimi literami: [A-Z_][A-Z0-9_]*
  • Brakujące/puste zmienne powodują błąd podczas wczytywania
  • Użyj $${VAR}, aby uzyskać dosłowne wyjście
  • Działa także w plikach $include
  • Podstawianie w treści: "${BASE}/v1" → "https://api.example.com/v1"
Dla pól obsługujących obiekty SecretRef możesz użyć:
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
Szczegóły SecretRef (w tym secrets.providers dla env/file/exec) znajdziesz w Zarządzanie sekretami. Obsługiwane ścieżki poświadczeń są wymienione w Powierzchnia poświadczeń SecretRef.
Zobacz Środowisko, aby poznać pełną kolejność pierwszeństwa i źródła.

​
Pełna dokumentacja referencyjna

Aby zobaczyć kompletną dokumentację referencyjną wszystkich pól, przejdź do Dokumentacja referencyjna konfiguracji.
Powiązane: Przykłady konfiguracji · Dokumentacja referencyjna konfiguracji · Doctor