OpenHands 코딩 비서 빠른 시작: 설치, CLI 플래그, 예시

OpenHands CLI, 몇 분 만에 빠르게 시작하세요

Page content

OpenHands 는 AI 기반 소프트웨어 개발 에이전트를 위한 오픈소스, 모델 불특정 플랫폼입니다. 이 플랫폼은 에이전트가 단순한 자동 완성 도구가 아닌, 실제 코딩 파트너처럼 행동할 수 있도록 합니다.

OpenHands 는 파일을 조작하고, 샌드박스 환경에서 명령을 실행하며, 필요 시 웹 브라우징을 수행할 수 있습니다.

이 빠른 시작 가이드는 OpenHands CLI에 초점을 맞추고 있습니다. 이는 터미널에서 가장 빠르게 생산성을 높일 수 있는 방법이며, 스크립트나 CI 실행과 같은 자동화 패턴과 깔끔하게 매핑되기 때문입니다. 더 넓은 범위의 정보를 원하시면 AI 개발 도구: AI 기반 개발을 위한 완전 가이드 를 참조하세요.

openhands text user interface

OpenHands 란 무엇이며, 무엇이 다른가?

AI 코딩 어시스턴트는 일반적으로 언어 모델을 사용하여 코드를 생성하거나 편집하도록 도와줍니다. OpenHands 는 이 개념을 “에이전트” 워크플로우로 확장합니다: 시스템은 반복적으로 계획을 세우고, 동작을 취하며 (파일 작성이나 테스트 실행 등), 결과를 관찰하고, 작업이 완료될 때까지 계속합니다.

OpenHands 는 과거 OpenDevin이라고 불리던 프로젝트로도 널리 알려져 있으며, CLI, 로컬 웹 GUI, 클라우드 호스팅 UI, SDK 등 다양한 사용 방식을 갖춘 커뮤니티 주도 플랫폼으로 성장했습니다.

엔지니어링 관점에서 핵심 차별점은 OpenHands 가 에이전트가 텍스트만 생성하는 것이 아니라 안전하게 명령과 도구를 실행할 수 있도록 실행 환경 (샌드박스) 을 중심으로 구축되었다는 점입니다. OpenHands 논문은 현실적인 개발자 상호작용 패턴을 지원하기 위해 쉘과 브라우징 기능을 갖춘 Docker 샌드박스 런타임 환경을 설명합니다.

OpenHands CLI 설치

OpenHands 는 여러 설치 방법을 지원합니다. 대부분의 개발자에게는 로컬 CLI 설치 (빠른 반복) 로 시작하고, 나중에 실행 시 엄격한 격리가 필요할 때 Docker 기반 워크플로우를 선택적으로 추가하는 것이 좋습니다.

uv 를 통한 설치

현재 OpenHands CLI 문서는 uv를 사용하여 설치를 권장하며, **Python 3.12+**가 필요합니다.

uv tool install openhands --python 3.12
openhands

업그레이드도 마찬가지로 간단합니다.

uv tool upgrade openhands --python 3.12

왜 실제로는 uv 가 중요한가요? uv 는 현재 프로젝트 환경과 더 나은 격리를 제공하며, 기본 MCP 서버에 필수적입니다.

독립 실행형 CLI 이진 파일 설치

“단일 명령"설치 흐름을 원한다면 OpenHands 는 설치 스크립트를 제공합니다.

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

macOS 를 사용하는 경우 실행하기 전에 ‘보안 및 개인정보’에서 이진 파일을 명시적으로 허용해야 할 수 있습니다.

격리를 위해 Docker 로 실행

설치를 제한된 상태로 유지하려는 경우, CLI 문서에는 Docker 기반 흐름도 제시되어 있습니다. 이 방식은 OpenHands 가 접근할 디렉터리를 마운팅하고, 마운팅된 워크스페이스에 루트 소유 파일을 생성하지 않도록 사용자 ID 를 전달하는 데 의존합니다.

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"

첫 실행 설정 및 설정 저장 위치

최초 실행 시 CLI 는 필요한 LLM 설정 구성을 안내하며, 향후 세션을 위해 이를 저장합니다. CLI 문서에 따르면 설정은 ~/.openhands/settings.json에 저장되고 대화 내역은 ~/.openhands/conversations에 저장되지만, 제가 최근 OpenHands 를 설치했을 때 설정은 ~/.openhands/agent_settings.json에 저장되었습니다. 따라서 문서가 완전히 정확한 것은 아닐 수 있습니다.

더 깊은 설정 및 도구 통합을 위해 OpenHands 는 ~/.openhands/agent_settings.json(에이전트 및 LLM 설정), ~/.openhands/cli_config.json(CLI 환경 설정), ~/.openhands/mcp.json(MCP 서버) 과 같은 추가 설정 파일도 문서화하고 있습니다.

로컬 Ollama 및 llama.cpp 와 함께 OpenHands 설정

OpenHands 는 OpenAI 호환 로컬 백엔드 (Ollama, LocalAI, llama.cpp 등) 와 함께 작동합니다. 어떤 것을 사용해야 할지 확실하지 않다면, Ollama vs vLLM vs LM Studio: 로컬에서 LLM 실행하는 최상의 방법 에서 비교를 확인하세요.

OpenHands 를 처음 시작하면 설정 페이지가 표시됩니다. 이미 이 첫 단계를 넘어섰다면 /settings를 입력한 다음 ctrl+j를 눌러 다시 이 페이지를 열 수 있습니다. 이제 다음을 입력합니다.

  • Custom Model 필드: ollama/devstral-small-2:24b 또는 선호하는 다른 로컬 모델
  • Base Url 필드: http://localhost:11434

openhands settings ollama mistral

Ollama 명령에 대한 빠른 참조는 Ollama CLI 치트시트: serve, run, ps 및 모델 관리 를 참조하세요.

설정 페이지의 외관을 마음에 들지 않는 경우 OpenHands 설정 파일을 수동으로 편집하려면 다음을 실행합니다.

nano ~/.openhands/agent_settings.json

또는 GUI 가 더 많은 에디터를 선호한다면:

gedit GUI ~/.openhands/agent_settings.json

llm 속성은 두 곳에 있으며, 저는 이 중 일부가 ollama 를 참조하도록 하위 속성을 설정했습니다.

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

OpenHands 를 로컬 llama.cpp 인스턴스를 가리키려면 동일한 방식으로 두 곳에서 설정합니다:

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

llama.cpp 에 연결하기 위해 다음과 같이 구성했습니다.

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

다음 명령으로 llama.cpp 를 시작했습니다 (플래그 세부 사항은 llama.cpp CLI 및 서버를 사용한 빠른 시작 참조):

./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 는 이를 연결하여 “웹사이트 변경 사항을 알리기 위해 bing 및 다른 검색 엔진의 indexnow 엔드포인트를 호출하는 Go CLI 도구를 만들어줘"라는 테스트 요청을 성공적으로 완료했습니다. 소스 코드, 실행 파일, README.md 가 모두 생성되었습니다.

실제 OpenHands CLI 동작 방식

기본 openhands 명령은 대화형 터미널 경험을 시작합니다. OpenHands 는 에이전트가 작업하는 동안 에이전트를 빠르게 조종할 수 있도록 명령 팔레트 및 세션 내 명령을 제공합니다.

초기에 알아야 할 유용한 대화형 제어 기능에는 명령 팔레트 열기, 에이전트 일시 중지, 애플리케이션 종료 등이 포함됩니다.

  • Ctrl+P는 명령 팔레트를 엽니다.
  • Esc는 실행 중인 에이전트를 일시 중지합니다.
  • Ctrl+Q 또는 /exit는 CLI 를 종료합니다.

CLI 내부에서 OpenHands 는 /help, /new, /condense와 같은 슬래시 접두사 명령도 지원합니다. 이는 재시작 없이 긴 대화를 관리할 때 유용합니다.

OpenHands 는 터미널 UI 에서 멈추지 않습니다. CLI 는 다양한 개발자 워크플로우에 잘 매핑되는 여러 인터페이스를 포함합니다:

  • 자동화 및 CI 를 위한 헤드리스 모드.
  • 브라우저에서 CLI 경험을 실행하기 위한 웹 인터페이스.
  • Docker 를 통해 시작되는 전체 로컬 웹 애플리케이션을 위한 GUI 서버.
  • 에디터 기반 워크플로우를 위한 ACP 를 통한 IDE 통합.

실제로 사용할 주요 명령줄 매개변수

높은 수준에서 OpenHands CLI 는 다음과 같은 형태를 따릅니다:

openhands [OPTIONS] [COMMAND]

이는 전역 옵션 (작업, 재시작, 헤드리스 등) 과 하위 명령 (serve, web, cloud, acp, mcp, login, logout) 을 포함합니다.

일상 작업용 핵심 옵션

가장 일반적으로 사용되는 전역 옵션은 다음과 같습니다:

  • -t, --task: 대화에 초기 작업을 시드합니다.
  • -f, --file: 파일을 시드합니다. 작업이 버전 관리에 커밋되어 있을 때 유용합니다.
  • --resume [ID] 및 --last: 이전 실행을 계속합니다.
  • --headless: 비대화형 실행, 일반적으로 자동화에 사용됩니다.
  • --json: 머신 파싱을 위해 헤드리스 모드에서 JSONL 출력을 스트리밍합니다.

안전성과 승인도 일급 시민입니다:

  • --always-approve: 프롬프트 없이 동작을 자동으로 승인합니다.
  • --llm-approve: LLM 기반 보안 분석기를 사용하여 동작을 승인합니다.

환경 변수를 통한 모델 및 제공자 구성

OpenHands 는 모델 구성을 위해 환경 변수를 지원합니다:

  • LLM_API_KEY: 제공자 API 키를 설정합니다.
  • LLM_MODEL 및 LLM_BASE_URL: openhands --override-with-envs를 실행할 때 오버라이드로 적용할 수 있습니다.

예시 오버라이드 흐름:

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

OpenHands 는 명시적으로 --override-with-envs로 적용된 오버라이드가 지속되지 않는다고 명시합니다.

알아야 할 하위 명령

하루 만에 모든 하위 명령이 필요한 것은 아니지만, 이 명령들은 빠르게 필요해집니다:

  • openhands serve: Docker 를 사용하여 전체 GUI 서버를 시작합니다. 일반적으로 http://localhost:3000에서 접근 가능하며, --mount-cwd 및 --gpu와 같은 옵션이 있습니다.
  • openhands web: CLI 를 브라우저에서 접근 가능한 웹 애플리케이션으로 시작하며, 기본 포트는 12000입니다.
  • openhands login: OpenHands Cloud 와 인증하고 설정을 가져옵니다.
  • openhands cloud: CLI 에서 OpenHands Cloud 에 새로운 대화를 생성합니다.

즉시 사용할 수 있는 복사 및 붙여넣기 예시

OpenHands 에서 가치를 얻는 가장 빠른 방법은 이를 작업 주도형 코딩 에이전트처럼 대하는 것입니다. 작업을 명확하게 하고, 파일 이름을 포함하며, 적절한 경우 테스트 또는 검증을 요청하세요.

초기 작업으로 대화형 코딩 세션 시작

이는 “기본 개발자 경험"이며 가장 일반적인 패턴 중 하나입니다.

openhands -t "auth.py 의 버그를 수정하고 회귀 테스트를 추가하세요"

OpenHands CLI 문서는 -t로 세션을 부트스트랩하는 이 아이디어를 정확히 보여줍니다.

파일에서 작업 시드

파일 사용은 재현 가능성, 팀 검토 또는 CI 재사용이 필요할 때 유용합니다.

cat > task.txt << 'EOF'
데이터베이스 연결 모듈을 리팩토링하세요.
유닛 테스트를 추가하고 테스트 수트가 통과하도록 하세요.
EOF

openhands -f task.txt

CLI 빠른 시작은 -f로 작업 파일에서 시작하는 것을 명시적으로 지원합니다.

CI 또는 자동화를 위한 헤드리스 모드 실행

헤드리스 모드는 대화형 UI 없이 실행되며 CI 파이프라인 및 자동화 스크립팅을 위해 구축되었습니다.

openhands --headless -t "auth.py 에 대한 유닛 테스트를 추가하고 실행하세요"

여기서 두 가지 중요한 엔지니어링 현실이 있습니다:

  • 헤드리스 모드는 --task 또는 --file이 필요합니다.
  • 헤드리스 모드는 항상 승인 모드로 실행되며 변경할 수 없고, --llm-approve는 헤드리스 모드에서 사용할 수 없습니다. 강력한 자동화로 간주하고 제어된 환경에서 실행하세요.

로그 파싱 또는 기타 도구와 통합하려면 JSONL 출력을 활성화하세요:

openhands --headless --json -t "헬스체크 엔드포인트가 있는 간단한 Flask 애플리케이션을 생성하세요" > openhands-output.jsonl

OpenHands 는 --json을 헤드리스 모드에서의 JSONL 이벤트 스트리밍으로 문서화하며 출력 파일을 리디렉션하는 방법을 보여줍니다.

컨텍스트 손실 없이 작업 재개

OpenHands 를 비자명한 변경 사항에 사용할 때 재개는 중요합니다.

최근 대화 목록:

openhands --resume

가장 최근 대화 재개:

openhands --resume --last

또는 특정 대화 ID 재개:

openhands --resume abc123def456

이 흐름은 CLI 명령 참조 및 “대화 재개” 가이드에 문서화되어 있습니다.

필요 시 브라우저에서 CLI 실행

openhands web는 웹 접근 가능한 CLI 를 시작합니다 (기본 포트 12000).

openhands web

로컬에서 실행 중인 경우, 로컬호스트에만 바인딩하는 것이 합리적인 기본값입니다:

openhands web --host 127.0.0.1 --port 12000

OpenHands 는 웹 인터페이스를 네트워크에 노출하는 경우 OpenHands 기능을 완전히 접근할 수 있으므로 적절한 보안 조치가 필요하다고 경고합니다.

안전성, 문제 해결 및 주의 사항

OpenHands CLI 에서 가장 중요한 안전성 레버는 승인입니다:

  • 대화형 CLI 는 민감한 동작 전에 확인을 요청할 수 있으며, 세션 내에서 확인 설정을 구성할 수 있습니다.
  • --always-approve는 마찰을 제거하지만 안전장치도 제거합니다.
  • --llm-approve는 승인을 위한 LLM 기반 분석기를 추가합니다.
  • 헤드리스 모드는 항상 승인하므로 제어된 환경의 자동화에만 예약하세요.

로컬 코드와 작업할 때는 명시적이고 최소 권한 접근 패턴을 선호하세요:

  • GUI 서버의 경우, openhands serve --mount-cwd는 현재 디렉터리를 /workspace에 마운팅하여 에이전트가 프로젝트 파일을 읽고 수정할 수 있게 합니다.
  • Docker 기반 CLI 실행의 경우, SANDBOX_VOLUMES를 사용하여 OpenHands 가 접근할 수 있는 디렉터리를 정확히 정의하세요.

구식 OpenHands 상태 디렉터리가 있는 경우, OpenHands 는 로컬 설정 문서 및 문제 해결 가이드에서 ~/.openhands-state에서 ~/.openhands로의 마이그레이션 경로를 명시합니다.

마지막으로 OpenHands 를 스크립트에 통합하는 경우, 종료 코드는 다음과 같이 문서화되어 있습니다:

  • 0 성공
  • 1 오류 또는 작업 실패
  • 2 잘못된 인수

제가 OpenHands 를 사용한 경험

저에게 OpenHands 는 잘 작동했지만, 항상 그런 것은 아니었습니다… 저는 Ollama 에 호스팅된 Devstral-Small-2 와 함께 작동하게 하려고 시도했지만, 계속 중단되었습니다.

OpenHands with Ollama-hosted Devstral-Small-2.

하지만 OpenHands 는 로컬에서 호스팅된 llama.cpp Qwen 3.5 35b 와 함께 잘 작동했습니다. 지금까지 저에게 OpenCode 가 훨씬 더 신뢰할 수 있었습니다.