OpenHarness를 언제 도입하고 언제 과한가 2026 — 세션·도구구조·운영비용 체크리스트

Posted on by

Claude Code 같은 경험을

내 서비스나 팀 도구에

옮겨보고 싶어질 때가 있다.

그 순간 사람 머릿속에는

거의 자동으로

이 장면이 뜬다.

파일 읽고,

셸 돌리고,

필요하면 다른 에이전트에게 던지고,

세션도 이어지고,

권한 승인도 끼워 넣을 수 있는

제법 그럴듯한 하네스.

그럴 때

OpenHarness 이름이

꽤 자주 보인다.

2026년 4월 16일 기준

OpenHarness 공식 소개 페이지는

이 프로젝트를

Vercel AI SDK 위에 올라간

오픈소스 AI 에이전트 프레임워크로 설명한다.

공식 docs가 앞세우는 키워드는

또렷하다.

stateless agents,

composable middleware,

subagent delegation,

provider abstraction,

MCP integration,

AGENTS.md,

skills,

UI streaming.

이 조합만 보면

솔직히 꽤 매력적이다.

문제는 여기서부터다.

이런 프레임워크는

좋아 보여서 넣는 순간보다,

나중에 운영비를

누가 떠안느냐에서

진짜 성격이 드러난다.

그래서 이 글은

OpenHarness 멋있네

요약이 아니다.

2026년 4월 16일 기준

공식 사이트,

공식 docs,

GitHub repo,

npm 정보를 바탕으로

이게 어떤 팀에 맞고,

언제는 너무 이른 선택인지

운영자 언어로 번역해보는 글이다.

즉,

이 글은

OpenHarness를 며칠 붙여 돌린

장기 운영 후기라기보다,

하네스 관점에서 공식 문서를 뜯어본

도입 판단 메모에 가깝다.

한 줄로 먼저 말하면,
OpenHarness는 “에이전트 제품을 코드로 만들 팀”에겐 꽤 매력적이고,
“툴 2개 붙인 사내 자동화”에는 자주 과하다.

한 줄 답

  • OpenHarness는 단일 프롬프트 래퍼보다 한 단계 아래가 아니라, 한 단계 위 설계다.
  • 공식 docs 기준 핵심은 stateless agent에 Session, middleware, subagent, MCP, permissions를 조립하는 방식이다.
  • 그래서 상태 관리, 승인 UX, 도구 안전성, 장기 세션, 재개 가능한 서브에이전트가 필요한 팀에는 값이 난다.
  • 반대로 한두 개 툴만 쓰는 내부 자동화나 일회성 CLI에는 AI SDK 직결이나 작은 래퍼가 더 낫다.
  • 2026년 4월 16일 기준 @openharness/core 최신 버전은 0.6.2이고, GitHub 저장소는 2026년 2월 23일 생성된 아직 어린 프로젝트라 도입 판단에 성숙도 체크가 꼭 들어가야 한다.

먼저 구조를 짧게 번역해보자

공식 introduction 문서는

OpenHarness의 출발점을

아주 분명하게 말한다.

Claude Code,

Codex,

OpenCode 같은

고급 에이전트 하네스의 빌딩 블록을

조금 더 가볍고 조합 가능하게

코드로 쓰게 만들겠다는 쪽이다.

여기서 중요한 단어가

stateless다.

공식 docs는

agent를

pass in history, get back events

라고 설명한다.

즉,

에이전트 본체는

상태를 꼭 쥐고 있는

거대한 런타임이라기보다,

메시지 히스토리를 넘기면

이벤트를 흘려주는 실행기 쪽에 가깝다.

그리고 대화 상태는

Session 층에서

다시 감싼다.

README 예시를 보면

new Session({ agent, contextWindow: 128_000 })

같은 형태가 바로 나온다.

공식 Sessions 문서의 설명도

상태 있는 멀티턴 대화,

compaction,

retry,

persistence 쪽에 초점이 맞춰져 있다.

이 구조가 왜 중요하냐면

하네스에서 제일 귀찮은 게

대개 모델이 아니라

상태이기 때문이다.

한 번 잘 답하는 것보다,

세 번 이어서 답하고,

중간에 툴을 쓰고,

필요하면 압축하고,

다음 세션에서 복구하는 게

훨씬 어렵다.

OpenHarness는

그 어려운 부분을

agent 안에 꽁꽁 숨기지 않고,

session,

middleware,

provider,

permissions,

subagent 같은 레이어로

나눠서 보여준다.

이건 장점이자

단점이다.

좋게 말하면

통제가 쉽고,

나쁘게 말하면

네가 결정할 게 많다.

이름보다 구조를 먼저 봐야 한다

내 인박스에 들어온 2차 메모에는

Ohmo

같은 표현이 있었고,

개인 에이전트 느낌으로

읽히기도 했다.

그런데 2026년 4월 16일 기준

공식 사이트,

공식 docs,

README에서

앞에 나오는 중심 메시지는

특정 캐릭터 이름보다

구조다.

stateless agents,

sessions,

subagents,

skills,

AGENTS.md,

MCP,

permissions,

built-in tools.

이 포인트는 꽤 중요하다.

왜냐하면

프레임워크 도입 판단을

브랜딩이나 데모 화면이 아니라

운영 구조로 해야 하기 때문이다.

개인 에이전트가 멋져 보이네

가 아니라,

우리는 세션 재개가 필요한가,

권한 승인 콜백을 정말 붙일 건가,

MCP와 정적 툴을 한 도구셋으로 합칠 건가,

프로젝트 지침 파일을 자동 로드할 이유가 있는가

를 먼저 물어야 한다.

공식 AGENTS.md 문서는

첫 실행 시

현재 작업 디렉터리에서 루트까지 올라가며

AGENTS.md 또는 CLAUDE.md를 찾아

첫 파일을 시스템 프롬프트 앞에 붙인다고 설명한다.

이건 그냥 편의 기능이 아니다.

팀에 따라서는

엄청난 장점이 된다.

반대로

지침 파일 충돌을 싫어하는 팀에는

바로 디버깅 포인트가 된다.

그래서 이 프레임워크는

마스코트보다

규칙 로딩 방식과

상태 계층을 보는 게 맞다.

OpenHarness가 진짜 맞는 팀

아래 조건이 많을수록

OpenHarness 쪽으로 기운다.

팀 상황 적합도 이유
사내 에이전트 제품을 직접 만들고 싶다 높음 stateless core 위에 session, permissions, streaming UI까지 조립할 수 있다
장기 세션과 컨텍스트 압축이 필요하다 높음 공식 docs가 Session과 compaction을 핵심으로 민다
툴 승인 UX를 명시적으로 넣고 싶다 높음 approve 콜백으로 도구 실행 게이트를 둘 수 있다
MCP 서버와 자체 툴을 같이 붙여야 한다 높음 MCP 도구를 정적 툴셋과 합치고, 여러 서버면 네임스페이스도 관리한다
서브에이전트를 백그라운드로 굴리고 싶다 중상 README와 subagents docs가 재개 가능한 세션과 background runs를 강조한다
일회성 자동화 스크립트 하나가 필요하다 낮음 AI SDK 직결이나 작은 래퍼가 더 단순하다
팀에 에이전트 운영 경험이 거의 없다 낮음 구조를 잘게 나눠 보여주는 만큼 결정 비용도 커진다

조금 더 사람 말로 풀면

이렇다.

OpenHarness는

에이전트를 쓴다

보다

에이전트 제품을 만든다

에 가깝다.

툴 호출 한두 번 붙이는 수준이 아니라,

상태,

승인,

도구 권한,

지침 로딩,

서브에이전트 합류,

UI 스트리밍까지

한 번에 설계하고 싶은 팀이면

이 구조가 예쁘게 느껴질 수 있다.

특히

Claude Code류 경험을

내 워크플로에 맞게

조금씩 변형하고 싶은 팀에선

꽤 설득력이 있다.

반대로

LLM에게

파일 읽기랑 bash만 주고

가끔 자동화 돌리면 끝인 팀은

이 프레임워크의 장점보다

설정 표면적이 먼저 커 보일 가능성이 높다.

바로 좋아 보인 지점

첫째,

stateless agent와

stateful session을

분리한 감각이 좋다.

이 방식은

문제가 생겼을 때

어디를 의심해야 하는지를

분리해준다.

에이전트 로직 문제인지,

세션 압축 문제인지,

영속화 문제인지,

경계가 상대적으로 선명하다.

둘째,

도구 계층이

생각보다 실무적이다.

공식 built-in tools 문서는

filesystem 쪽에서

readFile,

writeFile,

editFile,

listFiles,

grep,

deleteFile

세트를 제공한다고 적는다.

bash 도구는

기본 timeout 30초,

최대 5분,

출력 truncation까지

기본 안전장치를 둔다.

이건 데모용 프레임워크보다

운영용 빌딩 블록에

조금 더 가깝다는 신호다.

셋째,

permissions 설계가

깔끔하다.

공식 permissions 문서는

기본적으로 모든 도구 호출이 허용되지만,

approve 콜백을 주면

툴 실행을 게이트할 수 있다고 적는다.

그리고 거절된 도구 호출은

ToolDeniedError로 surfaced되어

모델이 다른 접근을 시도하거나

사용자에게 되묻게 만들 수 있다.

이 부분은

하네스를 오래 만진 사람일수록

좋아할 포인트다.

승인 UX는

항상 귀찮지만,

없으면 더 무섭다.

넷째,

MCP와 AGENTS.md,

skills를 같은 철학으로

묶는 점이 좋다.

공식 docs에 따르면

MCP 서버는

stdio,

HTTP,

SSE 세 가지 transport를 지원하고,

첫 run() 때 lazy connection으로 붙는다.

AGENTS.md는

작업 디렉터리에서 위로 올라가며

첫 파일을 로드한다.

이 둘을 같이 보면

OpenHarness는 단순히

툴 더 붙이는 프레임워크

가 아니라,

도구와 지침을

실행 시점에 합성하는 프레임워크에 가깝다.

다섯째,

서브에이전트 이야기를

진짜 운영 기능으로 밀고 있다.

README는

stateless 기본값 위에

dynamic subagent catalogs,

resumable subagent sessions,

background runs with separate run IDs and session IDs

를 언급한다.

이건 그냥

하위 에이전트도 됩니다

수준이 아니다.

백그라운드 작업과

재개 가능성까지

처음부터 고민한 흔적이다.

바로 경계한 지점

좋아 보이는 포인트가 많다는 건

동시에

운영 결정이 많다는 뜻이기도 하다.

가장 먼저 드는 경계심은

이 프레임워크가

생각보다 젊다는 점이다.

@openharness/core의 npm 정보 기준

최신 버전은 0.6.2,

수정 시각은

2026년 4월 15일이다.

GitHub 저장소 생성일은

2026년 2월 23일이다.

2026년 4월 16일 기준

star는 458개,

fork는 91개,

open issue는 0개였다.

이 수치가 나쁘다는 얘기는 아니다.

오히려 꽤 빠르게 주목받는 중이라고

볼 수도 있다.

다만

도입 판단은

기능이 많다

가 아니라

`어린 프로젝트의 변경 속도를

우리 팀이 감당 가능한가`

로 해야 한다.

두 번째 경계는

상태 계층의 책임이

결국 네 쪽에 남는다는 점이다.

세션이 있다고 해서

상태 설계가 사라지지 않는다.

무엇을 저장할지,

언제 압축할지,

어떤 실패에서 재시도할지,

어디까지 복구할지,

이건 프레임워크가 대신 안 해준다.

프레임워크가 해주는 건

이 문제를

다룰 수 있는 표면을 제공하는 쪽에 가깝다.

세 번째 경계는

승인 UX다.

공식 docs는

CLI 프롬프트,

웹 모달,

외부 서비스 승인 같은 패턴을 예로 든다.

그런데 이 말은 곧

네가 승인 경험까지

직접 설계해야 한다는 뜻이다.

사람이 버튼 누를 건지,

정책 엔진이 자동 승인할 건지,

로그를 어디까지 남길 건지,

실패했을 때 모델에게 무슨 에러를 보여줄 건지.

이건 생각보다

금방 커진다.

네 번째 경계는

문서가 예쁘다고

제품 아키텍처까지 바로 쉬워지진 않는다는 점이다.

OpenHarness는

분명 깨끗한 빌딩 블록을 준다.

하지만 빌딩 블록이 깨끗할수록

어떤 블록을 안 쓸지도

네가 정해야 한다.

이건 자유이면서

동시에 책임이다.

언제는 확실히 과하다

아래 상황이면

나는 먼저

OpenHarness 말고

더 작은 선택지를 본다.

  • 내부에서만 쓰는 일회성 조사 봇이다.
  • 대화 상태를 길게 이어갈 필요가 없다.
  • 도구가 파일 읽기 한두 개와 HTTP 호출 정도면 끝난다.
  • 승인 UX를 만들 시간보다 결과를 빨리 내는 게 중요하다.
  • MCP를 붙일 계획이 아직 없다.
  • 서브에이전트는 당장 필요 없고, 필요해도 순차 호출이면 된다.
  • 프로젝트 지침 파일 자동 로딩이 오히려 혼란이 될 수 있다.

이럴 땐

AI SDK 직결,

혹은 아주 얇은 사내 래퍼가

더 낫다.

왜냐하면

문제의 크기보다

프레임워크의 표면적이

커지기 때문이다.

쉽게 말해

자전거 한 대 타고 동네 마트 가는데

트럭 정비 매뉴얼부터 펼치는 느낌이 된다.

없는 기능이 문제인 순간보다,

있는데 안 써도 되는 기능이

머릿속 자리를 차지하는 순간이

더 피곤하다.

특히

혼자 쓰는 개인 자동화라면

세션 복구,

백그라운드 서브에이전트,

permissions,

MCP 네임스페이싱 같은 개념이

처음엔 멋있다가도

금방 유지보수 세금이 된다.

예를 들어

브라우저 안에서

반복 프롬프트 재사용,

탭 비교,

초안 생성 정도가 목적이라면

Gemini in Chrome Skills 2026 — 반복 프롬프트를 one-click workflow로 바꿀 때 먼저 정할 5가지

같은 더 얇은 레이어가

오히려 답일 수 있다.

다른 선택지와 비교하면 어디쯤이냐

선택지 좋은 점 아쉬운 점 추천 상황
AI SDK 직결 가장 단순하다 세션, 승인, 서브에이전트 구조를 직접 짜야 한다 작은 자동화, 빠른 실험
사내 얇은 래퍼 우리 팀 기준에 맞게 최소 기능만 넣을 수 있다 확장 시 재설계가 자주 온다 툴 수가 적고 요구가 안정적일 때
OpenHarness 세션, permissions, subagents, MCP, AGENTS.md가 한 철학 안에 있다 결정 비용과 구조 복잡도가 올라간다 에이전트 제품화, 운영형 워크플로
Claude Code/Codex/OpenCode 직접 사용 바로 강력한 UX를 쓴다 제품 내부 구조를 통제하기 어렵다 내부 툴 제작보다 사용이 목적일 때

핵심은

OpenHarness가

최강이냐 아니냐가 아니다.

어디까지 직접 만들고,

어디부터 제공된 경험을 쓸지의

중간 지점이라는 점이 중요하다.

완성품을 바로 쓰고 싶으면

Claude Code류가 편하다.

반대로

정말 작게 시작하고 싶으면

AI SDK 직결이 더 가볍다.

OpenHarness는

그 사이에서

완성품의 감각을

내 코드베이스의 통제력으로

옮기고 싶은 팀에 맞는다.

도입 전에 꼭 묻고 싶은 7가지

  1. 우리는 stateless agent와 session을 분리해 얻는 통제력이 실제로 필요한가.
  2. 세션 압축, 재시도, 영속화 정책을 누가 책임질 건가.
  3. 툴 승인을 CLI, 웹, 외부 서비스 중 어디서 처리할 건가.
  4. MCP 서버를 정말 여러 개 붙일 계획이 있는가.
  5. AGENTS.md 또는 CLAUDE.md 자동 로딩이 팀 규칙과 충돌하지 않는가.
  6. 서브에이전트를 병렬이나 백그라운드로 굴릴 문제를 이미 가지고 있는가.
  7. 아직 어린 오픈소스를 따라가며 버전 변화를 감당할 여력이 있는가.

이 질문 중

절반 이상이

아직 모르겠다

쪽이면

OpenHarness는

지금 바로 도입할 프레임워크가 아니라

관심 목록에 넣어둘 프레임워크일 가능성이 높다.

반대로

그게 지금 우리의 정확한 고통이다

라고 답하는 항목이

여럿 나오면,

이건 꽤 흥미로운 후보가 된다.

프레임워크는

기능 목록보다

고통과 맞닿는 정도로

평가하는 게 맞다.

실수 TOP 5

1. 파일 읽기와 bash만 필요하면서 프레임워크부터 넣는 실수

이 경우는

대부분 오버엔지니어링이다.

먼저 작은 래퍼로

실제 요구를 확인해도 늦지 않다.

2. Session이 있으니 상태 설계가 끝났다고 믿는 실수

세션은 저장 상자지,

판단 기준이 아니다.

무엇을 남기고

무엇을 버릴지는

여전히 네 몫이다.

3. permissions를 보안 기능으로만 읽는 실수

승인 콜백은

보안 기능이면서

동시에 UX 기능이다.

사용자 피로를 어떻게 관리할지

같이 봐야 한다.

4. AGENTS.md 자동 로딩을 무조건 장점으로 보는 실수

프로젝트 규칙이 자동 주입되는 건 편하다.

하지만 지침 파일이 여러 레이어에 섞여 있거나

팀이 그 흐름을 모르면

오히려 디버깅이 어려워진다.

5. 서브에이전트가 가능하니 바로 병렬화부터 하는 실수

백그라운드와 재개 가능한 세션은

멋있다.

그런데 문제 분해가 안 된 상태에서

병렬화부터 넣으면

디버깅 난이도만 오른다.

지금 판단

내 기준에서

OpenHarness의 매력은

기능 수보다

레이어 구분에 있다.

agent,

session,

tools,

permissions,

subagents,

MCP,

instructions를

한 덩어리 마법상자가 아니라

조립 가능한 부품으로 보여준다.

이건 분명 좋은 방향이다.

특히

에이전트 제품을

코드로 직접 만들고 싶은 팀에겐

정말 솔깃하다.

다만

2026년 4월 16일 기준

이 프로젝트는 아직 꽤 젊다.

그리고 젊은 프레임워크의 장점은

빠른 진화지만,

단점도 빠른 진화다.

그래서 내 판단은 이렇다.

  • 제품형 에이전트를 만들 팀이라면 적극적으로 봐도 된다.
  • 사내 실험용 자동화라면 작은 래퍼로 먼저 증명하고 넘어가는 편이 안전하다.
  • 세션과 승인 UX가 아직 추상적인 팀이라면 지금은 공부 대상이지 도입 대상은 아니다.

한마디로,

OpenHarness는

에이전트를 돌려보고 싶은 사람

보다

에이전트 런타임을 설계하고 싶은 사람

에게 더 잘 맞는다.

FAQ

OpenHarness는 Claude Code 대체재라고 보면 되나

완전한 대체재보다는

Claude Code류 경험을

내 코드베이스 안에서

구성하고 싶은 팀을 위한

프레임워크에 더 가깝다.

직접 제품을 만들고 싶으면

가치가 커지고,

그냥 바로 쓰고 싶으면

완성형 도구가 더 편하다.

OpenHarness를 쓰면 세션 관리가 자동으로 끝나나

끝나지 않는다.

공식 docs가 Session,

compaction,

retry,

persistence를 제공한다고 해도,

언제 저장하고

무엇을 압축하고

어떤 실패에서 복구할지는

여전히 팀 정책이 필요하다.

permissions는 꼭 넣어야 하나

공식 문서 기준

기본은 모든 도구 호출 허용이다.

즉,

안 넣어도 돌아갈 수는 있다.

하지만 파일 시스템이나 셸을 건드리는 순간

승인 UX를 어떻게 할지

빨리 결정하는 게 좋다.

나중으로 미루면

가장 아픈 곳에서 되돌아온다.

AGENTS.md 자동 로딩은 왜 중요하나

프로젝트 규칙,

금지 디렉터리,

테스트 규칙,

배포 메모 같은 걸

에이전트 실행 시 자동 주입할 수 있어서다.

다만 팀이 그 규칙을 모르고 있으면

왜 모델이 저렇게 행동하는지

추적하기 어려워질 수도 있다.

지금 당장 써볼 만한 사람은 누구인가

파일 도구,

bash,

세션,

서브에이전트,

MCP,

권한 승인을

한 런타임 안에서 통합해보고 싶은 팀이다.

특히

이미 하네스 문제를

직접 겪고 있는 팀일수록

가치 판단이 빨라진다.

관련 글

참고 자료