OpenHuman 설치 실패？2026년 완전 오류 해결 가이드（Mac / Windows / Docker / Node.js）

OpenHuman은 "로컬 우선, 장기 기억 기반 개인 AI 에이전트"라는 콘셉트로 2026년 초 주목을 받았지만, 프로젝트는 여전히 Early Beta 단계입니다. Rust + TypeScript 듀얼 스택 빌드, 시스템 수준의 의존성, 플랫폼별 권한 모델의 차이로 인해 첫 번째 단계에서 막히는 경우가 많습니다. 이 가이드는 4개 플랫폼에서 가장 자주 발생하는 오류 시나리오를 체계적으로 정리하고, 각 오류에 대해 바로 실행 가능한 수정 명령어를 제공합니다.

빠른 참조

• Mac（Apple Silicon / Intel）：Gatekeeper 차단, Rust 툴체인 누락, Xcode CLT 버전 충돌
• Windows：경로 공백 및 비ASCII 문자, WSL2 커널 버전 미달, MSVC와 GNU 툴체인 혼용
• Docker：이미지 풀 타임아웃, arm64/amd64 아키텍처 불일치, 볼륨 권한 오류
• Node.js：버전 불일치, 네이티브 모듈 리빌드 실패, pnpm/npm 의존성 충돌

1. Mac 문제 해결（Apple Silicon & Intel）

1.1 오류：“openhuman” cannot be opened because the developer cannot be verified

macOS Gatekeeper가 Apple의 공증(Notarized)을 받지 않은 바이너리를 차단하고 있습니다.

수정 방법 A（권장 — 해당 파일만 허용）：

# 터미널에서 격리 속성을 한 번에 제거하면 이후 더블클릭으로 정상 실행됩니다
xattr -dr com.apple.quarantine /Applications/OpenHuman.app

수정 방법 B（시스템 설정에서 허용）：「시스템 설정 → 개인 정보 보호 및 보안」을 열고 하단에서 차단된 앱을 찾아 「그래도 열기」를 클릭합니다.

1.2 오류：error: linker `cc` not found

Rust 컴파일러가 C 링커를 찾을 수 없습니다. 보통 Xcode Command Line Tools가 설치되지 않았거나 버전이 오래된 경우입니다.

# Xcode CLT 설치（약 2 GB, 최초 설치 시 네트워크 필요）
xcode-select --install

# 이미 설치되어 있지만 오류가 계속되면 경로 재설정
sudo xcode-select --reset

# 버전 확인
xcode-select -p
# 출력은 /Library/Developer/CommandLineTools 또는 /Applications/Xcode.app/... 여야 합니다

1.3 오류：rustup: command not found 또는 Rust 버전이 너무 오래됨

OpenHuman의 Rust 코어는 보통 stable ≥ 1.78을 요구합니다。

# rustup 설치（이미 설치된 경우 건너뜀）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 셸 환경 다시 로드
source "$HOME/.cargo/env"

# 최신 stable로 업데이트
rustup update stable

# 저장소에서 요구하는 버전으로 전환（rust-toolchain.toml이 있으면 자동 적용）
rustup show

1.4 오류：Apple Silicon에서 architecture arm64 is not compatible

일부 npm 네이티브 의존성이나 시스템 라이브러리가 arm64 빌드를 제공하지 않거나, Rosetta 버전과 네이티브 버전의 Homebrew가 동시에 설치된 경우 발생합니다.

# 현재 셸 아키텍처 확인
uname -m  # arm64 출력 확인（M 시리즈 칩 네이티브 셸）

# Homebrew 경로 확인（arm64 네이티브 버전은 /opt/homebrew 여야 함）
which brew

# brew가 /usr/local（Rosetta）을 가리키면 arm64 셸로 전환 후 의존성 설치
arch -arm64 /bin/zsh
arch -arm64 brew install openssl pkg-config

1.5 오류：error: failed to run custom build command for `ring`

ring 크레이트는 Clang/LLVM이 필요하며 Mac에서는 OpenSSL 경로를 명시해야 합니다.

# Homebrew로 OpenSSL 3 설치
brew install openssl@3

# 빌드 환경 변수 임시 설정（~/.zshrc에 추가해도 됩니다）
export OPENSSL_DIR="$(brew --prefix openssl@3)"
export OPENSSL_NO_VENDOR=1

# 다시 빌드
cargo build --release

2. Windows 문제 해결

2.1 오류：경로에 공백 또는 비ASCII 문자로 인한 빌드 실패

Cargo와 일부 npm 네이티브 모듈은 경로의 공백이나 비ASCII 문자에 대한 내성이 매우 낮습니다.

:: 공백 없는 순수 ASCII 경로에 저장소를 클론하세요（예시）
git clone https://github.com/tinyhumansai/openhuman C:\dev\openhuman

:: Cargo 캐시 디렉터리도 안전한 경로로 이동（PowerShell에서 실행）
[System.Environment]::SetEnvironmentVariable("CARGO_HOME","C:\dev\.cargo","User")
[System.Environment]::SetEnvironmentVariable("RUSTUP_HOME","C:\dev\.rustup","User")

2.2 오류：LINK : fatal error LNK1181

MSVC 툴체인이 누락되었거나 올바르게 구성되지 않았습니다.

:: 1. Visual Studio 2022 Build Tools（또는 전체 VS 2022）설치
::    필수 구성 요소：「C++을 사용한 데스크톱 개발」→ MSVC v143 + Windows SDK

:: 2. Rust를 MSVC 대상으로 전환
rustup default stable-x86_64-pc-windows-msvc
rustup target add x86_64-pc-windows-msvc

:: 3. 링커를 찾을 수 있는지 확인
where link
:: 출력 예：C:\Program Files (x86)\Microsoft Visual Studio\...\link.exe

2.3 오류：WSL2 커널 버전 미달

WSL2에서 OpenHuman을 실행하는 경우 커널 버전이 ≥ 5.15여야 합니다.

:: PowerShell（관리자）에서 WSL 커널 업데이트
wsl --update

:: 버전 확인
wsl --version

:: 대상 배포판을 WSL2 모드로 설정
wsl --set-version Ubuntu-22.04 2

2.4 오류：'python' is not recognized

일부 npm 네이티브 모듈의 빌드 스크립트가 python 명령어에 의존합니다.

:: 방법 A：python-is-python3 설치（WSL2 Ubuntu）
sudo apt install python-is-python3

:: 방법 B：Windows 네이티브 — npm 전역 설정으로 python3 지정
npm config set python python3

:: 방법 C：windows-build-tools 설치（지원 종료, VS Build Tools 권장）
:: 더 이상 권장하지 않음, 참고용

2.5 오류：error MSB8036: The Windows SDK version X was not found

:: Visual Studio Installer 열기 → 수정 → 개별 구성 요소
:: 해당 Windows SDK（10.0.22621 이상 권장）체크 후 설치
:: 설치 완료 후 터미널 재시작 후 빌드

3. Docker 문제 해결

3.1 오류：pull access denied 또는 풀 타임아웃

GitHub Container Registry 또는 Docker Hub가 일부 지역에서 제한됩니다.

# 방법 A：미러 레지스트리 구성（Docker Desktop → Settings → Docker Engine에서 편집）
# 아래 JSON 필드 추가：
# "registry-mirrors": ["https://mirror.gcr.io","https://docker.mirrors.ustc.edu.cn"]

# 방법 B：네트워크 접근이 가능한 머신에서 이미지를 내보내고 대상 머신으로 전송
docker save ghcr.io/tinyhumansai/openhuman:latest | gzip > openhuman.tar.gz
# 대상 머신에서 임포트
gunzip -c openhuman.tar.gz | docker load

3.2 오류：플랫폼 불일치（linux/amd64 vs linux/arm64）

Apple Silicon Mac에서 공식 AMD64 이미지를 사용할 때 발생합니다.

# 플랫폼을 명시하여 풀（Rosetta 에뮬레이션 발생, 성능 저하 있음）
docker pull --platform linux/amd64 ghcr.io/tinyhumansai/openhuman:latest

# 공식 arm64 이미지가 있다면 네이티브 이미지 우선 사용
docker pull --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

# 실행 시 플랫폼 지정
docker run --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

3.3 오류：permission denied — 컨테이너가 볼륨에 쓸 수 없음

컨테이너 프로세스가 비루트 사용자로 실행되지만 마운트된 호스트 디렉토리가 루트 소유입니다.

# 방법 A：컨테이너 내 사용자（uid 보통 1000）에게 호스트 디렉터리 권한 부여
sudo chown -R 1000:1000 ./openhuman-data

# 방법 B：docker run 시 root로 실행（개발 환경 전용, 운영 환경 비권장）
docker run --user root ...

# 방법 C：Docker Compose에서 user 지정
# services:
#   openhuman:
#     user: "1000:1000"
#     volumes:
#       - ./openhuman-data:/app/data

3.4 오류：exec: "sh": executable file not found

이미지가 distroless 또는 scratch 베이스를 사용하여 셸이 없습니다.

# 전체 bash 경로로 컨테이너 진입（존재하는 경우）
docker exec -it openhuman /bin/bash

# 이미지에 셸이 없는 경우 디버그 이미지 빌드 후 원본 데이터 볼륨 마운트하여 점검
docker build -f Dockerfile.debug -t openhuman-debug .
docker run -it --volumes-from openhuman openhuman-debug /bin/bash

3.5 Docker Compose：dependency failed to start

OpenHuman이 의존하는 DB나 벡터 인덱스 서비스가 느리게 시작되어 헬스 체크가 실패합니다.

# compose.yml의 의존 서비스에 healthcheck 추가
# services:
#   db:
#     healthcheck:
#       test: ["CMD", "pg_isready", "-U", "openhuman"]
#       interval: 5s
#       retries: 10
#   openhuman:
#     depends_on:
#       db:
#         condition: service_healthy

# 각 서비스 로그를 직접 확인하여 근본 원인 파악
docker compose logs --tail=50 db
docker compose logs --tail=50 openhuman

4. Node.js 문제 해결

4.1 오류：The engine "node" is incompatible with this module

OpenHuman의 프론트엔드와 플러그인 레이어는 보통 Node.js ≥ 20 LTS를 요구합니다.

# nvm으로 지정 버전 전환（LTS 20 또는 22 권장）
nvm install 20
nvm use 20
node --version  # v20.x.x 출력 확인

# fnm（더 빠른 버전 관리자）사용 시
fnm install 20
fnm use 20

4.2 오류：gyp ERR! build error — 네이티브 모듈 빌드 실패

의존성에는 네이티브 C++ 애드온이 포함되어 있어 완전한 빌드 툴체인이 필요합니다.

# macOS：Xcode CLT 설치 확인
xcode-select --install

# Windows：PowerShell（관리자）에서 node-gyp 전역 설치
npm install -g node-gyp
# Visual Studio Build Tools도 설치되어 있어야 합니다（2.2절 참고）

# Linux（Ubuntu/Debian）
sudo apt-get install -y python3 make g++

# 모든 네이티브 모듈 강제 재빌드
npm rebuild
# 또는 pnpm 사용
pnpm rebuild

4.3 오류：Cannot find module ERR_MODULE_NOT_FOUND

의존성 설치가 불완전하거나 node_modules 캐시가 lockfile과 일치하지 않습니다.

# 완전히 정리 후 재설치
rm -rf node_modules
rm package-lock.json   # 또는 pnpm-lock.yaml / yarn.lock

# 프로젝트의 패키지 매니저로 재설치（pnpm 예시）
corepack enable
pnpm install --frozen-lockfile

4.4 오류：ENOSPC: System limit for number of file watchers reached

Linux의 기본 inotify 감시자 한도가 부족합니다.

# 일시적으로 증가（재시작 후 초기화）
sudo sysctl fs.inotify.max_user_watches=524288

# 설정 영구 적용
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

4.5 오류：EACCES: permission denied, mkdir '.../.npm'

npm 전역 디렉토리 권한 문제입니다.

# npm 전역 디렉터리를 사용자 쓰기 가능 경로로 변경
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# 위 export 명령을 ~/.zshrc 또는 ~/.bashrc에 추가하여 영구 적용

5. 공통 문제 해결 체크리스트

어느 플랫폼이든 막혔을 때는 먼저 이 순서대로 확인하세요：

순서	확인 항목	빠른 확인 명령어
①	GitHub 등에 네트워크 접근 가능 여부	curl -I https://github.com
②	Git 버전 ≥ 2.40	git --version
③	Rust stable 툴체인이 저장소 요구사항과 일치하는지	rustup show
④	Node.js ≥ 20 LTS	node --version
⑤	디스크 여유 공간 ≥ 8 GB	df -h .
⑥	rust-toolchain.toml과 .nvmrc의 버전 요구사항 확인	cat rust-toolchain.toml && cat .nvmrc
⑦	완전한 오류 로그 캡처	cargo build 2>&1 | tee build.log

6. 여전히 해결되지 않나요? 다음 단계

• 공식 이슈 트래커 검색：GitHub Issues에서 오류 키워드로 검색하세요.
• 상세한 이슈 제출：cargo build 2>&1 | head -100의 출력과 시스템 환경 정보를 포함하세요.
• Docker로 전환：네이티브 설치가 계속 실패하는 경우, Docker 컨테이너가 환경 차이를 우회하는 가장 빠른 방법입니다.
• 추론 백엔드 외부화：로컬 컴퓨팅 자원이 부족한 경우, OpenHuman의 모델 엔드포인트를 원격 Ollama 인스턴스로 향하게 할 수 있습니다.

OpenHuman을 원격 Mac 노드와 연계하는 방법은 OpenHuman 20분 지식베이스 구축 글도 참고하세요.

7. 결론

OpenHuman 설치 문제의 90%는 세 가지 근본 원인으로 요약됩니다：빌드 툴체인 불완전, 런타임 버전 불일치, 플랫폼 권한 또는 네트워크 제한. 이 가이드를 순서대로 따라가면 대부분의 문제를 30분 내에 해결할 수 있습니다.

환경 설정에 시간을 쏟고 싶지 않다면 Docker가 가장 빠른 출발점입니다. 성능 최적화와 완전한 로컬화를 원한다면 Rust 툴체인을 제대로 설정하고 유니파이드 메모리가 충분한 Apple Silicon 머신을 선택하세요.