본문으로 건너뛰기

OpenHands: 오픈 소스 AI 코딩 에이전트 완전 해설

오픈 소스 AI 코딩 에이전트 OpenHands의 개요를 다룹니다. 아키텍처, Ollama로 로컬 설정, 실전 버그 수정, 보안과 한계, 그리고 Claude Code·Cursor·GitHub Copilot과의 비교를 포함합니다.
· 15분 읽기

AI와 탐험해 보세요

OpenHands는 저장소를 검사하고, 파일을 편집하고, 명령을 실행하며, 테스트를 구동할 수 있는 에이전트를 중심으로 한 AI 기반 소프트웨어 개발용 오픈 소스 플랫폼입니다. 이는 에이전트 중심(agentic) 개발로의 전환의 일환으로, 사용자가 전체 작업을 에이전트에 맡기면 완료되거나 사용자 입력이 필요할 때까지 에이전트가 단계별로 처리합니다.

이 글에서는 OpenHands의 아키텍처와 주요 기능을 살펴보고, 로컬 모델과 함께 설정하는 방법을 보여드리며, Claude Code, Cursor, GitHub Copilot과 비교해 보겠습니다.

AI 에이전트가 무엇인가요? 우리의 AI 에이전트 기초 트랙에 등록하여 AI 에이전트가 업무 방식을 어떻게 바꿀 수 있는지 알아보세요.

OpenHands란?

OpenHands는 코드와 함께 작업하는 AI 에이전트를 구축하고 실행하기 위한 오픈 소스 플랫폼입니다.

이 이름은 두 가지를 포괄합니다. 첫째는 SDK, 서버, 브라우저 UI, 호스팅 서비스로 구성된 리포지토리 모음(프로젝트)이고, 둘째는 그 위에서 동작하는 코딩 에이전트입니다.

작동 방식은 다음과 같습니다.

  • 소프트웨어 에이전트 SDK: 코드와 상호작용하는 에이전트를 구축하기 위한 Python 및 REST API 세트로, OpenHands CLI와 OpenHands Cloud의 엔진 역할을 합니다
  • 에이전트 서버: 에이전트 실행, 대화, 도구, 워크스페이스를 REST 및 WebSocket API로 노출합니다
  • Agent Canvas: 대화, 파일, 터미널 출력, 모델 구성, 백엔드, 자동화를 위한 단일 브라우저 UI
  • OpenHands Cloud: 자체 백엔드와 샌드박스 인프라를 운영하고 싶지 않은 팀을 위한 관리형 상용 서비스

사람들이 "OpenHands"라고 할 때 보통 에이전트를 의미합니다. 이 글에서도 그 에이전트를 다룹니다.

일반적으로 에이전트에 소프트웨어 작업을 전달하고, 코드가 있는 워크스페이스를 지정하면, 에이전트는 보유한 도구를 사용해 작업을 진행합니다. 기본 도구 세트는 터미널, 파일 편집기, 작업 추적기입니다.

워크스페이스는 꼭 사용자의 노트북일 필요가 없습니다. 에이전트는 로컬 머신을 워크스페이스로 사용할 수도 있고, Docker나 Kubernetes 같은 임시 워크스페이스에서 실행될 수도 있습니다.

OpenHands는 특정 모델 제공업체에 종속되지도 않습니다. Claude, GPT 또는 다른 어떤 LLM이든, 로컬 모델까지 포함해 사용할 수 있습니다. Agent Canvas는 기본 OpenHands 에이전트 대신 Claude Code나 Codex 같은 서드파티 에이전트도 실행합니다.

요약하면, OpenHands는 사용자가 원하는 방식으로 운영할 수 있는 개방형 에이전트 플랫폼입니다.

OpenHands의 동작 방식

OpenHands는 루프 형태로 동작합니다.

채팅 도우미는 프롬프트를 받아 텍스트를 반환합니다. OpenHands 에이전트는 작업을 받아 행동을 취하고, 결과를 확인한 뒤 다음에 무엇을 할지 결정합니다.

The OpenHands agent loop

OpenHands 에이전트 루프

전반적인 흐름은 다음과 같습니다.

  • 작업 수신: 예를 들어 "연도가 다른 월이 합쳐지지 않도록 월별 리포트를 수정하세요"처럼 목표를 자연어로 설명합니다
  • 리포지토리 검사: 디렉터리를 나열하고 파일을 열어 작업과 관련된 코드를 검색합니다
  • 계획 수립: 작업을 단계로 나누고 작업 추적기에 기록합니다
  • 파일 편집 또는 생성: 파일 편집기를 통해 코드를 변경합니다
  • 명령 및 테스트 실행: 터미널에서 테스트 스위트나 앱을 실행합니다
  • 결과 검사: 오류와 실패한 단언을 포함한 출력을 읽습니다
  • 반복: 여전히 문제가 있으면 돌아가 계획을 조정하고 다시 시도합니다

루프는 작업이 끝나거나, 누락된 자격 증명이나 요구 사항에 대한 결정처럼 사용자만 제공할 수 있는 것이 필요할 때 멈춥니다.

6단계가 OpenHands를 경쟁 제품과 구분합니다. 코드 자동 완성 도구는 자신이 생성한 코드가 실행될 때 무슨 일이 일어나는지 볼 수 없습니다. OpenHands는 실행 결과를 보기 때문에 실패한 테스트에 반응하고 원인을 수정할 수 있습니다.

OpenHands의 핵심 기능

자동 완성은 텍스트를 제안하지만, OpenHands는 프로젝트에 실제로 행동합니다. 다음과 같습니다.

코드 편집

OpenHands는 파일을 직접 편집하며, 한 번에 하나의 파일로 제한되지 않습니다.

예를 들어 어떤 함수의 이름을 바꿔야 한다고 해봅시다. 에이전트는 정의를 업데이트하고, 모든 호출 지점을 찾아 수정하며, 이를 참조하는 테스트까지 업데이트합니다. 모두 하나의 작업으로 처리합니다.

터미널 및 도구 사용

에이전트는 자체 터미널을 갖고 있습니다. 의존성 설치, 스크립트 실행, 테스트 수행, 임의 명령의 출력 읽기가 가능합니다.

또한 MCP(Model Context Protocol) 서버를 연결해, 이슈 트래커나 데이터베이스 클라이언트처럼 원래 설계에 없던 도구도 사용할 수 있습니다.

리포지토리 이해

대부분의 코드 생성기는 사용자가 프롬프트에 붙여넣은 내용만 볼 수 있습니다.

OpenHands는 리포지토리를 열어 탐색합니다. README를 읽고, import를 따라가며, 기존 테스트를 살펴 프로젝트 구조를 파악합니다. 덕분에 적용되는 변경 사항이 기존 코드와 더 잘 맞을 가능성이 큽니다.

긴 작업은 다른 문제를 만듭니다. 대화 기록이 모델의 컨텍스트 용량을 넘는 것입니다. OpenHands는 컨텍스트 콘덴서로 이를 처리해, 오래된 대화 내용을 요약하고 에이전트가 계속 작업할 수 있도록 합니다.

모델 선택

모델 호출은 LiteLLM을 통해 이뤄지므로, 해당 도구가 지원하는 어떤 제공업체와 모델이든 사용할 수 있습니다. OpenHands 문서는 Claude, GPT, Gemini 계열 모델과 OpenHands Index에서 성능이 좋은 오픈 웨이트 모델을 권장합니다.

코드를 로컬 환경 밖으로 내보낼 수 없다면 로컬 모델을 실행하면 됩니다. OpenHands는 LM Studio, Ollama, vLLM, SGLang 같은 로컬 서버에 연결합니다.

여기서 기억할 점은 모델에 따라 결과가 크게 달라진다는 것입니다. 일부 로컬 모델은 큰 컨텍스트 윈도우가 있어도 도구 사용의 안정성에 어려움을 겪습니다.

자율적 작업 실행

작업을 넘기면 에이전트는 루프를 스스로 진행합니다. 오류를 채팅에 다시 붙여 넣거나 다음에 열 파일을 알려줄 필요가 없습니다.

Agent Canvas는 자동화로 이를 한 단계 더 확장합니다. Slack, GitHub, Linear 등과 연동하며, 스케줄 또는 웹훅 이벤트에 반응해 실행됩니다.

하지만 자율성이 정확성을 보장하지는 않습니다. 병합 전에 항상 diff와 테스트 결과를 검토해야 합니다.

OpenHands 사용 방법

OpenHands를 이해하는 가장 좋은 방법은 버그를 맡겨 보고 어떻게 처리하는지 지켜보는 것입니다.

이 섹션에서는 Docker로 로컬에서 OpenHands를 실행하고, Ollama를 통해 로컬 모델을 연결한 뒤, 작은 Python 프로젝트의 버그를 고치도록 요청하겠습니다.

OpenHands 설정

OpenHands는 몇 가지 방법으로 실행할 수 있습니다:

  • CLI 런처: uv tool install openhands --python 3.14로 설치한 후 openhands serve로 GUI를 시작합니다

  • Docker: 단일 docker run 명령으로 앱 컨테이너를 직접 실행합니다

  • Agent Canvas: 로컬, 자체 호스팅, Cloud 또는 Enterprise 백엔드에 연결하는 최신 브라우저 클라이언트

  • OpenHands Cloud: 직접 아무 것도 운영하고 싶지 않을 때 사용하는 호스팅 버전

여기서는 Docker 경로와 로컬 GUI를 사용하겠습니다. OpenHands 문서에서는 이를 더 이상 권장하지 않는 Docker 기반 브라우저 애플리케이션으로 표기하고, 대체로 Agent Canvas를 지목하지만, 여전히 문서화되어 있고 GUI를 가장 빨리 띄우는 방법입니다.

macOS, Linux, 또는 WSL이 설치된 Windows에서 Docker Desktop이 필요합니다. macOS에서는 Docker Desktop을 열고 Settings > Advanced로 가서 기본 Docker 소켓을 활성화하세요.

그런 다음 앱을 시작합니다:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

OpenHands는 Docker 소켓 마운트를 사용해 별도의 샌드박스 컨테이너를 시작하며, 에이전트는 호스트가 아니라 그 샌드박스 안에서 명령을 실행합니다.

로그에서 서버가 올라왔다는 표시가 보이면 브라우저에서 http://localhost:3000을 엽니다.

OpenHands welcome page

OpenHands 환영 페이지

모델 연결

모델을 지정하기 전까지 OpenHands는 아무것도 하지 않습니다.

여기서는 Mistral의 에이전트형 코딩용 24B 모델인 Devstral Small 2를 사용합니다. 단일 RTX 4090이나 RAM 32GB 이상의 Mac에서 구동할 수 있습니다. Ollama 0.13.3 이상이 필요합니다.

더 큰 컨텍스트 윈도우로 Ollama를 시작하고 모델을 받아옵니다:

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 ollama serve &
ollama pull devstral-small-2:24b

컨텍스트 길이를 무시하지 마세요. Ollama 기본값은 4096 토큰으로, OpenHands 시스템 프롬프트조차 담기엔 너무 작습니다. 문서에서는 최소 22000을 요구합니다.

OpenHands에서 Settings를 열고 LLM 탭으로 이동한 뒤 Advanced를 켜세요. 그런 다음 다음과 같이 설정합니다:

  1. Custom Model: openai/devstral-small-2:latest

  2. Base URL: http://host.docker.internal:11434/v1

  3. API Key: local-llm 같은 아무 자리표시자 값

LLM settings for a local Ollama model

로컬 Ollama 모델을 위한 LLM 설정

openai/ 접두사는 OpenHands가 OpenAI 호환 API를 통해 Ollama와 통신하도록 지정합니다. API 키는 사용되진 않지만 필드를 비워둘 수는 없습니다.

리포지토리 열기

기본적으로 OpenHands는 사용자의 파일을 볼 수 없습니다. 프로젝트를 샌드박스에 마운트해야 합니다.

이 예제에서는 두 개의 파일이 들어 있는 budget-tracker/project 폴더가 필요합니다. 첫 번째 파일은 월별 지출 합계를 계산합니다:

# budget.py
def monthly_totals(transactions):
    """Sum spending per month, keyed as 'YYYY-MM'.

    Each transaction is a (date, amount) tuple, for example ("2025-01-15", 42.0).
    """
    totals = {}
    for date, amount in transactions:
        month = date[5:7]
        totals[month] = totals.get(month, 0) + amount
    return totals

docstring은 키가 YYYY-MM 형식이라고 약속하지만, date[5:7]은 월만 남깁니다. 2025년 1월과 2026년 1월이 같은 버킷에 들어갑니다.

두 번째 파일에는 버그를 잡는 두 개의 테스트가 있습니다:

# test_budget.py
from budget import monthly_totals


def test_same_month_in_different_years():
    transactions = [
        ("2025-01-10", 50.0),
        ("2025-01-20", 100.0),
        ("2026-01-12", 60.0),
    ]
    assert monthly_totals(transactions) == {"2025-01": 150.0, "2026-01": 60.0}


def test_single_month():
    transactions = [("2026-03-01", 20.0), ("2026-03-15", 5.5)]
    assert monthly_totals(transactions) == {"2026-03": 25.5}

폴더를 Git 리포지토리로 만들면 나중에 에이전트가 바꾼 내용을 확인할 수 있습니다:

cd budget-tracker
git init
git add .
git commit -m "Initial commit"

지금 python -m pytest를 실행하면 두 테스트 모두 실패합니다:

Failing tests

실패한 테스트

OpenHands에 접근 권한을 주기 위해 컨테이너를 중지하고 docker run 명령에 한 줄을 추가합니다:

-e SANDBOX_VOLUMES=$HOME/budget-tracker:/workspace:rw \

이제 전체 명령은 다음과 같습니다:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -e SANDBOX_VOLUMES=$HOME/Desktop/budget-tracker:/workspace:rw \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

형식은 host_path:container_path:mode입니다. 프로젝트는 샌드박스의 /workspace 아래에 표시되며, rw 모드는 에이전트의 편집을 허용합니다.

에이전트가 변경해야 하는 프로젝트만 마운트하세요. /workspace에 읽기-쓰기 모드로 마운트된 것은 무엇이든 에이전트가 수정할 수 있습니다.

에이전트에 작업 전달

새 대화를 시작하고 버그 리포트 쓰듯이 문제를 설명하세요:

월별 합계가 서로 다른 연도의 같은 달 지출을 합쳐 버립니다.

원인을 찾아 수정하고, 테스트를 실행해 통과하는지 확인하세요.

이것으로 충분합니다. budget.py를 가리키거나 어떤 줄이 잘못됐는지 알려줄 필요가 없습니다.

Conversation output

대화 출력

앞서 본 에이전트 루프가 여기서부터 작동합니다. 에이전트는 /workspace를 살펴보고 두 파일을 읽은 뒤 어떤 것이 실패하는지 보기 위해 테스트를 실행합니다. 그런 다음 코드를 편집하고 테스트를 다시 실행합니다.

The agent running pytest in the sandbox terminal

샌드박스 터미널에서 pytest를 실행하는 에이전트

변경 사항 검토

에이전트가 완료되었다고 합니다. 이제 코드 편집기를 열어 코드 변경 사항을 확인해 차이를 볼 수 있습니다.

올바른 수정은 budget.py의 한 줄입니다:

month = date[:7]

Fixed budget.py

수정된 budget.py

또한 git diff로 차이를 확인할 수 있습니다.

다음 항목을 확인하세요:

  • 소스 코드: 수정은 budget.py에 있어야 합니다

  • 테스트: 단언을 통과시키기 위해 에이전트가 test_budget.py를 수정하지 않았는지 확인하세요

  • 테스트 실행: python -m pytest를 직접 실행하세요. 에이전트의 요약만 믿지 마세요

OpenHands 아키텍처

OpenHands는 여섯 개의 주요 구성요소로 이루어져 있으며, 각자 맡은 역할이 분명합니다.

How the OpenHands components connect

OpenHands 구성요소의 연결 방식

AI 모델

모델은 추론을 담당합니다. 작업과 대화 내역을 입력으로 받아, 메시지 또는 도구 호출로 응답합니다.

모델은 파일을 변경하거나 무엇인가를 실행하지 않습니다. 다음에 할 일을 결정만 합니다. 모델 호출은 LiteLLM을 거치므로, 동일한 에이전트가 호스팅된 제공업체나 이 글의 Devstral 설정처럼 로컬 모델과도 함께 작동합니다.

에이전트 로직

에이전트는 모델과 그 외 모든 것 사이에 있습니다. 추론-행동 루프를 실행하며, 모델에 다음 행동을 요청하고 도구를 실행한 뒤 결과 또는 오류를 처리합니다.

또한 모델이 무엇을 볼 수 있는지도 결정합니다. 에이전트는 콘덴서를 사용해 대화 내역을 관리하고, 각 모델 질의에 스킬과 프롬프트를 추가합니다.

모든 단계는 기록됩니다. 에이전트는 행동을 실행하고 관측값을 받으며, 대화는 그 이벤트 내역을 보존합니다. 모델은 다음 턴에서 이러한 이벤트를 보게 되어, 이미 무슨 일이 일어났는지 알 수 있습니다.

도구와 액션

도구는 에이전트가 모델 외부에 영향을 미치는 수단입니다. 표준 세트에는 터미널, 파일 편집기, 작업 추적기가 포함되며 MCP 서버를 통해 더 추가할 수 있습니다.

모델은 "pytest 실행" 또는 "budget.py의 8번째 줄을 교체" 같은 행동을 요청합니다. 도구는 이를 실행하고, 테스트 출력이나 업데이트된 파일처럼 관측값을 반환합니다.

행동은 실행 전 보안 검사를 거칩니다. 보안 분석기는 각 행동을 먼저 평가하며, 사용자의 승인을 위해 에이전트를 일시 정지시킬 수 있습니다.

개발 환경

도구는 로컬 머신에서 실행되지 않습니다. 샌드박스 안에서 실행됩니다.

Docker 설정에서 OpenHands는 에이전트 서버를 자체 Docker 컨테이너 안에서 실행합니다. 이 글에서 Docker 소켓을 마운트한 이유가 바로 이것입니다. 앱 컨테이너가 샌드박스를 시작하려면 소켓이 필요합니다.

샌드박스는 로컬일 필요가 없습니다. 에이전트는 Docker나 Kubernetes의 임시 워크스페이스에서도 실행될 수 있으며, 에이전트 서버는 실행, 도구, 워크스페이스를 REST 및 WebSocket API로 노출합니다. 샌드박스가 어디서 실행되든 에이전트 로직은 동일합니다.

리포지토리

리포지토리는 에이전트가 작업하는 대상입니다. 샌드박스로 들어오는 경로는 두 가지입니다. 이 글처럼 로컬 폴더를 마운트하거나, GitHub, GitLab, Bitbucket 통합을 통해 연결합니다.

리포지토리는 에이전트의 동작 방식을 지시할 수도 있습니다. 루트 수준의 AGENTS.md 파일은 대화 시작 시 시스템 프롬프트에 주입됩니다. 더 구체적인 지침은 .agents/skills/에 두며, 에이전트는 먼저 요약을 보고 필요할 때 전체 내용을 불러옵니다.

에이전트가 추측하기 어려운 프로젝트 규칙을 여기에 적어 두세요. 예: "pytest가 아닌 make test로 테스트를 실행한다."

사람에 의한 검토

마지막 구성요소는 사용자입니다.

OpenHands는 세 가지 확인 정책을 지원합니다. 모든 행동 승인, 승인 없음, 위험한 행동만 승인입니다. 마지막 옵션은 보안 분석기에 의존하며, 각 행동을 LOW, MEDIUM, HIGH, UNKNOWN 위험으로 표시합니다. 기본값은 NeverConfirm이므로, 변경하지 않는 한 에이전트는 멈추지 않고 실행됩니다.

두 번째 점검은 마지막에 있습니다. diff를 읽고 테스트 결과를 확인하기 전까지 에이전트의 작업은 끝난 것이 아닙니다.

OpenHands 워크플로

한 줄짜리 버그 수정 방법을 보여드렸지만, 물론 OpenHands는 훨씬 더 큰 작업도 처리할 수 있습니다.

이들 작업의 공통점은 한 번에 끝나지 않는다는 것입니다. 에이전트 루프가 유용한 작업 유형 여섯 가지는 다음과 같습니다.

버그 수정

이 글의 버그는 단일 파일에서 쉽게 보였습니다. 현실에서는 거의 그렇지 않습니다.

예를 들어 운영 환경 로그에 KeyError가 보이고, 스택 트레이스가 나쁜 데이터가 들어오는 지점에서 세 번 떨어진 함수로 향한다고 합시다. 스택 트레이스를 OpenHands에 붙여 넣고 수정을 요청합니다.

에이전트는 호출 체인을 데이터의 근원까지 추적하고, 오류를 재현하는 테스트를 작성해 실패를 확인합니다. 이후 코드를 수정하고 전체 테스트 스위트를 실행해 다른 것이 망가지지 않았는지 확인합니다.

재현 테스트가 핵심입니다. 이는 에이전트가 오류가 드러난 위치가 아니라 실제 버그를 찾았음을 증명합니다.

기능 구현

기능 작업은 보통 예상보다 더 많은 파일을 수정합니다.

예를 들어 커맨드라인 리포트 스크립트에 날짜로 트랜잭션을 필터링하는 --since 플래그가 필요하다고 합시다. 에이전트는 인자 파서를 찾아 플래그를 추가하고, 값을 필터 로직으로 전달하며, 도움말 텍스트를 업데이트해야 합니다. 그런 다음 새 동작에 대한 테스트를 작성하고 README를 업데이트합니다.

작은 기능 하나에도 네다섯 개의 파일을 건드립니다. 에이전트는 작업 추적기에 이를 기록하여 첫 파일만 동작한다고 멈추지 않습니다.

리팩터링

리팩터링은 동작은 바꾸지 않고 구조만 바꾸는 일이며, 테스트 스위트는 동작이 바뀌지 않았음을 증명하는 수단입니다.

예를 들어 프로젝트에 날짜, 문자열, 파일 헬퍼가 뒤섞인 거대한 utils.py가 있다고 합시다. 이를 세 개의 모듈로 나누라고 OpenHands에 요청합니다.

에이전트는 새 모듈을 만들고, 함수를 옮기며, 코드베이스 전반의 import를 업데이트합니다. 이동할 때마다 테스트를 실행합니다. 이렇게 하면 무언가 깨지면 어떤 이동이 원인인지 알 수 있습니다.

테스트 작성

테스트 없는 코드는 에이전트 작업의 흔한 출발점입니다. 작업이 명확하고 검증이 쉽기 때문입니다.

예를 들어 날짜 파싱 모듈에 테스트가 하나도 없다면, 에이전트는 함수를 읽고 정상 입력과 빈 문자열, 윤년, 잘못된 형식 같은 경계 사례에 대한 pytest 케이스를 작성한 뒤 실행합니다.

새 테스트가 실패하면, 테스트가 틀렸는지 코드에 버그가 있는지 에이전트가 판단해야 합니다. 이 결정은 직접 확인해야 합니다.

기존 코드베이스 조사

모든 작업이 코드 변경을 필요로 하지는 않습니다.

OpenHands에 "이 앱은 데이터베이스에 도달하기 전에 사용자 입력을 어디에서 검증하나요?" 같은 질문을 할 수 있습니다. 에이전트는 코드베이스를 검색하고, 파일을 가로지르는 함수 호출을 따라가며, 파일 경로와 줄 번호를 인용해 답변합니다.

새 프로젝트에 합류했거나 몇 달 만에 코드를 다시 본 경우 유용합니다. 읽기 전용 작업에는 :rw 대신 :ro 모드로 리포지토리를 마운트해 에이전트가 실수로라도 아무것도 바꾸지 못하게 하세요.

애플리케이션 실행 및 디버깅

일부 버그는 애플리케이션을 실제로 실행해야만 드러납니다.

예를 들어 API 엔드포인트가 500 오류를 반환하고, 테스트는 이를 다루지 않는다면 에이전트는 터미널에서 서버를 시작하고, curl로 요청을 보내며, 서버 로그의 트레이스백을 읽습니다.

그다음 코드를 고치고 서버를 재시작한 뒤 같은 요청을 다시 보냅니다. 응답이 여전히 잘못되면 그 지점부터 루프가 계속됩니다.

이는 사용자가 직접 하는 편집-실행-확인 사이클과 동일하지만, 에이전트가 모든 재시작과 재시도를 처리합니다.

OpenHands와 다른 AI 코딩 에이전트 비교

OpenHands만이 작업을 맡겨 자율적으로 처리할 수 있는 도구는 아닙니다. Claude Code, Cursor, GitHub Copilot도 에이전트 기능을 갖추고 있지만, 몇 가지 중요한 차이가 있습니다.

OpenHands vs Claude Code

두 도구는 가장 비슷합니다. 모두 코드 읽기, 파일 편집, 명령 실행, 결과 확인을 포함한 에이전트 루프를 실행합니다.

첫 번째 차이는 소유권입니다. 공개된 각 OpenHands 리포지토리는 자체 오픈 소스 라이선스를 가지며, 코드를 읽고, 수정하고, 자체 호스팅할 수 있습니다. Claude Code는 Anthropic의 독점 에이전트형 코딩 도구로, 터미널, IDE, 데스크톱 앱, 브라우저에서 사용할 수 있습니다.

이는 모델 선택으로 이어집니다. Claude Code는 Anthropic의 Claude 모델을 중심으로 구축되었습니다. OpenHands는 이 글의 로컬 Ollama 설정을 포함해 LiteLLM이 지원하는 어떤 제공업체와도 작동합니다.

일상적인 워크플로도 다릅니다. Claude Code는 터미널 도구로 시작했으며, 지금도 많은 개발자가 그 방식으로 사용합니다. OpenHands는 브라우저 UI에 의존하고, CLI는 기능이 완비되어 있지만 주로 안정성을 위해 유지됩니다.

두 도구 모두 에이전트의 동작을 제어할 수 있습니다. Claude Code는 CLAUDE.md, 설정, 훅, 스킬, 명령, 서브에이전트를 .claude 디렉터리에서 읽습니다. OpenHands는 리포지토리의 AGENTS.md와 스킬을 읽으며, SDK를 통해 Python으로 자체 에이전트를 구축할 수 있습니다.

자율성의 구현도 다릅니다. Claude Code는 권한 모드, 훅, 허용/거부 규칙으로 도구 사용을 제어하고, 명령을 샌드박스할 수 있습니다. OpenHands는 기본적으로 모든 명령을 Docker 샌드박스에서 실행하고, 그 위에 확인 정책을 추가합니다.

요약하면, Claude Code는 바로 설치해서 사용할 수 있는 다듬어진 옵션이고, OpenHands는 더 많은 설정을 요구하지만 그만큼 더 많은 제어권을 제공합니다. 또한 두 도구는 상호 배타적이지 않습니다. Agent Canvas는 기본 OpenHands 에이전트 대신 Claude Code를 에이전트로 실행할 수 있습니다.

OpenHands vs Cursor

Cursor는 AI 코드 에디터입니다. OpenHands는 에이전트 플랫폼입니다. 이것이 가장 큰 차이이며, 대부분의 차이는 여기서 파생됩니다.

Cursor에서는 에디터 안에서 작업하고 에이전트가 옆에서 함께 작업합니다. 파일에 수정이 나타나면 이를 수락하거나 거부하고 계속 코딩합니다. OpenHands에서는 작업을 설명하고, 에이전트가 샌드박스에서 작업하며, 사용자가 결과를 검토합니다. GUI에 샌드박스를 들여다보는 VS Code 뷰가 포함되어 있지만, 주된 작업 공간은 아닙니다.

리포지토리 접근도 이 차이를 따릅니다. Cursor의 에이전트는 에디터에서 연 코드에서 작업합니다. OpenHands는 샌드박스에 마운트했거나 Git 통합으로 연결한 대상에서 작업합니다.

Cursor의 Cloud Agents와 비교하면 격차가 줄어듭니다. 이들은 클라우드에서 무인으로 실행되어 브랜치와 풀 리퀘스트로 결과를 반환하며, GitHub, GitLab, Azure DevOps, Bitbucket 계정 연결과 유료 플랜이 필요합니다. 이는 OpenHands가 하는 일과 비슷하지만 Cursor 인프라에서 동작합니다.

확장성은 두 도구가 가장 크게 다른 부분입니다. Cursor는 MCP 서버와 프로젝트 규칙을 지원하지만, 에디터와 에이전트는 폐쇄형 제품입니다. OpenHands에서는 에이전트 자체를 변경하고, 어디서나 호스팅하며, 로컬 모델로 실행할 수 있습니다.

OpenHands vs GitHub Copilot

GitHub Copilot은 에디터의 자동 완성 도구로 시작해 에이전트 기능으로 확장되었습니다. OpenHands는 태생부터 에이전트였습니다.

Copilot의 가장 큰 강점은 위치입니다. VS Code와 JetBrains IDE 내부에서 작동하고, 클라우드 에이전트는 GitHub와 직접 연동됩니다. OpenHands는 그런 수준의 IDE 통합이 없습니다.

리포지토리 수준 작업에서는 Copilot 클라우드 에이전트가 가장 가까운 비교 대상입니다. 이슈를 할당하면, GitHub Actions 기반의 자체 임시 개발 환경에서 작업하며, 푸시 전 테스트와 린터를 실행할 수 있습니다. OpenHands Cloud는 이슈나 풀 리퀘스트 댓글에 @openhands를 멘션하면 유사하게 동작합니다.

가장 큰 차이는 플랫폼입니다. Copilot 클라우드 에이전트는 GitHub에 저장된 리포지토리에서 모든 유료 Copilot 플랜에 제공됩니다. OpenHands는 GitHub, GitLab, Bitbucket 또는 로컬 폴더와 함께 작동하며, 원한다면 자체 하드웨어에서 실행됩니다.

Copilot도 작업별 모델 선택을 허용하지만, GitHub가 제공하는 모델로 한정됩니다. OpenHands는 이런 제한이 없습니다.

간단히 요약하면:

 OpenHandsClaude CodeCursorGitHub Copilot
소스오픈 소스독점독점독점
모델로컬 포함 모든 LiteLLM 제공업체Claude 모델복수 제공업체 + 사내 모델GitHub 제공 모델
주요 인터페이스브라우저 UI, SDK터미널, IDE, 데스크톱, 브라우저AI 코드 에디터IDE 확장, GitHub
에이전트 실행 위치로컬 또는 원격 Docker 샌드박스로컬 머신 또는 Anthropic 클라우드에디터 또는 Cursor 클라우드IDE 또는 GitHub Actions
자체 호스팅가능불가엔터프라이즈 한정불가

다른 AI 에이전트와 비교한 OpenHands

소프트웨어 엔지니어링 팀을 위한 OpenHands

개별 개발자에게 OpenHands는 필요할 때 여는 도구이지만, 팀에서는 다르게 작동합니다.

대부분의 팀은 이미 이슈 중심으로 작업을 조직하며, OpenHands Cloud는 여기에 연결됩니다. GitHub, GitLab, Bitbucket은 물론 Slack, Jira, Linear와 통합됩니다. 이슈나 풀 리퀘스트 댓글에 @openhands를 멘션하면 에이전트가 그 작업을 가져갑니다.

또한 누구도 직접 요청하지 않지만 모두에게 필요한 작업이 있습니다. Agent Canvas 자동화는 스케줄에 따라 또는 웹훅 이벤트에 반응하여 실행됩니다. 예를 들어, 팀은 코드 리뷰와 의존성 업데이트를 위해 하나의 에이전트 서버를 공유하고, 각 개발자는 자신의 노트북에서 개인 에이전트를 실행할 수 있습니다.

테스트는 이 글과 동일하게 작동합니다. 에이전트는 보고하기 전에 샌드박스에서 테스트 스위트를 실행합니다. 하지만 샌드박스 실행은 CI의 대체물이 아닙니다. 사람 작성 코드와 마찬가지로 모든 풀 리퀘스트에서 파이프라인은 계속 실행됩니다.

풀 리퀘스트도 중요한 주제입니다. OpenHands Cloud가 GitHub와 함께 작동할 때는 8시간 후 만료되는 단기 토큰을 요청하며, 콘텐츠, 이슈, 풀 리퀘스트, 워크플로 읽기/쓰기 권한을 포함합니다. 자체 호스팅 엔터프라이즈 설정에서는 에이전트가 트리거한 사용자의 GitHub 권한을 사용하므로, 모든 변경 사항은 사람에게 추적됩니다.

책임은 이렇게 작동해야 합니다. 에이전트가 풀 리퀘스트를 열 수는 있지만, 승인은 개발자가 합니다. 브랜치 보호와 필수 리뷰는 에이전트의 풀 리퀘스트에도 동일하게 적용됩니다.

격리된 환경은 이러한 작업이 규모 있게 작동하도록 합니다. 각 작업이 자체 샌드박스에서 실행되므로, 서로 다른 두 버그를 고치는 두 에이전트가 같은 파일을 덮어쓰거나 동일한 포트를 두고 충돌하지 않습니다.

OpenHands 보안과 샌드박싱

코드 자동 완성 도구는 항상 텍스트를 제안하며, 이를 수락할지는 사용자에게 달려 있습니다.

에이전트는 다릅니다. 프로젝트를 살펴보고, 명령을 실행하며, 패키지를 설치하고, 종종 묻지도 않고 파일을 수정합니다. 따라서 질문은 "이 코드가 올바른가?"에서 "에이전트가 거기에 이르기까지 무엇을 실행했는가?"로 바뀝니다.

격리된 실행 환경

Docker 샌드박스는 호스트의 파일과 프로그램, 리소스, 다른 컨테이너와 프로세스를 보호합니다. 에이전트가 파괴적인 명령을 실행해도 컨테이너로 제한됩니다.

로컬 설정에서 주의할 예외가 하나 있습니다. 앱 컨테이너는 샌드박스를 시작하기 위해 호스트의 Docker 소켓을 마운트하며, 해당 소켓에 접근하면 머신의 Docker를 제어할 수 있습니다.

리포지토리 권한

샌드박스는 마운트하지 않은 것만 보호합니다. 마운트된 파일과 디렉터리는 수정되거나 삭제될 수 있습니다.

작업 중인 프로젝트만 마운트하고, 홈 디렉터리는 절대 마운트하지 마세요. 코드 조사 같은 읽기 전용 작업에는 :ro 모드를 사용하세요. Git 통합에서는 에이전트에 반드시 필요한 특정 리포지토리만 접근 권한을 부여하세요.

시크릿과 자격 증명

API 키나 토큰 같은 자격 증명을 제공하면 에이전트가 이를 사용할 수 있습니다. 그리고 시크릿을 읽을 수 있는 에이전트는 로그에 출력하거나 외부로 전송할 수도 있습니다.

따라서 운영 키가 담긴 .env 파일이 있는 폴더를 마운트하지 마세요. 범위가 제한된 테스트 자격 증명을 제공하고, 자주 교체하세요.

네트워크 액세스

기본적으로 에이전트는 컨테이너 내부에서 인터넷에 접근할 수 있습니다. 패키지 설치에 필요하지만, 모든 외부 서비스에도 도달할 수 있습니다.

이는 프롬프트 인젝션의 문을 엽니다. 웹 페이지나 이슈 댓글에 에이전트가 따를 수 있는 지침이 포함될 수 있습니다. GitHub는 자체 클라우드 에이전트에 대해 기본적으로 인터넷 액세스를 제한하는 방화벽으로 이 위험을 낮추며, OpenHands 설정에서도 유사한 제한을 고려할 가치가 있습니다.

명령 실행

승인 없이 실행할 명령을 제어할 수 있습니다. OpenHands는 모든 행동 승인, 승인 없음, 위험한 행동만 승인하는 세 가지 확인 정책을 지원합니다. 기본값은 NeverConfirm입니다.

"위험한 행동" 옵션에는 주의점이 있습니다. 기본 LLM 보안 분석기는 모델이 자신의 행동에 부여한 위험 수준을 사용합니다. 모델이 파괴적인 명령을 LOW로 표시하면 묻지 않고 실행됩니다. 분석기는 정책 계층을 위해 위험을 분류할 뿐 자체적으로 아무 것도 차단하지 않으며, 문서는 이를 Docker 격리와 함께 사용할 것을 권장합니다.

생성된 변경 사항 검토

위의 모든 것은 에이전트가 할 수 있는 일을 제한합니다. 하지만 검토 단계는 에이전트가 실제로 무엇을 했는지 확인하는 과정이므로 중요합니다.

기대했던 파일만이 아니라 전체 diff를 읽으세요. CI 구성, 의존성 파일, 스크립트에 특히 주의를 기울이세요. OpenHands Cloud에서 에이전트의 GitHub 토큰은 워크플로 쓰기 권한을 포함하므로, .github/workflows 변경은 파이프라인에서 무엇이 실행되는지를 바꿀 수 있습니다.

OpenHands의 한계

OpenHands가 작성한 코드에도 여전히 버그가 있을 수 있습니다. 테스트 통과는 코드가 테스트와 일치함을 뜻할 뿐이며, 에이전트가 테스트와 코드를 모두 작성할 수도 있습니다. 테스트가 약하면 코드는 통과하더라도 여전히 잘못일 수 있습니다.

복잡한 작업에는 종종 사용자의 개입이 필요합니다. 모호한 요구 사항이나 에이전트가 결정할 수 없는 설계 결정은 에이전트를 멈추게 하거나, 더 나쁘게는 잘못된 방향으로 보낼 수 있습니다.

강력한 호스팅 모델과 함께라면 OpenHands는 다중 파일 작업을 잘 처리합니다. 작은 로컬 모델과 함께라면 도구 호출 실패나 챗봇 같은 답변을 보게 될 수 있으며, 큰 컨텍스트 윈도우가 있어도 일부 로컬 모델은 도구 사용을 안정적으로 수행하지 못합니다.

에이전트 루프는 채팅보다 비용이 더 듭니다. 각 단계가 대화 내역을 모델에 다시 보내며, 긴 작업은 많은 단계를 필요로 합니다. OpenHands 문서는 에이전트가 LLM에 많은 프롬프트를 발행한다고 경고하며, 지출 한도와 사용 모니터링을 권장합니다. 컨텍스트 콘덴서는 도움이 되지만, 오래된 단계를 요약하므로 긴 작업에서는 세부사항이 손실될 수 있습니다.

도구 접근은 보안 위험을 더합니다. 터미널과 네트워크 접근 권한이 있는 에이전트는 잘못된 지침을 따르면 실제 피해를 줄 수 있으므로, 샌드박스와 사용자의 검토가 매우 중요합니다.

그리고 모든 변경에는 여전히 사람의 승인이 필요합니다. 이를 항상 염두에 두세요.

OpenHands와 AI 코딩 에이전트의 미래

AI 코딩 도구는 자동 완성에서 채팅을 거쳐 전체 작업을 수행하는 에이전트로 발전해 왔습니다. OpenHands는 그 마지막 단계를 앞당기는 몇 안 되는 프로젝트 중 하나입니다.

업계 전반의 방향성은 분명합니다. Cursor는 자율적인 클라우드 에이전트가 더 큰 작업을 더 긴 기간에 걸쳐 맡는 시대의 도래를 설명합니다. Copilot은 이제 GitHub와 Linear의 이슈를 처리합니다. Claude Code는 터미널, 브라우저, Slack에서 실행됩니다.

오픈 소스 플랫폼은 이러한 전환에서 특별한 역할을 합니다. OpenHands를 사용하면 에이전트가 어떻게 동작하는지 확인하고, 자체 인프라에서 실행하며, 모델을 선택할 수 있습니다. 엄격한 데이터 규칙을 가진 팀에는 이것이 종종 에이전트를 사용할 수 있는 유일한 방법입니다.

더 긴 작업은 새로운 문제도 가져옵니다. 한 시간 동안 작업하는 에이전트는 1분 동안 작업하는 에이전트보다 더 많은 결정을 내리며, 각 결정은 원래 의도에서 벗어날 가능성을 높입니다. 더 나은 모델이 도움이 되지만, 샌드박스, 확인 정책, 검토도 마찬가지로 중요합니다.

결론

OpenHands를 경쟁 제품과 구분하는 점은 통제력입니다. 소스를 읽고, 자체 하드웨어에 호스팅하며, 로컬을 포함한 어떤 모델로도 실행할 수 있습니다. Claude Code, Cursor, GitHub Copilot 같은 상용 도구는 더 다듬어진 사용 경험을 주지만, 제공업체의 조건 안에서입니다.

하지만 터미널과 리포지토리에 접근하는 에이전트의 작업은 여전히 사람이 확인해야 합니다. 항상 diff를 읽고 테스트를 직접 실행하세요.

에이전트를 처음부터 만드는 방법을 배우고 싶다면, 우리의 Introduction to Creating AI Agents in Python 웨비나를 시청하세요.

FAQs

OpenHands란 무엇인가요?

OpenHands는 코드와 함께 작업하는 AI 에이전트를 구축하고 실행하기 위한 오픈 소스 플랫폼입니다. 코딩 에이전트는 리포지토리를 검사하고, 파일을 편집하고, 명령과 테스트를 실행하며, 작업이 완료될 때까지 결과를 반복 개선합니다. 로컬 Docker, SDK, 또는 OpenHands Cloud에서 실행할 수 있습니다.

OpenHands는 무료로 사용할 수 있나요?

OpenHands 소프트웨어는 오픈 소스이므로 라이선스 비용 없이 자체 호스팅할 수 있습니다. 비용이 드는 부분은 모델입니다. Anthropic이나 OpenAI 같은 호스팅 제공업체는 토큰 사용량 기준으로 과금하며, 에이전트 루프는 토큰을 많이 사용합니다. Ollama나 LM Studio로 로컬 모델을 실행하면 비용은 하드웨어뿐입니다. OpenHands Cloud는 별도의 상용 서비스입니다.

OpenHands는 GitHub Copilot이나 Cursor와 어떻게 다른가요?

Copilot과 Cursor는 에디터 중심으로, 코드를 작성하는 동안 AI가 곁에서 함께 작업합니다. OpenHands는 에이전트 우선 접근입니다. 사용자가 작업을 설명하면, 에이전트가 샌드박스에서 처리하고, 사용자가 결과를 검토합니다. 또한 오픈 소스이고, LiteLLM이 지원하는 어떤 모델과도 작동하며, 자체 인프라에서 실행할 수 있는데, 이는 Copilot과 Cursor가 같은 수준으로 제공하지 않는 부분입니다.

로컬 모델로 OpenHands를 실행할 수 있나요?

예. OpenHands는 OpenAI 호환 API를 통해 LM Studio, Ollama, vLLM, SGLang 같은 로컬 서버에 연결합니다. Devstral Small 2나 Qwen3.6-35B-A3B처럼 에이전트형 코딩에 맞춰진 모델을 선택하고, 컨텍스트 윈도우를 최소 22000 토큰으로 설정하세요. 더 작은 범용 모델은 도구 호출에 자주 실패하고 챗봇처럼 답변하는 경우가 많습니다.

내 코드에 OpenHands 접근 권한을 주어도 안전한가요?

OpenHands는 에이전트의 명령을 Docker 샌드박스 안에서 실행해, 대부분의 실수로부터 호스트 시스템을 보호합니다. 하지만 샌드박스에 마운트한 것은 무엇이든 수정되거나 삭제될 수 있으며, 제공한 자격 증명은 에이전트가 사용할 수 있습니다. 기본적으로 에이전트는 행동 전에 승인을 요청하지 않으므로, 필요한 프로젝트만 마운트하고, 범위가 제한된 테스트 자격 증명을 사용하며, 병합 전마다 모든 diff를 검토하세요.

주제