블로그로 돌아가기
Tech Insight2026년 11월 17일135

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 로컬 GUIAgent Canvas
설치docker run … docker.openhands.dev/openhands/openhands:1.8npm install -g @openhands/agent-canvas
포트30008000 (/canvas)
CLIopenhands serve → 「더 이상 유지되지 않음」agent-canvas
문서docs.all-hands.devdocs.openhands.dev (308)
저장소All-Hands-AI/OpenHandsOpenHands/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-dataopenhands-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 서버 만들기에 있다.

사내 저장소에 붙이기 전에 정할 것 네 가지

트리숲이 코딩 에이전트를 팀에 붙일 때 먼저 묻는 순서다. 도구를 깔고 나서 정하면 되돌리는 비용이 크다.

  1. 어느 디렉터리를 보여 줄지. Docker 경로의 -v <경로>:/projects가 그 경계다. 저장소 루트를 통째로 주지 말고 작업 대상만 마운트한다.
  2. 쓰기 권한을 어디까지 줄지. 에이전트는 커밋도 푸시도 할 수 있다. 브랜치 보호와 PR 필수를 먼저 걸어 둔다.
  3. 비밀값을 어떻게 가릴지. .env가 마운트 안에 있으면 그대로 읽힌다. 에이전트용 작업 사본을 따로 두는 쪽이 안전하다.
  4. 비용 한도를 누가 보는지. 종량이라 한 번 잘못 돌면 하루치가 날아간다. 제공사 쪽 지출 한도를 반드시 건다.

이 네 가지를 코드로 고정하고 팀이 같은 기준으로 쓰게 만드는 일까지 묶어 진행하는 쪽이 에이전틱 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 확인)

관련 서비스: Agentic AI, 단순 챗봇을 넘어선 자율 에이전트