OpenHuman 입문 가이드: OpenClaw보다 더 사용하기 쉬운 오픈소스 AI 어시스턴트

GitHub: https://github.com/tinyhumansai/openhuman

프로젝트 소개

OpenHuman은 오픈소스 개인 AI 초지능(슈퍼 인텔리전트) 어시스턴트로, 핵심 철학은 「AI를 진짜로 일상에 녹여 넣는 것」입니다. OpenClaw와 비교했을 때 OpenHuman의 가장 큰 차이점은 UI 우선 설계예요. 설정 파일을 만지거나 명령어를 칠 필요 없이, 설치부터 동작하는 AI 에이전트를 갖추기까지 딱 몇 번의 클릭만 하면 됩니다.

이 프로젝트에는 눈길을 끄는 특징들이 몇 가지 있습니다:

118+ OAuth 원클릭 통합: Gmail, Notion, GitHub, Slack, Calendar 등 서비스에 대해 한 번의 권한 부여로 바로 사용
메모리 트리 + Obsidian Wiki: 이메일, 문서, 채팅 기록을 자동으로 Markdown으로 압축해 로컬의 SQLite 및 Obsidian 저장소에 보관
TokenJuice 스마트 압축: 각 요청은 LLM에 도달하기 전에 압축 과정을 거쳐 토큰 소모를 최대 80%까지 줄일 수 있음
내장 모델 라우팅: 하나의 구독에서 작업을 자동으로 적합한 모델(추론형, 빠른형, 비전형)에 분배
네이티브 음성 지원: STT 입력, ElevonLabs TTS 출력, 마스코트 립싱크

TIP

OpenClaw를 써본 적이 있다면 OpenHuman이 「손이 덜 가는」 일반 사용자에게 더 잘 맞는다는 걸 느낄 수 있을 거예요. 완성도 높은 ‘아웃오브더박스’ 경험이 상용 제품에 더 가깝습니다.

난이도/소요 시간/얻는 것

난이도: ⭐⭐☆☆☆ (입문급)
소요 시간: 약 15~20분(처음부터 실행까지)
얻는 것: 로컬 설치 및 설정, OAuth 서비스 통합, 메모리 시스템 사용법 익히기

대상 독자

오픈소스 AI 어시스턴트를 써보고 싶지만 터미널 설정을 하고 싶지 않은 개발자
로컬 지식 관리 시스템이 필요한 지식 작업자
OpenClaw에 관심은 있지만 진입장벽이 조금 높다고 느끼는 사용자
AI가 캘린더, 이메일, 문서를 자동으로 동기화해주길 원하는 효율 지향형 사용자

핵심 의존성 및 환경

필수 환경

의존성	버전 요구사항	설명
Node.js	>= 24.0.0	프론트엔드 개발 필수
pnpm	10.10.0	프로젝트 관리 도구
Rust	1.93.0	핵심 런타임
CMake	최신 안정 버전	Rust의 네이티브 의존성
Ninja	최신 안정 버전	macOS CEF 빌드 필수

Windows 추가 의존성

# Visual Studio C++ Build Tools (MSVC v143 및 Windows 11 SDK 포함)
# 설치 시 "Default installation" 선택

# LLVM/Clang (libclang 의존)
# https://github.com/llvm/llvm-project/releases 의 Windows x64 버전 다운로드
# 설치 시 "Add LLVM to system PATH for all users" 체크

# CMake
winget install Kitware.CMake

설치 확인

rustc --version    # 1.93.0 이상으로 표시되어야 함
cargo --version
clang --version
cmake --version
node --version     # v24.x.x 이상으로 표시되어야 함
pnpm --version     # 10.10.0으로 표시되어야 함

전체 프로젝트 구조

openhuman/
├── app/                         # pnpm workspace: openhuman-app
│   ├── src/                     # React 프론트엔드 소스
│   │   ├── components/         # UI 컴포넌트
│   │   ├── services/          # API/RPC 클라이언트
│   │   ├── store/             # Redux 상태 관리
│   │   └── utils/             # 유틸 함수
│   ├── src-tauri/               # Tauri 데스크톱 쉘
│   └── package.json
├── src/                         # Rust 핵심 라이브러리
│   ├── core/                    # 전송 계층 (HTTP/JSON-RPC/CLI)
│   │   ├── jsonrpc.rs           # JSON-RPC 서버
│   │   ├── cli.rs               # 명령줄 인터페이스
│   │   └── event_bus/          # 이벤트 버스
│   └── openhuman/               # 비즈니스 도메인
│       ├── memory/             # 메모리 시스템
│       ├── tokenjuice/         # Token 압축
│       ├── integrations/       # OAuth 통합
│       └── ...
├── scripts/                     # 설치 및 디버깅 스크립트
│   ├── install.sh              # macOS/Linux 원클릭 설치
│   ├── install.ps1            # Windows 원클릭 설치
│   └── load-dotenv.sh          # 환경 변수 로딩
├── gitbooks/                    # 공식 문서
├── Cargo.toml                   # Rust 의존성 설정
└── package.json                 # Node 의존성 설정

단계별 진행

1단계: 원클릭 설치

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash

Windows

irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex

설치 스크립트는 시스템 환경을 자동으로 감지하고, 해당 플랫폼의 바이너리 파일(DMG/EXE)을 다운로드합니다.

2단계: 소스에서 컴파일(선택)

개발에 참여하거나 최신 기능을 사용하고 싶다면:

# 1. 포크 후 레포지토리 클론
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman

# 2. 서브모듈 초기화
git submodule update --init --recursive

# 3. 의존성 설치
pnpm install

# 4. 순수 Web UI 개발
pnpm dev

# 5. 전체 데스크톱 앱 개발
pnpm dev:app

3단계: API Key 설정

환경 변수 템플릿을 복사합니다:

cp .env.example .env

.env 파일을 편집하고 LLM 제공업체를 설정합니다:

# 하나 또는 여러 모델 제공업체 선택

# Claude (권장)
ANTHROPIC_API_KEY=sk-ant-xxxxx

# OpenAI GPT
OPENAI_API_KEY=sk-xxxxx

# Google Gemini
GEMINI_API_KEY=xxxxx

WARNING

API Key는 로컬에 저장되므로 .env 파일을 git 저장소에 커밋하지 않도록 하세요.

3.5단계: Defapi로 비용 절감(권장)

공식 API 가격이 부담된다면 Defapi를 고려해볼 수 있어요. Defapi는 OpenAI v1/chat/completions 프로토콜과 호환되는 중간(프록시) 플랫폼이며, 공식의 절반 수준으로 사용할 수 있습니다.

Defapi는 다음 프로토콜을 지원합니다:

v1/chat/completions 인터페이스（OpenAI 호환）
v1/messages 인터페이스（Anthropic 호환）
v1beta/models/ 모델 목록 인터페이스

구성은 간단합니다. 공식의 API 주소를 Defapi 엔드포인트로 바꾸고, API Key도 Defapi용으로 변경하세요.

# Defapi 구성 예시
ANTHROPIC_API_KEY=dk-xxxxx        # Defapi의 Key (dk- 접두사)
OPENAI_API_KEY=dk-xxxxx

# 또는 base_url 지정(지원되는 경우)
ANTHROPIC_BASE_URL=https://api.defapi.org/v1
OPENAI_BASE_URL=https://api.defapi.org/v1/chat

Defapi에서 지원하는 모델 예시는 다음과 같습니다:

anthropic/claude-sonnet-4.5 / claude-opus-4.5 / claude-haiku-4.5
openai/gpt-4o / gpt-4o-mini / gpt-5
google/gemini-3-flash

TIP

OpenHuman의 내장 TokenJuice 압축 기능과 Defapi의 저가 전략을 함께 쓰면 장기적으로 비용을 꽤 절약할 수 있어요. 모델별 가격은 Defapi 공식 사이트에서 확인하세요.

4단계: OAuth 서비스 통합

앱을 시작한 뒤, 화면에서:

Settings → Integrations로 이동
통합하려는 서비스(Gmail, Notion, GitHub 등)를 클릭
OAuth 권한 부여 절차를 완료

또는 환경 변수로 설정합니다:

# Gmail OAuth
GMAIL_CLIENT_ID=xxxxx
GMAIL_CLIENT_SECRET=xxxxx

# GitHub OAuth
GITHUB_CLIENT_ID=xxxxx
GITHUB_CLIENT_SECRET=xxxxx

5단계: 메모리 시스템 설정

OpenHuman의 메모리 시스템은 데이터를 자동으로 동기화합니다. 핵심 설정 항목:

# 메모리 동기화 간격(기본 20분)
OPENHUMAN_MEMORY_SYNC_INTERVAL=20

# Obsidian 저장소 경로
OPENHUMAN_OBSIDIAN_VAULT_PATH=~/Documents/openhuman-vault

# TokenJuice 압축 수준
OPENHUMAN_TOKENJUICE_COMPRESSION=high

메모리 데이터는 로컬 SQLite에 저장됩니다:

# 기본 저장 경로
~/.openhuman/memory.db

6단계: 실행 및 검증

데스크톱 앱

# macOS
open -a OpenHuman

# Linux
openhuman-app

# Windows
OpenHuman.exe

CLI 모드

# 핵심 서비스 시작
openhuman serve

# 대화형 세션
openhuman run

실행 상태 확인

# 헬스 상태 확인
curl http://127.0.0.1:7788/health

# 핵심 토큰 확인
cat ~/.openhuman/core.token

자주 발생하는 문제 해결

1. 설치 스크립트에서 "command not found" 오류

시스템에 curl과 필요한 네트워크 도구가 설치되어 있는지 확인하세요:

# macOS
brew install curl

# Ubuntu/Debian
sudo apt install curl

# Windows (PowerShell 7+)
scoop install curl

2. 데스크톱 앱 실행 실패

Tauri 환경 의존성을 확인합니다:

# Windows 전용 확인
$env:LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin"
clang -v
cmake --version

Visual Studio Build Tools이 설치되어 있고 "Desktop development with C++" 작업 부하가 포함되어 있는지 확인하세요.

3. OAuth 권한 부여 실패

콜백 URL이 올바르게 설정됐는지 확인:

http://localhost:7788/oauth/callback

OAuth 앱 설정에 이 리디렉션 URI를 추가하세요.

4. 메모리 동기화가 작동하지 않음

다음 순서로 점검:

# 1. 핵심 로그 확인
tail -f ~/.openhuman/logs/core.log

# 2. 동기화 수동 실행
openhuman memory sync

# 3. Obsidian 저장소에 쓰기 가능한지 검증
ls -la ~/Documents/openhuman-vault

5. TokenJuice 압축이 유효하지 않음

압축이 활성화되어 있는지 확인:

# .env에서 설정
OPENHUMAN_TOKENJUICE_ENABLED=true
OPENHUMAN_TOKENJUICE_LEVEL=high

# 핵심 서비스 재시작
openhuman restart

6. 모델 라우팅이 적용되지 않음

모델 구성을 확인합니다:

# 현재 모델 설정 확인
openhuman config show

# 모델을 수동으로 지정
OPENHUMAN_MODEL=claude-sonnet-4-20250514

추가 읽을거리

공식 문서 — 전체 GitBook 문서
아키텍처 설계 — 시스템 아키텍처를 자세히 알아보기
agentmemory 백엔드 — Claude Code/Cursor와 함께 쓰는 메모리
모델 라우팅 설정 — 모델 선택을 최적화하는 방법
자동 가져오기 기능 — 20분 자동 동기화 원리

관련 프로젝트

OpenClaw — 또 다른 인기 있는 오픈소스 AI 에이전트
agentmemory — 공유 메모리 백엔드
Obsidian — 로컬 지식 저장소 도구