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 与长期工作流。