OpenHands: Cloud Mac를 도구 모음에서 Agent 플랫폼으로

지난 2주 Stack 연재에서 L1 Runner(Fact), L2 Ollama(Inference), L4 MCP(Context)를 차례로 세웠다. 독자 피드백은 한 문장이 반복된다: 「도구는 다 연결됐는데, 매일 여전히 손으로 플로우를 이어 붙인다.」 Claude Code는 diff를 내고, MCP는 GitHub Context를 끌어오고, Runner는 push 후 초록이 된다——그런데 「issue #142 고치고 PR 올려」는 여전히 터미널 앞에 40분 앉아 있어야 한다.

그것이 L5 · OpenHands가 답하는 질문이다. CLI 하나를 더 사는 이야기가 아니라, Cloud Mac을 도구 모음에서 다단계 공학 작업을 자율로 끝내는 Agent 플랫폼으로 올리는 것. 본문은 L5-Q01 · R1 · 시리즈 Hub: 독자를 「코딩 도구」에서 「Agent 플랫폼」 인식으로 옮긴다——Workflow가 Stack 어디에 있는지, OpenHands vs Claude Code가 대체 관계가 아닌 이유, 전형 작업, OpenHands self-hosted on macOS 아키텍처. Docker 설치 단계는 없음(그건 L5-Q02 SEO 랜딩).

「도구 모음」 함정: 각각은 훌륭한데, 전체 사슬은 여전히 사람 손

현장에서 자주 보는 한 주(고객 repo에서 여러 번 본 형태):

1. 월요: Claude Code로 API 층, MCP로 GitHub issue 목록——세션 안에서는 순조.
2. 화요: 동료가 다른 머신에서 push, Runner 빨강——Agent 변경과 CI 스크립트가 맞지 않음(L1 실행 엔진을 안 읽으면 반복).
3. 수요: 수동 테스트, 설정 수정, 다시 Claude Code 세션으로 파일 보완.
4. 목요: 드디어 초록, 그러나 문서, 마이그레이션 스크립트, 샘플 테스트는 여전히 빠짐——「코드 수정」과 「요구사항 납품」이 같은 일로 취급됐다.

도구 모음의 특징: 각 단계에 최적 도구는 있지만, 「요구사항 전체」에 책임지는 층이 없다. Agent 플랫폼이 더하는 것은 스스로 작업을 쪼개고, 실행하고, 실패에서 재시도하는 Workflow 층——OpenHands는 Stack에서 그 역할을 맡는 OSS 선택지(전신 OpenDevin 생태).

Stack 언어: Workflow와 Context / Diff / Fact

시리즈 전체 표기: Workflow를 Fact의 하류로 일방향 화살표로 그리지 마라. Workflow(L5)는 오케스트레이션 층으로, 작업 주기 안에 Context를 소비하고 Diff를 내고 Fact로 검증하며 「요구사항 완료」까지 반복한다:

Cloud Mac AI Stack · 산출물 관계(호출 순서 아님)

  Workflow(L5 · OpenHands)
  ├── Context(L4 · MCP)          ← repo / issue / API 읽기
  ├── Diff(L3 · Claude Code 등)  ← 코드 수정 / 파일 쓰기
  └── Fact(L1 · Runner / 테스트) ← test / build / CI 신호

Agent loop(Workflow 내부 · 여러 번 반복 가능)
       Diff  ↔  Fact
         ↑       ↓
      Observe → 재 Plan → 재 Execute …

네 산출물 기억: Context · Diff · Fact · Workflow(MCP · 코딩 층 · Runner · OpenHands). Inference(L2 · Ollama)는 선택이며 위 그림에서 빼 Agent loop와 혼동을 피한다.

Workflow는 「또 하나의 CI job」이 아니라 다단계·중단·재개 가능한 작업 상태기: 루프 안에서 Diff와 Fact를 여러 번 호출해 PR이 넘길 수 있을 때까지 돈다. Claude Code는 단일 라운드 Diff에 강하고, OpenHands는 전체 loop를 무인으로 돌리는 데 강하다——Context와 Fact가 먼저 깔려 있다는 전제.

OpenHands 1분定位(백과 아님)

OpenHands는 OSS 자율 소프트웨어 공학 Agent 플랫폼: 샌드박스(흔히 Docker)에서 자연어 목표를 받아 계획 → 코드/명령 → 출력 읽기 → 디버그를 자동화하고 GitHub(issue, PR, CI 상태)와 연결한다. Cloud Mac AI Stack에서 Claude Code 페어 경험이나 Runner의 객관 빌드 증명을 대체하지 않는다——둘 위에서 다단계 납품을 오케스트레이션한다.

OpenHands vs Claude Code: 경쟁이 아닌 이유

OpenHands vs Claude Code나 Claude Code alternative로 오는 사람의 본질: 하나로 바꿀 수 있나? Cloud Mac AI Stack에서는 아니오, 그래서도 안 된다——층이 다르고 산출물이 다르다:

• Claude Code(L3) → Diff 생산: 페어 코딩, 사람이 현장.
• OpenHands(L5) → Workflow 생산: 자율 agent, 사람은 목표만.

OpenHands를 「또 다른 Claude Code」로 보면 즉시 함정: 머릿속 흐릿한 제품 직관 정렬에는 약하고, Claude Code는 8단계 issue를 무인으로 끝내기 어렵다. 정답은 층층이 쌓기——낮에 Claude Code로 난제, 밤에 OpenHands가 issue 큐를 비운다.

경험 법칙(계약 아님): PR에서 변경 의도를 한 문장으로 말할 수 있으면 → Claude Code; 「issue 끝내」라고 말하면 → OpenHands 검토. 대형 repo에 CodeGraph 인덱스가 있으면 페어 층은 Claude Code가 흔하고, OpenHands는 템플릿화된 백엔드 작업에 맞다. 둘 다 MCP Context를 공유하지만 책임은 공유하지 않는다.

OpenHands로 뭘 할 수 있나?(검색 사용자의 첫 질문)

OpenHands agent나 OpenHands github로 오는 사람의 진짜 질문: 무엇을 맡기면 믿을 만한가? 아래는 테스트 + CI 전제에서 먼저 시도할 작업 유형——L5-Q02 튜토리얼 예시 풀이기도 하다:

첫 OpenHands 작업으로 부적합: 테스트 없는 대규모 리팩터, UX 대개편, 업무 승인 필요한 schema 마이그레이션, 프로덕션 시크릿 직접 접촉. 이는 Claude Code 페어 세션에 남기고, 사람 게이트 후 Runner가 Fact.

OpenHands 동작 원리(How OpenHands Works)

How OpenHands works, OpenHands architecture, OpenHands agent loop 검색자가 알고 싶은 것은 Docker 명령이 아니라: 자율 agent가 한 문장을 머지 가능 PR로 어떻게 바꾸나? 핵심은 네 단계——Plan → Execute → Observe → Debug:

OpenHands agent loop(개념 · 단일 파이프라인 아님)

        ┌──────────┐
        │   Plan   │  ← Context
        └────┬─────┘
             ▼
        ┌──────────┐
        │ Execute  │  → Diff
        └────┬─────┘
             ▼
        ┌──────────┐
        │ Observe  │  ← Fact(test / build / CI)
        └────┬─────┘
             │
      미통과 │ 통과
             ▼
        ┌──────────┐        ┌─────────────┐
        │  Debug   │ ──────▶│ Workflow 완료│ → PR / 납품
        └────┬─────┘        └─────────────┘
             │
             └──── Plan 또는 Execute로(다음 라운드)

「더 강한 Chat 설치」와 전혀 다르다. OpenHands architecture의 핵심은 상태 있는 작업기——각 Observe가 trajectory에 쓰이고 다음 Plan에 쓰인다. Fix bug, Lint cleanup 등은 같은 loop의 다른 입구. 다음 실제 작업 재생에서 issue 하나로 네 단계를 채운다; Docker와 UI는 L5-Q02.

L0–L4를 쌓고 L5——아니면 Agent는 샌드박스에서 혼자 놀 뿐

「첫날 OpenHands 설치」식 도구 쌓기는 반대한다. 순서는 L1 투입 순서와 같고 MCP 뒤 L5:

1. L0 — 상시 가동 Cloud Mac macOS 노드.
2. L1 — Runner: push → 초록/빨강 재현 가능.
3. L2–L3 — 선택 Ollama + Claude Code, Fact 위에서 코딩.
4. L4 — MCP Hub + 권한 모델: Agent 읽기/쓰기 감사 가능.
5. L5 — OpenHands: 다단계 Workflow.

L1 없이도 OpenHands는 기술적으로 PR까지 갈 수 있으나 merge 리스크 판단 불가——「Claude Code SSH 전부 초록, Actions 전부 빨강」과 같은 조직 사고. L4 권한 없으면 자율 Agent token 노출면 확대; MCP 보안 spec 참고.

실제 작업 재생: Plan → Execute → Observe → Debug 한 바퀴

아래는 OpenHands 샌드박스 fork에서 재생한 작업 형태(숫자는示意). agent loop와 단계별 대조:

목표: issue #218 「CSV보내기 UTF-8 BOM 누락」 수정

  ① issue + 관련 src/export/*.ts 읽기  ~2 min · Context(MCP/Git)
  ② 6단계 계획 생성                   ~1 min · Plan
  ③ 4파일 수정 + 테스트 1개 추가      ~8 min · Execute
  ④ pnpm test → 실패(스냅샷 불일치)   ~3 min · Observe · Fact
  ⑤ 로그 읽기 → 2파일 추가 수정       ~5 min · Debug → 재 Execute
  ⑥ 재테스트 → 초록                   ~3 min
  ⑦ PR 열기, issue 연결               ~1 min · Workflow 납품

합계 약 23분 wall time · 사람: 목표 승인 + 최종 merge review만

④(Observe) 주목: 테스트 실패는 재앙이 아니라 agent loop 입력. 페어 도구에서는 그 자리 수정; OpenHands는 Observe → Debug로 Fact를 다음 Execute에 되돌린다. 안정 테스트 명령이 없으면(L1 미고정) Observe 신호 없이 공회전——Runner를 먼저 두는 이유.

트리거 측 개념(설치 튜토리얼 아님, GitHub 연결만):

# 개념: issue 라벨로 자율 작업 트리거(의사 코드)
on:
  issues:
    types: [labeled]
if: github.event.label.name == 'agent:openhands'
run: |
  openhands run \
    --repo "${{ github.repository }}" \
    --issue "${{ github.event.issue.number }}" \
    --max-iterations 40 \
    --sandbox docker

Runner · OpenClaw · OpenHands: 세 이름, 세 역할

L5에서 가장 많이 묻는 삼각 관계:

OpenClaw는 아키텍처 결정을 대신하지 않는다——「언제 돌리고, 끝나면 어떻게 알릴지」. OpenHands는 Runner 대신 iOS 패키지에 서명하지 않는다——리뷰 가능한 PR과 단계 로그. 셋 다 한 Cloud Mac에 올릴 수 있으나 한 runbook에 책임을 섞지 마라.

Cloud Mac 전형 OpenHands 아키텍처(self-hosted · Docker · macOS)

OpenHands Mac, OpenHands self-hosted, OpenHands Docker 검색 엔지니어가 원하는 것은 배치 가능한 토폴로지——설치 단계가 아니라 「부품 위치」. Apple Silicon Cloud Mac에서 권하는 최소 프로덕션 형태:

OpenHands self-hosted on macOS(Cloud Mac · L0 베이스)

  GitHub(issues / webhooks / PR)
           │
           ▼
  ┌─────────────────────────────────────┐
  │  Cloud Mac · macOS · Apple Silicon   │
  │  ┌─────────────┐  ┌───────────────┐  │
  │  │ OpenHands   │  │ Claude Code   │  │  L5 Workflow + L3 Diff(동기 가능)
  │  │ (Docker)    │  │ (SSH/터미널)  │  │
  │  └──────┬──────┘  └───────────────┘  │
  │         │ sandbox workspace           │
  │         ▼                             │
  │  ┌─────────────┐  ┌───────────────┐  │
  │  │ MCP Servers │  │ Ollama(선택)  │  │  L4 Context · L2 Inference
  │  └─────────────┘  └───────────────┘  │
  │         │ git push                    │
  │         ▼                             │
  │  ┌─────────────────────────────────┐  │
  │  │ GitHub Runner(self-hosted)      │  │  L1 Fact
  │  └─────────────────────────────────┘  │
  └─────────────────────────────────────┘

Workflow 층을 노트북이 아닌 Cloud Mac에 두는 이유

• 시간 — OpenHands 작업은 30–90분이 흔함; 뚜껑 닫으면 끊김.
• OpenHands Docker — 샌드박스는 안정 daemon 필요; 24/7 Cloud Mac이 맞음.
• Runner와 동일 스택 — Agent 수정 후 같은 macOS 노드에서 검증, 「SSH 초록·Actions 빨강」 감소.
• ABI 일치 — iOS / macOS 타깃 repo는 Apple Silicon에서 Linux VPS보다 놀랄 일이 적음.

최소 OpenHands Docker 시작 형태(개념 조각; 전체 docker compose는 L5-Q02):

# Cloud Mac · OpenHands self-hosted(示意)
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.9
docker run -d --name openhands \
  -e SANDBOX_USER_ID=$(id -u) \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $HOME/.openhands:/.openhands \
  -p 3000:3000 \
  docker.all-hands.dev/all-hands-ai/openhands:0.9

L5 Agent Stack 권장 스펙: Workflow에서 어떤 Cloud Mac을 빌릴지

아키텍처 후 자연스러운 질문: Workflow 층에 어떤 머신? 실제 적층 기준 선정표(계약 SLA 아님):

상업 내러티브 Workflow → Cloud Mac → 스펙: L5 역량을 먼저 확인하고 Docker + (선택) Ollama + Runner를 버티는 노드를 고른다——머신부터 빌려 도구를 나중에 쌓지 마라.

적합·부적합: Agent 과장보다 경계가 중요

스크립트와 소규모 서비스: 예; 무방비 컴플라이언스 prod 쓰기: 아니오. OpenHands는 공학 가속기이지 면책 「자동 DevOps」가 아니다.

의사결정: Cloud Mac을 Agent 플랫폼으로 올려야 하나

아래 자가 진단에서 왼쪽 ≥3이면 L5 투입; 아니면 L1/L4를 먼저.

결론(요약이 아닌 결정): OpenHands 가치는 「더 똑똑한 Chat」이 아니라 Cloud Mac이 도구 모음에서 요구사항에 책임지는 플랫폼이 되는 것——전제는 Fact(Runner)와 Context/권한(MCP)이 이미 서 있다는 것. 아니면 수동 연결만 자동화했을 뿐, 조직은 여전히 merge 못 한다.

L5 연재: 결정에서 첫 자율 작업까지

L6 폐루프 전에 최소 ②: 재현 가능한 OpenHands tutorial 없으면 Hub에 랜딩이 없다. 전체 스택 지도는 L6-Q01; 시리즈는 「AI Tool Stack」에서 「AI Engineering Platform」으로, L6-Q05 Agent Governance가 마지막 고리.

FAQ

How OpenHands works / agent loop란?
Plan → Execute → Observe → Debug; Context 소비, Diff 산출, Fact 검증——동작 원리.

OpenHands vs Claude Code — 무엇을?
둘 중 하나가 아님. Diff는 Claude Code, 다단계 issue는 OpenHands——비교.

OpenHands tutorial / 설치?
본 Hub에 단계별 설치 없음. Docker + 첫 issue→PR은 L5-Q02(6/14 예정).

Mac에서 self-hosted 가능?
가능. 상시 Cloud Mac + Docker 샌드박스; 전형 아키텍처.

Runner 없이 OpenHands?
돌아가나 비권장. 먼저 L1.

OpenClaw는?
오케스트레이션 vs 자율 공학——삼각 분업과 OpenClaw 노트.

어떤 스펙을 빌릴까?
L5 Agent Stack 스펙; OpenHands만 M4 16GB, Claude Code 또는 Ollama 7B 병행 시 24GB.