Przejdź do głównej treści
Pomocniki konfiguracji do nieinteraktywnych edycji w openclaw.json: pobieranie/ustawianie/nakładanie poprawek/usuwanie/plik/schemat/walidacja wartości według ścieżki oraz wypisywanie aktywnego pliku konfiguracji. Uruchom bez podkomendy, aby otworzyć kreator konfiguracji (tak samo jak openclaw configure).
Gdy OPENCLAW_NIX_MODE=1, OpenClaw traktuje openclaw.json jako niezmienny. Polecenia tylko do odczytu, takie jak config get, config file, config schema i config validate, nadal działają, ale polecenia zapisujące konfigurację odmawiają działania. Agenci powinni zamiast tego edytować źródło Nix dla instalacji; dla własnej dystrybucji nix-openclaw użyj nix-openclaw Quick Start i ustaw wartości pod programs.openclaw.config lub instances.<name>.config.

​
Opcje główne

​
--section <section>
string
Powtarzalny filtr sekcji konfiguracji prowadzonej, gdy uruchamiasz openclaw config bez podkomendy.
Obsługiwane sekcje prowadzone: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

​
Przykłady

openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

​
config schema

Wypisuje wygenerowany schemat JSON dla openclaw.json na stdout jako JSON.
  • Bieżący główny schemat konfiguracji oraz główne pole tekstowe $schema dla narzędzi edytora.
  • Metadane dokumentacji pól title i description używane przez Control UI.
  • Zagnieżdżone obiekty, symbole wieloznaczne (*) i węzły elementów tablicy ([]) dziedziczą te same metadane title / description, gdy istnieje pasująca dokumentacja pola.
  • Gałęzie anyOf / oneOf / allOf także dziedziczą te same metadane dokumentacji, gdy istnieje pasująca dokumentacja pola.
  • Metadane schematu Pluginów i kanałów w trybie live na zasadzie najlepszej możliwości, gdy można wczytać manifesty runtime.
  • Czysty schemat awaryjny nawet wtedy, gdy bieżąca konfiguracja jest nieprawidłowa.
config.schema.lookup zwraca jedną znormalizowaną ścieżkę konfiguracji z płytkim węzłem schemat (title, description, type, enum, const, wspólne ograniczenia), dopasowanymi metadanymi podpowiedzi UI oraz podsumowaniami bezpośrednich elementów podrzędnych. Użyj tego do szczegółowego przechodzenia po ścieżkach w Control UI lub klientach niestandardowych.
openclaw config schema
Przekieruj wynik do pliku, gdy chcesz go sprawdzić lub zwalidować innymi narzędziami: 
openclaw config schema > openclaw.schema.json

​
Ścieżki

Ścieżki używają notacji kropkowej lub nawiasowej. Cytuj ścieżki w notacji nawiasowej w przykładach powłoki, aby powłoki takie jak zsh nie rozwijały [0] jako globu, zanim OpenClaw otrzyma ścieżkę: 
openclaw config get agents.defaults.workspace
openclaw config get 'agents.list[0].id'
Użyj indeksu listy agentów, aby wskazać konkretnego agenta: 
openclaw config get agents.list
openclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

​
Wartości

Wartości są parsowane jako JSON5, gdy to możliwe; w przeciwnym razie są traktowane jako ciągi znaków. Użyj --strict-json, aby wymagać standardowego parsowania JSON bez awaryjnego traktowania jako ciąg znaków. --json pozostaje obsługiwane jako starszy alias dla --strict-json. 
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
Gdy --strict-json jest włączone, składnia dostępna tylko w JSON5, taka jak komentarze, końcowe przecinki lub niecytowane klucze obiektów, jest odrzucana. Pomiń --strict-json, aby parsować wartości JSON5 z awaryjnym użyciem surowego ciągu znaków. config get <path> --json wypisuje surową wartość jako JSON zamiast tekstu formatowanego dla terminala.
Przypisanie obiektu domyślnie zastępuje ścieżkę docelową. Chronione ścieżki map/list, które często przechowują wpisy dodane przez użytkownika, takie jak agents.defaults.models, models.providers, models.providers.<id>.models, plugins.entries i auth.profiles, odmawiają zastąpień, które usunęłyby istniejące wpisy, chyba że przekażesz --replace.
Użyj --merge, gdy dodajesz wpisy do tych map: 
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
Użyj --replace tylko wtedy, gdy celowo chcesz, aby podana wartość stała się pełną wartością docelową.

​
Tryby config set

openclaw config set obsługuje cztery style przypisania: 
openclaw config set <path> <value>
Przypisania SecretRef są odrzucane na nieobsługiwanych powierzchniach modyfikowalnych w runtime (na przykład hooks.token, commands.ownerDisplaySecret, tokeny Webhook powiązania wątku Discord oraz JSON poświadczeń WhatsApp). Zobacz Powierzchnia poświadczeń SecretRef.
Parsowanie wsadowe zawsze używa ładunku wsadowego (--batch-json/--batch-file) jako źródła prawdy. --strict-json / --json nie zmieniają zachowania parsowania wsadowego.

​
config patch

Użyj config patch, gdy chcesz wkleić lub przekierować poprawkę w kształcie konfiguracji zamiast uruchamiać wiele poleceń config set opartych na ścieżkach. Wejście jest obiektem JSON5. Obiekty scalają się rekurencyjnie, tablice i wartości skalarne zastępują wartość docelową, a null usuwa ścieżkę docelową. 
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5
Możesz także przekazać poprawkę przez stdin, co jest przydatne w skryptach zdalnej konfiguracji: 
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
Przykładowa poprawka: 
{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      groupPolicy: "open",
      requireMention: false,
    },
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
      dmPolicy: "disabled",
      dm: { enabled: false },
      groupPolicy: "allowlist",
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
Użyj --replace-path <path>, gdy jeden obiekt lub tablica musi stać się dokładnie podaną wartością zamiast być poprawiany rekurencyjnie: 
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
--dry-run uruchamia sprawdzanie schematu i rozwiązywalności SecretRef bez zapisywania. SecretRefy oparte na exec są domyślnie pomijane podczas dry-run; dodaj --allow-exec, gdy celowo chcesz, aby dry-run wykonywał polecenia dostawcy. Tryb ścieżki/wartości JSON pozostaje obsługiwany zarówno dla SecretRefów, jak i dostawców: 
openclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

openclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
  --strict-json

​
Flagi kreatora dostawcy

Cele kreatora dostawcy muszą używać secrets.providers.<alias> jako ścieżki.
  • --provider-source <env|file|exec>
  • --provider-timeout-ms <ms> (file, exec)
  • --provider-allowlist <ENV_VAR> (powtarzalne)
  • --provider-path <path> (wymagane)
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
  • --provider-command <path> (wymagane)
  • --provider-arg <arg> (powtarzalne)
  • --provider-no-output-timeout-ms <ms>
  • --provider-max-output-bytes <bytes>
  • --provider-json-only
  • --provider-env <KEY=VALUE> (powtarzalne)
  • --provider-pass-env <ENV_VAR> (powtarzalne)
  • --provider-trusted-dir <path> (powtarzalne)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command
Przykład wzmocnionego dostawcy exec: 
openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

​
Dry run

Użyj --dry-run, aby zweryfikować zmiany bez zapisywania openclaw.json. 
openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run \
  --json

openclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec
  • Tryb buildera: uruchamia kontrole rozwiązywalności SecretRef dla zmienionych refs/providers.
  • Tryb JSON (--strict-json, --json lub tryb wsadowy): uruchamia walidację schematu oraz kontrole rozwiązywalności SecretRef.
  • Walidacja zasad uruchamia się również dla znanych nieobsługiwanych powierzchni docelowych SecretRef.
  • Kontrole zasad oceniają pełną konfigurację po zmianie, więc zapisy obiektu nadrzędnego (na przykład ustawienie hooks jako obiektu) nie mogą ominąć walidacji nieobsługiwanej powierzchni.
  • Kontrole exec SecretRef są domyślnie pomijane podczas dry-run, aby uniknąć skutków ubocznych poleceń.
  • Użyj --allow-exec z --dry-run, aby włączyć kontrole exec SecretRef (może to wykonać polecenia dostawcy).
  • --allow-exec działa tylko z dry-run i zgłasza błąd, jeśli zostanie użyte bez --dry-run.
--dry-run --json wypisuje raport czytelny maszynowo:
  • ok: czy dry-run zakończył się powodzeniem
  • operations: liczba ocenionych przypisań
  • checks: czy uruchomiono kontrole schematu/rozwiązywalności
  • checks.resolvabilityComplete: czy kontrole rozwiązywalności dobiegły końca (false, gdy refs exec są pomijane)
  • refsChecked: liczba refs faktycznie rozwiązanych podczas dry-run
  • skippedExecRefs: liczba refs exec pominiętych, ponieważ --allow-exec nie zostało ustawione
  • errors: ustrukturyzowane błędy brakującej ścieżki, schematu lub rozwiązywalności, gdy ok=false

​
Kształt danych wyjściowych JSON

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder" | "unset", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "missing-path" | "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}
  • config schema validation failed: kształt konfiguracji po zmianie jest nieprawidłowy; popraw ścieżkę/wartość albo kształt obiektu provider/ref.
  • Config policy validation failed: unsupported SecretRef usage: przenieś te dane uwierzytelniające z powrotem do wejścia plaintext/string i utrzymuj SecretRefs tylko na obsługiwanych powierzchniach.
  • SecretRef assignment(s) could not be resolved: wskazany provider/ref obecnie nie może zostać rozwiązany (brakująca zmienna env, nieprawidłowy wskaźnik pliku, awaria dostawcy exec albo niezgodność dostawcy/źródła).
  • Dry run note: skipped <n> exec SecretRef resolvability check(s): dry-run pominął refs exec; uruchom ponownie z --allow-exec, jeśli potrzebujesz walidacji rozwiązywalności exec.
  • W trybie wsadowym popraw wpisy kończące się niepowodzeniem i uruchom ponownie --dry-run przed zapisem.

​
Bezpieczeństwo zapisu

openclaw config set i inne narzędzia zapisujące konfigurację należące do OpenClaw walidują pełną konfigurację po zmianie przed zapisaniem jej na dysku. Jeśli nowy payload nie przejdzie walidacji schematu albo wygląda jak destrukcyjne nadpisanie, aktywna konfiguracja pozostaje bez zmian, a odrzucony payload jest zapisywany obok niej jako openclaw.json.rejected.*.
Aktywna ścieżka konfiguracji musi być zwykłym plikiem. Układy openclaw.json jako symlink nie są obsługiwane przy zapisach; zamiast tego użyj OPENCLAW_CONFIG_PATH, aby wskazać bezpośrednio rzeczywisty plik.
Preferuj zapisy przez CLI przy małych edycjach: 
openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate
Jeśli zapis zostanie odrzucony, sprawdź zapisany payload i popraw kształt pełnej konfiguracji: 
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate
Bezpośrednie zapisy w edytorze nadal są dozwolone, ale działający Gateway traktuje je jako niezaufane, dopóki nie przejdą walidacji. Nieprawidłowe bezpośrednie edycje powodują niepowodzenie uruchamiania albo są pomijane przez hot reload; Gateway nie przepisuje openclaw.json. Uruchom openclaw doctor --fix, aby naprawić konfigurację z prefiksem/nadpisaną albo przywrócić ostatnią znaną dobrą kopię. Zobacz rozwiązywanie problemów z Gateway. Odzyskiwanie całego pliku jest zarezerwowane dla naprawy przez doctora. Zmiany schematu Plugin lub rozjazd minHostVersion pozostają wyraźnie sygnalizowane zamiast wycofywać niepowiązane ustawienia użytkownika, takie jak modele, dostawcy, profile auth, kanały, ekspozycja Gateway, narzędzia, pamięć, przeglądarka czy konfiguracja cron.

​
Podpolecenia

  • config file: Wypisuje ścieżkę aktywnego pliku konfiguracji (rozwiązaną z OPENCLAW_CONFIG_PATH albo domyślnej lokalizacji). Ścieżka powinna wskazywać zwykły plik, a nie symlink.
Po edycjach uruchom ponownie gateway.

​
Walidacja

Waliduj bieżącą konfigurację względem aktywnego schematu bez uruchamiania gateway. 
openclaw config validate
openclaw config validate --json
Gdy openclaw config validate przechodzi, możesz użyć lokalnego TUI, aby osadzony agent porównał aktywną konfigurację z dokumentacją podczas walidowania każdej zmiany z tego samego terminala:
Jeśli walidacja już się nie powodzi, zacznij od openclaw configure albo openclaw doctor --fix. openclaw chat nie omija ochrony przed nieprawidłową konfiguracją.
openclaw chat
Następnie w TUI: 
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
Typowa pętla naprawy:
1

Porównaj z dokumentacją

Poproś agenta o porównanie bieżącej konfiguracji z odpowiednią stroną dokumentacji i zasugerowanie najmniejszej poprawki.
2

Zastosuj ukierunkowane edycje

Zastosuj ukierunkowane edycje za pomocą openclaw config set albo openclaw configure.
3

Ponownie waliduj

Uruchom ponownie openclaw config validate po każdej zmianie.
4

Doctor dla problemów runtime

Jeśli walidacja przechodzi, ale runtime nadal jest w złym stanie, uruchom openclaw doctor albo openclaw doctor --fix, aby uzyskać pomoc w migracji i naprawie.

​
Powiązane