OpenClaw konfiguracja — openclaw.json, port Gateway, auth i dane

Gdzie leży konfiguracja i co jeszcze siedzi w katalogu stanu

OpenClaw czyta opcjonalny plik ~/.openclaw/openclaw.json zapisany w formacie JSON5. Jeśli pliku nie ma, silnik startuje na bezpiecznych wartościach domyślnych — świeża instalacja działa więc bez żadnej ręcznej konfiguracji. JSON5 oznacza, że możesz wstawiać komentarze i pisać klucze bez cudzysłowów, co bardzo pomaga przy dłuższych plikach.

Sam plik to tylko element większej całości. Wszystko żyje pod katalogiem stanu, domyślnie ~/.openclaw, a jego lokalizację nadpisuje zmienna OPENCLAW_STATE_DIR. Historia czatu i stan routingu agenta trafiają do bazy SQLite pod ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite, a katalog agenta trzyma profile auth, rejestr modeli i konfigurację per-agent.

Workspace agenta to osobna sprawa. Domyślnie jest to ~/.openclaw/workspace, ale przy OPENCLAW_PROFILE ustawionym na wartość inną niż "default" ścieżka zmienia się na ~/.openclaw/workspace-<profile>. Obie te wartości nadpisuje OPENCLAW_WORKSPACE_DIR, a ustawić je można też kluczem agents.defaults.workspace.

Jeśli trzymasz config poza katalogiem stanu — na przykład w repozytorium z resztą infrastruktury — użyj OPENCLAW_CONFIG_PATH. Dokumentacja radzi wskazywać realny plik, a nie dowiązanie symboliczne, żeby watcher konfiguracji nie miał problemów z wykrywaniem zmian.

openclaw config file
openclaw config get gateway.port

• openclaw.json — aktywny plik konfiguracyjny
• agents/<agentId>/ — stan i sesje pojedynczego agenta
• credentials/ — poświadczenia kanałów i providerów
• workspace/ — przestrzeń robocza agenta z plikami Markdown
• .env — globalny fallback dla zmiennych środowiskowych

Cztery sposoby edycji i hot reload, który nie wybacza literówek

Config zmienia się na cztery sposoby i wszystkie prowadzą do tego samego pliku. Jest kreator interaktywny (openclaw configure), zestaw komend CLI (openclaw config get/set/unset/file/schema/validate), Control UI pod http://127.0.0.1:18789 oraz zwykła edycja pliku w ulubionym edytorze. Do startu od zera służy openclaw onboard, opcjonalnie z flagą --install-daemon.

Gateway obserwuje plik i przeładowuje zmiany na gorąco. Ręczny restart potrzebny jest wyłącznie przy zmianach infrastrukturalnych — czyli portu albo ustawień uwierzytelniania. Edycje z zewnątrz są traktowane jako niezaufane do momentu walidacji: watcher czeka, aż ucichnie zapis i zmiana nazwy pliku tymczasowego edytora, dopiero potem czyta wersję finalną.

Walidacja jest bezlitosna i akurat to działa na Twoją korzyść. Dokumentacja stawia sprawę jasno: OpenClaw przyjmuje tylko konfiguracje w pełni zgodne ze schematem, a nieznane klucze, złe typy i niepoprawne wartości powodują odmowę startu. Odrzucona edycja nie nadpisuje działającego pliku — ląduje obok jako openclaw.json.rejected.<timestamp>.

Praktyczny nawyk: po każdej ręcznej zmianie odpal openclaw config validate, zamiast dowiadywać się o literówce z logów po restarcie.

openclaw configure
openclaw config set gateway.port <nowy_port>
openclaw config validate
openclaw config schema

Port Gateway 18789 i to, kto może się do niego dobić

Domyślny port Gateway to 18789 i pod tym adresem otwiera się też Control UI na http://127.0.0.1:18789. Precedencja ustawiania jest czterostopniowa: flaga --port bije zmienną OPENCLAW_GATEWAY_PORT, ta bije klucz gateway.port, a na końcu zostaje wartość domyślna. Warto o tym pamiętać, gdy port „nie chce się zmienić" mimo edycji configu.

Za ekspozycję sieciową odpowiada gateway.bind. Dopuszczalne tryby to loopback (domyślny, tylko połączenia lokalne), lan, tailnet, auto i custom. W Dockerze domyślny loopback nasłuchuje na 127.0.0.1 wewnątrz kontenera, więc przy zwykłym mapowaniu portu (-p 18789:18789) ruch przychodzi na eth0 i Gateway pozostaje nieosiągalny — trzeba świadomie zmienić gateway.bind i zadbać o uwierzytelnianie. Dokumentacja ostrzega wprost, żeby nigdy nie wystawiać Gateway bez uwierzytelnienia na 0.0.0.0, i zamiast bindowania na LAN poleca Tailscale Serve.

Konflikt portu objawia się błędem EADDRINUSE albo komunikatem o tym, że inna instancja Gateway już nasłuchuje. Diagnoza zajmuje kilkanaście sekund: sprawdzasz, kto siedzi na porcie, potem status Gateway i doctora. Naprawa to albo zwolnienie portu, albo ustawienie innego kluczem gateway.port; CLI ma też flagę --force, która ubija istniejące listenery.

lsof -i :18789
openclaw gateway status --deep --json
openclaw doctor

Uwierzytelnianie działa fail-closed — i dobrze

Uwierzytelnianie Gateway jest wymagane domyślnie. Dokumentacja formułuje to jako fail-closed: bez skonfigurowanej poprawnej ścieżki auth Gateway odmawia połączeń WebSocket. Jeśli przy starcie zobaczysz komunikat o odmowie bindowania bez auth, to nie awaria, tylko zamierzone zachowanie.

Do wyboru są trzy tryby ustawiane kluczem gateway.auth.mode: token (współdzielony bearer token), password oraz trusted-proxy dla reverse proxy świadomego tożsamości. Wartości podaje się w gateway.auth.token i gateway.auth.password, a ich odpowiedniki środowiskowe to OPENCLAW_GATEWAY_TOKEN i OPENCLAW_GATEWAY_PASSWORD. Webhooki i hooki uwierzytelniają się nagłówkiem Authorization: Bearer albo nagłówkiem x-openclaw-token.

Osobna warstwa to uprawnienia plików. Dokumentacja zaleca 600 na ~/.openclaw/openclaw.json i 700 na katalog ~/.openclaw, bo w środku leżą poświadczenia kanałów, tokeny OAuth i transkrypty sesji. OpenClaw jest zaprojektowany w modelu zaufania „personal assistant", a nie jako system wielodostępowy z izolacją między użytkownikami — na współdzielonej maszynie ta różnica ma konkretne konsekwencje.

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

Zmienne środowiskowe, sekrety i klucze API

Sekrety wczytywane są z trzech źródeł w ustalonej kolejności: zmienne procesu rodzica, plik .env z bieżącego katalogu roboczego, a na końcu globalny ~/.openclaw/.env jako fallback. W samym configu możesz użyć bloku env oraz podstawień w postaci ${NAZWA_ZMIENNEJ} wewnątrz stringów — działa to tylko dla nazw pisanych wielkimi literami.

Kilka zmiennych warto znać z nazwy. OPENCLAW_CONFIG_PATH wskazuje plik konfiguracyjny, OPENCLAW_STATE_DIR przenosi cały katalog stanu, OPENCLAW_INCLUDE_ROOTS podaje listę ścieżek dopuszczających odwołania $include między katalogami (separator to ":" na POSIX i ";" na Windows), a OPENCLAW_LOAD_SHELL_ENV=1 importuje brakujące zmienne z powłoki logowania. Ta ostatnia ratuje sytuację, gdy Gateway działa jako usługa systemowa i nie dziedziczy środowiska użytkownika.

Modele czyta się z gałęzi agents.defaults.models, a bieżący stan pokazuje openclaw models status. Przy błędzie HTTP 429 rate_limit_error dokumentacja podpowiada trzy ruchy: przełączyć się na model ze standardowym oknem kontekstu, użyć poświadczenia uprawnionego do długiego kontekstu albo skonfigurować modele zapasowe, żeby awaria jednego providera nie zatrzymywała agenta.

Tokeny kanałów sprawdzaj bez wypisywania ich wartości — to dobry odruch przy migracji i przy zgłoszeniach do wsparcia. Do samego zgłoszenia lepiej nadaje się openclaw status --all, które daje diagnozę tylko do odczytu wraz z ogonem logów i zredagowanymi tokenami.

awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

Kanały: instalacja pluginu i polityki dostępu

Kanały są pluginami. Instalujesz je komendą openclaw plugins install @openclaw/<id>, przez kreator openclaw onboard albo przez openclaw channels add. Gateway ładuje zewnętrzny plugin dopiero wtedy, gdy kanał jest faktycznie aktywny, a po instalacji potrzebny jest restart. Lista obejmuje kilkanaście platform — Telegram, Slack, Discord, WhatsApp, Signal, iMessage, Matrix, Teams i dalej; WebChat jest wbudowany w rdzeń.

Kontrola dostępu wygląda tak samo w każdym kanale i opiera się na dwóch kluczach. Tryb "open" wymaga przy tym jawnego wpisu "*" na allowliście kanału — bez niego wiadomości nadal będą blokowane. dmPolicy przyjmuje "pairing" (domyślnie — nieznany nadawca dostaje kod parowania o ograniczonym czasie życia), "allowlist", "open" i "disabled". groupPolicy przyjmuje "open", "allowlist" i "disabled". Uzupełniają je groupAllowFrom (allowFrom działa tylko jako fallback), groups i requireMention.

Kody parowania wygasają po godzinie, a w WhatsAppie oczekujące żądania są limitowane do trzech na konto. Jeśli agent milczy, zwykle nie jest to awaria, tylko routing: w logach zobaczysz „drop guild message (mention required", „pairing request" albo „blocked" i „allowlist".

Pułapka warta zapamiętania dotyczy Slacka: allowlisty kanałów muszą używać identyfikatorów Slacka w rodzaju C12345678. Klucze oparte na nazwach z hashem po cichu nie działają przy groupPolicy ustawionym na "allowlist" — nic się nie wywala, po prostu nic nie przechodzi.

openclaw channels status --probe
openclaw pairing list <kanał>
openclaw pairing approve <kanał> <CODE>

Gdy config zostaje odrzucony — i jak się przed tym zabezpieczyć

Komunikaty „Invalid config" i „config reload skipped" znaczą, że Gateway odmówił przyjęcia nowej wersji pliku. Odrzucone i nadpisane wersje są zachowywane obok configu jako pliki *.rejected.<timestamp> oraz *.clobbered.*, więc masz do czego wrócić. Naprawę robi openclaw doctor --fix, który przywraca ostatnią znaną dobrą kopię, a przy okazji usuwa nieaktualne cienie OAuth per-agent.

Backup warto robić przed większą zmianą, nie po niej. Komenda openclaw backup create obejmuje katalog stanu, aktywny plik konfiguracyjny, credentials, workspace, profile auth, stan sesji i bazy SQLite — te ostatnie zrzucane są przez online backup API SQLite i kompaktowane przez VACUUM. Flaga --verify sprawdza archiwum od razu po utworzeniu.

Warto rozdzielić dwie rzeczy. FAQ projektu radzi trzymać workspace agenta w prywatnym repozytorium git, bo to tam żyją pamięć i pliki AGENTS/SOUL/USER, i jednocześnie ostrzega, żeby nigdy nie commitować ~/.openclaw — w środku są poświadczenia, sesje, tokeny i zaszyfrowane payloady sekretów. Backupujesz obie lokalizacje, ale w zupełnie różny sposób.

Jeśli ta warstwa operacyjna to nie jest praca, którą chcesz wykonywać ręcznie, alternatywą jest gotowa instancja w chmurze. ClawLabs uruchamia agenta na silniku OpenClaw w chmurze EU (Hetzner) w około 60 sekund, z 13 kanałami, własnym kluczem API w modelu BYOK i DPA na żądanie — plany od 399 zł miesięcznie, a 5-dniowy trial obejmuje wyłącznie plan Premium i wymaga podpięcia karty.

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw doctor --fix
openclaw gateway restart