OpenHands Coding Assistant – Snabbstart: Installation, CLI-flaggor och exempel

OpenHands-kommandotolken: Kom igång på några minuter

Sidinnehåll

OpenHands är en öppen källkodsplattform som är modellagnostisk för AI-drivna agenter för mjukvaruutveckling. Den låter en agent bete sig mer som en kodpartner än ett enkelt verktyg för automatisk komplettering.

Den kan arbeta med filer, utföra kommandon i en sandboxad miljö och använda webbläsning när det behövs.

Denna snabbstart fokuserar på OpenHands CLI, eftersom det är det snabbaste sättet att bli produktiv från din terminal, och det kartläggs rent på automatiseringsmönster som skript och CI-körningar. För en bredare titt på området, se AI Developer Tools: The Complete Guide to AI-Powered Development.

openhands text user interface

Vad OpenHands är och vad det gör annorlunda

En AI-kodassistent hjälper vanligtvis dig att generera eller redigera kod med hjälp av en språkmodell. OpenHands utvidgar den idén till ett “agent-baserat” arbetsflöde: systemet kan iterativt planera, utföra åtgärder (som att skriva filer eller köra tester), observera resultat och fortsätta tills uppgiften är klar.

OpenHands är också brett känt som projektet som tidigare hette OpenDevin, och det har utvecklats till en plattform driven av communityt med flera sätt att använda det: en CLI, en lokal web-GUI, en molnhostad UI och en SDK.

Från ett ingenjörsperspektiv är den avgörande skillnaden att OpenHands byggs kring en exekveringsmiljö (en sandbox) så att en agent säkert kan köra kommandon och verktyg snarare än bara att producera text. OpenHands-papern beskriver en Docker-sandboxad runtime-miljö med en skal och webbläsning, specifikt för att stödja realistiska interaktionsmönster för utvecklare.

Installera OpenHands CLI

OpenHands stöder flera installationsmetoder. För de flesta utvecklare är det bäst att börja med en lokal CLI-installation (snabb iterering) och sedan tillägga Docker-baserade arbetsflöden om du vill ha strikt isolering kring exekvering.

Installera med uv

De aktuella OpenHands CLI-dokumenterna rekommenderar att installera med uv, och kräver Python 3.12+.

uv tool install openhands --python 3.12
openhands

Uppgradering är på samma sätt enkelt.

uv tool upgrade openhands --python 3.12

Varför uv är viktigt i praktiken: uv ger bättre isolering från din nuvarande projektmiljö och krävs för standard MCP-server.

Installera den fristående CLI-binär

Om du vill ha en “enkelt kommando”-installationsflöde, tillhandahåller OpenHands ett installationskommando.

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

På macOS kan du behöva explicit tillåta binären i Integritet & säkerhet innan den kör.

Kör via Docker för isolering

Om du föredrar att hålla installationen innesluten, visar även CLI-dokumentationen ett Docker-baserat flöde. Detta tillvägagångssätt bygger på att montera en katalog du vill att OpenHands ska få tillgång till och skicka igenom ditt användar-ID för att undvika att skapa root-ägda filer i den monterade arbetsplatsen.

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"

Konfiguration vid första körning och var inställningar finns

Vid första körningen guidar CLI:t dig genom att konfigurera krävda LLM-inställningar och sparar dem för framtida sessioner. CLI-dokumenterna anger att inställningar sparas under ~/.openhands/settings.json, och samtalshistorik sparas i ~/.openhands/conversations, men när jag installerade OpenHands nyligen, sparades konfigurationen i ~/.openhands/agent_settings.json, så dokumentationen kanske inte är helt rätt.

För djupare konfiguration och verktygsintegration dokumenterar OpenHands även ytterligare konfigurationsfiler som ~/.openhands/agent_settings.json (agent- och LLM-inställningar), ~/.openhands/cli_config.json (CLI-förståningar) och ~/.openhands/mcp.json (MCP-server).

Konfigurera OpenHands med lokal Ollama och llama.cpp

OpenHands fungerar med alla lokala backends som är OpenAI-kompatibla — Ollama, LocalAI, llama.cpp och andra. Om du inte är säker på vilken du ska använda, se Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally för en jämförelse.

När du startar OpenHands första gången visar det inställningssidan. När du redan har passerat detta första steg, kan du öppna denna sida igen genom att skriva /settings och sedan ctrl+j. Skriv nu:

  • i fältet Custom Model: ollama/devstral-small-2:24b, eller vad du annars har som din favoritolokala modell,
  • och i fältet Base Url: http://localhost:11434

openhands settings ollama mistral

För en snabb referens till Ollama-kommandon, se Ollama CLI cheatsheet: serve, run, ps, and model management.

För att redigera OpenHands-konfigurationsfilen manuellt, till exempel om du inte gillar hur inställningssidan ser ut - kör

nano ~/.openhands/agent_settings.json

eller om du föredrar en editor med mer GUI:

gedit GUI ~/.openhands/agent_settings.json

Det finns llm-egenskapen på två ställen, jag satte dem att ha dessa underliggande egenskaper förutom andra för att peka mot Ollama

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

För att peka OpenHands mot en lokal llama.cpp-instans - samma sak, på två ställen:

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

För att ansluta till llama.cpp konfigurerade jag

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

och startade llama.cpp med kommandot (se llama.cpp Quickstart with CLI and Server för flaggdetaljer):

./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 kunde ansluta till det och fullföljde min testbegäran skapa för mig ett CLI-verktyg i Go som anropar Bing och andra sökmotorers indexnow-endpunkter för att meddela om ändringar på min webbplats framgångsrikt - med källkod, körbar fil och README.md.

Hur OpenHands CLI fungerar i praktiken

Det förvalade openhands-kommandot startar en interaktiv terminalupplevelse. OpenHands tillhandahåller en kommandopalette och kommandon under sessionen så att du snabbt kan styra agenten medan den arbetar.

Användbara interaktiva kontroller att känna till tidigt inkluderar att öppna kommandopalletten, pausa agenten och avsluta appen.

  • Ctrl+P öppnar kommandopalletten.
  • Esc pauser den körande agenten.
  • Ctrl+Q eller /exit avslutar CLI:t.

Inuti CLI:t stöder OpenHands även kommandon med snedstreck som /help, /new och /condense, vilket är värdefullt om du vill hantera långa samtal utan att starta om.

OpenHands stannar inte vid en terminalgränssnitt. CLI:n inkluderar flera gränssnitt som kartläggs väl till olika utvecklararbetsflöden:

  • Headless-läge för automatisering och CI.
  • Webbgränssnitt för att köra CLI-upplevelsen i en webbläsare.
  • GUI-server för den fulla lokala webbapplikationen, startad via Docker.
  • IDE-integration via ACP för redigeringsbaserade arbetsflöden.

Huvudsakliga kommandoradsparametrar du faktiskt kommer använda

På en hög nivå följer OpenHands CLI denna struktur:

openhands [OPTIONS] [COMMAND]

Det inkluderar globala alternativ (ting som uppgifter, återuppta, headless), plus underkommandon (serve, web, cloud, acp, mcp, login, logout).

Kärnalternativ för daglig verksamhet

De mest använda globala alternativen är:

  • -t, --task för att sätta igång samtalet med en initial uppgift.
  • -f, --file för att sätta igång från en fil, vilket är användbart när du vill ha uppgifter commitade till versionskontroll.
  • --resume [ID] och --last för att fortsätta tidigare körningar.
  • --headless för icke-interaktiv exekvering, vanligtvis i automatisering.
  • --json för att strömma JSONL-utdata i headless-läge för maskinåtkomst.

Säkerhet och godkännanden är också förstahandsklass:

  • --always-approve godkänner automatiskt åtgärder utan att be om bekräftelse.
  • --llm-approve använder en LLM-baserad säkerhetsanalys för godkännande av åtgärder.

Modell- och leverantörskonfiguration via miljövariabler

OpenHands stöder miljövariabler för modellkonfiguration:

  • LLM_API_KEY sätter din leverantörs API-nyckel.
  • LLM_MODEL och LLM_BASE_URL kan appliceras som överkörningar när du kör openhands --override-with-envs.

Exempel på överkörningsflöde:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="din-api-nyckel"
openhands --override-with-envs

OpenHands noterar explicit att överkörningar applicerade med --override-with-envs inte sparas.

Underkommandon som är värda att känna till

Du behöver inte alla underkommandon från dag ett, men dessa är de som dyker upp snabbt:

  • openhands serve startar den fulla GUI-servern med hjälp av Docker, vanligtvis tillgänglig på http://localhost:3000, med alternativ som --mount-cwd och --gpu.
  • openhands web startar CLI:t som en webbapplikation som är tillgänglig i webbläsaren, med standardport 12000.
  • openhands login autentiserar med OpenHands Cloud och hämtar dina inställningar.
  • openhands cloud skapar ett nytt samtal i OpenHands Cloud från CLI:t.

Kopiera och klistra in exempel du kan använda omedelbart

Det snabbaste sättet att få värde från OpenHands är att behandla det som en uppgiftsdriven kodagent. Håll uppgifterna krispiga, inkludera filnamn och be om tester eller verifiering när det är lämpligt.

Starta en interaktiv kodsession med en initial uppgift

Detta är “standardutvecklareupplevelsen” och ett av de vanligaste mönstren.

openhands -t "Fixa buggen i auth.py och lägg till ett regressionstest"

OpenHands CLI-dokumentation visar exakt denna idé för att bootstrappa en session med -t.

Sätt en uppgift från en fil

Att använda en fil är användbart när du vill ha upprepningsbarhet, teamgranskning eller CI-återanvändning.

cat > task.txt << 'EOF'
Refaktorera databaskopplingsmodulen.
Lägg till enhetstester och se till att testsuiten passerar.
EOF

openhands -f task.txt

CLI Snabbstart stöder explicit att starta från en uppgiftsfil med -f.

Kör i headless-läge för CI eller automatisering

Headless-läge kör utan interaktivt användargränssnitt och är byggt för CI-pipelines och automatiserade skript.

openhands --headless -t "Lägg till enhetstester för auth.py och kör dem"

Två viktiga ingenjörsmässiga realiteter här:

  • Headless-läge kräver --task eller --file.
  • Headless-läge kör alltid i always-approve-läge och kan inte ändras, och --llm-approve är inte tillgängligt i headless-läge. Behandla det som kraftfull automatisering och kör det i en kontrollerad miljö.

För att integrera med loggparsing eller andra verktyg, aktivera JSONL-utdata:

openhands --headless --json -t "Skapa en enkel Flask-app med healthcheck-endpunkt" > openhands-output.jsonl

OpenHands dokumenterar --json som JSONL-händelseströmning i headless-läge och visar omdirigering av utdata till en fil.

Återuppta arbete utan att förlora kontext

Att återuppta är kritiskt när du börjar använda OpenHands för icke-triviala ändringar.

Lista senaste samtal:

openhands --resume

Återuppta den senaste:

openhands --resume --last

Eller återuppta en specifik samtal-ID:

openhands --resume abc123def456

Dessa flöden dokumenteras i CLI-kommandoreferensen och guiden “Resume Conversations”.

Kör CLI:t i en webbläsare när du behöver det

openhands web startar en webbåtkomlig CLI (standardport 12000).

openhands web

Om du kör lokalt är det en förnuftig standard att bara binda till localhost:

openhands web --host 127.0.0.1 --port 12000

OpenHands varnar för att att exponera webbgränssnittet mot nätverket kräver lämpliga säkerhetsåtgärder, eftersom det ger full tillgång till OpenHands-funktioner.

Säkerhet, felsökning och skarpa kanter

Den viktigaste säkerhetsknappen i OpenHands CLI är godkännanden:

  • Interaktiv CLI kan be om bekräftelse innan känsliga åtgärder, och du kan konfigurera bekräftelseinställningar under sessionen.
  • --always-approve tar bort friktion men tar också bort säkerhetsåtgärder.
  • --llm-approve lägger till en LLM-baserad analys för godkännanden.
  • Headless-läge godkänner alltid, så reservera det för automatisering i kontrollerade miljöer.

När du arbetar med lokal kod, föredra explicita, minst privilegierade tillgångsmönster:

  • För GUI-servern, openhands serve --mount-cwd monterar din nuvarande katalog till /workspace så att agenten kan läsa och ändra dina projektfiler.
  • För Docker-baserade CLI-körningar, använd SANDBOX_VOLUMES för att definiera exakt vilka kataloger OpenHands kan få tillgång till.

Om du har äldre OpenHands-tillståndsarkiv, noterar OpenHands en migreringsväg från ~/.openhands-state till ~/.openhands i dokumentationen för lokal uppställning och felsökningsguider.

Slutligen, om du integrerar OpenHands i skript, är utgångskoder dokumenterade som:

  • 0 framgång
  • 1 fel eller uppgift misslyckades
  • 2 ogiltiga argument

Min erfarenhet med OpenHands

För mig fungerade OpenHands bra, men inte alltid… Jag försökte få det att fungera med Devstral-Small-2 hostad på Ollama, och det stannade ständigt.

OpenHands with Ollama-hosted Devstral-Small-2.

Även om OpenHands fungerade bra med lokal hostad på llama.cpp Qwen 3.5 35b Så långt har OpenCode varit mycket mer pålitlig för mig.