OpenHuman 安裝配置指南 2026 | 本地數位人從零跑通保姆級教學

本文目錄

01 · OpenHuman 是什麼，能做什麼

OpenHuman 是 TinyHumans 開發的本地優先、開源 AI 智能體平台，可在 macOS、Windows、Linux 桌面運行。與一般聊天機器人不同，它透過 Memory Tree（本地 SQLite）把郵件、行事曆、Slack 討論串、程式碼倉庫整理成可檢索知識，每次對話都能調用這些脈絡給出精準回覆，而不只依賴單次提示詞。

2026 年版新增會議代理（Meeting Agent）、多模態情境感知與 Obsidian 知識庫連動。對創作者、獨立開發者與研究者而言，它更像持續學習你工作習慣的「數位分身」。關鍵優勢：核心資料預設留在本機，除非你主動設定遠端模型端點，否則不會上傳至雲端伺服器；在禁止雲端推理的企業環境，仍可結合 Memory Tree 與 Ollama 離線推理。

02 · 三大安裝痛點

動手安裝前，先釐清多數新手會踩的三類坑：

依賴版本衝突。 系統內建 Python 2.x/3.8 與 OpenHuman 要求的 3.10+ 不一致；未啟用虛擬環境就 pip install openhuman 常裝到錯誤路徑，連鎖導致依賴全壞。
模型權重下載受阻。 HuggingFace 在部分地區不穩，數 GB 檔案中斷後難續傳；ModelScope 需驗證、百度網盤有頻寬限制——各渠道門檻不同，教程很少說清楚取捨。
GPU 後端搞混。 Windows 上 CUDA 與 PyTorch 版本不匹配；Intel Mac 無 CUDA；Apple Silicon 應走 MPS 而非 CUDA，但網路教程多只寫 NVIDIA 路徑。

本文會逐一解決，並給出各平台可驗證的命令。

03 · 硬體要求與平台對照表

以下是 2026 年官方建議配置與三平台安裝路徑速覽：

項目	最低	建議	備註
OS	macOS 12 / Win 10 / Ubuntu 20.04	macOS 14+ / Win 11 / Ubuntu 22.04	Apple Silicon 需 macOS 13+
記憶體（RAM）	4 GB	16 GB+	大型信箱 + 本地模型建議 16 GB+
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 官網下載		建議搭配 CUDA 12.x

📌 三條硬數據：① 官方最低記憶體 4 GB，本地模型建議 16 GB+；② 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

                        # Verify Git

git --version   # 2.x+

# macOS

brew install git

Apple Silicon / CUDA 說明

使用 macOS Apple Silicon（M1–M4） 時會自動啟用 MPS，無需 CUDA。NVIDIA GPU（Windows/Linux）請先安裝 CUDA Toolkit 12.x，再依 PyTorch 官網選對應 wheel。

05 · 五步安裝流程

第一步：macOS — Homebrew（推薦）

                        # Official tap

brew tap humansai/openhuman

brew install openhuman

# Verify

openhuman --version

Homebrew 會驗證 bottle 並處理依賴，是 macOS 最穩定的安裝方式。完成後從「應用程式」或終端機啟動。建議另建 OpenHuman 專用 venv，避免與系統 Python 混用。

第二步：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 使用者：yay -S openhuman-bin。

第三步：Windows — 簽名 MSI

至 tinyhumans.ai/openhuman 下載簽名 MSI 並執行。GPU 加速請先裝 CUDA 12.x。安裝程式會加入開始功能表並設定背景同步服務。

第四步：首次登入與權限

啟動後以 GitHub/Google 登入。macOS 會要求輔助使用、輸入監控（語音快捷鍵）等權限，可在「系統設定」授予，或於 設定 → 自動化與通道 稍後開啟。

若要完全本地並使用自有 API Key，切換 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"

第五步：連接資料源，等待 Memory Tree 初始化

在 Integrations 面板 以 OAuth 連接 Gmail、GitHub、Slack 等最重要的三個來源。首次完整同步約 20 分鐘——期間請勿關閉應用；之後增量同步通常只需數秒。

若要走本地推理，請從 HuggingFace、ModelScope 或百度網盤取得權重，並在 config 或 Integrations 指定路徑。首次下載可能需 30 分鐘至數小時，與 Memory Tree 約 20 分鐘的首次同步可並行進行。

06 · 首次驗證與報錯速查

完成初始設定後，先送一則簡單測試指令確認回應，並在 Knowledge 面板確認 Memory Tree 已建立，再追加整合。

報錯	原因	處理
ModuleNotFoundError: openhuman	pip 裝到錯誤 Python 環境	啟用虛擬環境後重新安裝
MPS not available	PyTorch 不支援 MPS	安裝 macOS arm64 版 PyTorch 2.0+
Memory DB locked	多實例搶占 SQLite	結束所有 openhuman 行程後重啟
Integration OAuth failed	系統時間不同步	同步時間後重試 OAuth
Ingest timeout	首次接入來源過多	分批連接 Integrations

07 · 進階：本地 AI 與 Web UI

接入 Ollama 離線推理

若要完全離線，將模型後端指向本機 Ollama，編輯 config.toml：

                        [model]

provider = "custom"

base_url = "http://localhost:11434"

model    = "deepseek-r1:14b"

Apple Silicon M4 在 Ollama 跑 14B 量化模型約 18–25 tok/s，日常對話足夠；70B+ 建議 Mac mini M4（64 GB+ 統一記憶體）或 Mac Studio。

Memory Tree 資料庫路徑

macOS: ~/Library/Application Support/openhuman/memory.db
Linux: ~/.local/share/openhuman/memory.db
Windows: %APPDATA%\openhuman\memory.db

可將 Memory Tree 與 Obsidian Vault 關聯，讓 AI 直接讀寫個人筆記——研究與寫作者最愛的整合之一。

若需在同一台租用 Mac 上併跑 OpenClaw，請參考：2026 租用 Mac mini M4 跑 OpenClaw 與 OpenHuman。

08 · 自建硬體的局限：為何租用 Mac 更聰明

用自己的硬體跑 OpenHuman 完全可行，但投入前值得直說幾個摩擦：

一次性硬體成本高。 16 GB Mac mini M4 起價約新台幣兩萬多，512 GB Mac Studio 更高——若只想試幾天，負擔偏大。
與主力機搶資源。 日常 Mac 同時跑 Ollama 與背景同步，常讓瀏覽器、Xcode、設計軟體變慢；專用機器可完全隔離。
Windows/Linux 路徑複雜。 CUDA 版本矩陣、WSL2 相容性、路徑差異讓首次安裝耗時數小時；乾淨 macOS 可避開多數邊界情況。
統一記憶體無法事後擴充。 Apple Silicon 記憶體焊在晶片上，工作負載變大只能整機更換。

相較之下，按天租用 Mac mini M4 或 Mac Studio 可在 MPS 就緒的乾淨 macOS 上低成本驗證完整流程，不污染主力機。確認工作流適合後，再決定長租或自購——這是 2026 年最理性的試用策略。

Web UI 與 API 首次確認

安裝完成後，從終端機執行 openhuman 或從應用程式開啟 Web UI，送出簡單問題（例如「摘要本週未讀 Gmail」）確認助理能回應。若採 Ollama，請先執行 ollama pull deepseek-r1:14b 等指令拉取模型。建議先用雲端 API 確認連線，再切換本地端點，兩段式除錯較省時。

背景同步期間留意選單列進度。純 CPU 環境建議在首輪約 20 分鐘內不要同時跑大型本地模型。Apple Silicon 可在「活動監視器」GPU 分頁觀察 MPS 負載；Windows NVIDIA 使用者請在「工作管理員」確認 CUDA 程序是否啟動。

模型權重三渠道實務比較

HuggingFace 型號最全，跨境或高峰時段可能不穩，可搭配 HF_ENDPOINT 鏡像。ModelScope 在華語地區 CDN 較快，需完成帳號驗證。百度網盤 適合單檔 20GB 以上的檢查點，會員可緩解頻寬限制。下載後請統一 config 路徑與 Integrations 的 Local model 設定，避免指向空目錄。

日誌位於 macOS ~/Library/Logs/openhuman/、Linux ~/.local/state/openhuman/logs/、Windows %LOCALAPPDATA%\openhuman\logs\。OAuth 失敗常見於系統時間不同步、公司代理阻擋 localhost 回呼，或瀏覽器阻擋彈出視窗——請允許本機回呼 URL 完成授權。

與 OpenClaw 雙棧部署不同，本篇僅涵蓋 OpenHuman 單體安裝；驗證通過後再考慮多 Agent 編排與遠端 Mac 節點。

09 · FAQ

沒有 GPU 能跑嗎？

可以。只用雲端 API 時 CPU 模式足夠；Memory Tree 索引不依賴 GPU。本地推理會較慢，約為 M 系列 MPS 的 2–4 倍延遲；以郵件檢索、會議摘要為主的工作流仍可在無 GPU 下使用。

支援 Apple Silicon 嗎？

完全支援。Homebrew 為 arm64 原生編譯，macOS 13+ 自動啟用 MPS，效能遠優於 Rosetta 2。Intel Mac 建議以雲端 API 或 CPU 模式為主。

模型下載太慢怎麼辦？

建議順序：① ModelScope；② HuggingFace（HF_ENDPOINT=https://hf-mirror.com）；③ 百度網盤（超大檔、會員可緩解頻寬）。

如何更新？

macOS：brew upgrade openhuman；Linux：sudo apt-get install --only-upgrade openhuman；Windows 覆蓋安裝 MSI，設定與資料庫會保留。

商用需要授權嗎？

核心為 MIT 類開源，個人免費。商用或數十人規模部署請查 tinyhumans.ai 最新條款；部分雲端 API 與企業支援可能另計授權。

更多本地 Agent 可參考：2026 Hermes Agent 安裝部署教學。