OpenHands CLI란 무엇인가요

OpenHands CLI 1.16.0는 오픈소스 OpenHands 코딩 에이전트의 터미널 패키지로, 설정한 모델 제공자를 통해 변경 사항을 계획하고, 파일을 편집하며, 명령을 실행할 수 있습니다. OpenHands-CLI의 기본 브랜치 README는 이제 신규 설치 시 Agent Canvas를 안내합니다.

macOS 또는 Linux에 OpenHands CLI를 설치하는 방법은 무엇입니까

발행된 패키지는 Python 3.12(PyPI 제약 조건은 ==3.12.*)와 0.11.6 이상의 uv를 요구합니다. uv tool install openhands --python 3.12 명령을 사용하여 설치하거나, install.openhands.dev에 위치한 설치 스크립트를 사용하세요. Windows 환경에서는 CLI 문서에 따라 WSL 내부에서 해당 명령을 실행해야 합니다.

OpenHands 모델을 구성하는 환경 변수는 무엇입니까

--override-with-envs 옵션을 전달하지 않는 한 LLM_API_KEY, LLM_MODEL, LLM_BASE_URL은 무시됩니다. 이 방식으로 적용된 오버라이드는 agent_settings.json에 다시 기록되지 않습니다.

CI에서 OpenHands를 헤드리스 모드로 실행하는 방법은?

openhands --headless 를 --task 또는 --file 과 함께 실행하세요. 헤드리스 모드에서는 모든 작업이 자동으로 승인되며, --llm-approve 옵션은 사용할 수 없습니다. JSONL 이벤트를 스트리밍하려면 --json 을 추가하세요.

CLI에서 OpenHands 대화를 어떻게 재개합니까?

openhands –resume를 실행하여 최근 세션을 표시하고, openhands –resume CONVERSATION_ID를 실행하여 특정 세션을 복구하거나, openhands –resume –last를 실행하여 가장 최근 대화를 복구할 수 있습니다.

OpenHands 터미널 UI를 대체한 것

Agent Canvas는 프로젝트 문서에 현재 명시된 브라우저 제어 표면입니다. npx @openhands/agent-canvas 명령으로 실행하며, Node.js 24 이상과 uv가 필요합니다. 해당 도구는 http://localhost:8000 에서 리스닝합니다. openhands serve 는 여전히 포트 3000에서 기존(레거시) GUI를 시작하지만, Agent Canvas는 실행하지 않습니다.

OpenHands CLI QuickStart: 설치, 플래그, 헤드리스 모드

CLI 설치, 플래그, 헤드리스, 로컬 모델

Page content

OpenHands는 샌드박스 내에서 파일을 편집하고 명령을 실행하는 오픈소스 코딩 에이전트입니다. 이 CLI 퀵스타트는 2026년 10월 26일에 패키지 1.16.0 버전으로 검증되었습니다.

PyPI의 패키지는 2026년 5월 8일에 업로드된 openhands 1.16.0으로, openhands-sdk==1.21.0으로 고정되어 있습니다. 태그 README는 Python 3.12 및 0.11.6 이상 uv를 요구합니다. OpenHands-CLI의 기본 분기 README는 해당 저장소가 더 이상 능동적으로 유지보수되지 않는다고 명시하며, 신규 설치는 Agent Canvas로 유도합니다. 헤드리스 모드와 openhands acp는 여전히 1.16.0 명령 세트의 일부입니다.

openhands 텍스트 사용자 인터페이스

AI 개발 도구 가이드는 이 사이트의 다른 터미널 에이전트들을 따릅니다. 이 페이지는 OpenHands CLI에 집중합니다: 설치, 설정 파일, 로컬 모델 URL, 그리고 스크립트가 실제로 전달하는 플래그들.

CLI란 무엇인가

AI 코딩 어시스턴트는 일반적으로 프롬프트로부터 코드를 생성하거나 편집합니다. OpenHands는 이를 에이전트 루프로 확장합니다: 계획, 파일 작성이나 테스트 실행과 같은 행동 수행, 결과 관찰, 그리고 지속. 이 프로젝트는 과거에는 OpenDevin으로 불렸습니다. OpenHands 논문은 셸과 브라우징이 포함된 Docker 샌드박스 런타임을 설명하며, 이는 CLI가 여전히 래핑하는 실행 모델입니다.

릴리스 1.16.0은 이 루프를 실행하는 5가지 방법을 문서화합니다.

모드	명령	용도
터미널 UI	`openhands`	인터랙티브 세션. 승인 플래그를 전달하지 않는 한 각 동작 전에 질문합니다.
헤드리스	`openhands --headless -t "task"`	CI와 스크립트. `--task` 또는 `--file`이 필요합니다. 항상 동작을 승인합니다.
ACP	`openhands acp`	Zed, JetBrains, Toad, VS Code ACP 확장용 Agent Client Protocol 서버.
브라우저 TUI	`openhands web`	브라우저에서의 동일한 CLI. 기본 바인딩은 `0.0.0.0:12000`입니다.
레거시 GUI	`openhands serve`	CLI 런처를 통한 Docker GUI. 기본 URL `http://localhost:3000`.

현재 프로젝트가 문서화하는 설치 방법인 Agent Canvas

2026년 6월 3일 OpenHands FAQ는 터미널 UI를 2026년 10월 1일까지 유지보수 상태로 전환하고, 헤드리스 모드와 ACP는 완전히 지원된다고 발표했습니다. 로컬 GUI(openhands serve)는 Agent Canvas가 격리되고 일회용 샌드박스를 실행할 수 있을 때까지 유지보수 상태에 머물러야 했습니다. 해당 FAQ는 유지보수를 의존성 업데이트, 중대한 버그 수정, 그리고 새로운 LLM 지원으로 정의합니다. 주요 OpenHands 저장소는 2026년 10월 23일에 Agent Canvas 1.33.0을 배포했습니다.

agent-canvas는 현재 UI와 그 백엔드를 시작합니다. openhands serve는 레거시 GUI를 시작하며 Agent Canvas는 시작하지 않습니다.

Agent Canvas에는 Node.js 24 이상과 uv가 필요합니다. 전역 설치 없이 최초 실행하는 경우:

npx @openhands/agent-canvas

이 프로세스는 http://localhost:8000에서 리스닝합니다. 그 터미널을 닫으면 로컬 백엔드가停止됩니다. 전역 설치는 npm install -g @openhands/agent-canvas이고, 그 후 agent-canvas를 실행합니다. npm 경로는 에이전트 서버를 사용자의 계정으로 실행하므로, 에이전트는 사용자의 계정 권한으로 로컬 파일에 작용할 수 있습니다.

Docker 경로는 포트에 로컬호스트만 발행하고 프로젝트 디렉터리를 마운트합니다:

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

컨테이너는 http://localhost:8000/canvas에서 UI를 서빙합니다. 지정된 볼륨 openhands-data는 --rm 후에도 설정을 유지합니다. Linux에서 이 이미지에 ~/.openhands를 바인드 마운트하면 unable to open database file 오류가 발생합니다: 컨테이너 사용자는 UID 10001이며, 호스트 디렉터리는 일반적으로 사용자의 UID로 소유됩니다. 설치 페이지는 그 이유로 지정된 볼륨을 사용합니다. ~/.openhands에 이미 있는 설정은 새로운 볼륨으로 복사되지 않습니다.

OpenHands CLI 설치

openhands --headless 또는 openhands acp를 여전히 사용하려는 경우 CLI를 사용하세요. 게시된 휠은 Python 3.12에서만 설치됩니다(PyPI의 ==3.12.*). uv는 0.11.6 이상이어야 합니다. Windows에서는 설치 페이지에서 WSL(Ubuntu)에서 명령을 실행하라고 명시합니다.

uv로 설치

uv tool install openhands --python 3.12
openhands

동일한 인터프리터 핀으로 업그레이드합니다:

uv tool upgrade openhands --python 3.12

로컬-설정 페이지는 uv가 CLI를 프로젝트 가상环境与에서 격리시키며, 기본 MCP 서버가 이를 요구한다고 말합니다.

스탠드얼론 바이너리 설치

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

macOS에서 Gatekeeper 다이아로그가 바이너리를 차단할 수 있습니다(“Apple이 악성 소프트웨어 여부를 확인할 수 없어 openhands를 열 수 없음”). 설치 페이지의 경로는 시스템 설정, 개인 정보 및 보안, 그 다음 보안에서 어쨌든 허용, 그리고 openhands를 다시 실행하는 것입니다.

Docker를 통해 CLI 실행

설치 페이지의 컨테이너는 AGENT_SERVER_IMAGE_TAG를 에이전트-서버 이미지로 설정합니다. 컨테이너 내부의 uv tool install openhands는 PyPI CLI입니다. 이 페이지를 위해 확인된 해당 예제의 태그는 1.26.0-python입니다. 이 명령의 이전 복사본은 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)는 샌드박스 사용자가 호스트 사용자와 일치하도록 하여, 에이전트가 마운트된 워크스페이스에 루트 소유 파일이 남지 않도록 합니다. SANDBOX_VOLUMES는 에이전트가 액세스할 수 있는 디렉터리입니다.

OPENHANDS_VERSION은 openhands serve의 Docker 이미지 버전을 선택합니다. 이는 PyPI CLI 버전을 변경하지 않습니다.

설정 파일

최초 실행 시 CLI는 모델 설정을 묻고 ~/.openhands/ 아래로 작성합니다. 1.16.0 README와 명령 참고자료는 이 파일들을 이름으로 지칭합니다:

파일	보유 내용
`~/.openhands/agent_settings.json`	영속화된 에이전트 스펙, LLM 블록 및 컨덴서 구성 포함
`~/.openhands/cli_config.json`	CLI 선호 설정, 크리틱 활성화 여부 포함
`~/.openhands/mcp.json`	MCP 서버 정의
`~/.openhands/conversations/`	대화 기록

설치 페이지는 여전히 Docker 사용자에게 ~/.openhands/settings.json을 준비하라고 말합니다. CLI README와 1.16.0 트리에서의 AgentStore는 에이전트 스펙을 agent_settings.json에 영속화합니다. 설치 페이지의 파일명을 건너뛰고 agent_settings.json으로 작성한 CLI 설치와 그 소스는 일치합니다.

create_and_save_from_settings는 동일한 모델, API 키, 기본 URL로부터 두 개의 LLM 개체를 생성합니다: 하나는 에이전트를 위해, 다른 하나는 요약하는 컨덴서를 위해. 따라서 저장된 파일에서 llm 필드가 반복되는 것입니다. 에이전트 파일을 아무 에디터로든 편집하세요:

nano ~/.openhands/agent_settings.json

LLM_API_KEY, LLM_MODEL, LLM_BASE_URL은 옵트인을 하지 않으면 무시됩니다. 이 오버라이드는 저장되지 않습니다:

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

OPENHANDS_CLOUD_URL은 기본 클라우드 서버를 설정합니다. cloud와 login 명령은 그 변수가 설정되지 않았을 때 https://app.all-hands.dev를 기본값으로 사용합니다.

1.0.0 이전의 CLI로부터의 업그레이드는 설정을 다시 입력해야 합니다. 설치 페이지는 구성 형식이 1.0.0에서 변경되었다고 말합니다.

로컬 모델

2026년 5월 21일자로 발행된 로컬-LLM 가이드는 첫 로컬 모델로 시도할 것을 Qwen3.6-35B-A3B로 권장합니다. 양자화 빌드의 경우 최소 24GB VRAM의 GPU, 또는 최소 64GB 통합 메모리의 Apple Silicon Mac을 요구합니다. 동일한 페이지는 컨텍스트 길이를 최소 22000 토큰으로 설정하고, 시스템 프롬프트에 대해 Ollama의 기본값 4096은 너무 작다고 말합니다.

에이전트가 도구를 호출하지 않는 경우, 가이드는 이를 모델 한계로 취급하며 qwen2.5-coder-14b-instruct와 qwopus3.5-27b-v3에 대한 커뮤니티 보고를 인용합니다. 로컬 호스팅 비교는 Ollama, vLLM, LM Studio, LocalAI가 여전히 선택지일 때 서버별 테이블입니다.

Ollama

가이드의 Ollama 시작은 ollama serve 전에 컨텍스트 길이를 설정합니다. Ollama CLI 치트시트는 그 변수 옆에 serve, run, ps를 다룹니다.

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

Docker에서 실행되는 OpenHands에 대해, 가이드의 설정은 커스텀 모델 openai/qwen3.6:35b-a3b, 기본 URL http://host.docker.internal:11434/v1, 그리고 아무 플레이스홀더 API 키입니다. Ollama와 동일한 호스트에서 실행되는 CLI는 host.docker.internal 대신 http://127.0.0.1:11434/v1을 사용합니다. Linux LM Studio 및 기타 루프백 전용 서버는 컨테이너에서 127.0.0.1로는 도달할 수 없습니다. 가이드의 체크는 로컬 네트워크에서 서빙을 활성화하고 컨테이너 내부에서 host.docker.internal을 curl하는 것입니다.

터미널 페이지는 Ctrl+P, 그 다음 설정으로 그 화면을 엽니다. 저장된 CLI 프로필은 ollama/ 모델 ID와 /v1 없는 기본 URL을 사용했습니다:

커스텀 모델: ollama/devstral-small-2:24b
기본 URL: http://localhost:11434

openhands 설정 ollama mistral

그 Devstral-Small-2 세션은 계속 멈추던 것이었습니다. 에이전트 LLM과 컨덴서 LLM 양쪽 모두에 대해 작성된 필드들은:

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

llama.cpp과 vLLM

llama.cpp은 OpenAI 호환 접두사와 /v1 기본 URL을 사용했으며, 다시 한번 두 LLM 개체 모두에:

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

llama.cpp 퀵스타트에서 다루는 플래그를 가진 서버 명령은:

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

그 서버를 향한 CLI는 Go IndexNow 클라이언트를 완료했습니다: 소스, 실행 가능한 파일, 그리고 README. 작업 텍스트는 create for me a cli tool in Go, that would call bing and other search engines' indexnow endpoints to notify about changes on my website였습니다.

로컬-LLM 가이드의 더 새로운 Qwen3.6 모델용 vLLM 예제는 2-GPU 서빙입니다. vLLM 퀵스타트는 vllm serve 플래그와 아웃-오브-메모리 체크를 다룹니다. 가이드의 일치하는 OpenHands 모델 문자열은 openai/Qwen3.6-35B-A3B이고, 기본 URL은 http://host.docker.internal:8000/v1, 서버가 시작되었던 동일한 --api-key(mykey는 예제에서)입니다.

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

인터랙티브 제어

서브커맨드 없이 openhands를 실행하면 터미널 UI가 열립니다. 터미널 페이지는 이 제어들을 나열합니다:

제어	동작
`Ctrl+P`	커맨드 팔레트. 설정, MCP 상태, 히스토리, 계획, 테마, 종료.
`Esc`	실행 중인 에이전트 일시 정지.
`Ctrl+Q` 또는 `/exit`	CLI에서 나가기.

커맨드 참고자료의 슬래시 커맨드: /help, /new, /history, /confirm, /condense, /skills, /feedback, /exit. 팔레트 설정 항목에서의 모델 변경은 재시작 없이 적용됩니다. --exit-without-confirmation은 종료 다이아로그를 건너뜁니다. --exp는 텍스트 UI를 선택하며, 그 UI가 이미 기본값이기 때문에 호환성 플래그로 문서화되어 있습니다.

플래그와 서브커맨드

openhands [OPTIONS] [COMMAND]

커맨드 참고자료의 글로벌 옵션, 승인 및 환경 플래그는 1.16.0 태그의 argparsers/util.py에 대조하여 확인했습니다:

옵션	효과
`-v`, `--version`	버전을 출력하고 종료.
`-t`, `--task TEXT`	이 작업으로 대화 시작.
`-f`, `--file PATH`	파일로부터 대화 시작.
`--resume [ID]`	그 대화 복기. ID가 없으면 최근 대화 목록.
`--last`	`--resume`과 함께, 가장 최근 대화 복기.
`--headless`	UI 없음. `--task` 또는 `--file` 필요. 항상 승인.
`--json`	JSONL 이벤트 스트림. `--headless` 필요.
`--always-approve`, `--yolo`	모든 동작 승인. `--llm-approve`와 상호 배타적.
`--llm-approve`	LLM 보안 분석기가 고위험으로 표시한 동작에만 확인.
`--override-with-envs`	이 프로세스에 `LLM_API_KEY`, `LLM_MODEL`, `LLM_BASE_URL` 적용.
`--exit-without-confirmation`	확인 다이아로그 없이 종료.

--always-approve와 --llm-approve는 조합할 수 없습니다. 기본 인터랙티브 모드는 동작 전에 질문합니다.

TUI가 충분하지 않을 때 나타나는 서브커맨드:

openhands serve는 Docker에서 레거시 GUI를 시작합니다. --mount-cwd는 현재 디렉터리를 /workspace에 마운트합니다. --gpu는 nvidia-docker를 활성화합니다.
openhands web은 브라우저에서 CLI를 서빙합니다. --host는 0.0.0.0이 기본이고, --port는 12000, --debug는 꺼져 있습니다.
openhands acp는 stdio에서 Agent Client Protocol을 말합니다. 플래그: --resume, --last, --always-approve, --llm-approve, --streaming.
openhands cloud -t "task"는 클라우드 대화를 엽니다. --server-url은 https://app.all-hands.dev를 오버라이드합니다.
openhands login과 openhands logout은 그 클라우드 계정을 관리합니다. --server-url 없이 logout은 저장된 모든 서버에서 로그아웃합니다.
openhands mcp는 서버를 관리합니다: add, list, get, remove, enable, disable. add는 http, sse, 또는 stdio의 --transport가 필요합니다.

1.16.0 README의 MCP 서버:

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

예제

인터랙티브 작업

openhands -t "Fix the bug in auth.py and add a regression test"

작업 파일

cat > task.txt << 'EOF'
Refactor the database connection module.
Add unit tests and ensure the test suite passes.
EOF

openhands -f task.txt

헤드리스, JSONL 포함

헤드리스 모드는 --task 또는 --file이 필요합니다. 항상 항상-승인으로 실행되며, --llm-approve는 거절됩니다. 작업 디렉터리를 에이전트가 자유롭게 수정할 수 있는 것으로 취급하세요.

openhands --headless -t "Add unit tests for auth.py and run them"

openhands --headless --json -t "Create a simple Flask app with healthcheck endpoint" > openhands-output.jsonl

헤드리스 페이지는 --json을 이벤트당 하나의 JSON 객체로, JSONL로 스트림된다고 설명합니다.

복기

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

로컬호스트 바인딩된 브라우저 TUI

openhands web은 네트워크에서 도달 가능한 0.0.0.0:12000이 기본값입니다. CLI 문서에 따르면 그 인터페이스는 CLI의 완전한 능력을 가지므로, 로컬 전용 바인딩이 더 안전한 기본값입니다:

openhands web --host 127.0.0.1 --port 12000

에디터용 ACP

IDE 페이지의 ACP 클라이언트는 Zed와 JetBrains(네이티브), Toad(네이티브), VS Code(커뮤니티 확장)입니다. 에디터는 openhands acp를 시작하고 stdio에서 JSON-RPC 2.0을 말하며, CLI의 저장된 LLM 설정을 사용합니다.

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

승인, 종료 코드, 로컬 모델 결과

인터랙티브 세션은 동작 전에 질문합니다. /confirm은 세션에서 그 정책을 변경합니다. --always-approve(별명 --yolo)는 모든 것을 승인합니다. --llm-approve는 보안 분석기가 고위험으로 스코어링한 동작에만 질문합니다. 헤드리스 모드는 전체 실행 동안 항상-승인입니다.

openhands serve --mount-cwd는 레거시 GUI 컨테이너 내부에서 현재 디렉터리를 /workspace에 마운트합니다. Docker CLI 플로는 동일한 경계에 대해 SANDBOX_VOLUMES를 사용합니다.

커맨드 참고자료의 종료 코드:

코드	의미
0	성공
1	오류 또는 작업 실패
2	잘못된 인자

Ollama의 Devstral-Small-2 24B는 이 CLI에서 반복적으로 멈추었습니다.

Ollama 호스팅 Devstral-Small-2와 함께하는 OpenHands

위의 llama.cpp 세션, 70000 토큰 컨텍스트의 Qwen3.5-35B-A3B는 IndexNow 작업을 완료했습니다. 동일한 기계에서 계속 작업하는 터미널 에이전트에 대해, OpenCode 퀵스타트가 설치와 프로바이더 설정입니다.