OpenHands 아키텍처 해부: SDK·CLI·GUI·클라우드를 하나로 묶은 오픈소스 코딩 에이전트

SDK부터 클라우드까지 한 플랫폼에 욱여넣은 이유

OpenHands(구 OpenDevin)는 AI 코딩 에이전트를 SDK부터 CLI, GUI, 클라우드까지 단일 플랫폼으로 통합한 오픈소스 프로젝트다. 60,000개 이상의 GitHub 스타와 시리즈 A 1,880만 달러 투자를 받았고, Apple·Google·Amazon·Netflix의 엔지니어들이 실무에서 쓰는 생태계로 자리 잡았다. Claude Code와 Codex CLI 같은 독점 에이전트에 맞서는 오픈소스 대안으로서 그 아키텍처 설계를 뜯어본다.

네 가지 설계 원칙

OpenHands Software Agent SDK는 2026년 MLSys에서 발표된 논문(arXiv:2511.03690)이 제시한 네 원칙 위에 서 있다.

선택적 격리(Optional Isolation): 로컬을 우선하고, 필요할 때만 샌드박스를 온디맨드로 띄운다
무상태 컴포넌트(Stateless Components): 불변 설정과 이벤트 소싱으로 상태를 관리한다
관심사 엄격 분리: 코어(core)와 애플리케이션(application) 레이어를 나눈다
이중 레이어 구성성(Two-layer Composability): SDK·Tools·Workspace·Server 네 개 패키지를 모듈식으로 배포한다

⤢✕

SDK는 몇 줄로 시작해서 타입화된 컴포넌트로 확장된다

OpenHands SDK는 Python과 REST API 이중 인터페이스를 제공한다. 최소 구현은 단 몇 줄이면 되고, 복잡한 기능은 타입화된 교체 가능 컴포넌트(typed, swappable components)로 확장한다.

from openhands import Agent, Workspace

agent = Agent(
    model="claude-sonnet-4-5",
    workspace=Workspace.local("./my-project")
)
result = agent.run("Fix all failing tests and submit a PR")

CLI는 Claude, GPT, 또는 임의의 LLM으로 구동할 수 있는 가장 빠른 진입점이다. 실행 엔진은 에이전트 루프(observe → think → act)를 이벤트 소싱 방식으로 구현해, 중단 후 재시작해도 이전 상태를 정확히 복원한다.

로컬 GUI는 단일 페이지 React 애플리케이션으로 구성되며, Agent Server의 REST API와 WebSocket을 통해 실시간 에이전트 상태를 보여준다. 클라우드에 배포하면 같은 GUI가 Kubernetes 클러스터 위에서 멀티테넌트로 동작한다.

격리 수준은 세 단계 중에서 고른다.

모드	환경	네트워크	파일시스템
로컬	호스트 OS	전체 접근	전체 접근
Docker 샌드박스	컨테이너	제한적	마운트 볼륨만
Kubernetes 에이전트	에페머럴 파드	정책 기반	PVC 마운트

도구를 등록하고, PR마다 에이전트를 돌리고, 대형 코드베이스를 맡기는 법

Tool Registry는 에이전트가 쓸 도구를 동적으로 등록·해제하는 중앙 레지스트리다. 아래 인터페이스만 구현하면 즉시 등록된다.

from openhands.tools import BaseTool, tool_registry

class MyCustomTool(BaseTool):
    name = "my_tool"
    description = "팀 내부 API 호출 도구"

    def run(self, params: dict) -> str:
        # 구현
        ...

tool_registry.register(MyCustomTool())

GitHub Actions 워크플로우로 직접 호출할 수 있는 공식 Action도 제공한다. PR이 열릴 때마다 에이전트가 자동으로 코드 리뷰·테스트·수정을 수행하는 파이프라인을 구성할 수 있다.

- uses: OpenHands/openhands-action@v1
  with:
    task: "Review this PR for security issues and performance regressions"
    model: "claude-opus-4-5"
    sandbox: "docker"

라이선스는 엔터프라이즈 디렉토리를 제외하면 MIT다. 코어 에이전트 루프, LLM 라우터, 도구 레지스트리는 안정적인 공개 API를 유지하고, 플러그인과 확장은 별도 패키지로 독립 배포할 수 있어 커뮤니티 기여 구조가 명확하게 나뉜다.

Large Codebase SDK는 시스템 전반의 의존성을 맵핑하고 변경 순서를 자동 조율해, 여러 에이전트가 충돌 없이 병렬로 작업하게 한다. 레거시 코드베이스 마이그레이션 자동화에서 특히 강점을 보인다.

Claude Code·Codex CLI와 무엇이 다른가

항목	OpenHands	Claude Code	Codex CLI
오픈소스	MIT	독점	독점
모델 지원	100+ 제공자	Claude 전용	OpenAI 전용
GUI	로컬 React SPA	없음 (CLI)	없음 (CLI)
클라우드	자체 호스팅 + SaaS	없음	OpenAI 관리형
샌드박스	Docker/K8s	로컬	microVM
엔터프라이즈	VPC 자체 호스팅	없음	없음
GitHub Stars	60,000+	비공개	비공개

OpenHands의 오픈소스 전략은 모델 종속성 제거와 데이터 주권 보장이라는 두 축을 중심으로 한다. 100개 이상의 LLM 제공자를 라우팅할 수 있어 특정 벤더 락인 없이 최적 모델을 고를 수 있다. 반면 Claude Code와 Codex CLI는 각각 Anthropic과 OpenAI 모델에 최적화돼 있어 모델을 바꾸는 비용이 크다.

엄격한 컴플라이언스가 필요한 조직을 위해 OpenHands Enterprise는 Kubernetes로 자체 VPC에 셀프호스팅할 수 있는 소스-어베일러블(source-available) 버전을 제공한다. V1 출시 후 시스템 기인 장애율은 V0 대비 크게 줄었고, 이벤트 소싱으로 인한 오버헤드는 무시할 수 있는 수준으로 보고됐다.

OpenHands는 SDK·CLI·GUI·클라우드라는 네 인터페이스를 한 플랫폼에 묶고, MIT 라이선스로 모델 종속 없이 확장 가능한 코딩 에이전트 생태계를 만들었다. 선택적 격리, 무상태 컴포넌트, 이중 레이어 구성성이라는 설계 원칙은 로컬 개발자부터 대기업 엔지니어링 팀까지 폭넓게 적용된다. Claude Code와 Codex CLI가 독점 생태계를 고수하는 상황에서, OpenHands는 오픈소스 코딩 에이전트의 사실상 표준으로 자리매김하고 있다.