照著清單裝 OpenHuman:2026 從下載安裝到第一次跑通
OpenHuman 安裝教學最怕「看完很多,還是不知道自己做到哪一步」。這篇不按說明書長篇展開,而是把 OpenHuman 從 0 到跑通拆成可勾選清單——每一項都對應明確驗收點:你該看到什麼、沒看到先查什麼、什麼時候可以進入下一步。
先行結論:跑通 OpenHuman 至少要過七項驗收——安裝、啟動、登入、模型、整合、記憶、實戰輸出。全部打勾後,再擴大 OAuth 權限、接入真實工作郵箱或生產倉庫。產品處於 Early Beta,命令與介面以 tinyhumansai/openhuman 與 官方 GitBook 為準。
邊界說明:本文講的是桌面版 OpenHuman(個人 AI Agent,本機 Memory Tree + Obsidian 式 Markdown vault)。與 OpenHuman WebGL 數字人 SDK(面向網頁/3D 形象的開發套件)不是同一產品;若你在找 WebGL 嵌入文檔,請改看對應 SDK 倉庫,勿按本文裝桌面客戶端。
下文統一格式:☐ 檢查動作 → 通過標準 → 失敗先查。建議先用測試帳號或低風險數據源(如個人 Gmail 測試標籤、只讀 GitHub 倉庫)完成全清單,再接真實工作資料。是否值得現在安裝,可先讀本站 OpenHuman 適合誰用。
總清單:跑通 OpenHuman 的 9 個階段
按順序勾選;某一階段未通過時,不要進入下一階段。
| 階段 | 核心驗收 | 官方參考 |
|---|---|---|
| ① 安裝前 | 系統、磁碟、網路、帳號與權限預期對齊 | README「Local + managed services」說明 |
| ② 下載 | 選定安裝來源(官網 / Release / 包管理器 / 腳本) | tinyhumans.ai/openhuman |
| ③ 安裝 | 應用或 CLI 可啟動,版本可核對 | GitHub Releases / Homebrew / apt |
| ④ 啟動 | 主介面加載、無崩潰循環 | 應用內 onboarding |
| ⑤ 登入 | OpenHuman 帳號會話有效 | 託管登入(預設) |
| ⑥ 模型 | 託管路由或 BYOK / Ollama 能完成一次對話 | Model routing |
| ⑦ 整合 | 至少 1 個 OAuth 連接顯示已授權 | Composio 連接器層(預設託管) |
| ⑧ 記憶 | Memory Tree / vault 有增量,非空殼 | 約 20 分鐘 auto-fetch 週期 |
| ⑨ 實戰 + 收尾 | 基於上下文的回答 + 交付記錄 | 本文第 9–10 節 |
1. 安裝前準備清單
在下載任何安裝包之前完成。OpenHuman 預設把 Memory Tree、Obsidian 式 vault、工作區配置放在本機,但帳號登入、模型路由、網頁搜索代理與託管 OAuth 仍可能走 OpenHuman 託管服務——安裝前請接受這一架構,而不是假設 100% 離線。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 確認平臺與芯片 | macOS(桌面體驗最佳)、Linux x64(Debian/Ubuntu 用 .deb;其他可看 AppImage 說明)、Windows(.msi)。Apple Silicon / amd64 與 Release 資產一致 | Latest release 是否提供對應安裝包 |
| ☐ | 磁碟與記憶體 | 預留 ≥10–20GB(SQLite、Markdown vault、嵌入緩存會增長);建議 ≥16GB 統一記憶體以便多整合 + 本地 Ollama 試驗 | 清理舊 vault;減少同時連接的整合數量 |
| ☐ | 網路與代理 | 可訪問 GitHub、tinyhumans.ai、OAuth 回調域名;公司代理下瀏覽器能完成登入 | 系統代理 / 防火牆;勿在腳本安裝中途斷網 |
| ☐ | OpenHuman 帳號 | 已在官網註冊或準備註冊;知悉預設使用託管模型路由(可選 BYOK) | 郵箱驗證、地區限制;查看 GitBook 賬戶說明 |
| ☐ | 測試數據源策略 | 先連個人測試郵箱 / 只讀 GitHub / 空白 Notion,不要第一步就授權公司全域 Google Workspace | 在整合設定中斷開連接,刪除測試 vault 後重來 |
| ☐ | macOS 額外項(若適用) | 允許從已識別開發者打開;後續整合可能請求日曆、麥克風等——按需授予 | 系統設定 → 隱私與安全性;重籤 DMG 後拖入應用程式文件夾 |
| ☐ | Linux Wayland 注意 | Debian/Ubuntu 優先用官方 signed .deb,而非一上來用 AppImage |
README 提及 AppImage 在 Wayland 下可能崩潰(見 issue #2463);換 .deb 或查 env 變通 |
2. 下載來源清單(如何取捨)
官方 README 把原生包管理器安裝標爲推薦路徑(走 OS 簽名鏈);腳本安裝可用但明確警告無獨立完整性校驗。
| 來源 | 適合誰 | 通過標準 | 失敗先查 |
|---|---|---|---|
官網 / GitHub Release.dmg .msi .deb .AppImage |
要 GUI 安裝器、不熟悉終端的用戶 | 安裝包 SHA/簽名與 Release 頁一致;安裝後應用出現在啟動台或開始菜單 | 是否下錯架構;Gatekeeper 攔截 |
Homebrewbrew tap tinyhumansai/core && brew install openhuman |
macOS / Linux 開發者,要可升級 CLI | which openhuman 有路徑;openhuman --version 有輸出(若 CLI 暴露版本) |
tap 未添加;brew update 後 brew upgrade openhuman |
| apt(Debian/Ubuntu) signed repo + apt install openhuman |
Linux 伺服器或桌面長期部署 | dpkg -l | grep openhuman 顯示已安裝 |
GPG key / sources.list 步驟是否完整(見 README) |
| curl / irm 腳本 | 快速試用;能接受「腳本字節無法防篡改」風險 | 腳本結束無 error;應用可啟動。README 稱 verified script(GPG)流程即將在 Release 提供——發佈前以倉庫為準 | 改用 Homebrew / 官網安裝包;檢查 raw.githubusercontent.com 是否被代理劫持 |
3. 三大平臺安裝清單
macOS
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 方式 A:從 官網 下載 DMG,拖入「應用程式」 | Dock / 啟動台能打開 OpenHuman,首次不閃退 | 右鍵打開繞過 Gatekeeper;磁碟空間 |
| ☐ | 方式 B:brew tap tinyhumansai/core && brew install openhuman |
二進制名爲 openhuman(README);可從終端啟動或按文檔打開 GUI |
Xcode CLT;Homebrew 權限 |
Linux(Debian/Ubuntu 爲例)
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 添加 apt key 與 source(README 完整命令)後 sudo apt install -y openhuman |
包管理器報告 installed;桌面圖標或 openhuman 可執行 |
arch=amd64 限制;GPG key 路徑 |
| ☐ | Arch:AUR openhuman-bin(若已發佈) |
與 README「Once published」狀態一致;未發佈則改用 Release 資產 | 查 AUR 頁面是否可用 |
Windows
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 從 Release 下載 signed .msi 並安裝 |
開始菜單有 OpenHuman;首次啟動無反覆 UAC 循環 | SmartScreen;或以 PowerShell 腳本爲備選(同 README 警告) |
4. 首次啟動與登入清單
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 冷啟動應用 | 主介面 / onboarding 導覽出現;無「啟動即退出」 | 查看應用內 Diagnostics 或系統日誌(路徑以當前版本 UI 為準);Linux 換 .deb |
| ☐ | 完成 OpenHuman 帳號登入 | 設定頁顯示已登入用戶;重啟後仍保持會話 | 瀏覽器彈窗被攔;時鐘不同步;公司 SSO 限制 |
| ☐ | 走完簡短 onboarding(若有) | 可進入對話介面;吉祥物 / 主聊天區可交互 | 跳過非必填步驟後是否阻塞;更新到最新 Release |
5. 模型與 BYOK 配置清單
預設由 OpenHuman 後端做 model routing(按任務選推理 / 快速 / 視覺模型),訂閱內包含多模型,無需自己拼一堆 API Key。若要自帶密鑰或本地推理,在設定裏切自定義 / Ollama(見 GitBook)。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 託管路由冒煙測試 | 發送「用一句話介紹你自己」類消息,數秒內收到連貫回覆;無持續 401/429 | 帳號訂閱狀態;網路;GitBook「Model routing」故障項 |
| ☐ | (可選)BYOK:填入自有 provider Key | 設定保存成功;測試消息走自有額度;Key 不出現在聊天導出裏 | Key 權限範圍;公司密鑰策略 |
| ☐ | (可選)Ollama 本地模型 | Ollama 服務運行;OpenHuman 內選用本地模型後對話成功(僅支持文檔列出的 workload) | 模型體積 vs 記憶體;Ollama 端口;回退託管路由 |
6. 整合授權清單
官方稱 118+ 整合,預設經 Composio 連接器與託管 OAuth。建議順序:Calendar 或只讀 GitHub → Gmail 測試標籤 → Slack 測試區,避免第一步授權生產郵箱全域。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | Integrations 頁添加 1 個低風險連接 | 狀態爲 Connected / Active;OAuth 回調無 error | 瀏覽器權限;Composio 彈窗;改用 direct mode + 自有 Composio API Key(高級,見 README) |
| ☐ | 確認 auto-fetch 已啟用 | 文檔稱核心約每 20 分鐘 遍歷活躍連接拉增量;UI 有上次同步時間或 ingest 活動 | 連接是否處於 active;等待一個週期;查看 GitBook「Auto-fetch」 |
| ☐ | 工具調用冒煙 | 讓 Agent「列出我 GitHub 上最近更新的 repo」或「今天日曆有幾場會」——回答引用真實數據而非編造 | 整合 token 過期;重授權;是否連錯帳號 |
7. 記憶同步驗收清單
OpenHuman 把連接數據 canonicalize 爲 ≤3k token 的 Markdown chunk,寫入本機 SQLite Memory Tree,並同步到 Obsidian 兼容 vault。可選 memory.backend = "agentmemory" 走外部 daemon(見 GitBook),預設無需改 config.toml。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 打開 Intelligence → Memory(或當前版本等價入口) | 連接源下列出條目;非「永久 0 條」 | 是否未滿一個 auto-fetch 週期;整合是否真有新數據 |
| ☐ | 檢查 Obsidian / Markdown vault | 工作區下出現 .md 文件,內容與剛連接的數據相關(郵件主題、repo 名等可對上) |
設定裏 vault 路徑;磁碟權限;是否指向空目錄 |
| ☐ | (可選)Knowledge Vault 本地文件夾 | 對測試文件夾執行 Sync 後,Memory 頁有 vault 條目;SQLite 在 {workspace_dir}/vault/vault.db(新功能,見倉庫 PR 說明) |
路徑是否絕對;單文件 5MiB 上限;排除 node_modules 等 |
| ☐ | 確認不是「空記憶殼」 | 對話問「我上週在 X 整合裏發生了什麼」能引用 chunk 摘要,而非純幻覺 | TokenJuice 過度壓縮時換更具體關鍵詞;手動觸發同步 |
8. 第一個實戰任務清單
用一道可核對答案的任務證明 Agent 已可用。在測試數據上完成,通過後再換真實項目。
| ☐ | 檢查動作 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 任務 A(跨源摘要) | 「根據我已連接的 GitHub + 日曆,用三條 bullet 總結我本週開發重點」——內容與真實帳號一致,你可手工 spot-check | 記憶未同步;回到第 7 節 |
| ☐ | 任務 B(本地工具) | 讓 Agent 在允許的工作區內讀一個小文件並總結(coder toolset)——不越界訪問系統目錄 | 工作區路徑設定;macOS 文件訪問授權 |
| ☐ | 任務 C(可追溯) | 回答中能看出引用了哪些整合或 memory chunk(或你能在 vault 找到對應 .md) | 模型幻覺 → 要求「只根據 memory 回答,沒有就說沒有」 |
9. 排錯與收尾清單
9.1 按階段倒查(常見失敗)
| 症狀 | 優先回到哪一階段 | 快速動作 |
|---|---|---|
| 裝完打不開 / Linux 秒退 | ②③ | 換 signed .deb / DMG;勿死磕 AppImage+Wayland |
| 登入循環 | ④⑤ | 清瀏覽器 cookie;系統時間;換網路 |
| 對話一直失敗 | ⑥ | 切託管路由;檢查訂閱與配額 |
| 整合連上但 Agent 不知道我的郵件 | ⑦⑧ | 等 20 分鐘;看 Memory 頁;重授權 OAuth |
| vault 有文件但回答胡編 | ⑧⑨ | 約束 prompt;核對 chunk 是否過舊 |
9.2 交付記錄(建議保存)
| 交付項 | 記錄內容(示例) |
|---|---|
| 版本 | Release tag 或應用「關於」頁版本;安裝日期 2026-05-28 |
| 安裝方式 | Homebrew / DMG / apt / msi 其一 |
| 模型模式 | 託管 / BYOK / Ollama |
| 已連接整合 | 列表 + 是否生產帳號 |
| vault 路徑 | 設定中顯示的 Obsidian vault 絕對路徑 |
| 回滾 | 卸載應用;備份 vault 目錄後刪除;斷開所有 OAuth |
9.3 全部通過後再做的事
- ☐ 逐步接入真實工作郵箱、Slack 工作區、生產 GitHub org
- ☐ 在 provider / Composio 控制台核對 OAuth 權限範圍,移除不需要的 scope
- ☐ 定期備份 vault 與 SQLite(具體路徑以你本機設定為準)
- ☐ 關注 Release 與 Beta 說明,大版本升級前導出記憶
七項驗收全部打勾,即表示 OpenHuman 已從「裝上了」進入「能基於你的數據說話」。此後擴容權限時,重複第 6–8 節各一項即可。
用 Mac mini 跑記憶同步,更穩也更省心
OpenHuman 的 Memory Tree、Markdown vault 與約 20 分鐘一次的 auto-fetch 都偏愛長期在線、低中斷的環境。macOS 桌面版體驗最完整;把 Agent 放在 Mac mini M4 上,Apple Silicon 統一記憶體有利於嵌入與多整合併發,待機功耗可維持在很低水平,適合 7×24 掛着同步,而把 OAuth 試錯與大量本地 Markdown 限制在專用機器,與日常 MacBook 隔離。
相比同價位小型 PC,macOS 的 Gatekeeper、SIP 與 FileVault 能降低惡意軟體與誤改系統風險;無需 WSL 即可用 Homebrew 安裝 openhuman。若你正按本文清單驗收,Mac mini M4 是性價比很高的個人 AI 記憶節點——現在即可入手,讓清單裏的整合、vault 與首次實戰在穩定硬體上一次性通過。