OpenHanako: 기억과 인격을 가진 멀티 에이전트 개인 AI 어시스턴트 데스크톱 앱

9bow · 6월 26, 2026, 10:30오전

OpenHanako 소개

OpenHanako는 코드 편집기 안에 갇혀 있는 AI 에이전트를 일상 컴퓨터 사용 환경 전체로 끌어내기 위한 데스크톱 앱입니다. 명령줄에 익숙하지 않은 사용자도 그래픽 인터페이스로 에이전트와 대화하고 파일을 다루며 웹을 검색할 수 있도록, Electron 기반의 단일 애플리케이션으로 패키지된 점이 특징입니다. macOS, Windows, Linux를 모두 지원하며 mac 빌드는 Apple Developer ID 서명과 공증을 받았습니다.

OpenHanako의 차별점은 에이전트를 단순한 도구가 아니라 기억과 인격을 가진 존재로 다룬다는 점입니다. 각 에이전트는 자체 인격 템플릿과 장기 기억을 가진 폴더 단위로 관리되며, 백업과 공유가 쉽고 여러 에이전트가 같은 컴퓨터 위에서 협업하거나 서로 작업을 위임할 수 있도록 설계됐습니다. 텔레그램, 라크(飞书), QQ, 위챗 등 외부 메신저로 같은 에이전트에 접근할 수 있는 브릿지도 내장되어 있습니다.

참고로 프로젝트는 현재 앱 안팎에서 자신을 HanaAgent 로 부르며 README도 이 이름으로 정리되어 있습니다. 다만 저장소와 릴리스 URL은 마이그레이션 단계라 아직 기존 openhanako 경로(github.com/liliMozi/openhanako, openhanako.com)를 유지하고 있어, 이 글에서는 저장소 기준 이름인 OpenHanako로 표기합니다.

본 게시물에서는 OpenHanako가 어떤 문제를 풀려고 하는지, 어떤 구성 요소로 동작하는지, 그리고 어떤 모델 제공자와 어떤 보안 모델 위에서 돌아가는지를 정리합니다.

OpenHanako의 주요 기능

OpenHanako는 자신을 "한 명의 비서이자 동료" 로 위치시키며, 다음과 같은 축으로 기능을 정리하고 있습니다.

기억(Memory): 최근 대화 내용을 강하게 유지하는 자체 기억 시스템을 갖추고 있으며, 큰 모델로 주기적으로 컴파일해 장기 기억으로 옮깁니다.
인격(Personality): 인격 템플릿과 커스텀 인격 파일로 말투와 행동 패턴을 정의하고, 에이전트마다 독립된 폴더로 관리해 백업과 이식이 쉽습니다.
도구(Tools): 파일 읽기 쓰기, 일회성 명령 실행과 지속형 터미널 세션, 웹 브라우저 자동화, 검색, 스크린샷, 분할 긴 스크린샷, 미디어 미리보기, 웹페이지 검사 등을 기본 제공합니다. server-first CLI로 같은 Hana Server에 접속해 터미널에서 상태 확인, 세션 목록 조회, 대화 이어가기도 가능합니다.
전체 화면 미디어 뷰어: 채팅이나 책상의 이미지, SVG, 영상을 클릭하면 어두운 오버레이의 전체 화면 뷰어가 열려 휠 확대, 드래그 이동, + - 0 단축키, 같은 세션이나 폴더 내 인접 미디어 좌우 이동을 지원합니다.
세션 관리: 사이드바에서 제목 우선으로 대화 기록을 검색하고 필요하면 본문까지 탐색하며, 지난 세션은 보관 후 설정에서 복원하거나 영구 삭제할 수 있습니다. 채팅 본문에서 선택한 텍스트는 입력창 인용 카드로 들어가 후속 질문 시 원문 맥락을 유지합니다.
Skills 지원: 외부 Skills 커뮤니티 생태계와 호환되며, 에이전트가 GitHub에서 필요한 Skill을 직접 설치하거나 새 Skill을 작성해 학습할 수 있는 자율성을 제공합니다. 기본값은 엄격한 Skill 심사 모드입니다.
캐릭터 카드와 Skill Bundle: 에이전트는 인격, 아바타, 선택적 기억과 Skill을 화이트리스트 기반으로 묶은 로컬 우선 zip 파일로 내보낼 수 있으며, Skill 묶음 단위의 그룹 관리와 그룹 활성화를 지원합니다.
멀티 에이전트와 책상(Desk): 여러 에이전트를 만들고 채널 단위로 그룹 대화를 시키거나 서로 작업을 위임할 수 있고, 각 에이전트는 파일과 메모를 올려두는 "책상" 작업 공간을 가집니다.
정기 작업과 하트비트: 에이전트는 Cron 기반 정기 작업을 등록할 수 있으며, 책상 위 파일 변경도 주기적으로 감시합니다.
다중 플랫폼 접속과 모바일 LAN 프런트엔드: 같은 에이전트가 Telegram, 飞书, QQ, 위챗 봇으로 동시에 노출될 수 있고, Hana Server는 PWA로 모바일에서 같은 세션을 이어갈 수 있게 합니다.
플러그인 시스템: 도구, Skill, 명령, Agent 템플릿, HTTP 라우트, 이벤트 훅, LLM Provider, 페이지, 사이드바 위젯, 설정 스키마, 백그라운드 작업까지 기여할 수 있는 확장 아키텍처를 제공합니다. 라우트는 PluginContext 주입을 통해 코어 서비스에 접근하며, restricted / full-access 두 단계 권한 모델로 안전성을 보장합니다.
다국어: UI는 중국어, 영어, 일본어, 한국어, 번체 중국어 5개 언어를 지원합니다.

OpenHanako의 아키텍처

OpenHanako는 다음과 같은 디렉터리 구조로 자신을 소개합니다.

core/           엔진 오케스트레이션 계층 + Manager (PluginManager 포함)
lib/            핵심 라이브러리 (기억, 도구, 샌드박스, Bridge 어댑터)
server/         Hono HTTP + WebSocket 서버 (독립 Node.js 프로세스)
hub/            스케줄러, 채널 라우터, 이벤트 버스
desktop/        Electron 앱 + React 프런트엔드
shared/         계층 간 공유 유틸 (config schema, error bus, 모델 참조 등)
plugins/        앱과 함께 패키징되는 내장 시스템 플러그인
skills2set/     내장 스킬 정의
scripts/        빌드 도구 (server 패키징, 런처, 서명)
tests/          Vitest 테스트

엔진 계층은 core/ 디렉터리에서 Agent, Session, Model, Preferences, Skill, Channel, BridgeSession, Plugin 등 여러 Manager를 조정하며 통합된 facade를 통해 외부에 노출합니다. hub/ 는 하트비트 점검, 자동화 정기 작업, 채널 라우팅, 에이전트 간 통신, DM 라우팅 같은 백그라운드 작업을 현재 채팅 세션과 독립적으로 처리합니다. server/ 는 Electron이 spawn하거나 독립적으로 실행되는 별도 Node.js 프로세스로 동작하며, Vite로 패키징하고 @vercel/nft로 의존성을 추적하며, Electron 렌더러 프로세스와는 WebSocket으로 통신합니다. 사용자 데이터 디렉터리는 환경 변수 HANA_HOME 으로 결정되며, 프로덕션 기본값은 ~/.hanako, 개발 기본값은 ~/.hanako-dev 입니다. Pi SDK 자체 데이터는 ${HANA_HOME}/.pi/ 하위로 격리됩니다.

세션 안에서 사용자에게 보이는 파일은 SessionFile 사이드카로 등록되어, 데스크톱, Bridge, 모바일 PWA, 다른 원격 프런트엔드가 같은 파일 신원을 자신의 능력에 맞게 소비합니다. Bridge 플랫폼별 미디어 전송 규칙은 .docs/BRIDGE-MEDIA-CAPABILITIES.md, 플러그인 파일 기여 규칙은 PLUGINS.md 에 정리되어 있습니다. Telegram, 飞书, 위챗은 각자의 업로드 API를, QQ는 공식 Bot 분할 업로드와 msg_type: 7 리치 미디어 메시지를 사용합니다. 공용 미디어 URL이 필요한 경우에 한해 preferences.bridge.mediaPublicBaseUrl 또는 HANA_BRIDGE_PUBLIC_BASE_URL 이 /api/bridge/media/:token 라우트의 origin으로 쓰이며, 파일은 단기 토큰과 다운로드 횟수, 로컬 경로 화이트리스트로 보호됩니다. Hana는 공용 터널을 자동으로 열지 않으며, 공용 입구가 필요하면 사용자가 직접 명시적으로 제공해야 합니다.

OpenHanako의 기술 스택

OpenHanako는 기술 스택 표에서 다음 구성 요소로 동작한다고 밝히고 있습니다.

계층	기술
데스크톱	Electron 42
프런트엔드	React 19 + Zustand 5 + CSS Modules
빌드	Vite 7
서버	Hono + @hono/node-server
에이전트 런타임	Pi SDK
데이터베이스	better-sqlite3 (WAL 모드)
테스트	Vitest
국제화	중국어, 영어, 일본어, 한국어, 번체 중국어

에이전트 실행 자체는 외부 Pi SDK 가 담당하며, OpenHanako는 그 위에 기억, 인격, 도구, 샌드박스, 멀티 에이전트 협업 같은 계층을 얹은 형태로 정리할 수 있습니다. 플랫폼 지원 현황은 macOS Apple Silicon과 Intel(서명·공증 완료), Linux(AppImage / deb), Windows(Beta), 모바일 PWA(같은 Hana Server에 접속해 세션과 책상에 접근하는 v0 단계)로 구분됩니다.

OpenHanako의 보안 샌드박스

OpenHanako는 자체 PathGuard 4단계 접근 제어와 운영체제 단계 샌드박스를 이중으로 두는 2단 격리(double-layer isolation) 모델을 채택합니다. macOS에서는 Seatbelt, Linux에서는 Bubblewrap, Windows에서는 restricted token이 운영체제 측 격리를 담당합니다.

평상시 에이전트는 사용자의 시스템 일반 파일은 읽기만 할 수 있고, 쓰기와 삭제는 작업 디렉터리와 통제된 데이터 디렉터리로 제한됩니다. Windows의 명령 샌드박스는 현재 쓰기 격리 모델로, 읽기와 네트워크는 사용자 권한을 따라가는 자연스러운 흐름을 유지합니다. macOS와 Linux의 네트워크 격리는 각 운영체제 샌드박스 능력에 따라 달라집니다. 사용자는 설정의 보안 페이지에서 샌드박스 등급을 조정하거나 시스템 프록시, 수동 프록시, 직접 연결을 선택할 수 있습니다.

OpenHanako 설치와 첫 실행

배포 채널은 GitHub Releases 가 단일 진입점이며 운영체제별로 다음 파일을 내려받습니다.

macOS (Apple Silicon, Intel): 최신 .dmg 를 내려받습니다. Apple Developer ID 서명과 공증이 적용되어 있어 기본 설정으로 실행할 수 있습니다.
Windows: 최신 .exe 설치 패키지를 사용합니다. 현재는 코드 서명이 적용되지 않아 SmartScreen 경고가 뜰 수 있으며, "추가 정보 → 실행" 으로 진행합니다.
Linux: .AppImage 또는 .deb 패키지를 사용합니다.

첫 실행 시 마법사가 언어, 사용자 이름, 모델 제공자(API key + base URL), 그리고 대화 모델, 소형 도구 모델, 대형 도구 모델 세 가지를 묻습니다. 큰 모델은 기억 컴파일과 심층 분석에 사용됩니다. 설정 페이지에서 별도로 비전 모델을 지정하면, 텍스트 모델이 Vision Bridge를 통해 이미지 첨부를 처리합니다. 모델 제공자는 OpenAI 호환 API, Anthropic 스타일 API, OAuth Provider, Ollama 기반 로컬 모델 등을 지원합니다. OpenAI OAuth 로그인도 새로 추가됐으며, 저자는 "Anthropic OAuth는 계정 정지 위험이 있어 현재 제공하지 않는다" 고 밝히고 있습니다.

소스에서 직접 빌드하고 싶다면 package.json 의 스크립트를 따라 다음 명령으로 시작할 수 있습니다.

# 의존성 설치
npm install

# Electron 실행 (renderer 자동 빌드)
npm start

# Vite HMR 개발 (npm run dev:renderer 먼저)
npm run start:vite

# server만 실행
npm run server

# server-first CLI
npm run cli

# 테스트와 타입 체크
npm test
npm run typecheck

OpenHanako의 라이선스

OpenHanako는 Apache License 2.0 으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있고, 변경 사항을 공개할 의무가 없는 permissive 라이선스입니다.

더 읽어보기

OpenHanako 공식 홈페이지

OpenHanako 프로젝트 GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~