OpenHuman 技术全览：本地优先的 AI 大脑、Agent 编排与深度研究工作流的开源实现

本文基于仓库内 docs/README.de.md 及英文主 README.md 的产品与架构叙述整理，并对照仓库中的源码、配置文件与本地文档做了交叉印证。文中涉及的集成数量、压缩比例等营销性数字均标注为"项目文档所述"，请以官方口径为准。

OpenHuman 是一个面向 macOS、Windows 与 Linux 的开源个人 AI（早期 Beta 阶段，官方自述"Expect rough edges"）。它把自己定位成三个大多数助手不具备的东西：一个会构建持久化本地记忆的大脑、一个在可持久化图上运行 Agent 舰队的编排器（Orchestrator），以及一个在你问完问题之前就开始扫描你数据和 Web 的深度研究者（Deep Researcher）。本文将从仓库文档出发，拆解其记忆架构、编排模型、工作流系统、内置工具链、隐私机制与从源码构建的完整路径，帮助读者理解这套"Local-first + 图执行 + 审批门控"设计的落地细节。

一、三种身份：大脑、编排器与深度研究者

项目官方文档用三个维度概括 OpenHuman 的核心能力，几乎每一个功能点都在仓库的 gitbooks 目录下有独立的展开说明（这些 Markdown 既是项目文档，也是文章续读的一手资料）：

1. 🧠 一个大脑——建立对你世界的持久化、本地记忆；
2. 🕸️ 一个编排器——在持久化图（durable graphs）上运行成队的 Agent；
3. 🔬 一个深度研究者与执行者——内置 Web 搜索、抓取、编码、浏览器与语音等全套工具。

下文将按这三个维度逐层拆解，并补充安装、配置与源码贡献层面的实操内容。

二、大脑：Memory Tree + Obsidian Wiki + TokenJuice

2.1 把数据压缩成"带评分的 Markdown 树"而非向量汤

官方文档描述的 Memory 方案与主流 RAG 的"向量池黑盒"形成鲜明对比：

• Memory Tree：你的数据在本地机器上被压缩为经过评分（scored）的 Markdown 树，存储在 SQLite 中；
• Obsidian Wiki：这份树同时镜像为一个 Obsidian Vault，你可以直接打开、人工编辑与校对。项目深受 Karpathy "LLM Knowledgebase" 思路的启发，明确反对不可解释的向量池方案。

从仓库结构看，"记忆"并非单一模块，而是贯穿多个子系统的主题：根目录 src/ 下的核心是 Rust（src/openhuman/memory/、src/openhuman/memory/ 等模块树），应用层另有 src/openhuman/medulla/、src/openhuman/inference/ 等模块协作；完整概念图可阅读 gitbooks/features/obsidian-wiki/README.md 与 gitbooks/features/obsidian-wiki/memory-tree.md。

2.2 Auto-Fetch：每 20 分钟为大脑喂一次上下文

为了让 Agent "在明天早上就拥有明天的上下文"，官方文档强调 Auto-Fetch 机制：

• 接入你的账号（Gmail、Notion、GitHub、Slack 等，项目文档称支持 100+ OAuth 集成、5000+ MCP 服务器、90000+ Skills，均可一键接入）；
• Auto-Fetch 以 20 分钟为一个周期把新数据拉取到本地；
• Memory Tree 把这些内容持续压缩进 Markdown 文件，智能归档到 Obsidian Wiki。

按文档的说法，只需一次同步周期，Agent 就能获得收件箱、日历、仓库、文档与消息的完整（压缩后）上下文——不需要训练期，也不需要"先给它几周"。

2.3 TokenJuice：把工具输出压缩后再交给模型

对于如此庞大的"大脑"体量，直接向模型投喂原始工具输出会非常昂贵。文档介绍了内建压缩层 TokenJuice：

• 工具输出在触达模型之前先被压缩；
• 官方声称"同样的信息，Token 最多可减少 80%"；
• 这是让"大记忆体"在单订阅成本下可负担的关键设计，详见 gitbooks/features/token-compression.md。

2.4 可选后端：把 agentmemory 作为共享持久存储

如果你已经在为 Claude Code、Cursor、Codex、OpenCode 等编码 Agent 自托管 agentmemory，OpenHuman 还附带一个可选的 Memory 后端用于代理（proxy）到该服务：

• 在 config.toml 中设置 memory.backend = "agentmemory"；
• 同一个持久存储即可同时驱动 OpenHuman 与其他编码 Agent，形成跨工具共享的记忆底座。

配置说明以项目文档与 gitbooks/features/obsidian-wiki/ 下的设置页为准；config.toml 属于用户级配置文件，不在仓库内提交。

2.5 附带功能：Goals & Todos

文档还提到长生命周期目标系统：支持长期目标、每个线程内的持久目标，以及每个会话共享的 Kanban 看板。细节见 gitbooks/features/goals-and-todos.md。

下面是文档中用于说明"上下文构建"流程的示意图（原图位于 gitbooks/.gitbook/assets/）：

三、编排器：图执行、断点续跑与端到端加密的 A2A

3.1 图而非循环

绝大多数 Agent harness 是"一个 Agent 在一个循环里跑"。OpenHuman 的定位是编排器：

• Turn 以带检查点的图（checkpointed graphs）执行：可以"为人类暂停"，可以"在重启后存活"，并能在运行中途恢复；
• 引擎层基于开源项目 tinyagents（文档明确给出其作为图运行库的引用）；
• 完整编排架构见 gitbooks/features/orchestration.md。

3.2 子 Agent 舰队与"卡住即转根因报告"

编排模型还包括：

• 子 Agent 舰队：专业 Agent 可向下派生 三层深度 的专才；
• 停滞处理：卡住的 Agent 会被引导（steered），被中止的 Agent 会返回一份根因报告（root cause）；
• 可回放的运行日志：每一次运行都可以按真实的"每次调用成本"回放，用于可观测与费用核算。

3.3 Agent 到 Agent：Signal 协议 E2E 加密 + x402 支付

文档特别强调消息面：Agent 到 Agent 的通信运行在 Signal 协议端到端加密会话之上，并带 x402 支付通道。任何外部 Agent（Claude Code、Codex、OpenClaw、Hermes 等）都可以接入，由 OpenHuman 统一编排；任何服务器都不会看到明文。

官方编排示意图如下：

四、Workflows：看得见的、由 Agent 提议的自动化

4.1 从"用户搭自动化"到"Agent 提议、用户审批"

受 n8n 与 Zapier 启发，Workflows 把"可视化 + 触发器驱动的自动化"搬到 Agent 侧，但关键差异在于图是 Agent 替你画的：

1. 你提出一个自动化诉求；
2. Agent 产出一个基于开源项目 tinyflows 的图方案；
3. 你在可视化 Canvas 上审查该图；
4. 确认后才保存为持久化工作流。

4.2 持久化、触发器驱动、审批门控

保存后的 Workflow 具备三层保障：

• 持久化：重启后依然存在；
• 触发器驱动：可响应时间调度（schedules）、Webhook、渠道事件（channel events）；
• 审批门控：所有副作用执行前都需经过审批（approval-gated）。

官方工作流 Canvas 示意图：

五、内置工具箱：搜索、浏览器、语音、媒体生成与多通道触达

5.1 "Deep Researcher & Doer"全栈内置

项目文档称其内置能力覆盖：

• Web 搜索、网页抓取器（scraper）、编码工具集；
• 一个真实可用的浏览器（浏览器与电脑操作相关工具见 gitbooks/features/native-tools/ 目录）；
• 原生语音：进程内（in-process）运行 Whisper，详见 gitbooks/features/native-tools/voice.md；
• 图像与视频生成：Seedream/SeedEdit 出图、Seedance/Veo 出视频，直接落到你的工作区；
• Model Routing（模型路由）：按负载自动挑选合适的 LLM，一个订阅即可覆盖不同任务；同时支持自备模型 Key 或完全本地的 Ollama 模型，文档称这是"默认而非锁定"，可自由混用三种来源。路由机制详见 gitbooks/features/model-routing/。

5.2 17 个消息通道

文档列出的渠道覆盖 Telegram、Discord、Slack、WhatsApp、Signal、iMessage 等，并额外包含原生邮件（IMAP IDLE + SMTP），让 Agent 在你本来就停留的地方触达你。相关说明见 gitbooks/features/channels.md 与 gitbooks/features/integrations/。

六、人本、隐私与个性化

6.1 UI-first：无需配置文件与终端

项目定位强调"从安装到可用 Agent 只需几次点击"，不要求手写配置文件、不要求进终端；同时内置会说话、会回应、会记住你的 Mascot（吉祥物） 形象（前端资产可见于 app/public/lottie 与 app/public/tiny_mascot.riv）。

6.2 Privacy Mode：一个开关，强制纯本地推理

安全面设计为分层纵深：

• 设备端加密存储；
• **审批门（Approval Gate）**控制副作用；
• 密钥保存在操作系统钥匙串（OS keyring）；
• 可选 沙箱（sandboxing）；
• 另有 Privacy Mode：只需拨一个开关，所有推理就不离开本机，且该约束在 Rust 核心层强制实施（而非仅靠 UI 层软约束）。

相关主题文档见 gitbooks/features/privacy-and-security.md 与 gitbooks/features/privacy-mode.md。

6.3 Themes 与 Theme Studio

支持五套主题族，并提供完整的可视化编辑器，主题可导出为 JSON。详见 gitbooks/features/theming.md。

七、与其他 Agent Harness 的高层对照

docs/README.de.md 与 README.md 都附了一张高层对照表（产品仍在快速演进，需与各厂商实际情况核验）。核心差异点归纳如下（🚀 表示文档自述优势项）：

维度	文档所述现状
开源	Claude Cowork 专有；OpenClaw / Hermes 为 MIT；OpenHuman 文档标注为 GNU（完整许可文本见 LICENSE）
上手难度	目标为"干净 UI、几分钟可用"，避免"先终端"路径
Memory	Memory Tree + Obsidian Vault，可选 agentmemory 后端，非 chat 限定
自动拉取	20 分钟周期同步进记忆（Auto-Fetch）
编排	Agent 图 + 检查点 + E2E 加密 A2A（对应普通单循环实现）
Workflows	可视化、持久化、Agent 提议、审批门控
会议	文档称可加入 Meet/Zoom/Teams/Webex、发言并提供实时转录
纯本地模式	一键强制的 Privacy Mode
可观测性	可回放运行日志 + 按次调用成本核算
Model Routing	内置自动路由（对应单一模型或手动切换）
原生工具	代码 + 搜索 + 抓取 + 浏览器 + 语音 + 媒体生成

需要说明：以上对照属于项目自述的高层定位，且"OpenHuman 在发布后一周内连续 9 天成为 GitHub 趋势榜首"同样来自仓库 README 的自我陈述，引用时请标注出处。

八、安装与终端安装路径

官方 README 推荐的安装入口是把各平台原生安装包作为首选（能获得正常的签名/完整性校验）。仓库内另有专门的 INSTALL.md 汇总终端安装命令，摘要如下：

• macOS（Homebrew Cask）：brew install --cask openhuman
• Linux（Debian/Ubuntu，.deb）：从发布页下载 OpenHuman_<version>_amd64.deb（或 arm64）后执行 sudo apt-get install -y --no-install-recommends ./OpenHuman_*_amd64.deb，让 apt 解析运行时依赖（可规避 AppImage 在部分发行版上的 sharun / libgbm.so.1 等问题）
• Linux（Arch / AUR）：仓库内包含 packages/arch/openhuman-bin/ 配方，发布后可 yay -S openhuman-bin
• Windows：运行签名后的 .msi
• 手动安装：.dmg / .deb / .AppImage / .msi 均可从官方发布页直接获取

此外还有一条脚本安装路径（macOS/Linux 的 scripts/install.sh 与 Windows PowerShell 的 scripts/install.ps1，脚本本身位于仓库 scripts/install.sh 与 scripts/install.ps1）。文档明确警告：该路径不附带独立签名，无法做篡改检测，属于 unverified install，能走原生包就尽量走原生包。

九、从源码构建与贡献：环境、命令与本地校验

面向希望从源码构建或贡献的开发者，文档给出的"短路径"如下（均可在仓库中找到依据）：

1. 准备工具链：文档要求 Git、Node.js 24+、pnpm 10.10.0（package.json 中 packageManager 字段确认为 pnpm@10.10.0）、Rust 与 rustfmt + clippy、CMake、Ninja、ripgrep 及对应平台的桌面构建前置依赖。
   • 注意版本口径差异：仓库 rust-toolchain.toml 当前固定 channel = "1.96.1"（其注释说明 1.96 是 rusqlite 0.40 / libsqlite3-sys 0.38 所需 cfg_select! 宏的稳定版本），贡献前请以该文件与实际编译结果为准。
2. 克隆并初始化子模块：Fork 并克隆仓库后，必须先执行 git submodule update --init --recursive，再执行 pnpm install，以便拉齐随仓库分发的 Tauri/CEF 源码（可执行 git clone https://gitcode.com/GitHub_Trending/op/openhuman.git 获取本镜像仓库）。
3. 本地开发与校验命令（来自根 package.json 的 scripts，可对照确认）：
   • 纯 Web UI 开发：pnpm dev
   • 桌面外壳开发：pnpm --filter openhuman-app dev:app
   • 类型检查：pnpm typecheck
   • 格式检查：pnpm format:check
   • Rust 库检查：cargo check -p openhuman --lib
   • 完整校验还包括 pnpm lint、pnpm test、pnpm test:rust 等（见仓库 package.json）。

文档建议：首次贡献者从 CONTRIBUTING.md（Fork/PR 流程与本地校验命令）或 CONTRIBUTING-BEGINNERS.md（含面向 AI 编码 Agent 的复制即用提示词）开始。

十、继续深入仓库的第一手阅读清单

围绕本文主题，仓库内最有价值的本地证据链如下：

• 架构与主题文档入口：gitbooks/README.md、gitbooks/features/、gitbooks/developing/
• 记忆与知识库：gitbooks/features/obsidian-wiki/README.md、gitbooks/features/obsidian-wiki/memory-tree.md
• 编排与工作流：gitbooks/features/orchestration.md、gitbooks/features/workflows.md
• 工具与模型路由：gitbooks/features/native-tools/、gitbooks/features/model-routing/
• 隐私与个性化：gitbooks/features/privacy-mode.md、gitbooks/features/privacy-and-security.md、gitbooks/features/theming.md
• Rust 核心源码（前端的 Tauri 应用在 app/src-tauri/，核心库与各子系统在根 src/openhuman/ 下按 memory/、flows/、inference/、channels/、tools/、security/ 等领域组织）

阅读时请留意：当前项目整体处于早期 Beta，官方 README 明确提示"开发活跃、存在毛边"；文档中出现的集成数量、压缩比例、趋势排名等数据属于项目自述，不应视为经过独立验证的基准测试结论。