Jak uruchomić Claude Code headless (tryb -p, bez interakcji)

Claude Code

Jak uruchomić Claude Code headless (tryb -p, bez interakcji)

W skrócie

Claude Code, oficjalne narzędzie CLI od Anthropic do programowania z AI, w codziennej pracy używamy jako interaktywnego asystenta w terminalu. Ale ten sam program potrafi też działać w trybie bezobsługowym (headless) - jednorazowo wykonać polecenie, wypisać wynik na standardowe wyjście i zakończyć się. To ten tryb pozwala wpiąć Claude Code w skrypt bash, zadanie crona albo krok w pipelinie CI. Problem w tym, że domyślnie narzędzie zakłada, że siedzisz przed klawiaturą, więc w potoku trzeba mu jawnie powiedzieć, żeby nie czekał na człowieka.

Jak to wygląda w praktyce

Wpisujesz w skrypcie zwykłe claude i licząc na wynik dostajesz zawieszony proces. W terminalu narzędzie rysuje kolorowy interfejs czatu i miga kursorem w oczekiwaniu na Twoje pytanie, a w środowisku bez terminala (na przykład w runnerze CI) proces stoi w miejscu, aż zadanie padnie na limicie czasu. Jeszcze częstszy objaw to zatrzymanie w połowie: Claude Code chce coś zapisać albo uruchomić komendę, wyświetla pytanie o zgodę i czeka - a w potoku nie ma komu tej zgody kliknąć. Skrypt wisi, a Ty widzisz tylko pusty log.

Dlaczego Claude Code tak działa

To celowa różnica dwóch trybów pracy. Bez dodatkowych flag Claude Code startuje jako REPL - interaktywna pętla, w której człowiek zadaje pytania, a narzędzie odpowiada i po każdej ryzykownej operacji prosi o potwierdzenie. Taki model jest bezpieczny przy pracy z człowiekiem, ale zabójczy dla automatyzacji, bo zakłada, że ktoś odpowie. W trybie bezobsługowym narzędzie oznacza sesję jako nieinteraktywną, nie rysuje interfejsu i nie zwraca się do nikogo - musi jednak wiedzieć z góry, co wolno mu zrobić bez pytania i w jakim formacie ma oddać wynik. Dlatego samo claude nie wystarczy; potrzebne są flagi, które te decyzje podejmą za Ciebie.

Jak to rozwiązać krok po kroku

1. Podaj polecenie po fladze -p (skrót od --print). To przełącza narzędzie w tryb jednorazowy: wykonuje zadanie, wypisuje odpowiedź na standardowe wyjście i kończy się. Przykład: claude -p "wypisz w punktach, co robi ten skrypt" < deploy.sh.
2. Wybierz format wyjścia flagą --output-format. Wartość text daje czysty tekst dla człowieka, a json - ustrukturyzowaną odpowiedź, którą łatwo sparsować w dalszych krokach pipelinu. Do skryptów zwykle wygodniejszy jest json.
3. Rozstrzygnij uprawnienia z wyprzedzeniem. Wypisz narzędzia, których wolno użyć bez pytania, flagą --allowedTools (na przykład --allowedTools "Read,Grep,Glob" dla samego czytania kodu). Dzięki temu Claude Code nie zatrzyma się na prośbie o zgodę.
4. Ustaw tryb uprawnień flagą --permission-mode, jeśli potrzebujesz czegoś więcej niż domyślne reguły - to on decyduje, jak narzędzie traktuje operacje spoza listy dozwolonych.
5. Na hostach zupełnie bez nadzoru dołóż --permission-prompts none. Wtedy wszystko, co normalnie wywołałoby pytanie o zgodę, zostaje automatycznie odrzucone, zamiast wieszać proces - a aktywny tryb uprawnień nadal decyduje o reszcie.
6. Odbierz wynik ze standardowego wyjścia. W bashu podstaw go do zmiennej: WYNIK=$(claude -p "streszcz zmiany" --output-format text) i użyj dalej w skrypcie.
7. Uzależnij kolejne kroki od kodu wyjścia. Claude Code zwraca zero przy sukcesie i wartość niezerową przy błędzie, więc w pipelinie możesz przerwać budowę, gdy zadanie się nie powiodło.

Jak sprawdzić, że zadziałało

Uruchom polecenie ręcznie w terminalu i obserwuj, czy narzędzie od razu wypisuje odpowiedź i wraca do znaku zachęty, zamiast otwierać kolorowy czat. Podstaw wynik do zmiennej i wypisz go - powinien zawierać samą treść odpowiedzi, a przy --output-format json poprawny obiekt JSON. Sprawdź kod wyjścia komendą echo $? tuż po uruchomieniu: zero oznacza sukces. Na koniec odpal ten sam skrypt w środowisku bez terminala (na przykład przekierowując wejście z /dev/null) i upewnij się, że nie wisi na pytaniu o zgodę - jeśli przechodzi bez zatrzymania, tryb bezobsługowy działa poprawnie.

Wróć do listy: 100 najczęstszych problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5