Konfiguracja OpenClaw — przewodnik po ustawieniach

Plik konfiguracyjny

Cała konfiguracja OpenClaw zapisana jest w jednym pliku w formacie JSON5 (rozszerzenie JSON o komentarze i trailing commas). Domyślna lokalizacja pliku to:

~/.openclaw/openclaw.json

Plik jest tworzony automatycznie podczas pierwszej konfiguracji (openclaw onboard). Możesz go edytować ręcznie lub przez Control UI.

Metody konfiguracji

OpenClaw oferuje cztery sposoby modyfikowania ustawień:

1. Kreator (wizard)

openclaw onboard

Interaktywny kreator, który przeprowadza przez podstawową konfigurację krok po kroku. Idealny dla początkujących użytkowników.

2. Polecenia CLI

openclaw config set agent.model "openai/gpt-4o"
openclaw config get agent.model
openclaw config list

Pozwala na szybkie zmiany pojedynczych wartości bez otwierania pliku. Przydatne do skryptowania i automatyzacji.

3. Control UI

Panel webowy dostępny pod http://localhost:18789 oferuje graficzny edytor konfiguracji z walidacją w czasie rzeczywistym, podpowiedziami i dokumentacją inline.

4. Edycja ręczna

Zaawansowani użytkownicy mogą edytować plik openclaw.json bezpośrednio w ulubionym edytorze tekstu.

Walidacja i diagnostyka

Po wprowadzeniu zmian warto zweryfikować poprawność konfiguracji:

openclaw doctor

Polecenie doctor sprawdza:

• Poprawność składni JSON5
• Obecność wymaganych pól
• Dostępność providerów AI (testowe zapytanie)
• Połączenie z kanałami komunikacji
• Uprawnienia systemu plików
• Wersje zależności

Każdy test jest oznaczony kolorem: zielony (OK), żółty (ostrzeżenie) lub czerwony (błąd krytyczny).

Kanały i polityki DM

Sekcja channels definiuje podłączone kanały komunikacji. Każdy kanał ma własny blok konfiguracyjny:

{
  channels: {
    telegram: {
      enabled: true,
      token: "BOT_TOKEN",
      dm_policy: "pairing",   // pairing | allowlist | open
      group_policy: "mention", // mention | always | off
    },
    discord: {
      enabled: true,
      token: "BOT_TOKEN",
      dm_policy: "allowlist",
      allowed_users: ["user_id_1", "user_id_2"],
    }
  }
}

Polityki DM kontrolują, kto może rozmawiać z agentem prywatnie:

• pairing — nowy użytkownik musi wprowadzić kod parowania wygenerowany w Control UI
• allowlist — tylko użytkownicy z listy allowed_users mogą pisać do bota
• open — każdy może pisać (używaj ostrożnie, generuje koszty API)

Modele AI

Model AI konfigurowany jest w formacie provider/model:

{
  agent: {
    model: "openai/gpt-4o",
    fallback_model: "anthropic/claude-sonnet-4-20250514",
    temperature: 0.7,
    max_tokens: 4096,
    system_prompt: "Jesteś pomocnym asystentem. Odpowiadaj po polsku.",
  }
}

Możesz ustawić model zapasowy (fallback_model), który zostanie użyty, gdy główny provider zwróci błąd lub będzie niedostępny.

Sesje

OpenClaw zarządza sesjami rozmów automatycznie. Konfiguracja sesji:

{
  sessions: {
    ttl: "24h",           // czas życia sesji
    max_messages: 100,     // maks. wiadomości w kontekście
    storage: "file",       // file | redis | sqlite
    isolation: "per_user", // per_user | per_channel | global
  }
}

Parametr isolation określa, czy każdy użytkownik ma osobną sesję, czy rozmowa jest wspólna w ramach kanału.

Sandbox narzędzi

Narzędzia (browser, shell, file access) mogą być uruchamiane w izolowanym sandboxie:

{
  sandbox: {
    enabled: true,
    runtime: "docker",     // docker | nsjail | none
    network: "restricted", // restricted | full | none
    timeout: 30,           // sekundy
    allowed_domains: ["*.wikipedia.org", "api.example.com"],
  }
}

Sandbox chroni przed nieautoryzowanym dostępem do systemu i sieci. W trybie restricted agent może łączyć się tylko z domenami z listy dozwolonych.

Crony

Crony pozwalają agentowi wykonywać zadania cyklicznie:

{
  crons: [
    {
      name: "morning_briefing",
      schedule: "0 8 * * *",
      prompt: "Przygotuj poranny briefing z najważniejszymi wiadomościami.",
      channel: "telegram",
      target: "chat_id_123",
    },
    {
      name: "weekly_report",
      schedule: "0 18 * * 5",
      prompt: "Podsumuj aktywność z tego tygodnia.",
      channel: "slack",
      target: "#general",
    }
  ]
}

Harmonogram używa standardowej składni cron (minuta, godzina, dzień miesiąca, miesiąc, dzień tygodnia).

Webhooki

OpenClaw może nasłuchiwać na przychodzące żądania HTTP i przekazywać je do agenta:

{
  webhooks: [
    {
      path: "/webhook/github",
      secret: "WEBHOOK_SECRET",
      prompt: "Przeanalizuj zdarzenie GitHub: {{payload}}",
      channel: "slack",
      target: "#dev-notifications",
    }
  ]
}

Webhooki są dostępne pod adresem http://localhost:18789/webhook/.... Zmienna {{payload}} jest zastępowana treścią żądania.

Hot reload

OpenClaw obsługuje przeładowywanie konfiguracji bez restartu Gateway. Dostępne tryby:

• hybrid (domyślny) — bezpieczne zmiany (system prompt, temperature) stosowane natychmiast; zmiany wymagające restartu (kanały, provider) powodują automatyczny restart
• hot — wszystkie zmiany stosowane natychmiast, bez restartu. Szybkie, ale może powodować krótkie przerwy w działaniu kanałów.
• restart — każda zmiana konfiguracji powoduje pełny restart Gateway
• off — zmiany wymagają ręcznego restartu (openclaw gateway restart)

{
  gateway: {
    reload_mode: "hybrid",
  }
}

Zmienne środowiskowe i sekrety

Wrażliwe wartości (klucze API, tokeny) nie muszą być wpisywane bezpośrednio w pliku konfiguracyjnym. OpenClaw obsługuje odwołania do zmiennych środowiskowych:

{
  channels: {
    telegram: {
      token: "${TELEGRAM_BOT_TOKEN}",
    }
  },
  agent: {
    model: "openai/gpt-4o",
    api_key: "${OPENAI_API_KEY}",
  }
}

Zmienne są rozwiązywane podczas startu Gateway. Możesz też przechowywać sekrety w pliku ~/.openclaw/secrets.env, który jest automatycznie ładowany.

Wskazówka bezpieczeństwa: Nigdy nie commituj pliku openclaw.json z prawdziwymi kluczami API do repozytorium. Używaj zmiennych środowiskowych lub pliku secrets.env.