OpenHands Coding Assistant Snelstart: Installatie, CLI-Vlaggen, Voorbeelden

OpenHands is een open-source, model-agnostisch platform voor door AI-aangedreven softwareontwikkelingsagenten.
Het stelt een agent in staat om zich meer te gedragen als een programmeerpartner dan als een eenvoudig hulpmiddel voor automatische voltooijing.

Het kan werken met bestanden, commando’s uitvoeren in een sandbox-omgeving en webbladeren gebruiken wanneer nodig.

Deze QuickStart richt zich op de OpenHands CLI, omdat dit de snelste manier is om productief te worden vanuit uw terminal, en het sluit naadloos aan op automatiseringspatronen zoals scripts en CI-loops. Voor een bredere kijk op het veld, zie AI Developer Tools: De complete gids voor door AI-aangedreven ontwikkeling.

Wat OpenHands is en wat het anders doet

Een AI-programmeerassistent helpt u doorgaans code te genereren of bewerken met behulp van een taalkundig model. OpenHands breidt dit concept uit naar een “agentic” workflow: het systeem kan iteratief plannen, acties ondernemen (zoals bestanden schrijven of tests uitvoeren), resultaten observeren en doorgaan totdat de taak voltooid is.

OpenHands staat ook algemeen bekend als het project dat vroeger OpenDevin heette, en het is uitgegroeid tot een door de communiteit gedreven platform met meerdere manieren om het te gebruiken: een CLI, een lokale web-GUI, een cloud-gehoste UI en een SDK.

Vanuit een engineeringperspectief is de belangrijkste differentiator dat OpenHands is gebouwd rondom een uitvoeringsomgeving (een sandbox), zodat een agent veilig commando’s en hulpmiddelen kan uitvoeren in plaats van alleen tekst te produceren. Het OpenHands-papier beschrijft een Docker-ge sandboxde runtime-omgeving met shell- en bladermogelijkheden, specifiek ontworpen om realistische, ontwikkelaarachtige interactiepatronen te ondersteunen.

OpenHands CLI installeren

OpenHands ondersteunt meerdere installatiemethoden. Voor de meeste ontwikkelaars is het het beste om te beginnen met een lokale CLI-installatie (snelle iteratie) en optioneel later Docker-gebaseerde workflows toe te voegen wanneer u strikte isolatie rondom uitvoering wilt.

Installeren met uv

De huidige OpenHands CLI-documentatie adviseert installatie met uv en vereist Python 3.12+.

uv tool install openhands --python 3.12
openhands

Upgraden is even eenvoudig.

uv tool upgrade openhands --python 3.12

Waarom uv in de praktijk belangrijk is: uv biedt betere isolatie van uw huidige projectomgeving en is vereist voor standaard MCP-servers.

De standalone CLI-binaire installeren

Als u een “één-commando” installatiestroom wilt, biedt OpenHands een installatiescript.

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

Op macOS moet u mogelijk expliciet toestemming geven voor de binaire in Privacy & Security voordat het wordt uitgevoerd.

Uitvoeren via Docker voor isolatie

Als u de installatie liever bevat houdt, tonen de CLI-documenten ook een Docker-gebaseerde stroom. Deze aanpak leunt op het monteren van een map die u wilt dat OpenHands toegang krijgt en het doorgeven van uw gebruikers-ID om te voorkomen dat bestanden in de gemonteerde werkruimte als root worden aangemaakt.

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"

Eerste uitvoeringsconfiguratie en waar instellingen worden opgeslagen

Bij de eerste uitvoering leidt de CLI u door het configureren van vereiste LLM-instellingen en slaat deze op voor toekomstige sessies. De CLI-documenten stellen dat instellingen worden opgeslagen onder ~/.openhands/settings.json en dat gespreksgeschiedenis wordt opgeslagen in ~/.openhands/conversations, maar toen ik OpenHands zojuist installeerde, slaagde het op in ~/.openhands/agent_settings.json, dus de documentatie is misschien niet helemaal correct.

Voor diepere configuratie en integratie met hulpmiddelen documenteert OpenHands ook aanvullende configuratiebestanden zoals ~/.openhands/agent_settings.json (agent- en LLM-instellingen), ~/.openhands/cli_config.json (CLI-preferenties) en ~/.openhands/mcp.json (MCP-servers).

OpenHands configureren met lokale Ollama en llama.cpp

OpenHands werkt met elke OpenAI-compatibele lokale backend — Ollama, LocalAI, llama.cpp en anderen. Als u niet zeker weet welke u moet gebruiken, bekijk dan Ollama vs vLLM vs LM Studio: Beste manier om LLM’s lokaal te draaien voor een vergelijking.

Wanneer u OpenHands voor de eerste keer start, toont het u de instellingenpagina. Wanneer u dit eerste stadium reeds hebt gepasseerd, kunt u deze pagina opnieuw openen door /settings in te typen en vervolgens ctrl+j te drukken. Typ nu:

• in het veld Custom Model: ollama/devstral-small-2:24b, of welke andere favoriete lokale model u ook gebruikt,
• en in het veld Base Url: http://localhost:11434

Voor een snelle referentie over Ollama-commando’s, zie de Ollama CLI-cheat sheet: serve, run, ps en modelbeheer.

Om het OpenHands-configuratiebestand handmatig te bewerken, bijvoorbeeld als u niet tevreden bent met hoe de instellingenpagina eruitziet, voer uit:

nano ~/.openhands/agent_settings.json

of als u liever een editor met meer GUI gebruikt:

gedit GUI ~/.openhands/agent_settings.json

Er is een llm-eigenschap op twee plekken, die ik heb ingesteld om onder meer deze sub-eigenschappen te hebben om naar Ollama te verwijzen:

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

Om OpenHands te wijzen op een lokale llama.cpp-instance - hetzelfde, op twee plekken:

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

Om verbinding te maken met llama.cpp heb ik het volgende geconfigureerd:

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

en ik startte llama.cpp met het commando (zie llama.cpp Quickstart met CLI en Server voor details over vlaggen):

./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 kon succesvol verbinding maken met mijn testverzoek maak voor mij een cli-tool in Go, die bing en andere zoekmachines' indexnow-endpoints zou aanroepen om te melden over wijzigingen op mijn website - met broncode, een uitvoerbaar bestand en README.md.

Hoe de OpenHands CLI in de praktijk werkt

Het standaard openhands-commando start een interactieve terminalervaring. OpenHands biedt een commandopallette en commando’s binnen sessies zodat u de agent snel kunt sturen terwijl het aan het werk is.

Nuttige interactieve besturingselementen om vroeg te kennen, zijn het openen van de commandopallette, het pauzeren van de agent en het verlaten van de app.

• Ctrl+P opent de commandopallette.
• Esc pauzeert de werkende agent.
• Ctrl+Q of /exit verlaat de CLI.

Binnen de CLI ondersteunt OpenHands ook commando’s met een slash-prefix zoals /help, /new en /condense, wat waardevol is als u lange gesprekken wilt beheren zonder opnieuw te starten.

OpenHands stopt niet bij een terminal-UI. De CLI bevat meerdere interfaces die goed aansluiten bij verschillende ontwikkelaar-workflows:

• Headless-modus voor automatisering en CI.
• Web-interface om de CLI-ervaring in een browser te draaien.
• GUI-server voor de volledige lokale webapplicatie, gestart via Docker.
• IDE-integratie via ACP voor editor-gebaseerde workflows.

Belangrijkste commandoregelparameters die u daadwerkelijk zult gebruiken

Op hoog niveau volgt OpenHands CLI deze vorm:

openhands [OPTIES] [COMMANDO]

Dit omvat globale opties (dingen zoals taken, hervatten, headless), plus subcommando’s (serve, web, cloud, acp, mcp, login, logout).

Kernopties voor dagelijkse werkzaamheden

De meest gebruikte globalen zijn:

• -t, --task om het gesprek te initialiseren met een initiële taak.
• -f, --file om te initialiseren vanuit een bestand, wat handig is wanneer u taken wilt die in versiebesturing zijn opgenomen.
• --resume [ID] en --last om eerdere loops voort te zetten.
• --headless voor niet-interactieve uitvoering, typisch in automatisering.
• --json om JSONL-output te streamen in headless-modus voor machine parsing.

Veiligheid en goedkeuringen hebben ook eerste klas status:

• --always-approve keurt acties automatisch goed zonder te vragen.
• --llm-approve gebruikt een op LLM gebaseerde veiligheidsanalyseur voor goedkeuring van acties.

Model- en providerconfiguratie via omgevingsvariabelen

OpenHands ondersteunt omgevingsvariabelen voor modelconfiguratie:

• LLM_API_KEY stelt uw provider-API-sleutel in.
• LLM_MODEL en LLM_BASE_URL kunnen als overrides worden toegepast wanneer u openhands --override-with-envs uitvoert.

Voorbeeld van override-stroom:

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

OpenHands merkt expliciet op dat overrides die met --override-with-envs worden toegepast, niet worden vastgehouden.

Subcommando’s die de moeite waard zijn om te kennen

U heeft niet elke subcommando op dag één nodig, maar deze komen snel naar boven:

• openhands serve start de volledige GUI-server met behulp van Docker, typisch bereikbaar op http://localhost:3000, met opties zoals --mount-cwd en --gpu.
• openhands web start de CLI als een via browser bereikbare webapplicatie, met als standaard poort 12000.
• openhands login authenticeert met OpenHands Cloud en haalt uw instellingen op.
• openhands cloud maakt een nieuw gesprek aan in OpenHands Cloud vanuit de CLI.

Kopieer- en plakvoorbeelden die u direct kunt gebruiken

De snelste manier om waarde uit OpenHands te halen, is om het te behandelen als een taakgedreven programmeeragent. Houd taken beknopt, inclusief bestandsnamen, en vraag om tests of verificatie waar passend.

Start een interactieve programmeersessie met een initiële taak

Dit is de “standaard ontwikkelaarervaring” en een van de meest voorkomende patronen.

openhands -t "Repareren de bug in auth.py en een regressietest toevoegen"

OpenHands CLI-documentatie toont dit exacte idee voor het opstarten van een sessie met -t.

Initialiseer een taak vanuit een bestand

Het gebruik van een bestand is nuttig wanneer u herhaalbaarheid, team-review of CI-hergebruik wilt.

cat > task.txt << 'EOF'
Refactor de databaseverbindingsmodule.
Voeg unit-tests toe en zorg ervoor dat de testsuite slaagt.
EOF

openhands -f task.txt

De CLI Quick Start ondersteunt expliciet het starten vanuit een taakbestand met -f.

Draai in headless-modus voor CI of automatisering

Headless-modus draait zonder de interactieve UI en is gebouwd voor CI-pijplijnen en geautomatiseerd scripting.

openhands --headless -t "Voeg unit-tests toe voor auth.py en voer ze uit"

Twee belangrijke engineeringrealiteiten hier:

• Headless-modus vereist --task of --file.
• Headless-modus draait altijd in always-approve-modus en kan niet worden gewijzigd, en --llm-approve is niet beschikbaar in headless-modus. Behandel het als krachtige automatisering en voer het uit in een gecontroleerde omgeving.

Om te integreren met log parsing of andere hulpmiddelen, schakel JSONL-output in:

openhands --headless --json -t "Maak een simpele Flask-app met een healthcheck-endpoint" > openhands-output.jsonl

OpenHands documenteert --json als JSONL-event streaming in headless-modus en toont het doorsturen van output naar een bestand.

Voortzetten van werk zonder context te verliezen

Hervatten is cruciaal zodra u begint met OpenHands voor niet-triviale wijzigingen.

Lijst recente gesprekken op:

openhands --resume

Vervolgens het meest recente:

openhands --resume --last

Of hervatten een specifiek gespreks-ID:

openhands --resume abc123def456

Deze stromen zijn gedocumenteerd in de CLI-commando-referentie en de “Resume Conversations”-gids.

Voer de CLI in een browser uit wanneer u het nodig heeft

openhands web start een via web bereikbare CLI (standaard poort 12000).

openhands web

Als u lokaal draait, is het binden aan localhost alleen een zinvolle standaard:

openhands web --host 127.0.0.1 --port 12000

OpenHands waarschuwt dat het blootstellen van de web-interface aan het netwerk passende veiligheidsmaatregelen vereist, omdat het volledige toegang biedt tot OpenHands-mogelijkheden.

Veiligheid, probleemoplossing en scherpe randjes

De belangrijkste veiligheidshefboom in OpenHands CLI is goedkeuringen:

• De interactieve CLI kan om bevestiging vragen voordat er gevoelige acties worden ondernomen, en u kunt bevestigingsinstellingen in de sessie configureren.
• --always-approve verwijdert wrijving, maar verwijdert ook veiligheidsmaatregelen.
• --llm-approve voegt een op LLM gebaseerde analyseur toe voor goedkeuringen.
• Headless-modus keurt altijd goed, dus reserveer het voor automatisering in gecontroleerde omgevingen.

Bij het werken met lokale code, geeft u voorkeur aan expliciete, minst-privilege-toegangspatronen:

• Voor de GUI-server, openhands serve --mount-cwd monteert uw huidige map naar /workspace zodat de agent uw projectbestanden kan lezen en wijzigen.
• Voor Docker-gebaseerde CLI-loops, gebruik SANDBOX_VOLUMES om precies te definiëren welke mappen OpenHands kan bereiken.

Als u oudere OpenHands-statusmappen heeft, merkt OpenHands een migratiepad op van ~/.openhands-state naar ~/.openhands in de lokale setup-documenten en probleemoplossingsrichtlijnen.

Tot slot, als u OpenHands integreert in scripts, zijn exit-codes gedocumenteerd als:

• 0 succes
• 1 fout of taak mislukt
• 2 ongeldige argumenten

Mijn ervaring met OpenHands

Voor mij werkte OpenHands goed, maar niet altijd… Ik probeerde het werkend te krijgen met Devstral-Small-2 gehost op Ollama, en het stopte constant.

.

Hoewel OpenHands goed werkte met lokaal gehoste Qwen 3.5 35b op llama.cpp. Tot nu toe is voor mij OpenCode zoveel betrouwbaarder.