Szybki start asystenta OpenHands do kodowania: instalacja, flagi CLI, przykłady

Szybki start z CLI OpenHands w kilka minut

Page content

OpenHands to platform open-source, agnostyczna wobec modeli, służąca dla agentów oprogramowania napędzanych przez AI. Pozwala ona agentowi zachowywać się bardziej jak partner programistyczny, a nie jak proste narzędzie do autouzupełniania.

Może on pracować z plikami, wykonywać polecenia w osadzonym środowisku (sandbox) i korzystać z przeglądania sieci w razie potrzeby.

Ten przewodnik szybkiego startu koncentruje się na CLI OpenHands, ponieważ jest to najszybszy sposób na uzyskanie wydajności z terminala, a jego struktura idealnie mapuje się na wzorce automatyzacji, takie jak skrypty i uruchamianie CI. Aby uzyskać szerszy przegląd tego obszaru, zobacz AI Developer Tools: The Complete Guide to AI-Powered Development.

openhands text user interface

Czym jest OpenHands i co robi inaczej

Asystent programistyczny AI zazwyczaj pomaga generować lub edytować kod przy użyciu modelu językowego. OpenHands rozszerza tę koncepcję na przepływ pracy „agentyczny": system może iteracyjnie planować, podejmować działania (np. tworzyć pliki lub uruchamiać testy), obserwować wyniki i kontynuować, aż zadanie zostanie ukończone.

OpenHands jest również szeroko znany jako projekt, który pierwotnie nosił nazwę OpenDevin, i wyewoluował w platformę napędzaną przez społeczność z wieloma sposobami wykorzystania: CLI, lokalny interfejs graficzny w przeglądarce, interfejs hostowany w chmurze oraz SDK.

Z perspektywy inżynierskiej, kluczowym wyróżnikiem jest to, że OpenHands został zbudowany wokół środowiska wykonawczego (sandbox), dzięki czemu agent może bezpiecznie uruchamiać polecenia i narzędzia, a nie tylko generować tekst. W artykule o OpenHands opisano środowisko uruchomieniowe osadzone w Dockerze z powłoką i możliwością przeglądania sieci, konkretnie w celu wsparcia realistycznych wzorców interakcji podobnych do tych, jakich używają deweloperzy.

Instalacja CLI OpenHands

OpenHands obsługuje wiele metod instalacji. Dla większości deweloperów najlepiej zacząć od lokalnej instalacji CLI (szyte iteracje), a opcjonalnie dodać przepływy pracy oparte na Dockerze później, gdy potrzebna będzie ścisła izolacja wykonania.

Instalacja przy użyciu uv

Aktualna dokumentacja CLI OpenHands zaleca instalację przy użyciu uv i wymaga Python 3.12+.

uv tool install openhands --python 3.12
openhands

Aktualizacja jest równie prosta.

uv tool upgrade openhands --python 3.12

Dlaczego uv ma znaczenie w praktyce: uv zapewnia lepszą izolację od bieżącego środowiska projektu i jest wymagana dla domyślnych serwerów MCP.

Instalacja samodzielnej wersji CLI

Jeśli chcesz mieć przepływ instalacji „jeden polecenie", OpenHands udostępnia skrypt instalacyjny.

curl -fsSL https://install.openhands.dev/install.sh | sh
openhands

Na systemie macOS możesz musieć jawnie zezwolić na uruchomienie binarki w sekcji Prywatność i zabezpieczenia przed jej wykonaniem.

Uruchomienie przez Docker dla izolacji

Jeśli wolisz zachować instalację zamkniętą, dokumentacja CLI pokazuje również przepływ oparty na Dockerze. To podejście polega na montowaniu katalogu, do którego OpenHands ma dostęp, i przekazywaniu identyfikatora użytkownika, aby uniknąć tworzenia plików należących do roota w zamontowanym obszarze roboczym.

export SANDBOX_VOLUMES="$PWD:/workspace"

docker run -it \
  --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.12.0-python \
  -e SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --add-host host.docker.internal:host-gateway \
  --name openhands-cli-$(date +%Y%m%d%H%M%S) \
  python:3.12-slim \
  bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

Pierwsze uruchomienie i miejsce przechowywania ustawień

Podczas pierwszego uruchomienia CLI przeprowadzi Cię przez konfigurację wymaganych ustawień LLM i zapisze je dla przyszłych sesji. Dokumentacja CLI stwierdza, że ustawienia są zapisywane w pliku ~/.openhands/settings.json, a historia rozmów przechowywana jest w ~/.openhands/conversations, ale kiedy niedawno instalowałem OpenHands, konfiguracja została zapisana w ~/.openhands/agent_settings.json, więc dokumentacja może być nieco nieaktualna.

Dla głębszej konfiguracji i integracji narzędziowej, OpenHands dokumentuje również dodatkowe pliki konfiguracyjne, takie jak ~/.openhands/agent_settings.json (ustawienia agenta i LLM), ~/.openhands/cli_config.json (preferencje CLI) oraz ~/.openhands/mcp.json (serwery MCP).

Konfigurowanie OpenHands z lokalnym Ollama i llama.cpp

OpenHands działa z dowolnym lokalnym backendem kompatybilnym z OpenAI — Ollama, LocalAI, llama.cpp i inne. Jeśli nie masz pewności, co wybrać, zobacz Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally porównanie.

Kiedy po raz pierwszy uruchomisz OpenHands, wyświetli Ci stronę ustawień. Gdy już przejdziesz ten pierwszy etap, możesz ponownie otworzyć tę stronę, wpisując /settings, a następnie ctrl+j. Teraz wpisz:

  • w polu Custom Model: ollama/devstral-small-2:24b lub inny Twój ulubiony lokalny model,
  • oraz w polu Base Url: http://localhost:11434

openhands settings ollama mistral

Dla szybkiego odniesienia do poleceń Ollama, zobacz Ollama CLI cheatsheet: serve, run, ps, and model management.

Aby edytować plik konfiguracyjny OpenHands ręcznie, na przykład jeśli nie podoba Ci się wygląd strony ustawień, wykonaj:

nano ~/.openhands/agent_settings.json

lub jeśli wolisz edytor z bardziej graficznym interfejsem:

gedit GUI ~/.openhands/agent_settings.json

Właściwość llm znajduje się w dwóch miejscach, ustawiłem je tak, aby zawierały między innymi te podwłaściwości wskazujące na Ollama:

"llm":{"model":"ollama/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Aby wskazać OpenHands na lokalną instancję llama.cpp — to samo, w dwóch miejscach:

"llm":{"model":"openai/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Aby połączyć się z llama.cpp, skonfigurowałem:

  • “model”:“openai/Qwen3.5-35B-A3B-UD-IQ3_S.gguf”
  • “base_url”:“http://localhost:8080/v1”

i uruchamiałem llama.cpp poleceniem (zobacz llama.cpp Quickstart with CLI and Server dla szczegółów flag):

./llama.cpp/llama-server \
    -m /mnt/ggufs/Qwen3.5-35B-A3B-UD-IQ3_S.gguf \
    --ctx-size 70000 \
    -ngl 40 \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00

OpenHands połączył się z nim i pomyślnie zrealizował moje testowe żądanie stwórz dla mnie narzędzie CLI w Go, które będzie wywoływać punkty końcowe indexnow wyszukiwarek bing i innych, aby powiadamiać o zmianach na mojej stronie — z kodem źródłowym, plikiem wykonywalnym i README.md.

Jak działa CLI OpenHands w praktyce

Domyślne polecenie openhands uruchamia interaktywne doświadczenie w terminalu. OpenHands dostarcza paletę poleceń i polecenia w sesji, dzięki czemu możesz szybko sterować agentem podczas jego pracy.

Warto wiedzieć o przydatnych interaktywnych sterownikach na wczesnym etapie, takich jak otwieranie palety poleceń, wstrzymywanie agenta i wychodzenie z aplikacji.

  • Ctrl+P otwiera paletę poleceń.
  • Esc wstrzymuje działającego agenta.
  • Ctrl+Q lub /exit kończy sesję CLI.

Wewnątrz CLI OpenHands obsługuje również polecenia zaczynające się od ukośnika, takie jak /help, /new i /condense, co jest cenne, jeśli chcesz zarządzać długimi rozmowami bez konieczności restartu.

OpenHands nie kończy się na interfejsie terminala. CLI zawiera wiele interfejsów, które dobrze mapują się na różne przepływy pracy deweloperskie:

  • Tryb headless do automatyzacji i CI.
  • Interfejs WWW do uruchamiania doświadczenia CLI w przeglądarce.
  • Serwer GUI dla pełnej lokalnej aplikacji WWW, uruchamiany przez Docker.
  • Integracja z IDE przez ACP dla przepływów pracy opartych na edytorze.

Główne parametry linii polecenia, które faktycznie użyjesz

Na wysokim poziomie CLI OpenHands przyjmuje następujący kształt:

openhands [OPTIONS] [COMMAND]

Obejmuje to opcje globalne (takie jak zadania, wznowienie, headless) oraz polecenia podrzędne (serve, web, cloud, acp, mcp, login, logout).

Główne opcje do codziennej pracy

Najczęściej używane opcje globalne to:

  • -t, --task do nasiania rozmowy początkowym zadaniem.
  • -f, --file do nasiania z pliku, co jest przydatne, gdy chcesz zadania zatwierdzone w systemie kontroli wersji.
  • --resume [ID] i --last do kontynuowania poprzednich uruchomień.
  • --headless do uruchamiania niestandardowego, zazwyczaj w automatyzacji.
  • --json do strumieniowania wyjścia JSONL w trybie headless do parsowania przez maszynę.

Bezpieczeństwo i zatwierdzanie są również klasy pierwszorzędnej:

  • --always-approve automatycznie zatwierdza działania bez dopytywania.
  • --llm-approve używa analizatora bezpieczeństwa opartego na LLM do zatwierdzania działań.

Konfiguracja modelu i dostawcy przez zmienne środowiskowe

OpenHands obsługuje zmienne środowiskowe dla konfiguracji modelu:

  • LLM_API_KEY ustawia Twój klucz API dostawcy.
  • LLM_MODEL i LLM_BASE_URL mogą być stosowane jako nadpisanie, gdy uruchamiasz openhands --override-with-envs.

Przykład przepływu nadpisywania:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-api-key"
openhands --override-with-envs

OpenHands wyraźnie zaznacza, że nadpisanie zastosowane z --override-with-envs nie jest utrwalane.

Polecenia podrzędne, o których warto wiedzieć

Nie potrzebujesz każdego polecenia od pierwszego dnia, ale te pojawiają się szybko:

  • openhands serve uruchamia pełny serwer GUI używając Dockera, zazwyczaj dostępny pod adresem http://localhost:3000, z opcjami takimi jak --mount-cwd i --gpu.
  • openhands web uruchamia CLI jako aplikację WWW dostępną z przeglądarki, domyślnie na porcie 12000.
  • openhands login uwierzytelnia z OpenHands Cloud i pobiera Twoje ustawienia.
  • openhands cloud tworzy nową rozmowę w OpenHands Cloud z CLI.

Przykłady do kopiowania i wklejania, które możesz użyć natychmiast

Najszybszym sposobem na uzyskanie wartości z OpenHands jest traktowanie go jak agenta kodowania napędzanego zadaniami. Zachowuj zadania zwięzłe, dołączaj nazwy plików i poproś o testy lub weryfikację, gdy to właściwe.

Rozpocznij interaktywną sesję kodowania z początkowym zadaniem

To jest „domyślne doświadczenie dewelopera" i jeden z najczęstszych wzorców.

openhands -t "Napraw błąd w auth.py i dodaj test regresyjny"

Dokumentacja CLI OpenHands pokazuje dokładnie tę ideę dla bunderowania sesji z -t.

Zainicjuj zadanie z pliku

Używanie pliku jest przydatne, gdy chcesz powtarzalność, recenzję zespołu lub ponowne wykorzystanie w CI.

cat > task.txt << 'EOF'
Refaktoryzuj moduł połączenia z bazą danych.
Dodaj testy jednostkowe i upewnij się, że zestaw testów przechodzi.
EOF

openhands -f task.txt

Przewodnik szybkiego startu CLI jawnie obsługuje uruchamianie z pliku zadań przy użyciu -f.

Uruchom w trybie headless dla CI lub automatyzacji

Tryb headless działa bez interaktywnego UI i jest zbudowany dla pipeline’ów CI i skryptów automatyzacji.

openhands --headless -t "Dodaj testy jednostkowe dla auth.py i uruchom je"

Dwie ważne rzeczywistości inżynierskie tutaj:

  • Tryb headless wymaga --task lub --file.
  • Tryb headless zawsze działa w trybie zawsze-zatwierdź i nie może być zmieniony, a --llm-approve nie jest dostępne w trybie headless. Traktuj to jako potężną automatyzację i uruchamiaj w kontrolowanym środowisku.

Aby zintegrować się z parserami logów lub innymi narzędziami, włącz wyjście JSONL:

openhands --headless --json -t "Stwórz prostą aplikację Flask z punktem końcowym healthcheck" > openhands-output.jsonl

OpenHands dokumentuje --json jako strumieniowanie zdarzeń JSONL w trybie headless i pokazuje przekierowanie wyjścia do pliku.

Wznow pracę bez utraty kontekstu

Wznowienie jest krytyczne, gdy zaczniesz używać OpenHands do niestandardowych zmian.

Wylistuj ostatnie rozmowy:

openhands --resume

Wznow najnowszą:

openhands --resume --last

Lub wznow konkretną rozmowę po ID:

openhands --resume abc123def456

Te przepływy są udokumentowane w referencji poleceń CLI i przewodniku „Wznow rozmów".

Uruchom CLI w przeglądarce, gdy tego potrzebujesz

openhands web uruchamia CLI dostępną przez sieć (domyślny port 12000).

openhands web

Jeśli uruchamiasz lokalnie, wiązanie tylko z localhostem jest rozsądnym domyślnym ustawieniem:

openhands web --host 127.0.0.1 --port 12000

OpenHands ostrzega, że wystawienie interfejsu WWW do sieci wymaga odpowiednich środków bezpieczeństwa, ponieważ zapewnia pełny dostęp do możliwości OpenHands.

Bezpieczeństwo, rozwiązywanie problemów i ostre krawędzie

Najważniejszym dźwignią bezpieczeństwa w CLI OpenHands są zatwierdzenia:

  • Interaktywny CLI może pytać o potwierdzenie przed wrażliwymi działaniami, a możesz konfigurować ustawienia potwierdzenia w sesji.
  • --always-approve usuwa tarcze, ale również usuwa zabezpieczenia.
  • --llm-approve dodaje analizator oparty na LLM dla zatwierdzeń.
  • Tryb headless zawsze zatwierdza, więc zarezerwuj go dla automatyzacji w kontrolowanych środowiskach.

Pracując z lokalnym kodem, preferuj jawnie, najniższe uprawnienia dostępu:

  • Dla serwera GUI, openhands serve --mount-cwd montuje Twój obecny katalog do /workspace, dzięki czemu agent może czytać i modyfikować pliki projektu.
  • Dla uruchomień CLI opartych na Dockerze, użyj SANDBOX_VOLUMES, aby zdefiniować dokładnie, do których katalogów OpenHands może uzyskać dostęp.

Jeśli masz starsze katalogi stanu OpenHands, OpenHands wskazuje ścieżkę migracji z ~/.openhands-state do ~/.openhands w dokumentacji lokalnego ustawienia i wytycznych rozwiązywania problemów.

Na koniec, jeśli integrujesz OpenHands ze skryptami, kody wyjścia są udokumentowane jako:

  • 0 sukces
  • 1 błąd lub zadanie nie powiodło się
  • 2 nieprawidłowe argumenty

Moje doświadczenia z OpenHands

Dla mnie OpenHands działał dobrze, ale nie zawsze… Próbowałem, żeby działał z Devstral-Small-2 hostowanym na Ollama, i ciągle się zatrzymywał.

OpenHands with Ollama-hosted Devstral-Small-2.

Mimo to OpenHands działał dobrze z lokalnie hostowanym na llama.cpp Qwen 3.5 35b. Dopóki dla mnie OpenCode jest tak dużo bardziej niezawodne.