Szybki start w OpenHands CLI: instalacja, flagi, tryb headless

OpenHands to otwartoźródłowy agent do kodowania, który edytuje pliki i wykonuje polecenia w środowisku odizolowanym. Ten szybki kurs CLI został sprawdzony 26.10.2026 w oparciu o pakiet 1.16.0.

Pakiet na PyPI to openhands 1.16.0, opublikowany 8 maja 2026 roku, z przypiętą wersją openhands-sdk==1.21.0. README dla tagu wymaga Pythona 3.12 oraz uv 0.11.6 lub nowszego. README dla gałęzi domyślnej repozytorium OpenHands-CLI informuje, że to repozytorium nie jest już aktywnie utrzymywane i kieruje nowych instalujących do Agent Canvas. Tryb headless oraz openhands acp nadal stanowią część zestawu poleceń wersji 1.16.0.

Przewodnik po narzędziach AI dla deweloperów śledzi inne agentów terminalowych na tej stronie. Ta strona koncentruje się na CLI OpenHands: instalacji, plikach konfiguracyjnych, adresach URL lokalnych modeli oraz flagach, które faktycznie przekazuje skrypt.

Czym jest CLI

Asystent AI do kodowania zazwyczaj generuje lub edytuje kod na podstawie polecenia. OpenHands rozszerza to na pętlę agenta: zaplanuj, podejmij działanie, takie jak zapisanie pliku lub uruchomienie testu, zaobserwuj wynik i kontynuuj. Projekt był wcześniej nazywany OpenDevin. Artykuł na temat OpenHands opisuje środowisko wykonawcze odizolowane w Dockerze z powłoką i przeglądarką, co jest modelem wykonawczym, który nadal obejmuje CLI.

Wersja 1.16.0 dokumentuje pięć sposobów uruchomienia tej pętli.

Agent Canvas, instalacja dokumentowana przez projekt

3 czerwca 2026 roku FAQ OpenHands przekazało interfejs terminalowy w tryb utrzymania do 1 października 2026 roku i oświadczyło, że tryb headless oraz ACP pozostaną w pełni wspierane. Lokalny interfejs graficzny (openhands serve) miał pozostać w trybie utrzymania, aż Agent Canvas będzie w stanie uruchamiać odizolowane, efemeryczne środowiska odizolowane. To FAQ definiuje tryb utrzymania jako aktualizacje zależności, naprawy krytycznych błędów oraz obsługę nowych LLM. Główny repozytorium OpenHands wydało Agent Canvas 1.33.0 23 października 2026 roku.

agent-canvas uruchamia bieżący interfejs i jego backend. openhands serve uruchamia legacy GUI i nie uruchamia Agent Canvas.

Agent Canvas wymaga Node.js 24 lub nowszego oraz uv. Pierwsze uruchomienie bez instalacji globalnej:

npx @openhands/agent-canvas

Proces nasłuchuje na http://localhost:8000. Zamknięcie tego terminala zatrzymuje lokalny backend. Instalacja globalna to npm install -g @openhands/agent-canvas, a następnie agent-canvas. Ścieżka npm uruchamia serwer agenta jako Twój użytkownik, więc agent może działać na lokalnych plikach z uprawnieniami Twojego konta.

Ścieżka Docker publikuje port tylko na localhost i montuje katalog projektów:

mkdir -p ~/projects

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

Kontener serwuje interfejs na http://localhost:8000/canvas. Nazwany wolumen openhands-data zachowuje ustawienia po --rm. Na Linuxie, montowanie bindowe ~/.openhands do tego obrazu kończy się błędem unable to open database file: użytkownik kontenera to UID 10001, a katalog hosta jest zazwyczaj własnością Twojego własnego UID. Strona instalacyjna używa nazwanego wolumenu właśnie z tego powodu. Ustawienia już znajdujące się w ~/.openhands nie są kopiowane do nowego wolumenu.

Instalacja CLI OpenHands

Używaj CLI, gdy nadal chcesz korzystać z openhands --headless lub openhands acp. Opublikowany wheel instaluje się tylko na Pythonie 3.12 (==3.12.* na PyPI). uv musi być w wersji 0.11.6 lub nowszej. Na Windowsie strona instalacyjna mówi, aby uruchomić polecenia w WSL (Ubuntu).

Instalacja z uv

uv tool install openhands --python 3.12
openhands

Aktualizacja z tym samym przypięciem interpretera:

uv tool upgrade openhands --python 3.12

Strona konfiguracji lokalnej mówi, że to uv izoluje CLI od wirtualnego środowiska projektu, a domyślne serwery MCP go wymagają.

Instalacja samodzielnej binarki

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

Na macOS dialog Gatekeeper może blokować binarkę (“nie można otworzyć openhands, ponieważ Apple nie może sprawdzić jej pod kątem złośliwego oprogramowania”). Ścieżka na stronie instalacyjnej to Ustawienia systemowe, Prywatność i bezpieczeństwo, a następnie Pozwól mimo to w ramach Bezpieczeństwa, a następnie ponownie uruchom openhands.

Uruchomienie CLI przez Docker

Kontener ze strony instalacyjnej ustawia AGENT_SERVER_IMAGE_TAG na obraz agent-servera. uv tool install openhands wewnątrz kontenera to CLI z PyPI. Tag w tym przykładzie, sprawdzony dla tej strony, to 1.26.0-python. Starsze kopie tego polecenia używały 1.12.0-python.

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.26.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"

SANDBOX_USER_ID=$(id -u) sprawia, że użytkownik sandboxu odpowiada użytkownikowi hosta, więc agent nie zostawia plików należących do roota w zamontowanym workspace. SANDBOX_VOLUMES to katalog, do którego agent może uzyskać dostęp.

OPENHANDS_VERSION wybiera wersję obrazu Docker dla openhands serve. Nie zmienia wersji CLI z PyPI.

Pliki konfiguracyjne

Przy pierwszym uruchomieniu CLI pyta o ustawienia modelu i zapisuje je pod ~/.openhands/. README 1.16.0 oraz referencja poleceń nazywa te pliki:

Strona instalacyjna nadal mówi użytkownikom Docker, aby przygotowali ~/.openhands/settings.json. README CLI i AgentStore w drzewie 1.16.0 trwale zapisują specyfikację agenta do agent_settings.json. Instalacja CLI, która pominęła nazwę pliku ze strony instalacyjnej i zapisała agent_settings.json, jest zgodna z tym źródłem.

create_and_save_from_settings buduje dwa obiekty LLM z tego samego modelu, klucza API i adresu bazowego URL: jeden dla agenta i jeden dla kondensera podsumowującego. Dlatego zapisany plik powtarza pola llm. Edytuj plik agenta dowolnym edytorem:

nano ~/.openhands/agent_settings.json

LLM_API_KEY, LLM_MODEL i LLM_BASE_URL są ignorowane, chyba że włączysz opcję. Nadpisanie nie jest zapisywane:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="twoj-klucz-api"
openhands --override-with-envs

OPENHANDS_CLOUD_URL ustawia domyślny serwer chmurowy. Polecenia cloud i login domyślnie używają https://app.all-hands.dev, gdy ta zmienna nie jest ustawiona.

Aktualizacje z CLI starszego niż 1.0.0 wymagają ponownego wprowadzenia ustawień. Strona instalacyjna mówi, że format konfiguracji zmienił się w wersji 1.0.0.

Lokalne modele

Przewodnik po lokalnych LLM z 21 maja 2026 roku poleca Qwen3.6-35B-A3B jako pierwszy lokalny model do przetestowania. Wymaga karty graficznej z co najmniej 24 GB VRAM dla zbudowanej wersji skwantowanej lub Maca z Apple Silicon z co najmniej 64 GB pamięci zunifikowanej. Ta sama strona mówi, aby ustawić długość kontekstu na co najmniej 22000 tokenów, oraz że domyślna wartość 4096 w Ollama jest zbyt mała dla polecenia systemowego.

Gdy agent nigdy nie wywołuje narzędzi, przewodnik traktuje to jako ograniczenie modelu i wymienia raporty społeczności dla qwen2.5-coder-14b-instruct i qwopus3.5-27b-v3. Porównanie hostingu lokalnego to tabela serwer po serwerze, gdy Ollama, vLLM, LM Studio lub LocalAI wciąż są otwartą kwestią.

Ollama

Uruchomienie Ollama w przewodniku ustawia długość kontekstu przed ollama serve. Ściągawka CLI Ollama omawia serve, run i ps obok tej zmiennej.

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1 ollama serve
ollama pull qwen3.6:35b-a3b

Dla OpenHands uruchamianego w Dockerze, ustawienia z przewodnika to niestandardowy model openai/qwen3.6:35b-a3b, bazowy adres URL http://host.docker.internal:11434/v1 i dowolny klucz API jako placeholder. CLI uruchamiany na tym samym hoście co Ollama używa http://127.0.0.1:11434/v1 zamiast host.docker.internal. LM Studio dla Linuxa i inne serwery tylko z pętlą zwrotną są niedostępne z kontenera na 127.0.0.1; sprawdzenie z przewodnika polega na włączeniu serwowania w lokalnej sieci i curlu host.docker.internal z wewnątrz kontenera.

Strona terminalowa otwiera ten ekran z Ctrl+P, a następnie Ustawienia. Zapisany profil CLI używał identyfikatora modelu ollama/ i bazowego adresu URL bez /v1:

• Model niestandardowy: ollama/devstral-small-2:24b
• Bazowy adres URL: http://localhost:11434

Ta sesja Devstral-Small-2 to ta, która nieustannie się zatrzymywała. Pola zapisane dla niej, zarówno dla LLM agenta, jak i LLM kondensera, to:

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

llama.cpp i vLLM

llama.cpp używał prefiksu kompatybilnego z OpenAI i bazowego adresu URL /v1, również w obu obiektach LLM:

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

Polecenie serwera, z flagami omówionymi w szybkim kursie llama.cpp, to:

./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

Przeciwko temu serwerowi CLI ukończył klienta Go IndexNow: źródło, plik wykonywalny i README. Tekst zadania brzmiał utwórz dla mnie narzędzie cli w Go, które będzie wywoływać endpointy indexnow Binga i innych wyszukiwarek, aby powiadomić o zmianach na mojej stronie internetowej.

Przykład vLLM dla nowszego modelu Qwen3.6 z przewodnika po lokalnych LLM to serwer na dwóch GPU. Szybki kurs vLLM przechodzi przez flagi vllm serve i kontrole pamięci zewnętrznej. Odpowiadający mu ciąg modelu OpenHands z przewodnika to openai/Qwen3.6-35B-A3B, z bazowym adresem URL http://host.docker.internal:8000/v1 i tym samym --api-key, z którym uruchomiono serwer (mykey w ich przykładzie).

vllm serve Qwen/Qwen3.6-35B-A3B \
    --host 0.0.0.0 --port 8000 \
    --api-key mykey \
    --tensor-parallel-size 2 \
    --served-model-name Qwen3.6-35B-A3B \
    --enable-prefix-caching

Sterowanie interaktywne

openhands bez podpolecenia otwiera interfejs terminalowy. Strona terminalowa wymienia te sterowania:

Polecenia slashowe z referencji poleceń: /help, /new, /history, /confirm, /condense, /skills, /feedback, /exit. Zmiany modelu z pozycji Ustawienia w palecie mają zastosowanie bez ponownego uruchomienia. --exit-without-confirmation pomija dialog wyjścia. --exp wybiera interfejs tekstowy i jest udokumentowane jako flaga kompatybilności, ponieważ ten interfejs jest już domyślny.

Flagi i podpolecenia

openhands [OPCJE] [POLECENIE]

Globalne opcje w referencji poleceń, sprawdzone na argparsers/util.py dla tagu 1.16.0 dla flag akceptacji i środowiska:

--always-approve i --llm-approve nie mogą być połączone. Domyślny tryb interaktywny pyta przed działaniami.

Podpolecenia, które pojawiają się, gdy TUI nie wystarcza:

• openhands serve uruchamia legacy GUI w Dockerze. --mount-cwd montuje bieżący katalog w /workspace. --gpu włącza nvidia-docker.
• openhands web serwuje CLI w przeglądarce. --host domyślnie 0.0.0.0, --port 12000, --debug wyłączone.
• openhands acp mówi Agent Client Protocol na stdio. Flagi: --resume, --last, --always-approve, --llm-approve, --streaming.
• openhands cloud -t "zadanie" otwiera rozmowę chmurową. --server-url nadpisuje https://app.all-hands.dev.
• openhands login i openhands logout zarządzają tym kontem chmurowym. logout bez --server-url loguje się z każdego zapisanego serwera.
• openhands mcp zarządza serwerami: add, list, get, remove, enable, disable. add wymaga --transport o wartości http, sse lub stdio.

Serwer MCP z README 1.16.0:

openhands mcp list
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<twój-klucz-api>"
openhands mcp enable tavily
openhands mcp disable tavily

Przykłady

Zadanie interaktywne

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

Plik zadania

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

openhands -f task.txt

Headless, w tym JSONL

Tryb headless wymaga --task lub --file. Zawsze działa jako always-approve, a --llm-approve jest tam odrzucane. Traktuj bieżący katalog roboczy jako ten, który agent może modyfikować swobodnie.

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

openhands --headless --json -t "Utwórz prostą aplikację Flask z endpointem healthcheck" > openhands-output.jsonl

Strona headless opisuje --json jako jeden obiekt JSON na zdarzenie, strumieniowany jako JSONL.

Wznowienie

openhands --resume
openhands --resume --last
openhands --resume abc123def456

Interfejs terminalowy w przeglądarce przypięty do localhosta

openhands web domyślnie używa 0.0.0.0:12000, co jest dostępne z sieci. Dokumentacja CLI mówi, że ten interfejs ma pełną funkcjonalność CLI, więc przypięcie tylko do lokalnego jest bezpieczniejszym domyślnym ustawieniem:

openhands web --host 127.0.0.1 --port 12000

ACP dla edytora

Klienci ACP ze strony IDE to Zed i JetBrains (natywny), Toad (natywny) oraz VS Code (rozszerzenie społecznościowe). Edytor uruchamia openhands acp i komunikuje się przez JSON-RPC 2.0 na stdio, używając zapisanych ustawień LLM z CLI.

openhands acp
openhands acp --llm-approve
openhands acp --resume --last

Zatwierdzanie, kody wyjścia i wyniki lokalnych modeli

Sesje interaktywne pytają przed działaniami. /confirm zmienia tę politykę w sesji. --always-approve (alias --yolo) zatwierdza wszystko. --llm-approve pyta tylko o działania, które analizator bezpieczeństwa ocenia jako wysokie ryzyko. Tryb headless to always-approve dla całego przebiegu.

openhands serve --mount-cwd montuje bieżący katalog w /workspace wewnątrz kontenera legacy GUI. Przepływ CLI z Dockerem używa SANDBOX_VOLUMES dla tej samej granicy.

Kody wyjścia w referencji poleceń:

Devstral-Small-2 24B na Ollama wielokrotnie się zatrzymywał w tym CLI.

Sesja llama.cpp powyżej, Qwen3.5-35B-A3B w kontekście 70000 tokenów, ukończyła zadanie IndexNow. Dla agenta terminalowego, który kontynuował pracę na tej samej maszynie, szybki kurs OpenCode to instalacja i konfiguracja dostawcy.