프레임워크

OpenHands 소스 분석: AI가 엔지니어처럼 직접 코드를 고친다

84,555스타를 받은 오픈소스 Agent 프레임워크가 터미널·브라우저·에디터를 LLM에 맡긴다. 아키텍처, 배포, 실제 동작 세 갈래로 풀어본다.

글자 크기

OpenHands 소스 분석: AI가 엔지니어처럼 직접 코드를 고친다

지난 1년, AI 코딩에서 가장 유용한 방향은 단순한 자동완성이 아니라 직접 일을 해내는 것이었다.

이슈 하나를 던져주면, 저장소를 읽고, 문제를 찾고, 파일을 고치고, 테스트를 돌리고, PR을 올린다. 이 흐름이 돌아야 진짜 "소프트웨어 엔지니어링 Agent"에 가까워진다.

Devin은 클로즈드 소스다. AutoGPT는 실험 프로젝트에 가깝다. OpenHands는 높은 관심도, 완전한 엔지니어링화, 실제 PR 제출까지 동시에 갖춘 드문 오픈소스다.

GitHub 메인 저장소는 현재 84,555 stars다. 프로젝트 원래 이름은 OpenDevin, 이후 OpenHands로改名됐다. 저장소는 순수 Python 프로젝트가 아니라 TypeScript + Python 이중 언어 구조다. Web 프런트엔드와 인터랙션 레이어는 주로 TypeScript, Agent·Runtime·Controller 등 백엔드 코어는 Python이다.

출처: OpenHands GitHub 메인 저장소

해결하려는 문제

일반적인 코드 자동완성은 "이 코드를 어떻게 쓰느냐"만 답한다. Agent는 완전한 작업을 처리해야 한다.

  • 이슈와 저장소 컨텍스트 읽기
  • 수정 계획 수립
  • 코드 검색
  • 파일 편집
  • shell 명령 실행
  • 테스트와 lint 실행
  • diff 검토
  • commit 또는 PR 생성

어려운 건 한 번의 코드 생성이 아니다.

어려운 건 매 단계에서 오류가 날 수 있다는 점이다. 테스트가 실패하면? 네트워크 요청이 실패하면? 엉뚱한 파일을 고치면? Agent가 결과를 관찰하고 다음 단계를 결정할 수 있느냐가 핵심이다.

OpenHands가 하는 일은 터미널, 파일 시스템, 브라우저를 Agent가 호출할 수 있는 도구로 바꾸는 것이다. 코드만 생성하는 게 아니라 실행과 검증까지 맡는다.

이 점이 Cursor Agent, Copilot과의 차이다. 후자는 주로 에디터 주변에서 동작한다. OpenHands의 목표는 더 직관적이다. 모델이 실행 가능하고, 격리되고, 관찰 가능한 개발 환경을 통째로 인수하는 것이다.

Devin과 비교하면 오픈소스다.

AutoGPT와 비교하면 훨씬 엔지니어링답다. Runtime, Controller, 이벤트 버스, SDK가 있고 Docker 배포 경로도 갖췄다.

사용 방법

가장 간단한 방법은 로컬에서 OpenHands를 띄우는 것이다.

docker run -d \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --name openhands \
  ghcr.io/openhands/openhands:latest

이후 http://localhost:3000을 연다.

OpenHands의 호스트 머신은 Web UI, API, Agent 제어를 담당한다. 실제로 명령을 실행하는 코드는 기본적으로 별도 Docker 샌드박스 안에 들어간다.

자동화 작업 작성에 더 맞는 방법도 있다. Python SDK를 사용하는 것이다. 아래 코드는 SDK 호출 형태의 핵심 예시다.

from openhands import OpenHandsAgent

agent = OpenHandsAgent(
    llm_model="claude-3-5-sonnet",
    workspace="./demo-project",
    runtime="docker"
)

task = "src/main.py의 0으로 나누기 버그를 고치고, tests/ 하위 모든 케이스를 통과시켜"
result = agent.run(task, max_steps=20)

print("상태:", result.status)
print("변경 파일:", result.modified_files)
print("테스트 출력:", result.test_output)

이 코드는 세 가지를 보여준다.

  1. workspace는 작업 대상 저장소를 가리킨다.
  2. runtime="docker"로 실행 환경을 지정한다.
  3. max_steps=20은 Agent에 동작 상한을 걸어 무한 루프를 막는다.

SDK의 가치는 "코드 대화"에 그치지 않는다. 배치 처리, CI 보조, 내부 작업 큐 어디에든 Agent를 붙일 수 있다.

모델 설정은 기본적으로 Anthropic 또는 OpenAI 클라우드 API를 사용한다. 클라우드 API를 쓰지 않을 때는 Ollama 또는 vLLM으로 바꿔 로컬에서 모델을 돌릴 수도 있다.

버전 차이에 주의해야 한다. 모델 이름과 SDK API는 프로젝트 업데이트에 따라 바뀐다. 배포 전에는 반드시 현재 버전 README, 예제, 설치 후의 인터페이스 정의를 기준으로 삼아야지, 옛 글의 모델 이름만 그대로 복사해서는 안 된다.

동작 원리 (아키텍처)

OpenHands의 핵심은 세 층으로 나눌 수 있다.

Runtime: Agent의 손과 발

Runtime은 실제 실행 환경이다.

코드는 주로 openhands/runtime/에 있다. 기본은 Docker 격리 기반이며, Agent에 세 가지 기본 능력을 제공한다.

  • shell 명령 실행
  • 파일 읽기/쓰기/편집
  • 브라우저 조작

이 세 가지 원시 동작만으로도 대부분의 개발 작업을 커버할 수 있다. 의존성 설치, 코드 수정, 서비스 기동, 페이지 에러 확인까지 조합해서 처리한다.

Runtime은 다국어 확장 방향도 지원하며 Python, Node.js, Go 등 프로젝트에서 쓸 수 있다. 실제로 쓸 수 있는 능력은 Runtime 타입과 플러그인 설정에 따라 달라진다.

이 레이어에서 가장 중요한 설계는 격리다. 모델이 보는 것은 제한된 워크스페이스다. 호스트 머신을 Agent에 그대로 노출해서는 안 된다.

Agent: 다음에 무엇을 할지 결정

Agent 컨트롤러는 작업 상태, 계획, 메모리, 도구 호출을 관리한다.

핵심 코드는 openhands/controller/agent/에 있다.

프롬프트 한 줄을 받아 곧장 답을 생성하는 게 아니라, 동작 체인을 유지한다.

  1. 현재 저장소와 작업 상태를 관찰한다.
  2. 도구를 하나 고른다.
  3. 인자를 넣어 실행한다.
  4. 명령 출력 또는 에러를 읽는다.
  5. 계획을 갱신하고 다음 단계로 넘어간다.

전형적인 Agent 루프는 ReAct와 비슷하다. Reasoning과 Acting을 번갈아 수행한다. 매 동작 전에 판단하고, 동작 후 피드백을 읽는다.

이 점이 Agent와 스크립트 생성기의 핵심 차이다. 스크립트 생성기는 텍스트만 뱉는다. Agent는 도구가 돌려준 실제 결과를 소비한다.

OpenHands는 커스텀 Action Space도 지원한다. 개발자가 새 도구를 등록해 인자, 반환값, 실행 방식을 규정하고 Agent에 넘길 수 있다.

예를 들어 "내부 API 문서 조회" 도구를 더하거나, "운영 에러 로그 조회" 동작을 추가할 수 있다. 도구 경계가 분명해져야 Agent가 실제 시스템을 건드릴 자격을 얻는다.

LLM: 추론만 담당

세 번째 층은 LLM이다.

이슈를 이해하고, diff를 분석하고, 어느 도구를 호출할지 결정한다. 다만 명령 실행, 파일 쓰기, 브라우저 제어는 모델 서버에서 직접 일어나지 않고 Runtime에서 이뤄진다.

이런 분리가 중요하다.

shell, 에디터, 브라우저를 전부 프롬프트에 욱여넣으면 권한 경계가 흐려진다. OpenHands는 이들을 통제된 도구로 만든다. 모델은 등록된 동작만 고를 수 있고, Runtime이 그 동작을 실행한다.

이벤트 버스: 과정을 관찰 가능하게

Agent의 매 단계 동작과 결과는 이벤트로 흐른다. 프런트엔드는 WebSocket으로 업데이트를 받는다.

볼 수 있는 것들:

  • Agent가 지금 어떤 파일을 읽는지
  • 어떤 명령을 실행했는지
  • 명령이 실패했는지
  • 어떤 파일을 수정했는지
  • 테스트 출력이 무엇인지
  • 현재 계획, 코딩, 검증 중 어느 단계인지

이런 관찰 가능성은 단순 데모용이 아니다. Agent가 진짜 문제를 고치고 있는지, 아니면 루프에 빠졌는지를 개발자가 판단하는 데 쓰인다.

장점과 한계

OpenHands의 장점은 분명하다.

첫째, 완전한 오픈소스다.

프로젝트는 MIT 라이선스를 채택했다. 상업적 사용, 소스 수정, 자체 배포가 가능하다. Cursor나 Copilot에 종속되고 싶지 않은 작은 팀은 내부 Agent 인프라로 채택할 수 있다.

둘째, 샌드박스 격리가 비교적 완전하다.

명령, 파일 편집, 브라우저 조작이 모두 Runtime 안에 들어간다. 모델이 호스트 머신을 함부로 만질 수 없다.

셋째, Action Space 확장이 가능하다.

내부 빌드 시스템, 코드 검색 서비스, 데이터베이스 쿼리 도구를 통제된 인터페이스로 붙일 수 있다.

넷째, 평가 데이터가 뒷받침된다.

OpenHands는 SWE-bench Verified에서 꾸준히 오픈소스 1위권을 유지해왔다. 2024년的大部分 시간 동안 오픈소스 Agent 중 선도적인 해법이었다. 구체적인 점수는 모델, 커밋 버전, 평가 설정에 따라 달라지므로 날짜가 다른 결과를 섞어 비교해서는 안 된다.

문제는 현실적이다.

로컬 배포는 자원을 꽤 먹는다. 완전한 서비스, 모델, 샌드박스를 동시에 돌리면 CPU, 메모리, 디스크 모두 가볍지 않다. 기본 환경은 최소 8GB 메모리 기준으로 준비하는 편이 안전하다.

클라우드 API가 여전히 주류 경로다. Ollama와 vLLM을 지원하긴 하지만, 작은 모델은 긴 저장소 이해, 도구 선택, 실패 복구에서 쉽게 퇴화한다.

중국산 모델适配은 아직 따라가는 중이다. OpenHands 공식 설정은 보통 Anthropic, OpenAI 같은 서비스를 우선 고려한다. 중국 네트워크 환경에서는 DeepSeek, 通义千问 같은 서비스를 쓰는 편이 보통 더 안정적이다.

복잡한 다중 파일 리팩터링은 루프에 빠지기 쉽다. 연속해서 엉뚱한 파일을 고치거나, 테스트가 외부 서비스에 의존하거나, 명령이 계속 타임아웃이 나는 식이다. max_steps는 손실만 제한할 뿐 잘못된 계획을 자동 복구하지는 못한다.

직접 돌려봤다

일부러 버그를 넣은 Python 프로젝트로 간단한 테스트를 해봤다. 목표는 단순하다. 0으로 나누기 문제를 고치고 tests/ 아래 모든 케이스를 통과시키는 것.

진행 순서는 다음과 같다.

  1. Docker로 OpenHands 기동.
  2. Claude 3.5 Sonnet 연결.
  3. 저장소를 워크스페이스에 마운트.
  4. 태스크下发: 0으로 나누기 버그 위치 파악, 코드 수정, 테스트 실행.

Agent는 먼저 src/main.py를 탐색해 나누는 수가 0인 분기를 찾아냈다.

바로 커밋하지 않았다. 수정한 뒤 pytest를 돌려 테스트 통과를 확인하고 diff까지 다시 봤다.

설정한 단계 상한은 20이었지만 실제로는 다 채우지 않았다.

중간에 requests 설치 시도도 있었다. 샌드박스에 외부 네트워크가 열려 있지 않아 설치가 실패했다. Agent는 에러를 읽고 무한 재시도를 하지 않고 Python 표준 라이브러리인 urllib로 우회했다. 결국 테스트를 통과했고 로컬 커밋까지 생성됐다.

같은 태스크를 DeepSeek-V3로도 바꿔 봤다.

결론은 세 가지다.

  • 완수 가능. 코드 예시만 뱉는 수준이 아니다.
  • 속도가 눈에 띄게 느리다. 같은 태스크에서 소요 시간이 약 40% 늘었다.
  • 단순 수정은 실패하지 않았다. 복잡한 리팩터링에서는 모델 안정성이 여전히 Claude나 GPT-4o에 미치지 못한다.

이건 엄밀한 벤치마크가 아니다. 같은 컨테이너, 같은 태스크, 같은 단계 상한에서의 체험 비교일 뿐이다. 연결 방식이可行하다는 점은 보여주지만, 모델 순위로 받아들이면 안 된다.

중국 사용자 자주 겪는 함정

Docker 이미지 풀링이 느린 게 첫 번째 함정이다.

ghcr.io 이미지 크기가 크고 네트워크가 흔들리면 쉽게 멈춘다. 고정 버전을 미리 받아 두고 Docker Hub에镜像 加速을 설정하고, OpenHands 이미지에는 명시적인 tag를 지정해두는 편이 낫다.

모호한 latest를 오래 써서는 안 된다. 업그레이드 도중 Runtime 동작, API 인자, 도구 결과가 바뀔 수 있다.

두 번째 함정은 모델 API다.

Anthropic, OpenAI 서비스는 일부 중국 네트워크 환경에서 지연이 크고 연결이 불안정하다. 실측상 DeepSeek나 通义千问으로 바꾸는 편이 더 안정적이었다.

모델 이름은 감으로 채우면 안 된다. 현재 버전의 모델 설정 페이지와 코드를 기준으로 해야 한다. 오래된 모델은 이미下线된 경우도 있고, 일부 서비스는 별도 인자 호환이 필요하다.

세 번째 함정은 권한이다.

Docker Runtime을 쓰려면 흔히 호스트 머신의 Docker socket을 컨테이너에 마운트한다. 편하지만 권한이 매우 크다.

운영 환경에서 개발 설정을 그대로 베끼면 안 된다. 컨테이너 권한을 제한하고 원격 Runtime으로 바꾸고, 내부 서비스에는短期凭证을 부여해야 한다.

네 번째 함정은 워크스페이스 영속성이다.

기본 샌드박스는 영구 워크스페이스가 아니다. 컨테이너가 다시 만들어지거나 서비스가 재시작되면 임시 파일이 사라질 수 있다.

코드를 보존해야 한다면 영속 volume을 마운트해야 한다. commit, PR, 작업 기록까지 남겨야 한다면 외부 Git 서비스나 객체 스토리지를 연결해야 한다.

누가 쓰면 좋을까

OpenHands는 세 부류에 잘 맞는다.

소규모 팀. 내부 AI 코딩 어시스턴트를 만들고 싶지만 Cursor, Copilot에 종속되고 싶지 않은 경우. 전제로 Docker, 모델, 내부 도구를 관리할 사람이 있어야 한다.

Agent 엔지니어. Runtime, Controller, 도구 프로토콜, 이벤트 스트림 소스를 봐야 하는 사람. OpenHands의 코드는 많은 데모 프로젝트보다 실제 운영 시스템에 가깝다.

평가 연구자. SWE-bench 류 태스크를 돌리거나 모델별 저장소 단위 수정 능력을 시험하고 싶은 사람. Runtime, Action Space, 이벤트 기록은 실험에 그대로 활용할 수 있다.

어울리지 않는 세 부류도 있다.

설정을 전혀 쓰고 싶지 않은 사용자. 코드 몇 줄 자동완성만 필요하다면 Cursor나 Copilot이 훨씬 간편하다.

완전 오프라인을 요구하는 사람. 로컬 추론은 GPU, 모델 호환성, 높은 메모리를 요구한다. 중국산 하드웨어에서의 도구 호출 안정성은 따로 튜닝이 필요하다.

민감 코드를 다루면서 격리 설정까지 꺼리는 사람. 샌드박스, volume, 네트워크 정책, 凭证 관리는 본인이 직접 확인해야 한다. 기본값이 안전하다는 뜻이지, 배포 환경을 무시해도 된다는 뜻은 아니다.

"AI가 저장소를 고칠 수 있느냐"만 놓고 보면 OpenHands는 이미 가능함을 입증했다.

실제 효과를 가르는 건 여전히 세 가지다. 모델이 제대로 계획할 수 있는지, Runtime이 충분히 통제 가능한지, 도구 결과가 Agent의 자가 교정을 도울 수 있는지.

아직 무감독으로 운영 업무를 돌리기엔 이르다. 하지만 수정 가능하고, 관찰 가능하고, 내부 도구를 붙일 수 있는 엔지니어링 Agent를 만들고 싶은 사람에게 OpenHands는 여전히 분해해 볼 가치가 충분한 오픈소스 프로젝트다.

출처: https://github.com/OpenHands/OpenHands