Lekcja 2611 min czytania

Bezpieczeństwo instancji OpenClaw: bind, auth, sekrety i kopie

Umowy, RODO i papiery to lekcja siódma i szesnasta. Ta jest o portach, tokenach i uprawnieniach plików. Żadna z tych rzeczy nie zajmuje więcej niż kwadrans, a pominięcie jednej potrafi wystawić Twoje dane na otwarty port.

Zanim otworzysz port: pięć trybów gateway.bind

Gateway multipleksuje WebSocket i HTTP na jednym porcie, domyślnie 18789, a o tym, kto może się do niego dobić, decyduje gateway.bind. Tryby to loopback (domyślny, tylko połączenia lokalne), lan, tailnet, auto i custom. Loopback jest opisany jako zalecany punkt startu dla instalacji typu osobisty asystent i naprawdę nie ma powodu, żeby ruszać go pierwszego dnia.

Dokumentacja formułuje warunek bardzo bezpośrednio: szersza ekspozycja wymaga uwierzytelniania gatewaya (współdzielonego tokenu, hasła albo poprawnie skonfigurowanego zaufanego proxy) oraz prawdziwej zapory. Wystawianie gatewaya na 0.0.0.0 bez auth jest odradzane wprost, bez żadnych zastrzeżeń typu „chyba że w sieci wewnętrznej”.

Zamiast otwierać LAN, dokumentacja poleca Tailscale Serve i tryb tailnet. Wtedy dostęp opiera się na tożsamości urządzenia w sieci prywatnej, a nie na tym, że ktoś zna adres IP i port. Audyt bezpieczeństwa ma zresztą osobny check gateway.tailscale_funnel, bo Funnel wystawia usługę do publicznego internetu i to jest już całkiem inna decyzja niż Serve.

Osobna warstwa to Control UI. gateway.controlUi.enabled jest domyślnie włączone, basePath domyślnie prowadzi do /openclaw, a gateway.controlUi.allowedOrigins staje się obowiązkowa przy dostępie spoza pętli zwrotnej. Istnieje też zmienna OPENCLAW_ALLOW_INSECURE_PRIVATE_WS, która zdejmuje wymóg szyfrowania na prywatnych nazwach DNS. Ustawiasz ją tylko w środowisku procesu i tylko na czas jednej awarii, nie w configu i nie na stałe.

Nazwa trybu auto sugeruje, że coś się samo domyśli. Nie domyśli się, że siedzisz w kontenerze, i to akurat mocno myli ludzi. Sprawdź to, zanim spędzisz wieczór na szukaniu, czemu przeglądarka nie widzi dashboardu.

Trzy odczyty, od których zaczyna się każda rozmowa o ekspozycji sieciowej instancji.

openclaw config get gateway.bind
openclaw config get gateway.port
openclaw gateway status --deep --json

Dlaczego -p 18789:18789 nie wystarcza w Dockerze

W kontenerze domyślny loopback oznacza 127.0.0.1 wewnątrz kontenera, a nie na Twoim hoście. Przy zwykłym mapowaniu -p 18789:18789 ruch przychodzi na interfejs kontenera, gateway nasłuchuje wyłącznie na pętli zwrotnej i połączenie nie dochodzi. Nie ma trybu, który włączy się sam po wykryciu kontenera, gateway.bind trzeba zmienić świadomie i od razu dołożyć uwierzytelnianie.

Dlatego oficjalny skrypt ./scripts/docker/setup.sh ustawia bind na lan i przy okazji generuje token podczas onboardingu. Konsekwencja jest prosta: skoro proces musi nasłuchiwać poza pętlą, auth przestaje być opcjonalne. Dashboard otwierasz potem pod http://127.0.0.1:18789/ z wygenerowanym tokenem. Obrazy oficjalne to ghcr.io/openclaw/openclaw:latest jako główne źródło i openclaw/openclaw:latest jako lustro na Docker Hubie.

Druga część pułapki jest sieciowa i kosztuje więcej. Publikowanie portów przez -p przepuszcza ruch przez łańcuchy forwardowania Dockera, a nie tylko przez INPUT hosta. Twoje reguły UFW mogą wyglądać na szczelne i nie łapać niczego, bo decyzja zapada w łańcuchu DOCKER-USER. Dokumentacja pokazuje przykładowy zestaw reguł dla tego łańcucha (przepuszczone 80, 443 i SSH plus połączenia established, reszta odrzucona) oraz osobne reguły IPv6 w /etc/ufw/after6.rules.

Przy pisaniu tych reguł nie zaszywaj nazw interfejsów w rodzaju eth0. Różnią się między obrazami VPS-ów, a reguła, która nie pasuje do niczego, po cichu nie blokuje niczego. To jest ten rodzaj błędu, którego nie widać w żadnym logu, dopóki ktoś nie zeskanuje Ci portu.

Trwałość stanu zapewniają trzy podpięte katalogi: /home/node/.openclaw na config, /home/node/.config/openclaw na profile uwierzytelniania i /home/node/.openclaw/workspace na przestrzeń roboczą. Znany objaw rozjechanego właścicielstwa to komunikat „blocked plugin candidate: suspicious ownership (uid=1000, expected uid=0 or root)”. Naprawa jest krótka: sudo chown -R 1000:1000 na katalog konfiguracji i workspace, potem openclaw doctor --fix.

Oficjalny obraz i naprawa najczęstszego objawu rozjechanych uprawnień w kontenerze.

docker pull ghcr.io/openclaw/openclaw:latest
# gdy plugin nie chce się załadować w kontenerze:
sudo chown -R 1000:1000 <config> <workspace>
openclaw doctor --fix

Uwierzytelnianie Gatewaya jest fail-closed, ustaw je świadomie

Uwierzytelnianie jest wymagane domyślnie i działa fail-closed: bez poprawnie skonfigurowanej ścieżki auth gateway odmawia połączeń WebSocket. Gateway odmawia bindowania bez skonfigurowanego auth, a w logu zostawia wtedy „refusing to bind gateway without auth”. Tryb ustawia gateway.auth.mode i przyjmuje wartości none, token, password oraz trusted-proxy.

Zalecany jest tryb token, czyli współdzielony bearer token w gateway.auth.token. Nie wymyślaj go sam, openclaw doctor --generate-gateway-token zrobi to za Ciebie. Odpowiedniki środowiskowe to OPENCLAW_GATEWAY_TOKEN i OPENCLAW_GATEWAY_PASSWORD, przy czym hasło lepiej trzymać właśnie w zmiennej niż w pliku konfiguracyjnym.

Tryb trusted-proxy ma dwie pułapki, na które dokumentacja zwraca uwagę osobno. Pierwsza: Twoje proxy musi nadpisywać nagłówek X-Forwarded-For, a nie dopisywać do niego kolejne wartości, inaczej klient sam podstawi sobie tożsamość. Druga: reverse proxy stojące na pętli zwrotnej musi mieć jawnie ustawione gateway.auth.trustedProxy.allowLoopback na true, bez tego i tak wymagany jest token albo hasło. Tożsamość przychodzi nagłówkiem wskazanym w userHeader.

Webhooki i hooki uwierzytelniają się nagłówkiem Authorization: Bearer albo x-openclaw-token. Audyt ma na to osobny check hooks.token_reuse_gateway_token, bo używanie tego samego sekretu do gatewaya i do hooków oznacza, że rotacja jednego wymusza rotację drugiego, a zwykle zapomina się o tym drugim. Drugi check z tej rodziny, hooks.allowed_agent_ids_unrestricted, wyłapuje hooki, które mogą trafić do dowolnego agenta.

Jedna rzecz proceduralna, o którą wszyscy się potykają: zmiana portu i zmiana ustawień uwierzytelniania to zmiany infrastrukturalne. Hot reload ich nie podniesie. Po edycji trzeba zrestartować gateway, inaczej będziesz debugować konfigurację, która jeszcze nie działa.

Wygenerowanie tokenu, przełączenie trybu i restart, bo zmiana auth nie wchodzi przez hot reload.

openclaw doctor --generate-gateway-token
openclaw config set gateway.auth.mode token
openclaw gateway restart

Sekrety mają leżeć na hoście gatewaya, nie w workspace

Zasada, którą dokumentacja formułuje najkrócej: zakładaj, że cokolwiek leży pod ~/.openclaw, może zawierać sekrety albo dane prywatne. Stąd konkretne uprawnienia. 600 na ~/.openclaw/openclaw.json, 700 na sam katalog ~/.openclaw, 600 na wszystko w ~/.openclaw/credentials oraz 600 na ~/.openclaw/state/openclaw.sqlite, gdzie siedzą tokeny MCP i stan runtime.

Poświadczenia dostawców modeli nie mają prawa leżeć w pliku .env wewnątrz workspace agenta. Ich miejsce to środowisko procesu gatewaya, globalny dotenv albo config. Powód jest prozaiczny: workspace projekt zaleca trzymać w prywatnym repozytorium git, a narzędzia agenta czytają go swobodnie. Klucz w tym katalogu to klucz w historii commitów.

Sekrety wczytywane są z trzech źródeł w ustalonej kolejności: zmienne procesu rodzica, plik .env z bieżącego katalogu roboczego, na końcu globalny ~/.openclaw/.env jako fallback. W samym configu działają podstawienia ${NAZWA_ZMIENNEJ} wewnątrz stringów, ale tylko dla nazw pisanych wielkimi literami. Gdy gateway chodzi jako usługa systemowa i nie widzi zmiennych użytkownika, ratuje OPENCLAW_LOAD_SHELL_ENV=1.

Katalogu ~/.openclaw nie wrzucaj do repozytorium nigdy. Są tam poświadczenia kanałów, tokeny OAuth, transkrypty sesji i zaszyfrowane payloady sekretów. Workspace i katalog stanu to dwie osobne lokalizacje, obie wymagają kopii, ale tylko jedna nadaje się do gita.

Przy zgłoszeniach do wsparcia i przy migracji przydaje się nawyk sprawdzania obecności tokenu bez wypisywania jego wartości. Do samego zgłoszenia lepiej nadaje się openclaw status --all, to diagnoza tylko do odczytu z ogonem logów i zredagowanymi tokenami.

Zalecane uprawnienia katalogu stanu i pakiet diagnostyczny, w którym tokeny są już zredagowane.

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod -R 600 ~/.openclaw/credentials
openclaw status --all

Sandbox ogranicza zasięg błędu, ale nie zastępuje polityki narzędzi

Sandbox oddziela wykonywanie narzędzi od procesu gatewaya i domyślnie jest wyłączony. Włączasz go w agents.defaults.sandbox globalnie albo w agents.entries.*.sandbox dla pojedynczego agenta. Trzy ustawienia sterują całością: sandbox.mode przyjmuje off, non-main i all (domyślnie off), sandbox.scope przyjmuje agent, session i shared (domyślnie agent), a sandbox.backend to docker, ssh albo openshell (domyślnie docker). Wariantu shared lepiej unikać.

Dostęp sandboxa do workspace ustawia workspaceAccess. Wartość none jest domyślna i daje narzędziom tylko workspace sandboxa, ro montuje workspace agenta do odczytu pod /agent, a rw daje zapis pod /workspace. Backend dockerowy startuje z restrykcyjnymi wartościami: network ustawiony na none, czyli brak ruchu wychodzącego, readOnlyRoot włączone i zrzucone capability. Obraz sandboxa budujesz skryptem scripts/sandbox-setup.sh, a w instalacji dockerowej włącza go OPENCLAW_SANDBOX=1 przed uruchomieniem setup.sh.

Dokumentacja nie udaje, że sandbox jest granicą bezpieczeństwa. Ogranicza dostęp do plików i procesów, gdy model zrobi coś głupiego, i na tym kończy się jego rola (sam gateway zostaje poza nim. Osobne wyjście awaryjne stanowi tools.elevated) uruchamia exec poza sandboxem i obchodzi całą tę warstwę. Trzymaj tools.elevated.enabled na false, a jeśli musisz go włączyć, tools.elevated.allowFrom ma być wąskie.

Twarda podstawa na start wygląda tak: gateway.mode local, gateway.bind loopback, gateway.auth.mode token, session.dmScope ustawione na per-channel-peer, tools.profile na messaging, tools.fs.workspaceOnly na true, tools.exec.security na deny i tools.exec.ask na always, tools.elevated.enabled na false. Do tego dmPolicy pairing na kanałach i requireMention w grupach.

Po stronie kanałów są dwa szczegóły, które lubią zaskakiwać. Tryb dmPolicy „open” wymaga jawnego wpisu „*” na allowliście kanału, bez niego wiadomości nadal będą blokowane. A w grupach działa groupAllowFrom; allowFrom pełni tam tylko rolę fallbacku. Ustawienie samego allowFrom i zdziwienie, że nic nie przechodzi, to klasyk.

Fragment ~/.openclaw/openclaw.json w JSON5: sandbox na każdej sesji plus zamknięta polityka narzędzi.

{
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "agent", backend: "docker", workspaceAccess: "none" }
    }
  },
  tools: {
    profile: "messaging",
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false }
  }
}

openclaw security audit robi to, czego nie chce Ci się sprawdzać ręcznie

Zamiast przechodzić powyższą listę z pamięci, odpal openclaw security audit. Komenda wykonuje ponad 80 sprawdzeń, każde z własnym identyfikatorem checkId i przypisaną wagą: critical, warn albo info. Przy każdym znalezisku widać też, czy istnieje automatyczna naprawa.

Zakres pokrywa dokładnie te miejsca, w których ludzie się mylą. Uprawnienia plików łapią fs.state_dir.perms_world_writable i fs.config.perms_writable. Ekspozycję sieciową i brak auth, gateway.bind_no_auth, gateway.http.no_auth oraz gateway.tailscale_funnel. Control UI, gateway.control_ui.allowed_origins_required i gateway.control_ui.device_auth_disabled. Sandbox, sandbox.dangerous_bind_mount i sandbox.dangerous_network_mode. Politykę wykonywania poleceń, tools.exec.security_full_configured. A dostępność narzędzi z otwartych kanałów: security.exposure.open_channels_with_exec.

Flaga --deep dokłada żywe sondowanie gatewaya i kolektory bezpieczeństwa pluginów, w tym checki plugins.code_safety i skills.code_safety szukające podejrzanych wzorców w kodzie. Do sondowania trzeba podać poświadczenia: --deep --token <token> albo --deep --password <hasło>. Wyjście maszynowe daje --json.

Flaga --fix jest celowo wąska i to jej zaleta. Stosuje naprawy deterministyczne: zaciska uprawnienia do 600 na plikach i 700 na katalogach oraz przestawia otwarte polityki grupowe na allowlisty. Nie rotuje poświadczeń i nie wyłącza narzędzi, takie decyzje zostają po Twojej stronie. Jeśli świadomie akceptujesz jakieś ryzyko, zapisz to w security.audit.suppressions, zamiast uczyć się ignorować czerwony wynik.

Praktyczny moment na uruchomienie audytu jest jeden: przed każdą zmianą ekspozycji sieciowej albo polityki dostępu. Nie po. Różnica polega na tym, że przed zmianą naprawiasz konfigurację, a po zmianie już tylko odtwarzasz, co się wydarzyło.

Audyt podstawowy, wersja z sondowaniem gatewaya, automatyczne naprawy i wyjście maszynowe do CI.

openclaw security audit
openclaw security audit --deep --token <token>
openclaw security audit --fix
openclaw security audit --json

Kopia zapasowa i plan na noc, w której coś wycieknie

Kopię robisz komendą openclaw backup create z flagą --verify, która waliduje archiwum od razu po utworzeniu. Obejmuje katalog stanu, aktywny plik konfiguracyjny, katalog credentials, katalogi workspace, profile uwierzytelniania, stan sesji i bazy SQLite. Bazy zrzucane są przez online backup API SQLite i kompaktowane przez VACUUM, więc gatewaya nie trzeba zatrzymywać.

Przydatne flagi: --dry-run do podglądu, --json do wyjścia maszynowego, --no-include-workspace, gdy workspace i tak żyje w gicie, oraz --only-config, gdy chcesz zapisać sam plik konfiguracyjny. Flaga --agent <id> nie należy do backup create, używa się jej przy openclaw backup sqlite create. Podkomendy create, list, verify i restore wskazują repozytorium snapshotów flagą --repository <katalog> i to ona jest tam obowiązkowa.

Plan na incydent ma trzy fazy i dobrze mieć go zapisany, zanim będzie potrzebny. Powstrzymanie: zatrzymujesz gateway, ustawiasz gateway.bind na loopback, wyłączasz ryzykowne polityki DM i grup. Rotacja: zmieniasz gateway.auth.token, gateway.remote.token oraz poświadczenia dostawców. Przegląd: czytasz openclaw logs, transkrypty sesji z ~/.openclaw/agents/<agentId>/sessions/ oraz ostatnie zmiany w konfiguracji.

Odrzucone konfiguracje zostają obok pliku jako openclaw.json.rejected.<timestamp>, a nadpisane jako *.clobbered.*. Gateway przyjmuje wyłącznie pliki w pełni zgodne ze schematem, więc literówka nie nadpisze działającej wersji. Do przywrócenia ostatniej znanej dobrej kopii służy openclaw doctor --fix.

Jeśli utrzymywanie tej warstwy samodzielnie nie jest pracą, którą chcesz wykonywać, istnieje wariant chmurowy: ClawLabs uruchamia instancję OpenClaw w chmurze EU (Hetzner), z własnymi kluczami API w modelu BYOK i DPA na żądanie, plany od 399 zł miesięcznie. Sam OpenClaw jest darmowy i otwarty, więc wybór sprowadza się do tego, kto ma pilnować portów, tokenów i kopii.

Kopia z natychmiastową weryfikacją, przegląd repozytorium snapshotów SQLite i przywrócenie ostatniej działającej konfiguracji.

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw backup sqlite list --repository ~/Backups/openclaw-sqlite
openclaw doctor --fix

Co warto zapamiętać

Domyślny gateway.bind to loopback, a w kontenerze oznacza to 127.0.0.1 wewnątrz kontenera, przy zwykłym -p 18789:18789 gateway pozostaje nieosiągalny, dopóki nie zmienisz bindu i nie dołożysz uwierzytelniania.
Publikowanie portu przez -p omija reguły INPUT hosta: decyzje zapadają w łańcuchu DOCKER-USER, a reguły IPv6 trzeba dopisać osobno w /etc/ufw/after6.rules.
gateway.auth.mode przyjmuje none, token, password i trusted-proxy; token generuje openclaw doctor --generate-gateway-token, a proxy musi nadpisywać X-Forwarded-For, nie dopisywać do niego.
Uprawnienia z dokumentacji: 700 na ~/.openclaw, 600 na openclaw.json, 600 na ~/.openclaw/credentials/** i 600 na ~/.openclaw/state/openclaw.sqlite, gdzie leżą tokeny MCP.
Sandbox jest domyślnie wyłączony; sandbox.mode ma wartości off, non-main i all, scope domyślnie agent, backend domyślnie docker, workspaceAccess domyślnie none. tools.elevated omija sandbox całkowicie.
openclaw security audit wykonuje ponad 80 sprawdzeń z identyfikatorami takimi jak gateway.bind_no_auth czy sandbox.dangerous_network_mode; --fix zaciska uprawnienia do 600/700 i zamienia otwarte polityki grup na allowlisty, ale nie rotuje poświadczeń.

Częste pytania

Uruchomiłem OpenClaw w Dockerze z -p 18789:18789 i nie mogę wejść na dashboard. Co jest nie tak?+

Prawie na pewno bind. Domyślny loopback oznacza 127.0.0.1 wewnątrz kontenera, a ruch z mapowania portu przychodzi na interfejs kontenera, więc nikt go nie odbiera. Trzeba świadomie zmienić gateway.bind i od razu włączyć uwierzytelnianie, bo bez auth gateway odmówi bindowania poza pętlą. Oficjalny skrypt ./scripts/docker/setup.sh robi obie rzeczy naraz: ustawia bind na lan i generuje token podczas onboardingu.

Mam UFW i przepuszczone tylko 22, 80 i 443. Czy port 18789 z kontenera jest zablokowany?+

Niekoniecznie. Publikowanie portów przez -p przepuszcza ruch przez łańcuchy forwardowania Dockera, a nie tylko przez INPUT hosta, więc reguły UFW mogą go w ogóle nie dotykać. Reguły trzeba dopisać w łańcuchu DOCKER-USER, a dla IPv6 osobno w /etc/ufw/after6.rules. Przy pisaniu nie zaszywaj nazw interfejsów w rodzaju eth0: różnią się między obrazami VPS-ów, a reguła, która nie pasuje, po cichu niczego nie blokuje.

Czy sandbox wystarczy, żeby agent nie zrobił szkód na serwerze?+

Nie wystarczy sam z siebie. Dokumentacja opisuje sandbox jako mechanizm, który realnie ogranicza dostęp do plików i procesów, ale nie jest doskonałą granicą bezpieczeństwa. Sam gateway działa poza sandboxem, a tools.elevated uruchamia exec z jego pominięciem. Sandbox trzeba więc łączyć z polityką narzędzi: tools.profile, tools.fs.workspaceOnly, tools.exec.security oraz tools.elevated.enabled ustawione na false.

Co zrobić najpierw, gdy podejrzewam, że ktoś dostał się do instancji?+

Trzy fazy w tej kolejności. Powstrzymanie: zatrzymaj gateway, ustaw gateway.bind na loopback, wyłącz ryzykowne polityki DM i grup. Rotacja: zmień gateway.auth.token, gateway.remote.token oraz poświadczenia dostawców modeli i kanałów. Przegląd: przejrzyj openclaw logs, transkrypty sesji w ~/.openclaw/agents/<agentId>/sessions/ i ostatnie zmiany konfiguracji. Dopiero potem wracaj do normalnej ekspozycji.

Źródła danych z tej lekcji

Krok 2Ćwiczenie do wykonaniaTeoria bez ćwiczenia zostaje wiedzą, której nie używasz.

Chcesz to przećwiczyć na żywo?

Uruchom własnego agenta i wypróbuj to, o czym przed chwilą przeczytałeś. Pierwsza subskrypcja pakietu Premium ma 5 dni za darmo, a kurs czytasz dalej niezależnie od tego.

Zobacz plany