2026 OpenHuman 가장 완전한 설치·설정 가이드: 0부터 가동까지 실전 튜토리얼

2. 잘못 설치하지 마세요: 데스크톱 어시스턴트 vs WebGL SDK

OpenHuman(본문 대상)은 tinyhumansai/openhuman 오픈소스 데스크톱 개인 AI 어시스턴트입니다. UI 우선, Memory Tree, Obsidian형 Markdown vault, OAuth 연동 118+개, 선택적 로컬 Ollama. 기본적으로 계정 로그인·모델 라우팅·검색 프록시·Composio 계층 OAuth는 OpenHuman 호스팅을 쓰며, 설정에서 BYOK·직접 Composio로 점진 전환할 수 있습니다.

온라인에는 OpenHuman WebGL 디지털 휴먼 SDK도 있습니다. 웹 3D 아바타용이며 본 가이드 설치 대상이 아닙니다. 「개인 지식베이스 + 메일/캘린더/저장소 맥락」이 목표라면 데스크톱 저장소와 tinyhumans.ai/openhuman 다운로드 페이지를 사용하세요.

일반 웹 채팅 탭과도 다릅니다. OpenHuman은 로컬 워크플로 데이터 + 정기 연동 pull을 강조합니다. CLI 우선 Agent와 달리 GUI + 짧은 온보딩으로, 첫 메시지 전에 설정 파일이 필수는 아닙니다.

3. 자주 막히는 지점

1. 제약: 「설치됨」= 「이미 나를 안다」. 공식 문서에 따르면 Memory Tree, Markdown vault, 워크스페이스 설정, 로컬 실행 상태는 본기에 있습니다. 다만 로그인·모델 라우팅·검색 프록시·기본 OAuth는 호스팅 백엔드를 쓸 수 있습니다. 연동·동기화 없이는 Agent가 일반론만 말합니다.
2. 숨은 비용: 권한 과다·첫날부터 생산 계정. OAuth 한 번에 메일 읽기·캘린더·저장소 등이 묶일 수 있습니다. Beta 단계에서는 테스트 메일함·테스트 GitHub 저장소로 범위·해제 경로를 확인한 뒤 실제 업무 데이터를 연결하세요.
3. 안정성·감사: 메모리·로그 위치 모름. 기록 없이 삭제·재설치하면 SQLite·vault의 유일한 동기화 흔적이 사라질 수 있습니다. 워크스페이스 경로, 연동 ID, 모델 모드(호스팅/BYOK/Ollama)를 남겨 두세요.

4. 설치 전 체크리스트

목적: 중간에 네트워크·디스크 문제를 발견하면 시간이 크게 낭비됩니다. 통과 기준: 아래 항목을 모두 확인한 뒤 설치 패키지를 받으세요.

• OS: macOS(Apple Silicon·Intel), Windows 10/11(64비트), Debian/Ubuntu·Arch 등 Linux 데스크톱. 최소 버전은 당시 Release 설명을 따르세요. 제품은 Early Beta—UI 경로가 바뀔 수 있습니다.
• 하드웨어: RAM 16GB+ 권장(로컬 Ollama는 더 필요). 디스크 ≥5GB 여유(앱+vault+SQLite+모델 캐시, 실제 사용량은 다름).
• 네트워크: GitHub, tinyhumans.ai, OAuth 리다이렉트 도메인 접근. 회사 프록시면 시스템 프록시·브라우저 팝업 허용.
• 계정: OpenHuman 제품 계정; BYOK 시 각 모델 벤더 API Key; Ollama 사용 시 본기 설치·모델 pull.
• 테스트 데이터: 전용 테스트 Gmail·테스트 GitHub 저장소—첫 실행에 회사 Slack·생산 메일함 연결 금지.
• 권한: macOS는 알림·마이크(음성)·파일/폴더 접근 요청 가능. Linux는 AppImage+Wayland 알려진 이슈(공식 #2463).

5. 다운로드 출처·보안 검증

공식 우선순위(README): ① 공식 사이트 / GitHub Release 설치 패키지 → ② 네이티브 패키지 관리자(Homebrew, 서명 apt, MSI) → ③ 스크립트 설치(독립 스크립트 서명 없음—위험을 이해할 때만).

실패 시 먼저: 파일 손상 → Release에서 재다운로드; SmartScreen/Gatekeeper → 발행자 확인 후 허용; 출처 불명 「미러」로 공식 패키지 대체 금지.

6. 3플랫폼 설치 단계

6.1 macOS(Homebrew 권장)

brew tap tinyhumansai/core
brew install openhuman

Release의 .dmg를 받아 응용 프로그램 폴더로 끌어 넣어도 됩니다. 통과 기준: Launchpad에서 OpenHuman 실행. 실패 시 먼저: 「개발자를 확인할 수 없음」→ 시스템 설정 → 개인 정보 보호 및 보안 → 그래도 열기; 첫 실행 시 알림·마이크·파일 접근(실제 쓰는 기능만 최소 허용).

6.2 Windows(서명 MSI)

최신 release에서 .msi를 받아 설치합니다. SmartScreen에서 발행자를 확인하세요. 통과 기준: 시작 메뉴 바로 가기로 앱 실행. 실패 시 먼저: 기업 정책, 백신 격리, OAuth 브라우저 콜백 방화벽.

6.3 Linux(apt 권장, AppImage 주의)

sudo apt-get install -y --no-install-recommends gnupg2 curl ca-certificates
curl -fsSL https://tinyhumansai.github.io/openhuman/apt/KEY.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/openhuman.gpg
echo "deb [signed-by=/etc/apt/keyrings/openhuman.gpg arch=amd64] \
  https://tinyhumansai.github.io/openhuman/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/openhuman.list
sudo apt-get update
sudo apt-get install -y openhuman

Arch는 저장소 openhuman-bin AUR(yay -S openhuman-bin, AUR 실제 목록 확인). AppImage는 Wayland·일부 Arch에서 실패할 수 있음(공식 #2463). Debian/Ubuntu는 .deb / apt 우선. 통과 기준: 데스크톱 메뉴에서 실행. 실패 시 먼저: 라이브러리, Wayland 환경 변수, X11 세션 전환.

6.4 플랫폼별 설치 의사결정 매트릭스

삭제·재설치: 먼저 OAuth 연동을 모두 끊고 중요한 vault 디렉터리를 백업하세요. 삭제 후에도 워크스페이스·SQLite가 사용자 프로필에 남을 수 있습니다—유일한 메모리 사본을 지우기 전 공식 데이터 경로를 확인하세요.

7. 첫 실행·계정 로그인

1. 앱을 실행하고 전용 워크스페이스 디렉터리를 선택하세요. 홈 폴더 전체는 피하세요.
2. OpenHuman 제품 계정으로 로그인(기본 호스팅 로그인). 통과 기준: 설정에 로그인 상태 표시.
3. 업데이트 채널·개인정보 관련 토글(알림, 음성, 검색 프록시) 확인—첫 가동 통과 전까지 기본값 유지 후 조정.

실패 시 먼저: 로그인 빈 화면 → 기본 브라우저·광고 차단 해제; 반복 실패 → 시스템 시간·DNS·프록시; 지역·구독 정책은 당시 공식 문서 기준—모든 지역에서 동일 기능을 보장하지 않습니다.

8. 모델 설정·BYOK

호스팅 모델(기본): OpenHuman 백엔드가 모델 라우팅(작업별 추론/고속/비전 모델 선택)을 수행합니다. 구독 내 다중 모델 라우팅 등 공식 표현이 있으며, 가격·할당량은 계정 페이지에서 변할 수 있습니다.

BYOK(Bring Your Own Key, 자체 API Key): 설정에 벤더 API Key를 입력—사용량 과금·할당량을 직접 관리. 기업 계약·비용 통제에 유리합니다.

로컬 모델(Ollama): 공식 문서는 선택적 로컬 AI를 지원합니다. Apple Silicon 통합 메모리는 소형 모델에 유리하나 대형 모델은 RAM 한계가 있습니다—지연·품질은 직접 검증하세요.

통과 기준: 테스트 프롬프트(예: 「한 문장으로 자기소개」)에 일관된 응답. 실패 시 먼저: 호스팅→구독/네트워크; BYOK→Key 권한·과금; Ollama→서비스 수신·모델명 일치.

9. 연동·권한 설정

OpenHuman은 Gmail, Slack, Notion, GitHub, Calendar, Drive 등 118+ 커넥터를 Composio 커넥터 계층으로 제공합니다. 기본 OAuth·도구 호출은 호스팅 백엔드를 경유합니다. 직접 Composio는 설정에 Composio API Key를 넣고 실시간 트리거 웹훅을 직접 호스팅하세요.

OAuth는 브라우저로 로그인해 앱에 제한된 대리 접근을 부여하는 표준 흐름입니다. 동의 화면의 권한 범위(scope)를 읽고, 실전에 필요한 것만 허용하세요. 불명확한 scope는 보류하세요.

통과 기준: Connected 표시, OAuth 콜백 오류 없음. 실패 시 먼저: 팝업 차단, 기업 SSO, Composio 상태, 네트워크 프록시.

10. 메모리 시스템 검수 방법

초보자에게 OpenHuman 메모리는 이렇게 이해하면 됩니다:

• Memory Tree: 연동에서 pull한 데이터를 계층 요약으로 정리해 SQLite에 로컬 저장, Agent가 검색.
• Markdown vault(Obsidian 호환): 동일 지식이 .md로도 저장되어 Obsidian에서 열람·편집 가능.
• auto-fetch: 활성 연결마다 대략 20분마다 새 데이터 pull—수동 폴링 스크립트 불필요.

검수 단계: 테스트 연동 → 20분 주기 1회 이상 대기(UI에 수동 트리거 있으면 사용) → Memory·vault에 새 Markdown 확인 → 테스트 데이터만 답할 수 있는 질문(테스트 메일 고유 키워드 등).

통과 기준: 답이 올바른 출처·파일 조각을 인용. 실패 시 먼저: 연동 비활성, 동기화 미완, 테스트만 연결했는데 생산 데이터 질문(빈 맥락 환각).

11. 첫 실전: 테스트 메일함 「주간 요약 + 할 일」

목표: 모델·연동·메모리·출력·해제 루프를 한 번에 검증.

1. 테스트 Gmail 계정 생성; 제목이 분명한 메일 2~3통 자신에게 발송(예: 「Q2 예산 논의」, 「금요일까지 주간 보고 제출」).
2. OpenHuman에서 해당 테스트 메일함만 연결, OAuth 완료.
3. 첫 auto-fetch 대기(≥20분 권장), vault/Memory에 새 콘텐츠 확인.
4. 질문: 「테스트 메일함 최근 메일을 바탕으로 주간 요약과 할 일 목록을 만들고, 각 항목의 출처 메일을 인용해 줘.」
5. 검증: 요약이 테스트 메일과 일치, 허구 주제 없음; 앱이 지원하면 출력 저장.
6. OpenHuman·Google 양쪽에서 권한 해제; Disconnect 후 해당 메일함 참조 중단 확인.

통과 기준: 출력이 테스트 메일과 일치, 출처 확인 가능, 해제 후 접근 중단. 실패 시 먼저: 모델(④) vs 메모리(⑥) 계층을 분리해 보지 말고 섞지 마세요.

12. 자주 발생하는 문제(계층별 트러블슈팅)

13. 완료 후 체크리스트: 루프 안정 후 확장

• 테스트 OAuth 해제 후, 실제 메일함·저장소를 연동마다 하나씩 추가.
• 워크스페이스·vault·주요 설정 스크린샷 백업; 모델 모드·월 예상 비용 기록.
• 공식 Privacy & Security 읽기; 알림·음성 토글 재검토.
• 삭제 경로 유지: 데이터 저장 위치를 알아 유일한 메모리 라이브러리를 지우지 않기.

7단계 런북 한눈에: 준비 → 공식 설치 → 로그인 → 모델 테스트 → 저위험 연동 1개 → 메모리 대기 → 실전·해제. 그다음 Slack·Notion·장기 워크플로를 붙이세요.