OpenHands: AI 코딩 에이전트의 SDK부터 CLI, GUI, 클라우드까지 통합한 오픈소스 플랫폼

9bow · 5월 16, 2026, 9:30오전

OpenHands 소개

OpenHands는 개발자가 자연어로 지시한 소프트웨어 작업을 자동으로 수행하는 AI 코딩 에이전트(AI-driven development) 플랫폼입니다. GitHub 이슈 해결, 코드 작성, 테스트 실행, 버그 수정 같은 작업을 사람이 일일이 단계마다 개입하지 않아도 에이전트가 도구를 호출해가며 처리하도록 설계되어 있습니다. 기존의 코드 자동 완성형 도구가 개발자의 옆에서 한 줄을 거드는 방식이라면, OpenHands는 개발자가 던진 목표를 받아 저장소를 직접 클론하고 파일을 열어 수정하며 실행 환경에서 결과를 검증하는 흐름까지 한 번에 책임지는 에이전트 방식에 가깝습니다. 이 방식이 실제로 동작 가능하다는 점은 OpenHands가 SWE-Bench 같은 코딩 에이전트 벤치마크에서 77.6점이라는 결과를 기록한 데에서도 확인할 수 있습니다. OpenHands 프로젝트의 기술 보고서(Tech Report)는 arXiv:2511.03690 에 공개되어 있으며, 모델·하네스(Harness)·런타임을 어떻게 조합했는지에 대한 설계 결정을 자세히 소개하고 있습니다.

OpenHands의 차별점은 단일 도구가 아니라 동일한 에이전트 코어 위에 여러 사용 형태를 쌓아 올린 통합 스택이라는 점입니다. 가장 아래에는 모든 기능의 엔진 역할을 하는 OpenHands Software Agent SDK가 있고, 그 위에 터미널에서 즉시 사용할 수 있는 OpenHands CLI, 로컬 노트북에서 GUI로 에이전트를 운용하는 OpenHands Local GUI, 그리고 호스팅 인프라에서 실행되는 OpenHands Cloud가 차례로 자리합니다. 대규모 사용자가 필요하다면 Kubernetes 기반으로 자체 VPC에 배포하는 OpenHands Enterprise 옵션까지 동일한 코어를 공유합니다. 덕분에 개인 개발자는 CLI나 Local GUI로 가볍게 실험을 시작하고, 팀이나 회사 단위에서는 Slack·Jira·Linear 통합과 권한 관리, 협업 기능이 포함된 클라우드/엔터프라이즈 형태로 자연스럽게 확장할 수 있습니다.

OpenHands는 Python으로 작성되었으며, Claude·GPT 같은 상용 모델뿐 아니라 로컬 또는 오픈소스 LLM도 백엔드로 연결할 수 있도록 모델 추상화 계층을 제공합니다. 에이전트는 코드 편집, 셸 실행, 브라우저 조작, 외부 도구 호출 등 여러 도구(Tool)를 통해 환경과 상호작용하며, 작업 결과는 로컬 GUI나 클라우드 콘솔의 채팅 패널에서 단계별로 확인할 수 있습니다. TikTok, VMware, Roche, Amazon, Netflix, NVIDIA, Google과 같은 기업의 엔지니어들이 도입했다고 소개될 만큼 다양한 환경에서의 운용 사례가 누적되어 있다는 점도 OpenHands를 평가할 때 함께 고려해 볼 만한 요소입니다.

OpenHands의 통합 스택 구조

OpenHands의 가장 큰 특징은 동일한 코어 위에서 여러 사용 형태가 일관되게 동작한다는 점입니다. 핵심은 OpenHands Software Agent SDK 로, Python 라이브러리 형태로 제공되어 에이전트의 행동 정의, 도구(Tool) 등록, 실행 정책 같은 모든 동작을 코드로 표현할 수 있습니다. 이 SDK가 제공하는 표준화된 인터페이스를 통해 로컬 환경에서 한두 개의 에이전트를 돌리는 시나리오부터, 클라우드에서 수천 개의 에이전트를 병렬로 운용하는 시나리오까지 동일한 추상화로 처리할 수 있습니다.

SDK 위에서 동작하는 사용자 인터페이스는 크게 다음 네 가지로 나뉩니다.

OpenHands CLI: 터미널에서 즉시 사용할 수 있는 진입점입니다. Claude Code나 OpenAI Codex 계열의 CLI 도구를 사용해 본 적이 있다면 익숙한 형태이며, Claude·GPT·기타 LLM을 백엔드로 자유롭게 선택할 수 있습니다.

OpenHands Local GUI: 노트북에서 에이전트를 실행하기 위한 단일 페이지 React 애플리케이션과 REST API 묶음입니다. Devin이나 Jules처럼 채팅·코드 편집·실행 결과 패널이 한 화면에 통합되어 있어, 에이전트가 무엇을 변경했는지 시각적으로 추적하기 쉽습니다.

OpenHands Cloud: 호스팅 인프라 위에서 동작하는 GUI 배포본입니다. Slack·Jira·Linear 통합, 다중 사용자 지원, RBAC 기반 권한 관리, 대화 공유 같은 협업 기능이 함께 제공되며, GitHub 또는 GitLab 계정으로 로그인하면 Minimax 모델을 사용해 무료로 체험해 볼 수 있습니다.

OpenHands Enterprise: 대규모 조직이 자체 VPC에서 Kubernetes로 OpenHands Cloud를 호스팅할 수 있는 옵션입니다. CLI·SDK와도 함께 사용 가능하며, 동일 저장소의 enterprise/ 디렉토리에 소스가 공개되어 있어 내부 검증이 가능합니다(상업 운용 시 별도 라이선스가 필요합니다).

OpenHands의 동작 방식과 도구 사용

OpenHands 에이전트는 사용자 메시지를 받아 작업 목표를 해석한 뒤, 셸 명령 실행, 파일 편집, 브라우저 탐색, 외부 API 호출 같은 도구를 순차적으로 호출하며 목표를 달성하려 시도합니다. 각 단계에서 모델은 다음에 호출할 도구와 그 인자를 결정하고, 실행 결과를 다시 컨텍스트에 받아 다음 의사결정을 내립니다. 이 과정은 GUI의 채팅 패널 또는 CLI 출력으로 그대로 노출되므로, 개발자는 에이전트가 어디서 잘못된 가정을 했는지 추적하고 필요할 때 개입할 수 있습니다.

저장소를 GitHub 또는 GitLab에서 직접 연결하면, 에이전트가 해당 저장소를 격리된 런타임에 클론한 뒤 코드 수정·테스트 실행·PR 생성까지 처리할 수 있습니다. 작업 결과는 변경된 파일 단위로 확인 가능하며, 별도의 브라우저 탭에서는 에이전트가 사용한 웹페이지 탐색 결과도 추적할 수 있습니다.

OpenHands 설치 및 사용법

가장 빠르게 사용해 보려면 OpenHands CLI를 설치하는 방법이 있습니다. Python 환경이 준비되어 있다면 다음과 같이 실행할 수 있습니다.

# OpenHands CLI 설치 (저장소 README 참조)
pip install openhands-ai

# CLI 실행 (대화형 모드)
openhands

# 모델을 명시적으로 지정하여 실행
openhands --model anthropic/claude-sonnet-4.5

SDK를 사용해 코드로 에이전트를 정의하는 경우에는 다음과 같은 형태로 시작할 수 있습니다. 자세한 API는 공식 SDK 문서에서 확인할 수 있습니다.

from openhands.sdk import Agent, Tool, run

# 사용할 도구를 등록한 에이전트 정의
agent = Agent(
    model="anthropic/claude-sonnet-4.5",
    tools=[Tool.shell(), Tool.file_editor(), Tool.browser()],
)

# 자연어 목표를 전달하면 에이전트가 도구를 호출하며 처리합니다
result = run(agent, task="이 저장소의 README를 한국어로 번역해 줘")
print(result.final_message)

Local GUI는 저장소를 클론한 뒤 README의 안내에 따라 Docker 또는 로컬 Python 환경에서 기동할 수 있으며, 클라우드를 체험하고 싶다면 app.all-hands.dev 에서 GitHub/GitLab 계정으로 로그인해 바로 시작할 수 있습니다.

OpenHands 라이선스

OpenHands의 코어 코드와 핵심 Docker 이미지(openhands, agent-server)는 MIT 라이선스로 공개되어 있어, 개인 및 상업적 목적으로 자유롭게 사용·수정·배포할 수 있습니다. 다만 저장소의 enterprise/ 디렉토리 코드는 별도의 엔터프라이즈 라이선스를 따르며, 1개월을 초과해 운영하려면 별도 라이선스 구매가 필요합니다.

OpenHands 공식 홈페이지

OpenHands 문서 사이트

OpenHands 기술 보고서 논문

OpenHands 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~