Jak zbudować agenta AI typu OpenClaw

Czym w rzeczywistości jest OpenClaw

OpenClaw to osobisty agent AI typu self-hosted. Użytkownik uruchamia go na własnym serwerze, łączy z używanymi aplikacjami czatowymi, a agent może wykonywać polecenia shell, kontrolować przeglądarkę, odczytywać i zapisywać pliki oraz reagować na przesyłane wiadomości. Produkt posiada licencję MIT, działa w modelu local-first i posiada ponad 380 000 gwiazdek w serwisie GitHub (stan na połowę 2026 roku), co czyni go jednym z najbardziej popularnych projektów na tej platformie. Pod warstwą skomplikowanych funkcji kryje się stosowo prostych komponentów połączonych w logiczny sposób. Niniejszy wpis opisuje te komponenty, aby wyjaśnić strukturę takiego narzędzia oraz wskazać potencjalne zagrożenia.

Ważne ostrzeżenie: w marcu 2026 roku w OpenClaw wykryto dziewięć luk bezpieczeństwa w ciągu czterech dni, w tym krytyczną lukę eskalacji uprawnień o ocenie 9.9/10 (CVE-2026-32922). Projekt wymaga samodzielnego zabezpieczenia przez operatora. Agent zdolny do wykonywania dowolnych poleceń jest tak bezpieczny, jak system, na którym pracuje, oraz jak nałożone na niego ograniczenia. Należy o tym pamiętać podczas lektury.

Daemon bramy (gateway): jeden proces, prywatna komunikacja

Centralnym elementem jest pojedynczy, długotrwały proces, nazywany bramą (gateway). Stanowi on warstwę kontrolną (control plane). Odbiera wiadomości, podejmuje decyzje, uruchamia narzędzia i wysyła odpowiedzi. Wszystkie pozostałe komponenty są do niego podłączone.

Kluczową kwestią dotyczącą bramy jest adres, na którym nasłuchuje. Domyślnie OpenClaw wiąże proces z adresem loopback, 127.0.0.1, co uniemożliwia dostęp z internetu, chyba że użytkownik celowo go wystawi. Zaleca się pozostawienie tej konfiguracji. Ponieważ proces ten służy do wykonywania poleceń, wystawienie bramy na świat daje każdemu znalazcy zdalny dostęp do serwera. W celu połączenia z laptopem należy używać sieci VPN lub tunelu SSH zamiast otwierania portów. Port, do którego nie można się połączyć, nie może zostać zaatakowany.

Konektory kanałów: odbieranie wiadomości i wysyłanie odpowiedzi

Osobisty agent jest użyteczny tylko wtedy, gdy można się z nim komunikować za pomocą istniejących aplikacji. Do tego służą konektory kanałów. Każdy z nich obsługuje jedną platformę (np. Telegram, WhatsApp, Slack lub Discord) przy użyciu API bota lub webhooków danej platformy.

Struktura wszystkich konektorów jest identyczna. Konektor rejestruje bota w platformie, odbiera przychodzącą wiadomość (poprzez odpytywanie platformy lub odbiór webhooka), przekazuje wiadomość do bramy, a następnie wysyła odpowiedź bramy z powrotem przez to samo API. Konektor stanowi cienką warstwę translacji. Przekształca zdarzenie „nadeszła wiadomość z Telegrama” na „oto tekst dla agenta” i odwrotnie. Stworzenie własnego konektora wymaga jedynie analizy dokumentacji API danej platformy i zmapowania formatu wiadomości na format bramy.

Mózg i pętla narzędziowa

Wewnątrz bramy znajduje się element, który odróżnia agenta od prostego chatbota. Jest to pętla (loop).

Po nadejściu wiadomości brama przesyła ją do modelu językowego wraz z listą narzędzi dostępnych do użycia. Model analizuje wiadomość i decyduje: odpowiedzieć bezpośrednio lub wywołać narzędzie. Jeśli model wybierze narzędzie, brama je uruchamia, przechwytuje wynik i odsyła go do modelu. Model analizuje wynik i ponownie podejmuje decyzję. Proces powtarza się, aż model nie będzie miał już dalszych zadań i wygeneruje końcową odpowiedź.

Ta pętla stanowi istotę działania agenta, niezależnie od tego, czy działa on w aplikacji czatowej, czy w terminalu. Aby dowiedzieć się więcej o standardowym sposobie podłączania narzędzi do tej pętli, należy przeczytać connecting tools through the Model Context Protocol, a w kwestii obsługi modelu zaleca się running the model itself on your own hardware.

Zestaw narzędzi jako kluczowy element i źródło zagrożeń

Narzędzia stanowią o potędze OpenClaw. Są to narzędzia do wykonywania poleceń shell, sterowania przeglądarką oraz odczytywania i zapisywania plików. Zapewnienie pętli dostępu do tych funkcji pozwala agentowi na wykonywanie niemal wszystkich operacji dostępnych użytkownikowi przy klawiaturze. Ten zakres możliwości jest jednocześnie głównym produktem, jak i głównym ryzykiem.

Agent zdolny do wykonywania dowolnych poleceń na podstawie instrukcji z aplikacji czatowej tworzy dużą powierzchnię ataku. Błędna instrukcja, atak typu prompt-injection ukryty na stronie internetowej lub błąd oprogramowania (jak te z marca 2026 roku) mogą zmienić polecenie „przeczytaj mój kalendarz” na „usuń moje pliki”. Ograniczenia nie są opcjonalne. Należy uruchamiać agenta jako dedykowanego, nieuprzywilejowanego użytkownika bez uprawnień sudo, aby uniemożliwić eskalację uprawnień w przypadku przejęcia kontroli. Należy wprowadzić etap zatwierdzania dla niebezpiecznych narzędzi, aby agent prosił o zgodę przed wykonaniem destrukcyjnych działań. Należy stosować piaskownicę (sandbox) dla wykonywanych narzędzi, aby ograniczyć skutki błędnych poleceń. Należy izolować klucze API modelu, aby ich wyciek nie umożliwił atakującemu przejęcia konta.

Przed wystawieniem jakichkolwiek funkcji wykonujących polecenia shell, należy rzetelnie przeprowadzić konfigurację podstawową. Poniżej znajduje się lista kontrolna dla własnego systemu:

Szczegółowe informacje o pracy na nieuprzywilejowanym użytkowniku znajdują się w running services as an unprivileged user, a pełny przewodnik po bezpiecznej konfiguracji dla rzeczywistego projektu znajduje się w running OpenClaw safely on a VPS.

Pamięć w formie plików tekstowych

Większość użytkowników oczekuje, że pamięć agenta będzie przechowywana w bazie danych. OpenClaw przechowuje ją inaczej. Pamięć jest zapisywana jako zwykłe pliki Markdown na dysku, co jest rozwiązaniem godnym polecenia.

Pliki są proste. Nie wymagają migracji schematów, utrzymywania usług ani nauki języka zapytań. Są w pełni inspekcyjne: można otworzyć folder i odczytać, co agent wie o użytkowniku, skorygować błędną informację poprzez edycję pliku lub usunąć pamięć poprzez usunięcie pliku. Są również przenośne – przeniesienie agenta na nowy serwer wymaga jedynie skopiowania katalogu. Dla osobistego agenta dla jednego użytkownika folder plików tekstowych jest wystarczający i zapewnia przejrzystość systemu.

Umiejętności (Skills): przenośny sposób rozszerzania funkcji

Poza wbudowanymi narzędziami, OpenClaw wykorzystuje przenośny format umiejętności (skills), co pozwala społeczności rozszerzać funkcjonalność bez modyfikacji rdzenia systemu. Umiejętność to samowystarczalny pakiet instrukcji, a czasem kodu, który uczy agenta nowego zadania. Agent ładuje umiejętność w momencie, gdy wymaga tego zadanie.

Zastosowanie takiego formatu pozwala na udostępnianie nowych funkcji. Użytkownik może pobrać gotową umiejętność stworzoną przez kogoś innego. Przy projektowaniu własnego agenta, zdefiniowanie jasnego formatu rozszerzeń na wczesnym etapie zapobiega konieczności hardkodowania każdej funkcji w rdzeniu systemu.

Własny model językowy

OpenClaw jest niezależny od modelu (model-agnostic). Nie zawiera własnego modelu językowego. Zamiast tego łączy się z wybranym modelem, który może być dostępny przez API lub uruchamiany lokalnie.

Ten podział ma znaczenie dla kosztów, prywatności i kontroli. API zewnętrznego dostawcy zapewnia dostęp do najsilniejszych modeli bez konieczności zarządzania sprzętem, ale wiąże się z kosztami za tokeny i przesyłaniem zapytań poza serwer. Model hostowany samodzielnie (np. za pomocą Ollama) zapewnia pełną prywatność danych, ale wymaga posiadania odpowiedniego sprzętu i generuje koszty energii. Można stosować oba podejścia jednocześnie. Aby zachować pełną prywatność agenta, należy rozważyć self-hosting the model on your VPS. Innym rozwiązaniem wartym porównania jest Hermes Agent.

Czy warto budować własny system?

Można zbudować wszystkie wymienione komponenty. Są to standardowe elementy: daemon, konektory czatowe, pętla modelu i narzędzi, folder z plikami Markdown oraz format wtyczek. Zrozumienie tych elementów jest przydatne, ponieważ pozwala zrozumieć działanie każdego agenta i wskazuje miejsca potencjalnych zagrożeń.

Jednak dla większości użytkowników najbardziej rozsądnym rozwiązaniem jest uruchomienie gotowego, sprawdzonego rozwiązania i jego odpowiednie zabezpieczenie, zamiast budowania systemu od nowa. OpenClaw posiada już gotowe konektory, pętlę oraz format umiejętności i przeszedł testy bezpieczeństwa. Warto poświęcić czas na konfigurację i zabezpieczenie agenta na własnym serwerze. Własne, małe projekty warto budować w celach edukacyjnych, natomiast do codziennego użytku należy stosować gotowe, zabezpieczone rozwiązania.

Podstawy teoretyczne opisano w building your own AI agent on a VPS, natomiast building an agent with Claude prezentuje te same koncepcje przy użyciu konkretnego modelu.

FAQ

Czy budowa agenta typu OpenClaw jest trudna?

Pojedyncze komponenty nie są trudne. Proces bramy, konektor czatowy, pętla modelu i narzędzi oraz folder z plikami są proste w implementacji. Trudne jest bezpieczne połączenie ich w całość. Agent wykonujący polecenia shell na podstawie wiadomości czatowych stanowi poważne zagrożenie bezpieczeństwa. Poprawne skonfigurowanie piaskownicy (sandbox), uprawnień i użytkownika nieuprzywilejowanego wymaga więcej pracy niż samo połączenie funkcji.

Dlaczego OpenClaw przechowuje pamięć w plikach Markdown zamiast w bazie danych?

Ponieważ dla osobistego agenta dla jednego użytkownika pliki są wystarczające i znacznie prostsze. Nie wymagają uruchamiania usługi bazy danych, pozwalają na łatwą ręczną edycję i ułatwiają przenoszenie agenta na inny serwer poprzez skopiowanie katalogu. Bazy danych są rozwiązaniem dla większej skali, a nie dla tego przypadku.

Co jest najbardziej niebezpiecznym elementem osobistego agenta AI?

Narzędzia umożliwiające działanie: wykonywanie poleceń shell, sterowanie przeglądarką i zapisywanie plików. To one stanowią powód, dla którego tworzy się agentów, ale to one również mogą wyrządzić szkodę. Incydent bezpieczeństwa OpenClaw z marca 2026 roku (dziewięć luk w cztery dni, w tym jedna krytyczna o ocenie 9.9) pokazuje, że warstwa narzędzi wymaga szczególnej uwagi: należy używać nieuprzywilejowanego użytkownika, zatwierdzać destrukcyjne akcje i stosować piaskownicę.

Czy do budowy agenta potrzebuję własnego modelu językowego?

Nie. Agenci tacy jak OpenClaw są niezależni od modelu, więc można wybrać dowolny. Może to być zewnętrzne API dla najsilniejszych modeli lub model uruchamiany lokalnie dla zachowania pełnej prywatności. Samodzielne hostowanie modelu (np. przez Ollama) zapewnia prywatność wszystkich wiadomości kosztem konieczności korzystania z mniejszego modelu.