Przejdź do głównej treści

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw odczytuje opcjonalną konfigurację z ~/.openclaw/openclaw.json. Aktywna ścieżka konfiguracji musi być zwykłym plikiem. Układy z dowiązaniem symbolicznym openclaw.json nie są obsługiwane dla zapisów należących do OpenClaw; zapis atomowy może zastąpić ścieżkę zamiast zachować dowiązanie symboliczne. Jeśli trzymasz konfigurację poza domyślnym katalogiem stanu, wskaż OPENCLAW_CONFIG_PATH bezpośrednio na rzeczywisty plik. Jeśli pliku brakuje, OpenClaw używa bezpiecznych wartości domyślnych. Typowe powody dodania konfiguracji:
  • Podłączenie kanałów i kontrola, kto może pisać do bota
  • Ustawienie modeli, narzędzi, sandboxingu lub automatyzacji (cron, hooki)
  • Dostrojenie sesji, multimediów, sieci lub UI
Zobacz pełną dokumentację, aby poznać wszystkie dostępne pola. Agenci i automatyzacja powinni używać config.schema.lookup, aby uzyskać dokładną dokumentację na poziomie pól przed edycją konfiguracji. Użyj tej strony jako wskazówek zadaniowych, a dokumentacji konfiguracji jako szerszej mapy pól i wartości domyślnych.
Zaczynasz od konfiguracji? Zacznij od openclaw onboard, aby przejść interaktywną konfigurację, albo sprawdź przewodnik Przykłady konfiguracji z kompletnymi konfiguracjami do skopiowania.

​
Minimalna konfiguracja

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

​
Edycja konfiguracji

openclaw onboard       # full onboarding flow
openclaw configure     # config wizard

​
Ścisła walidacja

OpenClaw akceptuje tylko konfiguracje w pełni zgodne ze schematem. Nieznane klucze, nieprawidłowo sformatowane typy lub nieprawidłowe wartości powodują, że Gateway odmawia uruchomienia. Jedynym wyjątkiem na poziomie głównym jest $schema (ciąg znaków), aby edytory mogły dołączać metadane JSON Schema.
openclaw config schema wypisuje kanoniczny JSON Schema używany przez Control UI i walidację. config.schema.lookup pobiera pojedynczy węzeł ograniczony do ścieżki oraz podsumowania elementów podrzędnych dla narzędzi szczegółowych. Metadane dokumentacji pól title/description są przenoszone przez zagnieżdżone obiekty, wildcard (*), elementy tablicy ([]) oraz gałęzie anyOf/ oneOf/allOf. Schematy runtime pluginów i kanałów są scalane po załadowaniu rejestru manifestów. Gdy walidacja się nie powiedzie:
  • Gateway nie uruchamia się
  • 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ć naprawy
Gateway przechowuje zaufaną ostatnią znaną dobrą kopię po każdym udanym uruchomieniu, ale uruchamianie i hot reload nie przywracają jej automatycznie. Jeśli openclaw.json nie przejdzie walidacji (w tym walidacji lokalnej dla pluginu), uruchomienie Gateway kończy się niepowodzeniem albo przeładowanie jest pomijane, a bieżący runtime zachowuje ostatnią zaakceptowaną konfigurację. Uruchom openclaw doctor --fix (lub --yes), aby naprawić konfigurację z prefiksami/nadpisaną albo przywrócić ostatnią znaną dobrą kopię. Awans do ostatniej znanej dobrej kopii jest pomijany, gdy kandydat zawiera zredagowane placeholdery sekretów, takie jak ***.

​
Typowe zadania

Każdy kanał ma własną sekcję konfiguracji pod channels.<provider>. Zobacz dedykowaną stronę kanału, aby poznać kroki konfiguracji:Wszystkie kanały współdzielą ten sam wzorzec zasad DM:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for 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; wpisy provider/* filtrują /model, /models i selektory modeli do wybranych dostawców, nadal korzystając z dynamicznego wykrywania modeli.
  • Użyj openclaw config set agents.defaults.models '<json>' --strict-json --merge, aby dodać wpisy do listy dozwolonych bez usuwania istniejących modeli. Zwykłe zastąpienia, które usunęłyby wpisy, są odrzucane, chyba że przekażesz --replace.
  • Odwołania do modeli używają formatu provider/model (np. anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx kontroluje zmniejszanie obrazów transkryptu/narzędzi (domyślnie 1200); niższe wartości zwykle zmniejszają zużycie tokenów wizji w przebiegach z dużą liczbą zrzutów ekranu.
  • Zobacz CLI modeli, aby przełączać modele na czacie, oraz Przełączanie awaryjne modeli, aby poznać rotację uwierzytelniania i zachowanie modeli zapasowych.
  • Dla niestandardowych/samodzielnie hostowanych dostawców zobacz Dostawcy niestandardowi w dokumentacji.
Dostęp DM jest kontrolowany per kanał przez dmPolicy:
  • "pairing" (domyślnie): nieznani nadawcy otrzymują jednorazowy kod parowania do zatwierdzenia
  • "allowlist": tylko nadawcy w allowFrom (lub sparowanym magazynie zezwoleń)
  • "open": zezwalaj na wszystkie przychodzące DM (wymaga allowFrom: ["*"])
  • "disabled": ignoruj wszystkie DM
Dla grup użyj groupPolicy + groupAllowFrom albo list dozwolonych specyficznych dla kanału.Zobacz pełną dokumentację, aby poznać szczegóły per kanał.
Wiadomości grupowe domyślnie wymagają wzmianki. Skonfiguruj wzorce wyzwalania per agent i pozostaw widoczne odpowiedzi w pokoju na domyślnej ścieżce narzędzia wiadomości, chyba że celowo chcesz używać starszych automatycznych odpowiedzi końcowych:
{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  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
  • Widoczne odpowiedzi: messages.visibleReplies może wymagać wysyłania przez narzędzie wiadomości globalnie; messages.groupChat.visibleReplies nadpisuje to dla grup/kanałów.
  • Zobacz pełną dokumentację, aby poznać tryby widocznych odpowiedzi, nadpisania per kanał i tryb self-chat.
Użyj agents.defaults.skills jako wspólnej bazy, a następnie nadpisz konkretnych agentów przez agents.list[].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 nie ograniczać Skills.
  • Pomiń agents.list[].skills, aby dziedziczyć wartości domyślne.
  • Ustaw agents.list[].skills: [], aby nie używać żadnych Skills.
  • Zobacz Skills, konfigurację Skills oraz dokumentację konfiguracji.
Kontroluj, jak agresywnie Gateway restartuje kanały, które wyglądają na przestarzałe:
{
  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 albo channels.<provider>.accounts.<id>.healthMonitor.enabled, aby wyłączyć automatyczne restarty dla jednego kanału lub konta bez wyłączania globalnego monitora.
  • Zobacz Kontrole kondycji, aby debugować operacyjnie, oraz pełną dokumentację dla wszystkich pól.
Daj lokalnym klientom więcej czasu na ukończenie przeduwierzytelnieniowego uzgadniania WebSocket na obciążonych lub mniej wydajnych hostach:
{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}
  • Domyślna wartość to 15000 milisekund.
  • OPENCLAW_HANDSHAKE_TIMEOUT_MS nadal ma pierwszeństwo dla jednorazowych nadpisań usługi lub powłoki.
  • Najpierw preferuj naprawę zacięć uruchamiania/pętli zdarzeń; to pokrętło jest dla hostów, które są zdrowe, ale wolne podczas rozgrzewania.
Sesje kontrolują ciągłość i izolację rozmów:
{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (wspólne) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: globalne wartości domyślne routingu sesji powiązanych z wątkami (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 poznać wszystkie pola.
Uruchamiaj sesje agentów w izolowanych środowiskach uruchomieniowych sandbox:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Najpierw zbuduj obraz - ze sklonowanych źródeł uruchom scripts/sandbox-setup.sh, a w przypadku instalacji z npm zobacz wbudowane polecenie docker build w sekcji Izolacja w sandboxie § Obrazy i konfiguracja.Zobacz Izolacja w sandboxie, aby poznać pełny przewodnik, oraz pełną dokumentację referencyjną, aby poznać wszystkie opcje.
Powiadomienia push oparte na przekaźniku są konfigurowane w openclaw.json.Ustaw to w konfiguracji Gateway:
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
Odpowiednik w CLI:
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
Co to robi:
  • Pozwala Gateway wysyłać push.test, sygnały wybudzające i wybudzenia do ponownego połączenia przez zewnętrzny przekaźnik.
  • Używa uprawnienia wysyłania ograniczonego do rejestracji, przekazanego przez sparowaną aplikację iOS. Gateway nie potrzebuje tokenu przekaźnika dla całego wdrożenia.
  • Wiąże każdą rejestrację opartą na przekaźniku z tożsamością Gateway, z którą sparowano aplikację iOS, więc inny Gateway nie może ponownie użyć zapisanej rejestracji.
  • Pozostawia lokalne/ręczne kompilacje iOS przy bezpośrednim APNs. Wysyłki oparte na przekaźniku dotyczą tylko oficjalnych dystrybuowanych kompilacji, które zarejestrowały się przez przekaźnik.
  • Musi pasować do bazowego URL przekaźnika wbudowanego w oficjalną kompilację iOS/TestFlight, aby ruch rejestracji i wysyłania trafiał do tego samego wdrożenia przekaźnika.
Przepływ od początku do końca:
  1. Zainstaluj oficjalną kompilację iOS lub kompilację z TestFlight skompilowaną z tym samym bazowym URL przekaźnika.
  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 przekaźniku przy użyciu App Attest wraz z pokwitowaniem aplikacji, a następnie publikuje oparty na przekaźniku ładunek push.apns.register do sparowanego Gateway.
  5. Gateway zapisuje uchwyt przekaźnika i uprawnienie do wysyłania, a następnie używa ich dla push.test, sygnałów wybudzających i wybudzeń do ponownego połączenia.
Uwagi operacyjne:
  • Jeśli przełączysz aplikację iOS na inny Gateway, połącz aplikację ponownie, aby mogła opublikować nową rejestrację przekaźnika powiązaną z tym Gateway.
  • Jeśli wydasz nową kompilację iOS wskazującą inne wdrożenie przekaźnika, aplikacja odświeży swoją buforowaną rejestrację przekaźnika zamiast ponownie używać starego źródła przekaźnika.
Uwaga dotycząca zgodności:
  • OPENCLAW_APNS_RELAY_BASE_URL i OPENCLAW_APNS_RELAY_TIMEOUT_MS nadal działają jako tymczasowe nadpisania env.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true pozostaje deweloperskim obejściem tylko dla local loopback; nie zapisuj adresów URL przekaźnika HTTP w konfiguracji.
Zobacz Aplikacja iOS, aby poznać przepływ od początku do końca, oraz Uwierzytelnianie i przepływ zaufania, aby poznać model bezpieczeństwa przekaźnika.
{
  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) albo block dla celów Heartbeat w stylu DM
  • Zobacz Heartbeat, aby poznać pełny przewodnik.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: usuwa ukończone izolowane sesje uruchomień z sessions.json (domyślnie 24h; ustaw false, aby wyłączyć).
  • runLog: przycina cron/runs/<jobId>.jsonl według rozmiaru i liczby zachowanych wierszy.
  • Zobacz Zadania Cron, aby poznać opis funkcji i przykłady CLI.
Włącz punkty końcowe HTTP typu Webhook 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/Webhook jako niezaufane dane wejściowe.
  • Używaj dedykowanego hooks.token; nie używaj ponownie współdzielonego tokenu Gateway.
  • Uwierzytelnianie hooków działa tylko przez nagłówek (Authorization: Bearer ... albo x-openclaw-token); tokeny w ciągu zapytania są odrzucane.
  • hooks.path nie może być /; trzymaj ruch przychodzący Webhook na dedykowanej podścieżce, takiej jak /hooks.
  • Pozostaw wyłączone flagi obchodzenia niebezpiecznej zawartości (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.
  • Dla agentów sterowanych hookami preferuj mocne nowoczesne klasy modeli i ścisłe zasady narzędzi (na przykład tylko wiadomości plus izolacja w sandboxie, gdzie to możliwe).
Zobacz pełną dokumentację referencyjną, aby poznać wszystkie opcje mapowania i integrację z Gmail.
Uruchamiaj wielu izolowanych agentów z osobnymi 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 Wielu agentów i pełną dokumentację referencyjną, aby poznać reguły powiązań i profile dostępu dla poszczególnych agentów.
Użyj $include, aby porzą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: głęboko scalana w kolejności (późniejsze wygrywają)
  • Klucze równorzędne: scalane po dołączeniach (nadpisują dołączone wartości)
  • Zagnieżdżone dołączenia: obsługiwane do 10 poziomów głębokości
  • Ścieżki względne: rozwiązywane względem pliku dołączającego
  • Zapisy wykonywane przez OpenClaw: gdy zapis zmienia tylko jedną sekcję najwyższego poziomu opartą na dołączeniu pojedynczego pliku, takim jak plugins: { $include: "./plugins.json5" }, OpenClaw aktualizuje ten dołączony plik i pozostawia openclaw.json bez zmian
  • Nieobsługiwany zapis przez include: dołączenia główne, tablice dołączeń i dołączenia z nadpisaniami przez klucze równorzędne kończą się bezpieczną odmową dla zapisów wykonywanych przez OpenClaw zamiast spłaszczać konfigurację
  • Ograniczenie: ścieżki $include muszą rozwiązywać się pod katalogiem zawierającym openclaw.json. Aby udostępnić drzewo między maszynami lub użytkownikami, ustaw OPENCLAW_INCLUDE_ROOTS na listę ścieżek (: w POSIX, ; w Windows) do dodatkowych katalogów, do których dołączenia mogą się odwoływać. Dowiązania symboliczne są rozwiązywane i sprawdzane ponownie, więc ścieżka, która leksykalnie znajduje się w katalogu konfiguracji, ale której rzeczywisty cel wychodzi poza każdy dozwolony katalog główny, nadal jest odrzucana.
  • Obsługa błędów: czytelne błędy dla brakujących plików, błędów parsowania i cyklicznych dołączeń

​
Gorące przeładowanie konfiguracji

Gateway obserwuje ~/.openclaw/openclaw.json i automatycznie stosuje zmiany - w przypadku większości ustawień ręczny restart nie jest potrzebny. Bezpośrednie edycje pliku są traktowane jako niezaufane, dopóki nie przejdą walidacji. Obserwator czeka, aż seria tymczasowych zapisów/zmian nazw edytora się ustabilizuje, odczytuje końcowy plik i odrzuca nieprawidłowe zewnętrzne edycje bez przepisywania openclaw.json. Zapisy konfiguracji wykonywane przez OpenClaw używają tej samej bramki schematu przed zapisem; destrukcyjne nadpisania, takie jak usunięcie gateway.mode albo zmniejszenie pliku o ponad połowę, są odrzucane i zapisywane jako .rejected.* do inspekcji. Jeśli zobaczysz config reload skipped (invalid config) albo start zgłosi Invalid config, sprawdź konfigurację, uruchom openclaw config validate, a następnie uruchom openclaw doctor --fix, aby naprawić. Zobacz Rozwiązywanie problemów z Gateway, aby poznać listę kontrolną.

​
Tryby przeładowania

TrybZachowanie
hybrid (domyślnie)Natychmiast stosuje bezpieczne zmiany na gorąco. Automatycznie restartuje przy zmianach krytycznych.
hotStosuje na gorąco tylko bezpieczne zmiany. Loguje ostrzeżenie, gdy restart jest potrzebny - restart wykonujesz samodzielnie.
restartRestartuje Gateway przy każdej zmianie konfiguracji, niezależnie od tego, czy jest bezpieczna.
offWyłącza obserwowanie pliku. Zmiany zaczynają 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 kanały i kanały typu PluginNie
Agent i modeleagent, agents, models, routingNie
Automatyzacjahooks, cron, agent.heartbeatNie
Sesje i wiadomościsession, messagesNie
Narzędzia i mediatools, browser, skills, mcp, audio, talkNie
UI i różneui, logging, identity, bindingsNie
Serwer Gatewaygateway.* (port, bind, auth, tailscale, TLS, HTTP)Tak
Infrastrukturadiscovery, pluginsTak
gateway.reload i gateway.remote są wyjątkami - ich zmiana nie wywołuje restartu.

​
Planowanie przeładowania

Gdy edytujesz plik źródłowy, do którego odwołuje się $include, OpenClaw planuje przeładowanie na podstawie układu zapisanego w źródle, a nie spłaszczonego widoku w pamięci. Dzięki temu decyzje dotyczące hot reloadu (hot-apply kontra restart) pozostają przewidywalne nawet wtedy, gdy pojedyncza sekcja najwyższego poziomu znajduje się we własnym dołączonym pliku, takim jak plugins: { $include: "./plugins.json5" }. Planowanie przeładowania kończy się bezpieczną odmową, jeśli układ źródłowy jest niejednoznaczny.

​
RPC konfiguracji (aktualizacje programowe)

W przypadku narzędzi zapisujących konfigurację przez API Gateway preferuj ten przepływ:
  • config.schema.lookup, aby sprawdzić jedno poddrzewo (płytki węzeł schematu + podsumowania elementów podrzędnych)
  • config.get, aby pobrać bieżący zrzut oraz hash
  • config.patch do częściowych aktualizacji (JSON merge patch: obiekty są scalane, null usuwa, tablice są zastępowane)
  • config.apply tylko wtedy, gdy zamierzasz zastąpić całą konfigurację
  • update.run do jawnej samoaktualizacji z restartem; dołącz continuationMessage, gdy sesja po restarcie ma wykonać jedną kolejną turę
  • update.status, aby sprawdzić najnowszy znacznik restartu aktualizacji i zweryfikować uruchomioną wersję po restarcie
Agenci powinni traktować config.schema.lookup jako pierwszy punkt dla dokładnej dokumentacji i ograniczeń na poziomie pól. Użyj Dokumentacji referencyjnej konfiguracji, gdy potrzebna jest szersza mapa konfiguracji, wartości domyślne lub linki do dedykowanych dokumentacji referencyjnych podsystemów.
Zapisy płaszczyzny sterowania (config.apply, config.patch, update.run) są ograniczone do 3 żądań na 60 sekund na deviceId+clientIp. Żądania restartu są łączone, a następnie wymuszają 30-sekundowy czas odnowienia między cyklami restartu. update.status jest tylko do odczytu, ale ma zakres administracyjny, ponieważ znacznik restartu może zawierać podsumowania kroków aktualizacji i końcówki wyjścia poleceń.
Przykład częściowej poprawki: 
openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
Zarówno config.apply, jak i config.patch akceptują raw, baseHash, sessionKey, note oraz restartDelayMs. baseHash jest wymagane dla obu metod, gdy konfiguracja już istnieje.

​
Zmienne środowiskowe

OpenClaw odczytuje zmienne środowiskowe z procesu nadrzędnego oraz z:
  • .env z bieżącego katalogu roboczego (jeśli istnieje)
  • ~/.openclaw/.env (globalna rezerwa)
Żaden z tych plików nie nadpisuje istniejących zmiennych środowiskowych. Możesz także ustawić wbudowane zmienne środowiskowe w konfiguracji: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Jeśli ta opcja jest włączona, a oczekiwane klucze nie są ustawione, OpenClaw uruchamia powłokę logowania i importuje tylko brakujące klucze:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Odpowiednik zmiennej środowiskowej: 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}" } } },
}
Reguły:
  • Dopasowywane są tylko nazwy pisane wielkimi literami: [A-Z_][A-Z0-9_]*
  • Brakujące/puste zmienne zgłaszają błąd podczas ładowania
  • Ucieknij za pomocą $${VAR}, aby uzyskać dosłowne wyjście
  • Działa wewnątrz plików $include
  • Podstawianie wbudowane: "${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) znajdują się w Zarządzaniu sekretami. Obsługiwane ścieżki poświadczeń są wymienione w Powierzchni poświadczeń SecretRef.
Zobacz Środowisko, aby poznać pełny priorytet i źródła.

​
Pełna dokumentacja referencyjna

Pełną dokumentację referencyjną pole po polu znajdziesz w Dokumentacji referencyjnej konfiguracji.
Powiązane: Przykłady konfiguracji · Dokumentacja referencyjna konfiguracji · Diagnostyka

​
Powiązane