OpenHands 사용법 2026 — 설치 명령이 바뀌었다, Agent Canvas와 샌드박스 없는 기본 경로
OpenHands 설치 명령이 바뀌었다. 검색에 나오는 포트 3000 docker run 은 공식이 폐기로 표시했고, 지금 권장은 npm 으로 띄우는 Agent Canvas 다. 그 기본 경로는 샌드박스가 없어 파일시스템에 접근한다. 모델 연결도 환경변수가 아니라 UI 로 옮겨졌다.
OpenHands를 검색해서 나오는 설치 명령 대부분이 지금 공식 문서가 「deprecated legacy」로 못 박은 것이다. 포트 3000에 docker run … openhands:1.8 하는 그 한 줄이다. 결론부터 적는다.
- 지금 권장 경로는 npm이다.
npm install -g @openhands/agent-canvas→agent-canvas→http://localhost:8000. 제품 이름도 Agent Canvas로 바뀌었다. - 🔴 그 npm 경로는 샌드박스가 없다. 공식 문서 표현 그대로 「에이전트가 당신의 파일시스템에 완전히 접근한다」. 격리를 원하면 Docker 경로를 써야 한다.
- 모델 연결은 더 이상 환경변수가 아니다. UI(
Settings > LLM)에서 고른다.LLM_MODEL·LLM_API_KEY같은 이름은 현행 문서에 없다. - 문서 호스트도 옮겨졌다 —
docs.all-hands.dev는docs.openhands.dev로 308 리다이렉트된다.
아래 명령과 이름은 2026-11-17에 공식 문서와 저장소 README를 직접 대조한 것이다.
바뀐 것부터 — 옛 명령을 그대로 쓰면 폐기된 제품이 뜬다
| 옛 경로 (deprecated) | 지금 경로 | |
|---|---|---|
| 제품 | OpenHands 로컬 GUI | Agent Canvas |
| 설치 | docker run … docker.openhands.dev/openhands/openhands:1.8 | npm install -g @openhands/agent-canvas |
| 포트 | 3000 | 8000 (/canvas) |
| CLI | openhands serve → 「더 이상 유지되지 않음」 | agent-canvas |
| 문서 | docs.all-hands.dev | docs.openhands.dev (308) |
| 저장소 | All-Hands-AI/OpenHands | OpenHands/OpenHands (옛것은 OpenHands/legacy에 보관) |
별도 저장소였던 OpenHands-CLI도 공식 문서가 「더 이상 활발히 유지되지 않는다」고 적는다. 즉 지금 블로그에서 보는 세 가지 설치법(옛 docker, openhands serve, 별도 CLI)이 전부 폐기 표시가 붙은 쪽이다.
🔴 가장 중요한 것 — 권장 설치가 당신의 디스크를 그대로 준다
여기서 사고가 난다. npm·npx·소스 빌드로 띄우면 에이전트 서버가 당신의 머신에서 직접 돌고, 공식 문서는 이렇게 적는다 — 「에이전트가 당신의 파일시스템에 완전히 접근한다」. 그리고 설치 페이지에 별도 경고가 하나 더 있다.
에이전트와 ACP 프로세스를 신뢰할 수 없는 것으로 취급하라. 당신 계정 권한으로 셸 명령을 실행하고 파일을 읽고 쓸 수 있다. Agent Canvas는 클라이언트일 뿐이고 그것들을 격리하지 않는다.
읽는 순서를 바꿔 적으면 이렇다 — 「Docker로 돌리니까 안전하겠지」가 npm 경로에는 해당하지 않는다. 많은 소개 글이 Docker 한 줄만 보여 주고 넘어가는데, 지금 문서가 첫 번째로 권하는 것은 npm이고 그쪽은 격리가 없다.
그래서 실무 기준은 단순하다.
- 내 개인 머신에서 가볍게 써 본다 → npm으로 띄우고, 민감한 디렉터리가 없는 사용자 계정에서 돌린다.
- 사내 저장소·고객 코드를 만진다 → Docker 경로만 쓴다. 마운트한 디렉터리 밖은 보이지 않는다.
이 구분이 특히 중요한 이유가 하나 더 있다. 코딩 에이전트는 작업 중에 스스로 명령을 고른다 — 테스트를 돌리고, 패키지를 깔고, 파일을 지우기도 한다. 사람이 매번 승인하는 구조가 아니다. 그러니 「무엇을 할 수 있나」를 프롬프트로 제한하려 하지 말고 보이는 범위 자체를 줄이는 쪽이 맞다. 격리는 지시가 아니라 경계로 만드는 것이다.
Docker로 격리해서 띄우기 — 그리고 문서와 README가 다르다
공식 설치 페이지가 주는 명령은 이렇다.
docker run -it --rm \
-p 127.0.0.1:8000:8000 \
-e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
-v openhands-data:/home/openhands/.openhands \
-v ~/projects:/projects \
ghcr.io/openhands/agent-canvas:latest그다음 http://localhost:8000/canvas를 연다. 에이전트는 /projects로 마운트한 것만 볼 수 있다.
그런데 저장소 README는 두 군데가 다르다.
| 항목 | 설치 문서 | GitHub README |
|---|---|---|
| 볼륨 이름 | openhands-data | openhands-state |
| 이미지 태그 | :latest | :1.41.0 (고정) |
둘 중 어느 쪽이 맞다는 안내가 없다. 운영에 쓸 거면 README 쪽처럼 태그를 고정하는 편이 안전하다 — :latest는 다음 주에 다른 것이 된다. 볼륨 이름은 상태가 저장되는 자리이므로 한 번 정하면 바꾸지 않는다(바꾸면 설정이 새로 시작된다).
-p 127.0.0.1:8000:8000에서 앞의 127.0.0.1을 빼면 LAN 전체에 열린다. 사내 네트워크에서 돌릴 때 특히 주의할 자리다.
전제 조건은 문서 기준으로 Node.js 24 이상, uv, 그리고 Docker 데몬이 돌고 있어야 한다(node --version · uv --version · docker ps로 확인). macOS·Windows에서는 Docker Desktop이 열려 있어야 한다. 리눅스에서는 컨테이너 사용자가 UID 10001이라 ~/.openhands를 그대로 바인드하면 unable to open database file이 난다 — 위 명령처럼 이름 있는 볼륨을 쓰는 이유다.
헤드리스로 띄우려면 agent-canvas --backend-only를 쓴다. 문서는 이걸 「로컬 머신·VM·서버의 헤드리스 백엔드」용으로 안내한다. CI에 붙이거나 사내 서버에 한 대 올려 여러 사람이 쓰게 하려면 이 모드인데, 그때는 위의 127.0.0.1 바인딩과 세션 키 설정을 다시 봐야 한다 — 기본값은 로컬 전용 전제다.
업데이트는 npm install -g @openhands/agent-canvas@latest 뒤 agent-canvas --version으로 확인한다. Docker 경로라면 태그를 올리고 컨테이너를 다시 띄우면 되지만, 볼륨은 그대로 두어야 설정과 대화 기록이 남는다.
모델 연결 — 환경변수가 아니라 화면이다
옛 자료는 LLM_MODEL·LLM_API_KEY·LLM_BASE_URL을 환경변수로 넣으라고 한다. 현행 문서에는 그 이름이 없다. Agent Canvas는 Settings > LLM에서 고른다.
- Basic 탭 — 제공사를 직접 고른다. 필드는
LLM Provider·LLM Model·API Key. - Advanced 탭 — 로컬 모델, LiteLLM 프록시, 커스텀
Base URL.
모델은 LiteLLM 형식 문자열로 적는다. 문서가 보여 주는 예를 그대로 옮기면:
openai/gpt-5.5 # 직접 호출
openai/<served-model-id> # 로컬 OpenAI 호환 서버
litellm_proxy/<model-name> # LiteLLM 프록시 경유
openrouter/z-ai/glm-5.1 # OpenRouter 경유
openrouter/moonshotai/kimi-k2.6로컬 모델을 Docker에서 붙일 때 흔히 막히는 자리 — 컨테이너 안의 127.0.0.1은 컨테이너 자신이다. 호스트에서 돌리는 추론 서버를 가리키려면 http://host.docker.internal:<포트>/v1을 써야 한다.
여러 제공사를 한 키로 바꿔 쓰려면 게이트웨이를 앞에 두는 쪽이 편하다 — 폴백과 비용 통제까지 묶는 방법은 OpenRouter 사용법에 정리해 뒀다.
문서가 권하는 모델 목록에는 Claude Opus와 GPT-5.5, Gemini, 그리고 오픈 모델(GLM·Kimi·MiniMax)이 올라 있다. 다만 Claude와 Gemini는 모델 문자열이 「아직 미기재」로 비어 있다 — 그 둘을 쓰려면 화면에서 직접 고르는 편이 확실하다.
그리고 문서가 비용에 대해 경고를 따로 둔다 — 「OpenHands는 설정한 LLM에 많은 프롬프트를 보낸다. 대부분 유료이므로 지출 한도를 걸고 사용량을 감시하라.」 에이전트는 한 작업에 수십 번 호출한다. 실패 시 재시도도 기본 4회(LLM_NUM_RETRIES)다.
Claude Code와 무엇이 다른가
| OpenHands (Agent Canvas) | Claude Code | |
|---|---|---|
| 모델 | 내가 고른다 (OpenAI·OpenRouter·로컬·LiteLLM) | Anthropic 모델 |
| 실행 위치 | npm은 호스트 직접 · Docker는 컨테이너 | 로컬 셸 |
| 격리 | Docker 경로에서만 | 권한 모드로 제어 |
| 라이선스 | 오픈소스 (자체 호스팅 가능) | 상용 구독 |
| 비용 구조 | 토큰 종량 (내 키) | 구독 |
| 띄우는 법 | agent-canvas → 브라우저 | 터미널에서 바로 |
고르는 기준은 취향이 아니라 제약이다. 모델을 우리가 정해야 하거나(폐쇄망·특정 벤더 금지·오픈 모델 요구) 자체 호스팅이 필요하면 OpenHands 쪽이고, 그 제약이 없으면 설치가 없는 쪽이 빠르다. Claude Code를 한국어로 고정해 쓰는 설정은 클로드 코드 한국어 설정에, 두 도구를 오가며 옮길 때의 절차는 Claude Code → Codex 마이그레이션에 적어 뒀다.
도구에 사내 데이터·시스템을 붙이는 일은 또 다른 층이다 — 그쪽은 MCP 서버 만들기에 있다.
사내 저장소에 붙이기 전에 정할 것 네 가지
트리숲이 코딩 에이전트를 팀에 붙일 때 먼저 묻는 순서다. 도구를 깔고 나서 정하면 되돌리는 비용이 크다.
- 어느 디렉터리를 보여 줄지. Docker 경로의
-v <경로>:/projects가 그 경계다. 저장소 루트를 통째로 주지 말고 작업 대상만 마운트한다. - 쓰기 권한을 어디까지 줄지. 에이전트는 커밋도 푸시도 할 수 있다. 브랜치 보호와 PR 필수를 먼저 걸어 둔다.
- 비밀값을 어떻게 가릴지.
.env가 마운트 안에 있으면 그대로 읽힌다. 에이전트용 작업 사본을 따로 두는 쪽이 안전하다. - 비용 한도를 누가 보는지. 종량이라 한 번 잘못 돌면 하루치가 날아간다. 제공사 쪽 지출 한도를 반드시 건다.
이 네 가지를 코드로 고정하고 팀이 같은 기준으로 쓰게 만드는 일까지 묶어 진행하는 쪽이 에이전틱 AI 구축이고, 사내 업무에 바로 붙여 쓰는 형태로 만들어 둔 것이 ax.trina.app이다.
Q: 검색해서 나온 docker run … openhands:1.8 명령을 쓰면 안 되나요?
돌아가기는 하지만 공식 문서가 그 경로를 「deprecated legacy local GUI」로 표시했고, 함께 쓰던 openhands serve는 「더 이상 활발히 유지되지 않는다」고 적혀 있습니다. 새로 시작한다면 Agent Canvas(npm install -g @openhands/agent-canvas 또는 ghcr.io/openhands/agent-canvas 이미지)로 가는 편이 맞습니다. 포트도 3000에서 8000으로 바뀌었습니다.
Q: npm으로 설치하면 정말 제 파일 전체가 보이나요?
공식 설치 페이지가 그렇게 적습니다 — npm·npx·소스 빌드는 에이전트 서버를 머신에서 직접 돌리고 「파일시스템에 완전히 접근」합니다. 그리고 Agent Canvas는 클라이언트일 뿐이어서 격리를 제공하지 않는다고 명시합니다. 사내 코드나 고객 자료가 있는 머신에서는 Docker 경로를 쓰는 편이 맞습니다.
Q: 이미지 태그를 latest로 둬도 되나요?
개인 실습이면 괜찮습니다. 다만 설치 문서는 :latest를, 저장소 README는 :1.41.0 고정을 보여 주고 어느 쪽이 맞다는 안내가 없습니다. 운영에 쓸 거면 태그를 고정하는 쪽을 권합니다 — 이 생태계는 이번 주에도 제품 이름과 포트가 바뀌었습니다.
Q: Claude나 Gemini를 붙이려면 모델 문자열을 어떻게 적나요?
문서의 권장 모델 표에 Claude와 Gemini가 올라 있는데 모델 문자열은 「아직 미기재」로 비어 있습니다. 그래서 문자열을 추측해 넣지 말고 Settings > LLM의 Basic 탭에서 제공사를 직접 고르는 편이 확실합니다. 문서에 문자열이 명시된 것은 openai/gpt-5.5, litellm_proxy/<model-name>, openrouter/… 계열입니다.
Q: 비용이 얼마나 드나요?
종량이라 한 작업에 몇 번 호출되는지에 달립니다. 문서가 「OpenHands는 많은 프롬프트를 보낸다, 지출 한도를 걸고 사용량을 감시하라」고 따로 경고하고, 실패 시 재시도가 기본 4회입니다. 그래서 먼저 제공사 쪽 지출 한도를 걸고 작은 작업으로 한 번 돌려 호출 수를 보는 순서를 권합니다.
참고한 1차 출처 (2026-11-17 확인)
- OpenHands 문서 (구
docs.all-hands.dev→ 308) · Agent Canvas 설치 · 모델 설정 · 레거시 로컬 설치(폐기 표시) - GitHub 저장소