Jak korzystać z AI OpenHands: Praktyczny przewodnik po konfiguracji, promptach i rzeczywistych workflowach
Jeśli kiedykolwiek marzyłeś o kompetentnym developerze, który mógłby programować z Tobą w parze 24/7, AI OpenHands jest uderzająco bliski temu ideałowi. To open-source'owy "inżynier AI", który potrafi czytać Twoje repozytorium, pisać kod, uruchamiać terminale, przeglądać dokumentację i iterować – zupełnie jak młodszy programista, który szybko się uczy i niestrudzenie pracuje. Ale ta moc ujawnia się dopiero po poprawnej konfiguracji i nauczeniu się, jak nim sterować.
Ten przewodnik krok po kroku pokaże Ci, jak korzystać z AI OpenHands – od instalacji po zaawansowane workflowy – dzięki czemu będziesz mógł szybciej i pewniej dostarczać projekty.
- Opcje instalacji i szybki start
- Uruchamianie OpenHands lokalnie lub z modelami chmurowymi
- Najlepsze praktyki dotyczące promptów, repozytoriów i zadań
- Sprawdzone workflowy dla prac nad funkcjami, debugowania, testów i dokumentacji
- Mechanizmy kontrolne, prywatność i współpraca
Warto zauważyć: OpenHands jest aktywnie rozwijany przez zespół All Hands i społeczność. Oficjalna dokumentacja jest Twoją gwiazdą polarną, jeśli chodzi o aktualne instrukcje i wskazówki. Możesz również śledzić praktyczne przewodniki instalacyjne od praktyków, którzy udokumentowali konfiguracje lokalne i na maszynach wirtualnych. W przypadku uruchamiania z lokalnymi modelami dokumentacja zawiera również szczegółowe wskazówki.
Czym jest AI OpenHands – i dlaczego warto go używać?
Pomyśl o AI OpenHands jako o koledze z zespołu AI z klawiaturą. W przeciwieństwie do asystentów opartych wyłącznie na czacie, OpenHands potrafi:
- Otwierać i czytać pliki projektu
- Używać terminala do uruchamiania poleceń, testów i linterów
- Edytować kod w różnych plikach i katalogach
- Przeglądać sieć (w zależności od konfiguracji)
- Proponować i stosować plany krok po kroku
Dzięki temu idealnie nadaje się do zadań takich jak implementacja funkcji, naprawianie błędów, pisanie testów, tworzenie dokumentacji, refaktoryzacja i modernizacja codebase'ów. Zamiast żonglować promptami i kopiować/wklejać, dajesz OpenHands cel i pozwalasz mu iterować, nadzorując jego ruchy.
Szybki start: Najszybszy sposób na użycie OpenHands
Istnieje kilka sposobów na rozpoczęcie. Twój wybór zależy od tego, czy chcesz używać chmurowego LLM, czy uruchamiać wszystko lokalnie.
Opcja A: Użyj chmurowego LLM (najłatwiejsza)
- Postępuj zgodnie z oficjalną dokumentacją "Start Building" i "Getting Started", aby zainstalować i uruchomić aplikację. Zazwyczaj będziesz musiał:
- Zainstalować wymagania wstępne (Docker, Node, Python, Git w zależności od ścieżki)
- Podać klucz API dla obsługiwanego modelu chmurowego (np. OpenAI, Anthropic lub inne, które projekt obsługuje w danym momencie)
- Uruchomić interfejs OpenHands i podłączyć swoje repozytorium
Ta ścieżka szybko zapewni Ci produktywność przy minimalnym narzucie obliczeniowym.
Opcja B: Uruchom OpenHands z lokalnym LLM
- Jeśli wolisz przechowywać kod i prompty poza chmurą lub chcesz uniknąć kosztów API, skorzystaj z przewodnika Local LLMs w oficjalnej dokumentacji.
- Skonfigurować kompatybilny model lokalny (za pośrednictwem Ollama lub innych backendów obsługiwanych w danym momencie)
- Skonfigurować punkty końcowe modelu i limity kontekstu
- Upewnić się, że Twoja maszyna ma wystarczającą ilość VRAM/CPU i miejsca na dysku
Opcja C: Wdrożenie na maszynie wirtualnej
- Jeśli potrzebujesz dedykowanego środowiska, praktycy udokumentowali, jak uruchomić OpenHands na maszynie wirtualnej i zbudować aplikację w kilka minut. Jest to przydatne dla zespołów, które chcą stabilnej, współdzielonej instancji inżyniera AI.
Pierwsze uruchomienie: Konfiguracja projektu i określenie zadania
OpenHands błyszczy, gdy widzi Twój kod. Zacznij od:
- Otworzenia repozytorium, nad którym chcesz pracować.
- Uruchomienia lub zindeksowania projektu, aby OpenHands mógł zmapować strukturę.
- Określenia jasnego celu z ograniczeniami.
Dobry przykład określenia zadania:
- "Dodaj resetowanie hasła użytkownika do usługi
auth za pomocą linków e-mail opartych na tokenach. Użyj istniejącego modułu mailer. Dodaj testy jednostkowe dla generowania i wygasania tokenów. Nie zmieniaj schematu danych użytkownika."
Dlaczego to działa:
- Określa komponent, zakres, zależności i granice. Im jaśniej to określisz, tym lepiej OpenHands planuje i wykonuje.
Jak pisać skuteczne prompty dla OpenHands
Myśl o promptach jak o zwięzłych ticketach. Najlepsze z nich:
- Definiują wynik: "Zaimplementuj X z ograniczeniami Y"
- Odwołują się do plików, modułów lub testów: "Zobacz
auth/routes.py i tests/test_auth.py"
- Określają ograniczenia: "Żadnych zmian w schemacie DB; zachowaj istniejące interfejsy"
- Zawierają kryteria akceptacji: "Testy powinny przechodzić:
pytest -k password_reset"
Szablon, którego możesz użyć ponownie:
Cel: <Co chcesz zbudować lub naprawić>
Kontekst: <Istotne pliki, znane ograniczenia, usługi zewnętrzne>
Akceptacja: <Jak wygląda pomyślne zakończenie: testy, endpointy, metryki>
Granice: <Czego nie zmieniać lub jakich podejść unikać>
Narzędzia: <Polecenia, które może uruchamiać, skrypty lub źródła danych>
Podstawowy workflow: Plan → Wykonaj → Zweryfikuj → Udoskonal
OpenHands zwykle proponuje wieloetapowy plan. Oto jak go poprowadzić:
- Zatwierdź lub dostosuj jego plan na wczesnym etapie. Zmuś go do uruchomienia testów jako pierwszych, aby określić bazowe błędy.
- Poproś go o utworzenie lub aktualizację testu, aby zdefiniować sukces, a następnie zaimplementuj kod.
- Zleć mu częste uruchamianie zestawu testów i linterów.
- Jeśli się zatrzyma, dodaj więcej kontekstu: nazwy plików, ślady stosu lub logi.
Wskazówka: Zachęcaj do małych zmian wielkości PR zamiast monolitycznych edycji. To pomaga w recenzowaniu i wycofywaniu.
Przykładowe workflowy, które możesz skopiować
1) Implementacja funkcji
- Prompt: "Dodaj eksport CSV do strony
orders. Użyj paginacji po stronie serwera, przesyłaj strumieniowo wyniki przez text/csv. Dodaj przycisk Export w OrdersTable.jsx i endpoint w routes/orders.ts. Dołącz testy dla paginacji i nagłówków."
- Skanuje repozytorium; tworzy plan
- Dodaje endpoint i przycisk klienta
- Pisze testy i je uruchamia
- Nadzorujesz, zatwierdzasz zmiany i scalasz po przejściu testów.
2) Debugowanie nieudanej kompilacji
- Prompt: "CI zawodzi na Node 20. Napraw błędy importu ESM/CJS w
build.mjs. Zachowaj istniejące wtyczki rollup; zaktualizuj konfigurację i kod, aby CI przeszedł."
- Podaj logi lub link do artefaktów CI.
- Poproś OpenHands o replikację lokalnie (
npm run build) i zaproponuj minimalne diffy.
3) Pokrycie testami i wzmacnianie
- Prompt: "Zwiększ pokrycie dla
payments/service.py z 62% do 85%+. Dodaj testy jednostkowe dla retry_charge, refund, webhook_signature. Nie modyfikuj logiki biznesowej, chyba że test ujawni błąd."
- Pozwól OpenHands generować testy, uruchamiać je i udoskonalać.
4) Dokumentacja i Developer Experience
- Prompt: "Utwórz
CONTRIBUTING.md i DEVELOPMENT.md dla tego repozytorium. Dołącz konfigurację środowiska, skrypty, polecenia testowe i wytyczne dotyczące PR."
- Zleć mu weryfikację poleceń poprzez ich faktyczne uruchomienie.
Mechanizmy kontrolne: Zadbaj o to, aby OpenHands był pomocny i bezpieczny
- Zakres katalogu: Skieruj go do określonego repozytorium lub katalogu, aby uniknąć przypadkowych edycji w innych miejscach.
- Ochrona plików: Oznacz pliki konfiguracyjne lub krytyczną infrastrukturę jako tylko do odczytu, gdzie to możliwe.
- Audyt poleceń: Wymagaj zatwierdzenia dla destrukcyjnych poleceń (np.
rm -rf, resetowanie bazy danych).
- Higiena sekretów: Nigdy nie wklejaj kluczy API do promptów. Używaj zmiennych środowiskowych i maskowanych logów.
- Dostęp do sieci: Jeśli przeglądanie jest włączone, umieść je w piaskownicy i rejestruj połączenia wychodzące.
Modele lokalne vs chmurowe: Wybór tego, co jest dla Ciebie odpowiednie
- Zalety: Silne rozumowanie/kodowanie, minimalna konfiguracja, szybka iteracja
- Wady: Bieżące koszty, kwestie zarządzania danymi
- Zalety: Prywatność, kontrola, przewidywalność kosztów
- Wady: Wymagania sprzętowe, różna jakość modeli, potrzeba większego dostrojenia
Zobacz oficjalne instrukcje Local LLMs, aby skonfigurować backendy modeli i limity pamięci.
Gra zespołowa: Używanie OpenHands we wspólnym workflow
- Workflow z podziałem na branche: Zleć OpenHands utworzenie brancha dla funkcji i wypchnięcie zmian do recenzji PR.
- Higiena commitów: Poproś go o tworzenie atomowych commitów z jasnymi komunikatami i odniesieniami do numerów zgłoszeń.
- Szablony PR: Generuj i wymuszaj szablony PR, aby recenzenci wiedzieli, co się zmieniło i dlaczego.
- Właściciele kodu: Połącz z CODEOWNERS, aby kierować PR-y generowane przez AI do odpowiednich recenzentów.
Rozwiązywanie typowych problemów
- Zacina się lub zapętla: Zawęź zakres. Poproś go o wyjaśnienie następnego kroku. Podaj nieudany test.
- Niechlujne diffy: Zażądaj mniejszego, etapowego planu — najpierw testy, a następnie minimalne zmiany w kodzie.
- Błędne edycje plików: Określ dokładne ścieżki i przypomnij mu o granicach.
- Przechodzi lokalnie, ale zawodzi w CI: Udostępnij szczegóły środowiska CI i logi; zleć mu replikację za pomocą kontenera.
Wskazówki dotyczące wydajności i zaawansowane ruchy
- Kontekst warm-start: Poproś go o przeczytanie najpierw kluczowych plików (
README, package.json, główne pliki usługowe).
- Daj mu skrypty: Udostępnij
make test lub npm run verify, aby mógł szybko zweryfikować.
- Naucz go domeny: Zaproponuj krótki przegląd architektury; opłaca się to mniejszą liczbą błędów logicznych.
- Wymuś styl: Wskaż konfiguracje
.eslintrc, .prettierrc, black/ruff, aby formatował poprawnie.
- Używaj punktów kontrolnych: Po każdym kamieniu milowym poproś o podsumowanie i kolejne kroki, aby utrzymać go na właściwej drodze.
Scenariusz z życia wzięty: Od zgłoszenia błędu do poprawki w godzinę
- Sytuacja: Błąd produkcyjny powoduje nieobsługiwane 500-tki na źle sformatowanych ładunkach JSON w API
orders.
- Twój prompt: "Odtwórz 500 na źle sformatowanym JSON w
orders POST. Dodaj walidację schematu i zwróć 400 ze szczegółami błędu. Zaktualizuj testy, aby uwzględnić źle sformatowane ładunki."
- Uruchamia API lokalnie, odtwarza błąd
- Dodaje warstwę walidacji i obsługę błędów
- Aktualizuje testy i zapewnia, że CI przechodzi
- Tworzy zwarty PR z wpisem w dzienniku zmian
Zaoszędzony czas: Skoncentrowałeś się na analizie wpływu i wdrożeniu, podczas gdy OpenHands zajął się rusztowaniem.
Integracje, które doładowują OpenHands
- Uruchamiacze testów: pytest, Jest, Vitest, JUnit
- Narzędzia do budowania: Vite, Webpack, Rollup, Babel
- Menedżery pakietów: npm, pnpm, yarn, pip/poetry
- Lintery/formatery: ESLint, Prettier, black, ruff
- Kontenery: Docker Compose dla lokalnej parzystości z CI
Standaryzując te narzędzia, OpenHands może bardziej niezawodnie rozumieć Twój stack i zautomatyzować większą część pętli programistycznej.
Przy okazji: Używanie Sider.AI obok OpenHands
Ocena trafności: 8/10. Jeśli używasz OpenHands jako inżyniera AI, warto połączyć go z kopilotem do badań i pisania, aby tworzyć specyfikacje, opisy PR i dokumentację. Przy okazji, Sider.AI może pomóc Ci szybko sporządzić specyfikacje techniczne, podsumować RFC lub przekształcić logi uruchomieniowe OpenHands w przejrzyste dzienniki zmian i informacje o wersji. To połączenie zmniejsza przełączanie kontekstu: OpenHands obsługuje działania związane z kodem, podczas gdy Sider.AI przekształca wyniki w czystą, skierowaną do użytkownika dokumentację.
Lista kontrolna bezpieczeństwa, prywatności i zgodności
- Przechowuj sekrety w zmiennych środowiskowych; nigdy nie umieszczaj kluczy w promptach
- Sprawdzaj każdą zmianę wygenerowaną przez AI, tak jak zrobiłbyś to w przypadku PR młodszego developera
- Rejestruj polecenia i działania w celu audytu
- Przypnij wersje łańcucha narzędzi; unikaj przypadkowych aktualizacji w plikach blokady
- Jeśli używasz chmurowych LLM, dopasuj się do zasad przechowywania danych
Kiedy nie używać OpenHands
- Nowe projekty algorytmów bez silnego rusztowania testowego lub specyfikacyjnego
- Wysoce regulowane codebase'y bez solidnego procesu recenzji
- Jednorazowe skrypty, w których ręczne kodowanie jest szybsze
Twoje pierwsze 60 minut z OpenHands: Mini przewodnik
- Minuta 0–10: Zainstaluj i uruchom, korzystając z oficjalnego szybkiego startu
- Minuta 10–20: Podłącz swoje repozytorium; poproś go o zmapowanie struktury projektu
- Minuta 20–35: Zdefiniuj mały, testowalny cel; zatwierdź jego plan
- Minuta 35–50: Pozwól mu implementować i uruchamiać testy; popychaj w razie potrzeby
- Minuta 50–60: Przejrzyj diffy, udoskonal i scal z branchem funkcji
Kluczowe linki i kolejne kroki
- Oficjalne dokumenty "Start Building" i dokumentacja użytkowania OpenHands: wskazówki, szybki start i najlepsze praktyki.
- Przewodnik konfiguracji lokalnego LLM: skonfiguruj i uruchom OpenHands w całości na swoim komputerze.
- Przewodnik instalacji oparty na społeczności na maszynie wirtualnej: rzeczywiste kroki instalacji i szybki projekt demonstracyjny.
Kluczowe wnioski
- Określaj zadania jak tickety z jasnymi kryteriami akceptacji.
- Utrzymuj małe iteracje; testuj wcześnie i często.
- Używaj mechanizmów kontrolnych i sprawdzaj zmiany — traktuj go jak młodszego kolegę z zespołu.
- Wybierz chmurę dla wygody, modele lokalne dla prywatności.
- Połącz z narzędziami do dokumentacji (np. Sider.AI), aby przyspieszyć tworzenie specyfikacji i informacji o wersji.
FAQ
P1: Jak szybko zainstalować i zacząć korzystać z AI OpenHands?
Skorzystaj z oficjalnego szybkiego startu, aby zainstalować wymagania wstępne, podłączyć obsługiwany LLM (chmurowy lub lokalny) i uruchomić interfejs użytkownika, aby podłączyć swoje repozytorium. Dokumentacja "Start Building" zawiera instrukcje krok po kroku ze wskazówkami dotyczącymi konfiguracji.
P2: Czy mogę uruchomić OpenHands z lokalnym LLM zamiast modelu chmurowego?
Tak. Postępuj zgodnie z przewodnikiem Local LLMs, aby skonfigurować backend modelu lokalnego i dostosować ustawienia kontekstu. Jest to idealne rozwiązanie dla projektów wrażliwych na prywatność lub unikania kosztów API.
P3: Jaki jest najlepszy sposób na promptowanie OpenHands do zadań związanych z kodowaniem?
Pisz prompty jak zwięzłe tickety: zdefiniuj cel, odwołaj się do konkretnych plików, ustaw granice i dołącz kryteria akceptacji. Poproś go o utworzenie lub uruchomienie testów w celu sprawdzenia postępu.
P4: Czy korzystanie z AI OpenHands jest bezpieczne w kodzie produkcyjnym?
Traktuj go jak młodszego developera: używaj zabezpieczeń branchy, recenzji kodu i CI, aby sprawdzić zmiany. Dodaj mechanizmy kontrolne dla poleceń i trzymaj sekrety z dala od promptów.
P5: Jak OpenHands wypada w porównaniu z tradycyjnym asystentem kodu?
W przeciwieństwie do narzędzi opartych wyłącznie na czacie, OpenHands może uruchamiać polecenia, edytować pliki i iterować autonomicznie w Twoim repozytorium. Jest zbudowany do kompleksowych zadań, takich jak funkcje, debugowanie i testy.
