2026 OpenHuman 완전 설치 가이드
로컬 AI 아바타를 제로부터 구축
대상：OpenHuman을 처음 설치하려는 개발자·크리에이터로, Python 의존성·모델 가중치·GPU 백엔드가 헷갈리는 분입니다. 결론：OS별 공식 경로로 설치하고 Memory Tree 초기 동기화와 Web UI 응답으로 검증합니다. 구성：3대 병목, 하드웨어 표, 7단계, 오류 표, Ollama 연동, Mac 일일 임대 전환입니다.
목차
01 · OpenHuman이란 무엇인가
OpenHuman은 TinyHumans가 만든 로컬 우선 오픈소스 AI 에이전트 플랫폼으로 macOS·Windows·Linux 데스크톱에서 동작합니다. 일반 챗봇과 달리 이메일·캘린더·Slack·코드 저장소를 Memory Tree(로컬 SQLite)로 구조화해 쌓고, 대화마다 그 맥락을 불러 맞춤 응답을 제공합니다.
2026년 버전에는 Meeting Agent, 멀티모달 맥락 인식, Obsidian Vault 연동이 추가되었습니다. 개발자·연구자·크리에이터에게는 도구를 넘어 작업 패턴을 계속 학습하는 ‘디지털 분신’에 가깝습니다. 핵심은 데이터가 기본적으로 내 기기에만 남는다는 점—호스팅 모델 API를 직접 설정하지 않는 한 원격 서버로 가지 않습니다.
02 · 설치 시 흔한 세 가지 문제
단계별 설치에 들어가기 전, 첫 설치에서 자주 막히는 세 패턴을 짚습니다.
- Python 버전 충돌. macOS에 시스템 Python 2.7/3.8이 남아 있는데 가상환경 없이
pip install openhuman을 하면 잘못된 인터프리터에 의존성이 깔립니다. OpenHuman은 Python 3.10+가 필수입니다. - 모델 가중치 다운로드 실패. HuggingFace는 지역·회선에 따라 느리거나 차단되고, 수 GB 파일은 재개가 어렵습니다. ModelScope는 인증, 바이두网盘는 무료 대역 제한—채널마다 마찰이 있고 튜토리얼은 트레이드오프를 잘 설명하지 않습니다.
- GPU 백엔드 혼동. Windows에서 CUDA·PyTorch 조합을 틀리는 경우가 많고, Intel Mac에는 CUDA가 없습니다. Apple Silicon은 MPS가 정답인데 온라인 글은 대부분 CUDA만 다룹니다.
이 가이드는 세 문제 모두에 OS별 검증된 명령 순서를 제공합니다.
03 · 하드웨어 요구사항·플랫폼 표
아래 표는 2026년 OpenHuman 공식 권장 사양과 세 OS 설치 경로 요약입니다. 로컬 LLM을 쓸 계획이라면 RAM·디스크 열을 먼저 확인하세요.
| 항목 | 최소 | 권장 | 비고 |
|---|---|---|---|
| OS | macOS 12 / Win 10 / Ubuntu 20.04 | macOS 14+ / Win 11 / Ubuntu 22.04 | Apple Silicon은 macOS 13+ |
| RAM | 4 GB | 16 GB+ | 대용량 메일+로컬 LLM |
| GPU | 없음(CPU) | NVIDIA RTX / Apple M | 추론 속도 차 약 5–10배 |
| 저장공간 | 10 GB | 50 GB+ SSD | Memory Tree는 데이터에 따라 증가 |
| macOS | Homebrew brew install openhuman | Homebrew가 서명 검증 처리 | |
| Linux 설치 | apt 서명 apt 또는 AUR | Ubuntu 20.04 LTS+ | |
| Windows 설치 | MSI 서명 MSI | GPU 사용 시 CUDA 12.x | |
📌 세 가지 하드 데이터: ① 공식 최소 RAM 4GB, 로컬 모델 병행은 16GB+; ② Memory Tree 첫 전체 동기화 약 20분; ③ Apple Silicon MPS는 순 CPU 대비 약 5–8배 빠른 편입니다.
04 · 환경 준비
Python 버전 관리
OpenHuman은 Python 3.10 이상이 필요합니다. pyenv나 conda로 시스템 Python과 분리하세요.
# Verify Python
python3 --version # 3.10+
# macOS: pyenv
brew install pyenv
pyenv install 3.11.9 && pyenv global 3.11.9
# venv
python3 -m venv openhuman_env
source openhuman_env/bin/activate # Linux/macOS
openhuman_env\Scripts\activate # Windows
Git 설치 확인
# Git 버전 확인
git --version # 2.x+
# macOS
brew install git
GPU 백엔드 참고
Apple Silicon(M1–M4)에서는 MPS가 자동 활성화됩니다. CUDA 설치 불필요. NVIDIA GPU(Windows/Linux)는 CUDA Toolkit 12.x와 pytorch.org 대응 빌드를 먼저 설치하세요.
NVIDIA 사용자는 CUDA 12.x와 pytorch.org의 일치 wheel을 먼저 설치하세요. CUDA·PyTorch 불일치가 가장 흔한 GPU 오류 원인입니다.
05 · 5단계 설치 절차
1단계 — macOS: Homebrew(권장)
# Official tap
brew tap humansai/openhuman
brew install openhuman
# Verify
openhuman --version
Homebrew가 bottle 해시·의존성을 처리합니다. 설치 후 응용 프로그램 또는 터미널에서 실행하세요.
2단계 — Linux: 서명 apt 저장소
sudo apt-get install -y 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 Linux: yay -S openhuman-bin
3단계 — Windows: 서명 MSI
tinyhumans.ai/openhuman에서 MSI를 받아 실행합니다. GPU 가속은 CUDA 12.x를 먼저 설치하세요. 설치 프로그램이 시작 메뉴·백그라운드 동기 서비스를 설정합니다.
4단계 — 첫 로그인·권한
첫 실행 시 GitHub 또는 Google로 제품 로그인을 완료합니다. 이 단계는 Gmail·Slack 등 Integration OAuth와 별개입니다. macOS는 접근성·입력 모니터링(음성 단축키)·선택적 카메라/마이크(회의 에이전트) 권한을 요청합니다.
완전 셀프호스트·자체 API 키는 Custom / Local 모드로 전환 후 설정 파일을 편집합니다.
# macOS: ~/Library/Application Support/openhuman/config.toml
[model]
provider = "custom"
base_url = "https://api.deepseek.com"
api_key = "<YOUR_API_KEY>"
[memory]
backend = "local"
5단계 — 데이터 소스 연결·Memory Tree 초기화
Integrations 패널에서 Gmail·GitHub·Slack 등 우선 3개를 OAuth로 연결하고 백그라운드 첫 동기화를 기다립니다. 첫 전체 동기화는 약 20분—ingest 중 앱을 끄지 마세요. 이후 증분 동기화는 보통 수 초입니다.
로컬 추론을 쓰려면 HuggingFace·ModelScope·바이두网盘 중 한 채널에서 체크포인트를 받아 config 또는 Integrations에 경로를 지정하세요. 첫 다운로드는 30분~수 시간 걸릴 수 있으나 Memory Tree 20분 동기화와 병행 가능합니다.
06 · 첫 실행 검증·오류 표
Web UI 또는 API로 테스트 프롬프트를 보낸 뒤, Knowledge 패널에 Memory Tree 노드가 채워졌는지 확인하세요. 응답이 없으면 config.toml의 model provider와 API 키(또는 Ollama 엔드포인트)를 먼저 점검합니다.
| 오류 | 원인 | 조치 |
|---|---|---|
| ModuleNotFoundError: openhuman | pip가 다른 Python 환경에 설치 | venv 활성화 후 재설치 |
| MPS not available | PyTorch가 MPS 미지원 | macOS arm64용 PyTorch 2.0+ 설치 |
| Memory DB locked | 다중 인스턴스가 SQLite 경합 | openhuman 프로세스 종료 후 재시작 |
| Integration OAuth failed | 시스템 시각 불일치 | 시각 동기화 후 OAuth 재시도 |
| Ingest timeout | 첫 실행에 소스 과다 | Integration 단계적 추가 |
07 · 고급: 로컬 AI·Web UI
Ollama로 완전 오프라인
완전 오프라인·프라이버시 우선이라면 Ollama를 먼저 설치·모델 pull 후 OpenHuman의 model backend를 localhost:11434로 지정합니다.
[model]
provider = "custom"
base_url = "http://localhost:11434"
model = "deepseek-r1:14b"
Apple Silicon M4에서 14B 양자화 모델은 Ollama 기준 약 18–25 tok/s—일상 대화에 충분합니다. 70B급은 64GB+ 통합 메모리 Mac mini M4 또는 Mac Studio를 고려하세요.
Memory DB 경로
- macOS:
~/Library/Application Support/openhuman/memory.db - Linux:
~/.local/share/openhuman/memory.db - Windows:
%APPDATA%\openhuman\memory.db
Obsidian Vault와 Memory Tree를 연결하면 개인 지식 노트를 AI가 직접 읽고 씁니다. 연구자·작가에게 인기 있는 연동입니다.
한 대의 임대 Mac에서 OpenClaw와 함께 쓰려면 2026 OpenClaw & OpenHuman on 임대 Mac mini M4를 참고하세요.
08 · 자체 하드웨어의 한계: Mac 임대가 나은 이유
자체 장비로 OpenHuman을 돌리는 것은 가능하지만, 결정 전 알아둘 마찰이 있습니다.
- 초기 하드웨어 비용. 16GB Mac mini M4는 약 80만 원대, 512GB Mac Studio는 수천만 원—며칠 체험만 하려면 부담이 큽니다.
- 주력 PC 리소스 경합. 일상 Mac에서 Ollama+백그라운드 동기화를 돌리면 브라우저·Xcode·디자인 툴이 버벅입니다. 전용 머신이면 충돌을 피합니다.
- Windows/Linux 경로·의존성 복잡도. CUDA 매트릭스, WSL2 호환, 경로 구분자 차이로 첫 설치에 수시간—깨끗한 macOS가 엣지 케이스를 줄입니다.
- 통합 메모리는 증설 불가. Apple Silicon은 RAM이 SoC에 실장되어 워크로드가 커지면 본체 교체가 필요합니다.
일 단위 Mac mini M4/Mac Studio 임대로 MPS 가능한 깨끗한 macOS에서 전체 워크플로를 저비용 검증할 수 있습니다. 주력기를 오염시키지 않고, 확신이 서면 장기 임대·구매를 결정하세요.
Web UI·API 첫 확인
설치 후 터미널 openhuman 또는 앱 아이콘으로 Web UI를 열고, 간단한 질문(예: 연결된 Gmail 미읽음 요약)으로 응답을 확인하세요. Ollama 모드는 ollama pull 후 테스트하는 것이 안전합니다.
먼저 클라우드 API로 응답을 확인한 뒤 Ollama로 전환하는 2단계 디버깅이 시간을 절약합니다. Windows NVIDIA는 작업 관리자에서 CUDA 프로세스를 확인하세요.
백그라운드 동기화 중 메뉴 막대 진행 표시를 확인하세요. CPU 전용 환경에서는 첫 20분 동안 무거운 로컬 모델을 동시에 돌리지 않는 것이 좋습니다. Apple Silicon에서는 Activity Monitor GPU 탭에서 MPS 부하를 볼 수 있습니다.
모델 가중치 3채널 비교
HuggingFace 카탈로그가 가장 넓지만 회선에 따라 느립니다. ModelScope는 아시아 CDN에서 대용량이 안정적입니다. 바이두网盘는 초대형 단일 파일에 유리합니다. 다운로드 후 config 경로와 Integrations의 Local model 설정을 일치시키세요.
로그는 macOS ~/Library/Logs/openhuman/, Linux ~/.local/state/openhuman/logs/. OAuth 실패는 시각 동기화·회사 프록시의 localhost 콜백 차단을 의심하세요.
09 · FAQ
GPU 없이 실행할 수 있나요?
네. OpenAI·DeepSeek 등 클라우드 API만 쓰면 CPU 모드로 충분합니다. Memory Tree 인덱싱은 GPU 비의존입니다. 로컬 추론만 느려지며 MPS 대비 2–4배 정도 느릴 수 있습니다.
Apple Silicon 네이티브 지원인가요?
예. Homebrew bottle은 arm64 네이티브이고 macOS 13+에서 MPS가 자동 활성화됩니다. Rosetta 2보다 훨씬 빠릅니다.
모델 가중치가 너무 느릴 때는?
우선순위: ① ModelScope(국내 CDN); ② HuggingFace + HF_ENDPOINT=https://hf-mirror.com; ③ 바이두网盘(초대용량·회원 시 대역 완화). 다운로드 중단 시 같은 채널에서 resume 가능한 CLI(huggingface-cli, modelscope) 사용을 권장합니다.
업데이트 방법은?
macOS: brew upgrade openhuman. Linux: sudo apt-get install --only-upgrade openhuman. Windows: 새 MSI로 덮어쓰기—설정·DB 유지.
상업적 이용은 무료인가요?
코어는 MIT 계열로 개인 이용 무료입니다. 상업 배포는 tinyhumans.ai 최신 약관을 확인하세요. 호스팅 API는 별도 라이선스일 수 있습니다.