OpenHuman 詳細安裝與使用教學

本文件 deep-dive 整理 tinyhumansai/openhuman 的安裝、設定、核心架構、應用情境，並附上對 scripts/ 與 install pipeline 的資安審查結果。閱讀對象：想把 OpenHuman 納入個人 / 團隊日常工作流的開發者與 power user。
⚠️ 狀態：upstream 自我標記 Early Beta，0.53.x 版本線每天多次 release；issue #1567 公開揭露 9 個 high-severity Rust 依賴 CVE 待 patch — 在意安全性的場景請先看 §6 再決定是否使用。

1. 專案定位（一句話總結）

把 Karpathy-style Obsidian wiki + Memory Tree + 118 個 OAuth 整合 全部塞進一個跑在你自己電腦的 Tauri 桌面 app。

它是什麼？

桌面端 Personal AI Agent harness：Rust 核心（openhuman-core :7788 RPC）+ Tauri v2 桌面殼 + React 前端
本地優先：connection 資料、memory tree、Obsidian vault 全部存在裝置上的 SQLite + .md 檔
整合導向：非 BYO Tools — 預設 wired-in web search / scraper / 完整 coder toolset / 語音 / mascot / 模型路由
單一訂閱模式：取代「自己付 OpenAI / Anthropic / Gemini 多家 API key + 自寫壓縮層」

它不是什麼？

❌ 不是純 CLI agent（雖然 openhuman-core 有 CLI 介面，主入口是桌面 app）
❌ 不是 mobile（Tauri host 用 compile_error! 擋住非桌面 target）
❌ 不是 production-ready 穩定版（Early Beta，有未 patch 的 CVE）
❌ 與 OpenClaw / Hermes 不同，License 是 GPL v3 — 衍生作品有開源義務

2. 安裝指南

2.1 系統需求

平台	支援度	備註
macOS	✅ 完整	DMG 簽章 + Homebrew formula
Windows	✅ 完整	EXE + MSIX；近期才修好 CEF keyboard input cold-launch（commit `7ce3193`）
Linux x86_64	⚠️ 不穩	issue #1578 — 最新 release 的 linux-x86_64 asset 尚未發佈
Android / iOS	🚫 不支援	Tauri host 強制 compile error

2.2 步驟 1 — 一鍵安裝（推薦）

macOS / Linux

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

Windows (PowerShell)

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

Dry-run 模式（先看會做什麼，不實際安裝）

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

🔐 資安說明：install.sh / install.ps1 都會從 GitHub release manifest 取 SHA256 digest 並驗證下載 asset；不過 curl | bash pattern 本身要求你信任 GitHub repo 主人。詳見 §6。

2.3 步驟 2 — 從 Web 下載（不想跑 curl|bash）

到 https://tinyhumans.ai/openhuman 直接下載：

macOS：OpenHuman.dmg（含 Apple notarization）
Windows：OpenHuman_Setup.exe
Linux：OpenHuman.AppImage（若可用）

2.4 步驟 3 — 從原始碼建置（開發者）

 1git clone https://github.com/tinyhumansai/openhuman.git
 2cd openhuman
 3
 4# 1. Node + pnpm（強制版本）
 5corepack enable && corepack use pnpm@10.10.0
 6
 7# 2. Rust toolchain（讀 rust-toolchain.toml）
 8rustup show
 9
10# 3. 安裝依賴
11pnpm install                  # 前端 + workspace
12cargo build --bin openhuman   # Rust core sidecar（會被 stage 到 Tauri resources）
13
14# 4. 開發模式
15pnpm dev                      # 前端 + Tauri dev
16# 或
17pnpm tauri dev                # 桌面 app（會自動 load .env via scripts/load-dotenv.sh）
18
19# 5. 產品建置
20pnpm build                    # UI build
21pnpm tauri build              # 完整桌面 app

2.5 步驟 4 — Self-hosted Core（可選，給 server 部署）

1cp .env.example .env
2# 編輯 .env：至少設 BACKEND_URL 與 OPENHUMAN_CORE_TOKEN
3docker compose up -d
4curl http://localhost:7788/health

2.6 已知安裝問題

症狀	原因	解法
Linux 安裝失敗（issue #1578）	latest release 沒附 linux-x86_64 asset	等 upstream 補；或自建
Windows 啟動畫面閃爍（issue #1584）	Win11 視窗 race condition	等 upstream patch
401 cascade 認證錯誤	session 過期 retry loop	已修（commit `8b4350e`），升到最新
pnpm cache 在 CI 失敗	setup-node action deprecated	已修（commit `7824f50`）

3. 核心架構解析

3.1 三層分工（CLAUDE.md 明確規範）

 1┌─────────────────────────────────────────────────────────────┐
 2│  React + Vite (app/src/)                                    │  ← UX / 螢幕 / 導航
 3│  Tauri v2 host (app/src-tauri/)                             │  ← 桌面殼 + 系統整合
 4└─────────────────────────────────────────────────────────────┘
 5                          │  HTTP（核心 RPC）
 6                          ▼
 7┌─────────────────────────────────────────────────────────────┐
 8│  Rust core: openhuman_core lib + openhuman CLI binary       │  ← 業務邏輯（authoritative）
 9│  port :7788 — core_rpc_relay + core_rpc client              │
10└─────────────────────────────────────────────────────────────┘
11                          │
12                          ▼
13┌─────────────────────────────────────────────────────────────┐
14│  SQLite (workspace) + Obsidian vault (.md files)            │  ← Local-first 持久化
15│  OS keychain（macOS Keychain / Windows Credential Manager） │
16└─────────────────────────────────────────────────────────────┘

設計原則（CLAUDE.md ## Shell vs app code 章節）：

Rust core 是唯一真相（business logic / domains / RPC / persistence / CLI）
Tauri + React 只 present 與 orchestrate，禁止 duplicate 業務邏輯
桌面 host 用 sidecar pattern spawn openhuman-core，不直接 link

3.2 檔案總覽

 1openhuman/
 2├── README.md / AGENTS.md / CLAUDE.md      # AGENTS.md 641 行，CLAUDE.md 302 行；都在解釋 layer 分工
 3├── SECURITY.md                            # 53 行：揭露政策 + safe harbor
 4├── CONTRIBUTING.md                        # 243 行
 5│
 6├── Cargo.toml                             # Rust workspace；3 個 binary：openhuman-core / slack-backfill / gmail-backfill-3d
 7├── rust-toolchain.toml                    # 鎖 Rust 版本
 8├── package.json + pnpm-workspace.yaml     # pnpm 強制；migration from yarn
 9│
10├── src/                                   # 554 個 .rs — Rust core
11│   ├── api/                               # 對外 API
12│   ├── bin/                               # backfill scripts
13│   └── (core_server / openhuman::* domains / MCP routing)
14│
15├── app/                                   # pnpm workspace `openhuman-app`
16│   ├── src/                               # 80 .tsx + 122 .ts — React + Vite
17│   ├── src-tauri/                         # Tauri v2 desktop host（Rust）
18│   │   └── (compile_error! 擋住非桌面 target)
19│   └── test/                              # Vitest
20│
21├── packages/                              # 平台分發
22│   ├── deb/                               # Debian/Ubuntu .deb
23│   ├── homebrew/ + homebrew-core/         # Homebrew formula
24│   └── npm/                               # （CLI 用）npm package
25│
26├── scripts/                               # 工具腳本（重要！）
27│   ├── install.sh (590 行) / install.ps1  # curl|bash 安裝 + SHA256 驗證
28│   ├── debug/        cli.sh + 6 子腳本    # 除錯 CLI
29│   ├── rabbit/       cli.sh + cli.mjs     # Rabbit code review CLI
30│   ├── review/       cli.sh + 6 子腳本    # Review CLI
31│   ├── work/         cli.sh + start.sh    # Work CLI
32│   ├── release/      9 個 packaging       # 各平台 release packaging
33│   ├── tests/        OpenHumanWindowsInstall.Tests.ps1
34│   ├── tools-generator/  discover-tools.js + openClaw-formatter.js  # 自動產生 tool definitions
35│   ├── load-dotenv.sh / load-env.sh       # .env 載入（用 eval）
36│   └── 大量 debug-* / mock-* / test-* mjs
37│
38├── docker-compose.yml + Dockerfile        # self-hosted core
39├── e2e/                                   # WDIO E2E
40├── examples/  remotion/                   # 範例 + mascot 動畫
41├── docs/                                  # 內部架構深度文件
42└── gitbooks/                              # 公開文件 → tinyhumans.gitbook.io
43    └── {developing, features, legal, overview}/

3.3 Memory Tree 的工作原理（簡化）

 1[Connection 啟動 OAuth]
 2        │
 3        ▼
 4[每 20 分鐘 auto-fetch] ─→ Gmail / Notion / GitHub / ...
 5        │
 6        ▼
 7[TokenJuice 壓縮]：HTML→MD / 縮 URL / 去 non-ASCII / dedup
 8        │
 9        ▼
10[Canonicalize 成 ≤3K-token Markdown chunks]
11        │
12        ▼
13[寫入 SQLite + Obsidian-compatible vault (.md)]
14        │
15        ▼
16[Memory Tree 階層摘要] ← 低層 chunk fold 進高層 summary
17        │
18        ▼
19[Agent 查詢時自動 retrieve + rank]

3.4 三個 Rust binary

Binary	用途
`openhuman-core`	桌面 sidecar；listen :7788；提供 RPC + tool execution + memory ops
`slack-backfill`	一次性 Slack 歷史回填到 memory tree
`gmail-backfill-3d`	Gmail 過去 3 天 backfill（懷疑為 perf 測試 / debug 用）

為什麼移除 html2md 依賴？Cargo.toml 註解寫得很白：dhat-rs profiling 發現 html2md::walk 在 10KB Otter.ai 信件上 peak heap 894MB（line 31-37）。

4. Helper Scripts 詳細用法

4.1 高頻 CLI

 1# 開發
 2pnpm dev                         # 前端 + Tauri dev
 3pnpm tauri dev                   # 桌面 app（auto-load .env）
 4pnpm typecheck                   # tsc 檢查
 5pnpm lint / pnpm lint:fix
 6pnpm format / pnpm format:check
 7
 8# 測試
 9pnpm test                        # Vitest
10pnpm test:coverage
11pnpm test:rust                   # cargo test（delegate 到 scripts/test-rust-with-mock.sh）
12
13# 建置
14pnpm build                       # 前端 production build
15pnpm tauri build                 # 完整桌面 app（含 sidecar staging）
16
17# 工具 CLI
18pnpm rabbit                      # Rabbit code review CLI（scripts/rabbit/cli.sh）
19pnpm review                      # 自製 review CLI（scripts/review/cli.sh）
20pnpm work                        # work CLI
21pnpm debug                       # debug CLI
22
23# Mock & PR check
24pnpm mock:api                    # 起 mock backend（給 E2E）
25pnpm pr:checklist                # 檢查 PR description checklist

4.2 Rust core 直接互動

1cargo build --bin openhuman                    # 編譯 sidecar
2cargo run --bin openhuman -- <subcommand>      # CLI 模式
3cargo test                                     # 單元測試

4.3 release packaging（給 maintainer）

1scripts/release/bump-version.js                # 版本號統一 bump（package.json + Cargo.toml + Tauri）
2scripts/release/build-apt-packages.sh          # .deb 打包
3scripts/release/build-linux-arm64.sh           # ARM64 Linux build
4scripts/release/render-homebrew-core-formula.sh # Homebrew formula 產生
5scripts/release/publish-npm.sh                 # CLI 發到 npm
6scripts/release/publish-updater-manifest.sh    # 桌面 auto-updater manifest

4.4 .env 載入機制（注意 eval 風險）

scripts/load-dotenv.sh 用 eval 把 .env 變數注入 shell：

1eval "$(scripts/load-dotenv.sh [path/to/.env])"

這是常見模式，但**.env 內容若被竄改可導致任意 shell 注入** — 確保 .env 不要從不可信來源 source。

4.5 tools-generator（自動產生 tool definitions）

1node scripts/tools-generator/discover-tools.js  # 從 OAuth provider 拉所有 tool
2node scripts/tools-generator/openClaw-formatter.js  # 轉成 OpenClaw 相容格式

這是 OpenHuman「118+ 整合」的自動化產生來源。

5. 應用場景

5.1 個人用戶（power user）

情境	說明
把 Gmail / Calendar / Notion 統整給 AI	OAuth 一鍵綁定；20 分鐘後 agent 已有完整脈絡
桌面助理 + 語音對話	Mascot 朗讀 + ElevenLabs TTS + STT 即時聽寫
Google Meet 會議參與	mascot 加入 Meet 當代理人，會議結束自動寫 summary
本機 Obsidian 知識庫	所有資料都成 `.md`，可在 Obsidian 直接開、編輯、搜尋
取代 ChatGPT Plus + 多家 API 訂閱	一個訂閱 + Model Routing

5.2 開發者 / coder

情境	說明
Coder toolset	filesystem / git / lint / test / grep 全部 wired-in，免裝 plugin
本地 LLM 推理	Ollama 整合，敏感程式碼不離本機
Rust 程式碼貢獻	repo 強制 pnpm + rust-toolchain，CONTRIBUTING.md 詳細
Skill 開發	Skills 在另一個 repo（`tinyhumansai/openhuman-skills`），build 後接進來

5.3 中型團隊 / 內部 IT

情境	說明
內部知識集中	把 Slack / Notion / GitHub / Linear 統整到單一 agent
Self-hosted	docker-compose 起 `openhuman-core` 給多人連線
OAuth 集中管理	所有第三方整合走 OpenHuman OAuth flow，不用每人自申請

5.4 不適合的情境

⚠️ Production-critical workflow（Early Beta + 未 patch CVE）
⚠️ 高度合規環境（GPL v3 衍生作品開源義務）
⚠️ Mobile-first 場景（無 iOS / Android）
⚠️ 完全離線使用（雖然有 local AI 選項，主訂閱模式仍需網路）

6. 資安掃描報告（2026-05-13）

範圍：scripts/ 全部、install.sh / install.ps1、Cargo.toml 依賴、SECURITY.md 原則、CI secrets 範本、Tauri 設定。掃描方式：人工 grep + manifest 檢視。

6.1 結論

🟡 整體風險：中。設計與實作有不少安全亮點，但 upstream 主動揭露的 9 個 CVE 與 Early Beta 標記讓部署門檻提高。個人本機使用 OK，企業環境須等 #1567 patch 並做 cargo audit。

6.2 詳細結果

風險類別	結果	說明
依賴 CVE	🔴 upstream 自承 9 個 high-severity	issue #1567：作者明確說 Rust 依賴有 9 個未 patch high-CVE — 部署前自跑 `cargo audit` 檢視
`curl \| bash` 安裝	🟡 中	標準 devtool pattern；install.sh 有 SHA256 驗證（line 425+ `compute_sha256`），install.ps1 也驗 sha256（line 165, 199）；但仍須信任 GitHub repo 主人
HTTPS only	✅	所有 curl 都用 `https://raw.githubusercontent.com/`；reqwest 鎖 rustls-tls + native-tls
TLS stack	✅	rustls 0.23 + ring 0.17 + rustls-pki-types 1.14 — 現代且 audited
OAuth token 儲存	✅	SECURITY.md：用 OS Keychain（macOS Keychain / Windows Credential Manager），不存 plain text
Sidecar token gating	✅	docker-compose.yml 與註解皆強制 `OPENHUMAN_CORE_TOKEN` 才能 /rpc
CI secrets 模板	✅	ci-secrets.example.json 全空值；無洩漏
Hard-coded API keys	✅	grep 全 repo 無發現
`eval` 使用	🟡 低	僅 `load-dotenv.sh` / `load-env.sh` 用 `eval` 注入 .env — 標準 pattern，但 .env 內容須可信
`execSync` / `spawn`	🟡 低	scripts/*.mjs 用 `execSync` 跑 git / cargo 等子程序；都是 hard-coded 命令，無 user input 注入
Rust `unsafe` blocks	🟡 低	10+ 檔案有 `unsafe`（local_ai/voice/ollama_api/…）— 多為 FFI bridge，是 Tauri/Ollama integration 必要
Sentry 錯誤上報	🟡 中性	整合 Sentry（gitignore sentry_bugs，環境變數 SENTRY_*）— 上報內容須查文件確認不含使用者資料
Google Analytics	🟡 中性	commit `8e9aef6` 剛加入 GA — 部署前可能想關掉（檢查 `app/src/` 內 GA wrapper）
GPL v3 義務	⚠️ 法務	衍生作品 / fork 需開源；company internal use 可能受限

6.3 使用建議

場景	建議
個人本機嘗鮮	直接安裝；接受 Early Beta 風險；跑前看一次 `~/.openhuman` 設定確認 token 在 keychain
個人主力工具	等 #1567 解決 + 至少一個 GA 上報關閉選項；備份你的 Obsidian vault
小團隊 self-host	docker-compose；務必設強 `OPENHUMAN_CORE_TOKEN`；放在內網不對外
企業 production	🚫 目前不建議：Early Beta + 9 CVE + GPL v3；至少等 1.0 release
Fork 改造	可，但要遵守 GPL v3 — 修改後需開源回饋

6.4 主動安全亮點

✅ 有 SECURITY.md 與 safe harbor 政策
✅ install scripts 全部驗 SHA256
✅ TLS 用現代 stack（rustls + ring）
✅ OAuth credential 存在 OS keychain
✅ Sidecar 強制 token 認證
✅ Tauri host 限制平台（compile_error! 擋 mobile）
✅ cargo audit 友好的 Cargo.lock 完整 commit

7. 常見問題（FAQ）

Q1：和 Claude Cowork / OpenClaw / Hermes 比，主要差別？

維度	OpenHuman	對手
Memory	Memory Tree + Obsidian vault（first-class）	對手主要是 chat-scoped 或 plugin-based
Auto-fetch	20 分鐘輪詢主動拉資料	全部都需要使用者主動觸發
整合數量	118+ OAuth	通常 < 30
桌面整合	mascot / Meet 參與 / 系統 tray	多為 web app 或 terminal
License	GPL v3（複製要開源）	OpenClaw / Hermes 是 MIT

Q2：Memory tree 的 SQLite 在哪？我可以備份嗎？

依平台 default 在：

macOS：~/Library/Application Support/openhuman/
Windows：%APPDATA%/openhuman/
Linux：~/.local/share/openhuman/

直接 cp 整個目錄就是備份；Obsidian vault 的 .md 檔通常也在其下子目錄。

Q3：可以完全關掉雲端 LLM、只用 Ollama 本地推理嗎？

可以。Model Routing 設定裡選 Ollama provider；mascot / voice / scraper 等仍需要對應 API 的就獨立配置。

Q4：118+ 整合是怎麼維護的？

scripts/tools-generator/discover-tools.js 自動從 provider OAuth 拉所有 endpoint，再用 openClaw-formatter.js 轉成內部 schema。意思是大多數整合是「自動產生 + 手動 polish」。

Q5：為什麼選 GPL v3？

README 沒明說，但對比表明確列「OpenHuman: ✅ GNU」。常見動機是阻止 SaaS 公司直接 fork 賣（因為衍生作品也要 GPL）— 與 OpenClaw / Hermes 的 MIT 哲學不同。

Q6：是否可以開發自己的 Skill？

可以。Skills 在另一個 repo tinyhumansai/openhuman-skills，build 完接到本 repo。AGENTS.md 第 60 行有寫 workflow。

Q7：mascot 加入 Google Meet 怎麼運作？

文件指向 https://tinyhumans.gitbook.io/openhuman/features/mascot/meeting-agents — 用一個 virtual camera + 真人帳號加入 Meet（不確定是 STT pipeline 走 Meet API 還是 OS audio capture）。

Q8：升級會不會把我的資料蓋掉？

桌面 app 有 auto-updater（scripts/release/publish-updater-manifest.sh）。資料目錄與 app binary 分離，理論上 upgrade 不會動 SQLite / vault。但 Early Beta 階段有 schema 變更風險，升級前建議手動備份資料目錄。

8. 進階技巧

8.1 用 docker-compose 起 headless core（不用桌面 app）

1cp .env.example .env
2# 編輯 .env：BACKEND_URL + OPENHUMAN_CORE_TOKEN（強密碼）
3docker compose up -d
4curl -H "Authorization: Bearer $OPENHUMAN_CORE_TOKEN" http://localhost:7788/health

這對「我有 NAS / homelab，希望 OpenHuman 一直跑著抓 Gmail」的人很方便。

8.2 CI / 自動化整合

scripts/codex-pr-preflight.mjs：在 PR 前跑檢查
scripts/check-pr-checklist.mjs：驗 PR description checklist
scripts/check-coverage-matrix.mjs：跨平台測試覆蓋率矩陣

8.3 開發 Skill 的快速循環

1# 1. 在 openhuman-skills repo 寫 skill
2# 2. build skill → 產生 manifest
3# 3. 本機 OpenHuman 從 GitHub 拉新 skill
4#    或：scripts/load-dotenv.sh 先設 VITE_SKILLS_GITHUB_REPO

8.4 觀察 Memory Tree 的 fold 過程

1scripts/memory-tree-progress.sh
2# 印出最近的 chunk → summary → tree update 事件

8.5 自製 backfill（範例：Slack 歷史）

1cargo run --bin slack-backfill -- --workspace <id> --since 2024-01-01

適合「剛裝好 OpenHuman，想把過去一年的 Slack 都 fold 進 memory」的場景。

9. 整合進其他工作流

9.1 與 AI-knowledge template（本專案）串接

OpenHuman 的 Obsidian vault 預設是 .md 檔，可以：

在本專案 inbox/ symlink 到 OpenHuman vault → 自動把 OpenHuman 整理過的 note 也納入本專案知識管線
用 quarkdown 把 OpenHuman 產生的 note 轉成 HTML / PDF 報告
用 kami 進一步排版成出版品質文件

9.2 與 Claude Code 串接

OpenHuman 主要是 GUI 工具，但 openhuman-core 有 CLI 介面：

可在 Claude Code session 裡 cargo run --bin openhuman -- query "..."（如 CLI 支援）
或透過 RPC：curl -H "Authorization: Bearer $TOKEN" http://localhost:7788/rpc -d '{...}'

9.3 與 Linear / Jira / Slack 自動化串接

OpenHuman 自帶 OAuth 整合 + auto-fetch；通常不需要你寫額外的 webhook → OpenHuman 已經把資料 fold 進 memory，agent 直接可查。

10. 重點摘要 Checklist

安裝（macOS / Linux）：curl -fsSL ... | bash，install.sh 會驗 SHA256
安裝（Windows）：irm ... | iex，install.ps1 同樣驗 SHA256
Linux x86_64 目前缺 asset（issue #1578）— 暫時改下載 web 版或自建
Self-host：docker compose up -d，務必設強 OPENHUMAN_CORE_TOKEN
資料備份：升級前手動 cp 資料目錄（macOS：~/Library/Application Support/openhuman/）
資安門檻：個人 OK；企業 production 不建議（等 #1567 + 1.0 release）
License 注意：GPL v3，fork / 內部修改有開源義務
Memory Tree 入門：connect Gmail → 等 20 分鐘 auto-fetch → 開 Obsidian vault 看 .md 檔
開發 Skill：到 tinyhumansai/openhuman-skills repo
CVE 自查：cargo audit（Cargo.lock 已 commit）

11. 進一步閱讀

主 repo：https://github.com/tinyhumansai/openhuman
官網：https://tinyhumans.ai/openhuman
公開文件（GitBook）：https://tinyhumans.gitbook.io/openhuman/
架構深入：https://tinyhumans.gitbook.io/openhuman/developing/architecture
Discord 社群：https://discord.tinyhumans.ai/
Skills repo：tinyhumansai/openhuman-skills
安全揭露：見 SECURITY.md（不在 GitHub Issues 開）
本教學版本：2026-05-13；對應 commit b9f1c08 之後的 main 分支（v0.53.31）

🔄 OpenHuman 每天都有新 release（0.53.x 系列），本教學重大內容約 1–2 週後可能需要更新。

OpenHuman 詳細安裝與使用教學（含資安掃描報告）

Contents