2026 OpenHuman 全網最完整安裝與配置指南：從 0 到跑通的保姆教程

2. 別裝錯：OpenHuman 桌面助手和 OpenHuman WebGL SDK 的區別

OpenHuman（本文主角）是 tinyhumansai/openhuman 開源的桌面個人 AI 助手：UI 優先、Memory Tree、Obsidian 風格 Markdown vault、118+ OAuth 整合、可選本地 Ollama。預設仍會使用 OpenHuman 託管服務完成帳號登入、模型路由、搜尋代理，以及經 Composio 層的整合 OAuth（可在設定裡逐步切到 BYOK / 直連 Composio）。

網上另有同名或相近的 OpenHuman WebGL 數字人 SDK——面向網頁 3D 角色渲染，不是本文安裝物件。若你的目標是「個人知識庫 + 郵件/日曆/倉庫上下文」，請認準 GitHub 上的 openhuman 桌面倉庫與 tinyhumans.ai/openhuman 下載頁。

它和「普通網頁聊天」也不同：OpenHuman 強調本地工作流資料 + 定時拉取整合，而不是單次對話視窗。和純 CLI Agent（如部分終端優先工具）相比，OpenHuman 走圖形介面 + 短引導，不要求你先寫配置檔案才能說話。

3. 痛點拆解

1. 限制：把「安裝完成」當成「已經懂我」。官方明確：Memory Tree、Markdown vault、工作區配置和本地執行狀態在本機；但登入、模型路由、搜尋代理和預設 OAuth 仍可能走託管後端。沒連整合、沒等 sync，Agent 只能泛泛而談。
2. 隱性成本：權限開太大、一上來接生產帳號。OAuth 一次授權可能覆蓋郵件讀、日曆、倉庫等。應用還在 Beta，應用先用測試信箱或測試 GitHub 倉庫，確認範圍和撤銷入口，再接入真實工作資料。
3. 穩定性與審計：裝完不知道記憶存在哪、日誌在哪。出問題就解除安裝重灌，反而丟掉 SQLite 與 vault 裡唯一的同步線索。應記錄工作區路徑、整合 ID、模型模式（託管 / BYOK / Ollama），便於回滾。

4. 安裝前準備清單

目的：裝一半才發現網路或磁碟不夠，會浪費大量排查時間。通過標準：下面清單全部打勾後再下載安裝包。

• 系統：macOS（Apple Silicon 或 Intel）、Windows 10/11（64 位）、Debian/Ubuntu 或 Arch 等 Linux 桌面。具體最低版本以當時 Release 說明為準；產品標註 Early Beta，介面與路徑可能隨版本變化。
• 硬體：建議 16GB+ 記憶體（本地 Ollama 時更吃記憶體）；磁碟預留 ≥ 5GB（應用 + vault + SQLite + 模型快取，實際以使用為準）。
• 網路：能訪問 GitHub、tinyhumans.ai 與 OAuth 跳轉域名；公司代理需提前配置系統代理或允許瀏覽器彈窗。
• 帳號：OpenHuman 產品帳號；若走 BYOK，準備各模型廠商 API Key；若用 Ollama，先本機安裝並拉取模型。
• 測試資料：單獨註冊測試 Gmail / 測試 GitHub 倉庫，不要首次就連公司 Slack 或生產信箱。
• 權限：macOS 首次可能要求通知、麥克風（語音）、檔案/資料夾訪問；Linux 注意 AppImage 在 Wayland 下的已知問題（見官方 issue #2463）。

5. 下載來源與安全校驗

官方推薦優先順序（README）：① 官網 / GitHub Release 安裝包 → ② 原生包管理器（Homebrew、簽名 apt、MSI）→ ③ 指令碼安裝（無獨立簽名校驗，僅在你理解風險時使用）。

失敗先看：檔案損壞 → 重新從 Release 下載；SmartScreen / Gatekeeper 攔截 → 確認發布者後允許；不要用來歷不明的「加速映象」替代官方包。

6. 三平台安裝步驟

6.1 macOS（推薦 Homebrew）

brew tap tinyhumansai/core
brew install openhuman

也可從 Release 下載 .dmg 拖入應用程式資料夾。通過標準：Launchpad 能開啟 OpenHuman。失敗先看：「無法驗證開發者」→ 系統設定 → 隱私與安全性 → 仍要開啟；首次需允許通知/麥克風/檔案訪問（按你是否使用語音與本地資料夾功能勾選，最小集）。

6.2 Windows（簽名 MSI）

從 latest 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 環境可能啟動失敗（官方 issue #2463）；Debian/Ubuntu 優先用 .deb / apt。通過標準：桌面選單能啟動。失敗先看：依賴庫、Wayland 環境變數、改用 X11 會話。

6.4 平台安裝方式對比（決策矩陣）

解除安裝與重灌：先斷開所有 OAuth 整合並匯出你關心的 vault 目錄備份；解除安裝應用後，工作區與 SQLite 可能仍留在使用者目錄——重灌前確認官方文件中的資料路徑，避免誤刪唯一記憶副本。

7. 首次啟動與帳號登入

1. 啟動應用，按引導選擇工作區（workspace）位置——建議專用目錄，不要直接指向整個使用者主目錄。
2. 使用 OpenHuman 產品帳號登入（預設走託管登入流程）。通過標準：設定頁顯示已登入。
3. 檢查更新通道與隱私相關開關（通知、語音、搜尋代理等），先保持預設，跑通後再細調。

失敗先看：登入頁白屏 → 換預設瀏覽器、關廣告攔截；反覆失敗 → 核對系統時間、DNS、是否需代理；地區或訂閱策略以官方當前說明為準，本文不承諾所有地區功能一致。

8. 模型配置與 BYOK

託管模型（預設）：OpenHuman 後端做 model routing（為不同任務選推理/快速/視覺等模型），官方表述為訂閱內包含多模型路由，具體定價與額度以賬戶頁為準，會變動。

BYOK（Bring Your Own Key，自帶金鑰）：在設定中填入各廠商 API Key，由你承擔呼叫成本與配額；適合已有企業合約或想精細控費的團隊。

本地模型（Ollama）：官方文件支援可選本地 AI；Apple Silicon Mac 上統一記憶體對中小模型更友好，但大模型仍受記憶體上限約束，需自行驗證延遲與質量。

通過標準：傳送一句測試問題（如「用一句話介紹你自己」）得到連貫回覆。失敗先看：託管 → 訂閱/網路；BYOK → Key 權限與賬單；Ollama → 服務是否監聽、模型名是否匹配。

9. 整合與權限配置

OpenHuman 透過 Composio 聯結器層 提供 Gmail、Slack、Notion、GitHub、Calendar、Drive 等 118+ 整合。預設 OAuth 握手與工具呼叫經託管後端代理；若你要直連 Composio，需在設定中配置自己的 Composio API Key，並自行承擔即時 trigger webhook 的託管。

OAuth 是「用瀏覽器登入第三方並授權應用代表你訪問部分資料」的標準流程。授權頁務必閱讀權限範圍：只勾選跑通案例所需的最小權限；看不懂的 scope 先不要同意。

通過標準：整合狀態為已連接，且瀏覽器 OAuth 回調無報錯。失敗先看：彈窗被攔、公司 SSO、Composio 狀態、網路代理。

10. 記憶系統怎麼驗收

新手可這樣理解 OpenHuman 記憶流水線：

• Memory Tree（記憶樹）：把整合拉取的資料整理成層次化摘要，存在本機 SQLite，便於 Agent 檢索。
• Markdown vault（Obsidian 相容庫）：同一份知識還會落成 .md 檔案，可用 Obsidian 開啟瀏覽編輯。
• auto-fetch：對每個活躍連接約 每 20 分鐘 拉取一次新資料（無需你手寫輪詢指令碼）。

驗收步驟：連接測試整合 → 等待至少一輪 20 分鐘同步（或按 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 後 Agent 不再引用該信箱。

通過標準：輸出與測試郵件一致、來源可核對、撤銷後不再訪問。失敗先看：模型層（④）還是記憶層（⑥），不要混查。

12. 常見問題排查（按層）

13. 完成後清單：跑通後再擴展

• 撤銷測試 OAuth，再按需接入真實信箱/倉庫，每次只加一個整合。
• 備份工作區、vault 目錄與關鍵設定截圖；記錄當前模型模式與大致月費。
• 閱讀官方 隱私與安全 頁面，複查通知與語音開關。
• 保留解除安裝路徑：知悉資料落盤位置，避免誤刪唯一記憶庫。

七步 Runbook 速覽：準備 → 官方安裝 → 登入 → 模型測試 → 接一個低風險整合 → 等記憶 → 實戰並撤銷。全部通過後再疊加 Slack、Notion 與長期工作流。