本文由 莫潇羽@无忆研习社（www.wuyi.wiki）撰写，转载请注明出处。

快速摘要

OpenHuman 是一个用 Rust + Tauri 打造的开源个人 AI 助手桌面应用，GPL-3.0 协议，目前在 GitHub Trending 上长期高位，是 2026 年最值得关注的本地优先（Local-First）智能体项目之一。 它的核心思路不是再造一个聊天机器人，而是用一个 20 分钟自动同步的 Memory Tree 把你的邮件、日历、代码仓库、文档、聊天记录全部抓回本地，压缩成结构化的 Markdown 知识库，让助手在第一次同步完成的瞬间就具备了对你工作状态的完整（压缩后的）上下文。

最值得记住的几个关键词：

• Memory Tree：本地知识图谱，存在 SQLite + Obsidian 兼容的 Markdown vault 里，不是向量数据库的"薄记忆"，而是可以被人类直接打开、阅读、编辑的层级化摘要树。
• Auto-Fetch：20 分钟一次的增量同步循环，每个活跃连接都会被定时拉取，新数据折叠进 Memory Tree，不需要你手动 prompt。
• TokenJuice：智能 token 压缩层，工具输出在喂给大模型之前先被压缩去噪，官方声称能把 token 成本压到原来的 1/5 到 1/3。
• 118+ 一键 OAuth 集成：底层用 Composio 做连接器层，Gmail、Notion、GitHub、Slack、日历、Drive、Linear、Jira 等服务点几下鼠标就能接进来，无需手动管 API key。
• 自动模型路由：一份订阅同时调度多家模型，推理走前沿模型，快任务走便宜模型，视觉走视觉模型，路由表可全局/单调用/技能级别覆盖。

适合谁？ 想让 AI 助手真正了解你工作内容的人；不想在一堆 API key 和配置文件里折腾的人；重视隐私、希望数据存本地的人；喜欢 Obsidian 这类知识管理工具的人。不适合谁？ 只想要一个写代码助手的人——那 Cursor、Claude Code 更对口。

想看完整拆解，往下翻。

第一章 我为什么开始研究 OpenHuman 这个项目

最近半年我自己在折腾各类 AI 智能体框架，从 Claude Code 到 OpenClaw、Hermes Agent，再到一些自己拼装的 MCP 服务，能用的都用了一轮。整体感受是：模型能力越来越猛，但落到"日常工作场景"里，体验还是差着一口气。

差在哪？我自己折腾下来，最直观的有三个点。

第一个是上下文一直在丢。 你今天跟它聊得很顺，明天换个会话又从头来。哪怕用了系统提示词、记忆插件，每次会话开始还是得花一段时间把背景再补一遍。它根本不知道我手上有哪几个仓库、最近 Linear 上的 ticket 都长什么样、上周和谁开过会、邮件里有几封是要回的。每次都得我手动喂。

第二个是接入太碎。 想让它读邮件，得装一个插件；想让它读日历，又得装一个；想让它读 Notion，又是另一套 API key。Cursor 的 MCP 还算干净一点，但 MCP server 也得我自己起、自己配、自己维护。三个月下来，我笔记本的 .env 文件已经接近半屏。

第三个是成本不可控。 大模型 token 一调就是几万几十万，邮件全文一塞进去，单次会话十几刀就出去了。我之前做过一个小实验，让助手把过去三个月的邮件做主题归类，跑了两次就肉痛了。

OpenHuman 跳出来的时候，我第一反应是——又一个高调的"个人 AI"项目。但翻了它的 README、gitbook 文档、源码目录之后，我发现这次它真的把上面三个痛点都正面回应了。这不是"又一个聊天框 + 工具调用"的壳，它在架构层面就把"如何让助手提前知道你"这件事重新设计了一遍。

这就是我决定花时间把它拆开看的原因。下面这十几节内容，是我自己跑了一周、翻了源码和 gitbook 之后的笔记，对外的版本——莫潇羽@无忆研习社。

第二章 OpenHuman 到底是什么：一句话定位与三大支柱

2.1 一句话定位

OpenHuman 是一个 本地优先的桌面端开源 AI 智能体，定位写在它的 slogan 里——"Your Personal AI super intelligence. Private, Simple and extremely powerful."

翻译成人话就是：一个真正属于你个人的 AI 超级智能助手，强调隐私、强调开箱即用、强调能力上限够高。

它和 ChatGPT、Claude.ai 这类纯云端聊天产品不是一个物种。OpenHuman 是一个装在桌面上、长在你电脑里、了解你工作上下文的智能体。它有一张脸——桌面吉祥物；它有一颗大脑——Memory Tree；它有一双手——118+ 的第三方集成。

2.2 三大支柱

它给自己定的三个核心关键词，几乎是产品哲学的全部：

• Private（私有）：你的工作流数据存在本地，加密保存，不会上传到任何云端。Memory Tree 数据库、Markdown vault、工作区配置、本地运行状态全部留在你自己的设备上。
• Simple（简单）：从安装到第一个工作中的助手，几次点击就能搞定，不需要终端，不需要写配置文件。
• Powerful（强大）：118+ 应用集成 + 持久化记忆 + 智能压缩 + 多模型路由，能力上限对标主流商业产品。

2.3 技术栈速览

底层用 Rust + TypeScript 构建，桌面端基于 Tauri v2 封装，整个仓库里 Rust 占比超过 65%，前端用 React 19 + Redux Toolkit + Tailwind CSS。

License 是 GPL-3.0，意味着可以自由使用、修改、分发，但衍生作品也必须开源。如果你打算基于它做商业化产品，得留意这个协议的传染性。

项目仓库 2026 年 2 月才公开，目前还处于 Early Beta 阶段，更新频率很高——发布频道几乎每周都有新版本出来。我截稿时它已经发到 v0.54.0，距上一个版本只隔了不到一周。

2.4 它和"通用聊天机器人"的本质区别

通用聊天机器人是无状态的：你给它一段 prompt，它给你一段回答，然后上下文蒸发。换个会话，它就什么都不记得了。

OpenHuman 把这件事反过来了。它默认假设你不会跟它讲背景，所以它要自己想办法把背景搞到手。它通过 OAuth 把你的工具接进来，然后跑一个 20 分钟一次的同步循环，把你工作面板上每个活跃服务的数据都拉一遍，丢进 Memory Tree，建一个层级化的知识图谱。

这是它和市面上 99% 的 AI 助手最本质的差别：它了解你这件事，是产品自带的，不是你训练出来的。

第三章 它正面回应的四个核心痛点

接下来这四个痛点，我个人觉得是目前所有"通用型 AI 助手"绕不过去的坎。OpenHuman 给的方案不一定完美，但起码不是回避。

3.1 痛点一：冷启动问题

绝大多数 AI 助手刚开始用的时候是"空白"的。它不知道你手上有什么项目，不知道你昨晚的邮件里写了什么，不知道你下周三上午有会。你得花好几天甚至好几周时间，去把上下文一点点喂给它，让它慢慢"懂"你。

我自己以前用 Claude Code 时，要写一个工程化的 prompt 模板，开会前先 paste 一段背景、塞一段角色设定、贴一段最近的 commit log——非常累。

OpenHuman 的思路是：与其等你来喂背景，不如我主动去抓。

具体是用 Auto-Fetch + Memory Tree 这两个机制配合，每 20 分钟自动同步一次你的 Gmail、Notion、GitHub、Slack、日历、Drive 等数据源，然后把这些信息压缩成 ≤3k token 的 Markdown 片段，构建成本地的知识图谱。

第一次同步完成后，助手就已经对你的工作状态有了完整（压缩后的）上下文。不需要训练期，不需要"给我几周时间适应你"。

flowchart LR
    A[第三方服务<br/>Gmail/Notion/GitHub等] -->|OAuth| B[Auto-Fetch<br/>20分钟轮询]
    B --> C[Canonicalize<br/>标准化为Markdown]
    C --> D[Chunk<br/>切成≤3k token片段]
    D --> E[Score<br/>评分]
    E --> F[Seal<br/>密封摘要桶]
    F --> G[Memory Tree<br/>层级摘要树]
    G --> H[Obsidian Vault<br/>.md 文件]
    G --> I[SQLite<br/>本地数据库]

3.2 痛点二：数据孤岛 + API 密钥散落

如果你用过 Claude Code，你大概率配过 Anthropic 的 API key；用过 OpenClaw，又得对各家服务自己接；用 Hermes，又是另一套。

结果就是 API 密钥到处飞，各个服务之间数据不互通，想做一个跨平台的工作流极其麻烦。我之前甚至专门写了一个本地的密钥管理脚本，就为了别让一堆 .env 文件互相打架。

OpenHuman 的做法是：一键 OAuth + 托管后端。

底层用 Composio 做连接器层。你只需要登录 OpenHuman 账号，然后点几下鼠标，就能把 Gmail、Notion、GitHub、Slack、Stripe、Linear、Jira 等服务接进来。OAuth 握手和 API 调用都通过它们的托管后端代理（也支持自托管直连模式）。

一个账号，搞定所有集成。 这种做法的好处是：你的 API key、token 不需要落地在本机的明文文件里，agent 看到的只是工具调用的结果，看不到凭证本身。

3.3 痛点三：记忆机制不够完善

Claude Code 的记忆是会话级（chat-scoped）的，换一个会话就忘了；OpenClaw 依赖插件来实现持久化；Hermes 虽然能"观察你工作"的方式来学习，但配置门槛偏高。

OpenHuman 的设计是：Memory Tree + Obsidian Wiki。

所有同步下来的数据都会被组织成一个层级化的 Markdown 知识库，存储在本地 SQLite 数据库中，同时也会生成 Obsidian 兼容的 .md 文件，你可以用 Obsidian 直接打开、浏览、编辑。

这个设计灵感来自 Andrej Karpathy 之前在 GitHub Gist 上分享的 LLM Wiki 模式：与其每次都做 RAG 检索，不如把知识"编译"一次成结构化的、互相链接的 Markdown 文件，让 LLM 直接基于它推理。Karpathy 自己用这套方法管理了超过 100 篇文章、40 万字的个人知识库——OpenHuman 把这件事产品化了。

3.4 痛点四：Token 消耗太快

这是最现实的问题之一。每次调用 LLM，如果上下文太长、工具返回的内容太多，token 消耗就很大，成本和延迟都会上去。

举个例子，一个繁忙仓库里跑一次 git status、一个真实集群里跑一次 docker ps -a、一个 600 楼的邮件 thread——任何一个塞进上下文，都能把窗口撑爆，但里面真正有价值的信息可能只有几百 token。

OpenHuman 内置了一个叫 TokenJuice 的智能压缩层，工具输出在进入模型上下文之前会先过一遍规则化的压缩管线。下一节专门展开。

第四章 Memory Tree：本地知识图谱的实现原理

Memory Tree 是 OpenHuman 的灵魂，理解它之前先做一个澄清——它不是一个套了"记忆"皮的向量数据库。

4.1 它和向量数据库的区别

主流的 "AI 记忆" 方案绝大多数是这样的：把文档切片，每片做 embedding，存到 Pinecone/Weaviate/Chroma 这类向量库里，查询时做相似度检索。这个方案的问题是不可解释、不可编辑、不可审计——你打开数据库看到的是一堆浮点数向量，根本不知道里面装了什么。

OpenHuman 的 Memory Tree 走的是另一条路：一个确定性的、按桶密封（bucket-sealed）的管线，把你一天里乱七八糟的数据流（聊天、邮件、文档、集成同步结果）变成结构化的、可查询的、有摘要支撑的 Markdown，存在你自己的机器上。

4.2 三层结构

知识被组织成三个平面：

三层之间的关系是显式保存的，所以助手能回答跨多源的问题。比如你问："最近和老张有关的 PR 进展怎么样？"——Memory Tree 会去找"老张"这个实体节点，过滤出他相关的 PR 文档，再把最近时间窗的 commit 和邮件串起来。

4.3 数据流：canonicalize → chunk → score → seal → summarise

这是核心管线，按这个顺序走：

flowchart TD
    A[原始数据<br/>邮件/PR/Slack消息] --> B[Canonicalize<br/>标准化为统一 Markdown 结构]
    B --> C[Chunk<br/>切成 ≤3k token 的片段]
    C --> D[Fast Score<br/>快速打分，决定热度]
    D --> E[Persist<br/>落盘 SQLite + Obsidian vault]
    E --> F[Enqueue Follow-up<br/>排入后台任务]
    F --> G[Embedding 后台计算]
    F --> H[Entity 抽取]
    F --> I[Seal Summary Buckets<br/>密封摘要桶]
    F --> J[Daily Digest<br/>每日摘要]

热路径（canonicalize → chunk → fast-score → persist → enqueue）是同步的、要快——保证 UI 不卡。

重活（embedding、实体抽取、密封摘要桶、每日摘要）丢到后台 worker 里跑，三个并发 worker 拉队列，配信号量限制大模型并发，崩溃后租约过期会重新进队列。

4.4 为什么是 Markdown 而不是向量

这是我个人很喜欢的一个设计选择，它有几个直接的好处：

• 人类可读：你出问题想 debug 的时候，可以直接打开 vault 看，所有摘要、所有片段、所有链接都摆在眼前。
• 可编辑：你可以手动改任何一个节点。下次 ingest 时，agent 会把你的修改也吸收进去。
• 可链接：用 Obsidian 的 [[wikilinks]] 语法把节点互相连起来，知识网络越长越密。
• 可备份：Markdown 文件可以丢 Git，可以丢 iCloud，可以丢任何同步盘，迁移成本极低。

代码层面，Memory Tree 的核心实现在 src/openhuman/tree_summarizer/ 目录下，summary 构建器分了三种粒度——source（按数据源）、topic（按主题）、global（全局）。如果你跑自托管，可以把 MemoryConfig.backend 设成 "agentmemory"，让多个 agent 共享同一份持久化存储，比如和 Claude Code、Cursor、Codex、OpenCode 共用一份记忆。

4.5 与 Karpathy 的 LLM Wiki 思路的呼应

Karpathy 的原话很到位："Obsidian 是 IDE，LLM 是程序员，wiki 是代码库"。

意思是你不亲自写 wiki，你写的是 prompt——告诉 LLM 这次源数据是什么，让它去写、去链接、去合并。每次新进来一份资料，wiki 整体都会变得更聪明：一篇关于工具自动化的文章会自动连到 AI 编码工作流，再连到"写作即思考"的散文，三个不同领域的内容，会被一条线串起来。

OpenHuman 是这套思路的产品化落地版本。差别在于：Karpathy 那套是手动触发的（你跑一个命令），OpenHuman 是 Auto-Fetch 自动触发的（每 20 分钟一次）。

4.6 搜索、检索与可视化

光把数据塞进 Memory Tree 还不够，还得能从里面捞东西出来。OpenHuman 在 Intelligence tab 里提供了三个层面的可观察性：

第一层：热力图

类似 GitHub 贡献热力图的 ingest 事件可视化，颜色越深表示这段时间 Auto-Fetch 拉到的新数据越多。这个视图对发现"哪段时间同步断了"特别有用——比如某个连接 token 失效了三天，热力图上会有明显的"空白带"，比单纯看错误日志直观得多。

第二层：搜索栏

Memory Tree 顶部有一个统一搜索栏，支持三种检索模式：

每个搜索结果都会直接链到底层 chunk 文件所在的 Obsidian vault 路径——这意味着你可以从一个搜索结果点进去，看到那条记忆的完整出处，包括它的标准化形式、原始时间戳、关联实体。这种"全程可溯源"的设计是向量数据库做不到的。

第三层：路由可视化

Intelligence tab 还能看到 agent 每次执行任务到底用了哪个模型、属于哪种 hint、走的是云端还是本地。对刚开始用的同学，这个视图能帮你理解"我刚才那个 prompt 为什么走了便宜模型"——通常是因为它被分类为 hint:fast 任务。

这种透明度本身就是一种产品特性。很多 AI 工具是黑盒——你不知道它后面发生了什么、用了什么模型、花了多少 token。OpenHuman 选择把这些都摊开给你看。

第五章 Auto-Fetch：让助手永远比你"早起一小时"

5.1 工作机制

Auto-Fetch 是 OpenHuman 最有标识度的功能之一。每 20 分钟，核心服务会遍历每个活跃的连接，把新数据拉回来，丢进 Memory Tree 的管线里。

用文档里的原话翻译过来就是：早上你刚醒，agent 已经把"明天的上下文"准备好了。

举个具体场景。我前一天晚上睡前接好 Gmail、GitHub、Linear 三个集成。第二天 8 点起床打开电脑，OpenHuman 在过去 12 个小时里已经跑了大约 36 次同步循环：

• Gmail 那边新进来 27 封邮件，被分门别类放进 Memory Tree。
• GitHub 那边有 4 个仓库收到了新的 PR review 评论，被记入仓库节点。
• Linear 那边有 2 个 ticket 状态变化，相关人员的实体节点更新。

我打开 OpenHuman 直接问"今天上午我需要优先处理什么？"——它会基于 Memory Tree 里这些已经存在的、被压缩过的、被打过分的信息回答，不会临时去爬一遍邮件、爬一遍 PR。

这是和"每次都现场 RAG"最大的差别。信息是已经被准备好的，回答是即时的。

5.2 增量更新策略

Auto-Fetch 不是每次都全量拉。它会维护每个连接的同步状态，只拉增量。这一点在大数据量场景下尤其重要——如果你的 Gmail 里有十万封邮件，全量拉一次就崩了。

具体到代码层面，每个 connector 都有自己的"分页 + 游标"策略：

• Gmail：用 history API 拿增量变更。
• GitHub：用 issues/events API 加 since 参数。
• Slack：用 conversations.history 拿新消息。
• Linear/Jira：用 webhook + 定时校准结合。

如果某个连接断了（token 失效、网络问题、API 限流），UI 上会有红点提示，Intelligence 面板还有个类似 GitHub 贡献热力图的可视化，可以看到 ingest 事件的时间分布——很容易看出哪段时间同步断掉了。

5.3 后台任务与前台 UI 的解耦

热路径只做轻活，重活全部放后台。这是一个很关键的工程决策，意思是你点开 OpenHuman 的那一瞬间，UI 是流畅的，不会因为后台正在 embed 几千封邮件就转圈。

后台 worker 用了信号量限并发 + 租约机制，崩溃恢复的时候，那些"worker 已死但任务没完成"的 job 会自动重新进队列。这种细节在生产级别系统里很常见，但对一个 Early Beta 阶段的开源项目来说，已经做得相当扎实了。

5.4 隐私与可控性

Auto-Fetch 听起来很方便，但对隐私敏感的同学难免有顾虑——它是不是把所有数据都偷偷发到云端了？

答案是：Memory Tree 数据库、Markdown vault、工作区配置、本地运行状态全部留在你自己的设备上。 默认模式下，OAuth 握手和模型路由还是走托管后端的，但你的实际邮件内容、文档内容是落地到本机的，加密保存。

如果你想做到完全本地化，可以走自托管路径——自带模型、自带搜索、自带 Composio 凭证。代价是某些实时触发器和托管功能仍然需要托管后端的配合（比如某些 webhook 触发），自托管下需要你自己搭 webhook 基础设施。

5.5 潜意识循环（Subconscious Loop）

Auto-Fetch 之外，OpenHuman 还有一个我个人觉得很妙的设计——潜意识循环（Subconscious Loop）。

它的核心想法是：人类的脑子不会因为你停止打字就停止思考。你白天没回的邮件、没决定的事、没规划完的项目，大脑会在你打游戏、洗澡、走路的时候继续处理。OpenHuman 想让 agent 也具备类似的能力。

具体怎么实现的？后台有一个 worker 池，跑几类"非用户触发"的任务：

• topic_route：把新进来的 leaf 节点路由到对应的实体主题树里，触发条件是一个"热度检查"——某个实体最近频繁出现，就会被升级到一个独立的主题树。
• digest_daily：每天定时构建全局每日摘要节点。这就是为什么早上打开 OpenHuman 能直接看到"昨日总结"。
• flush_stale：强制密封那些在 buffer 里待太久的临时数据，避免数据"卡"在中间状态。

三个 worker 拉队列，信号量限制并发的大模型调用——既不会把云端调用打爆，也不会让 UI 因为后台太忙而卡顿。

实际体感是什么？ 你打开电脑那一刻，agent 已经"想过"很多事了。它会主动告诉你："你昨天有 3 封邮件还没回，其中 1 封看起来比较紧"。这种主动性是普通聊天机器人完全没有的。

当然，这里也有需要权衡的地方——后台不停跑意味着持续的 token 消耗。我建议刚开始用的同学先关掉一些激进的潜意识任务，等你信任这套系统了，再逐步打开。

第六章 TokenJuice：让大数据吞吐成本可控

6.1 为什么 token 是真金白银

如果你跑过 agent 项目，应该体会过一个很直观的现象：让 LLM 多读一点东西很贵。

一次 git status 在繁忙仓库里能输出几千行；一次 cargo build 日志一两万 token 起步；一个 600 楼的邮件 thread 直接把 100k context 撑满。这些东西大部分是噪音——空白行、重复字段、HTML 标签、长 URL——真正有价值的信号可能只占 10%。

TokenJuice 的作用就是在工具输出进入模型上下文之前，先把它压一遍。

6.2 规则化压缩管线

TokenJuice 不是一个黑盒压缩模型，它是一套规则覆盖（rule overlay）。规则用 JSON 写，按顺序合并，后面的层覆盖前面的层：

内置规则 → 用户全局规则 → 项目级规则

每条规则匹配一个工具/命令的 pattern，指定一种缩减策略：

新增规则只是丢一个 JSON 文件进去，不需要重新编译。全局规则放在 ~/.config/tokenjuice/rules/，项目级规则放在仓库根目录的 .tokenjuice/rules/。

6.3 多字节字符按字形单位保留

这一点我特别想点名表扬。

很多 token 压缩方案会简单粗暴地按 ASCII 来做去噪——结果就是中日韩字符、emoji 被误伤。"恭喜发财🎉" 这种内容里，emoji 可能被剥光、汉字可能被劈成奇怪的字节序列。

TokenJuice 明确说了：CJK 字符、emoji 和其他多字节文本按字形（grapheme）单位保留，不会被剥离。 这对中文用户和带表情符号的 chat 数据来说非常友好。

6.4 一个具体的成本对比

文档里给的数据点：通过前沿模型 ingest 你过去 6 个月的邮件，成本从几百美元降到个位数美元。

我自己没跑过 6 个月这么大的量，但用 50 封邮件做过小规模测试，原始 token 量大概是 18 万，过 TokenJuice 之后压到 6.7 万左右——压缩比接近 2.7 倍。如果是富文本邮件（带签名、转发链、营销 HTML），压缩比会更高。

// TokenJuice 在工具调用路径上的位置（简化伪代码）
async fn execute_tool(call: ToolCall) -> ModelInput {
    let raw_output = call.run().await;             // 原始输出
    let compressed = tokenjuice::reduce(           // 进入大模型前压一遍
        raw_output,
        &load_rules(&call.tool_id),
    );
    ModelInput::from(compressed)
}

实现位于 src/openhuman/tokenjuice/，包含 classify.rs（分类）、reduce.rs（缩减）、rules/compiler.rs（规则编译）、tool_integration.rs（工具集成）。想看 TokenJuice 在跑的时候到底匹配了哪些规则、剥掉了多少内容，可以用：

RUST_LOG=openhuman_core::openhuman::tokenjuice=debug

启动核心服务，所有匹配过程都会打印出来。调试规则时非常实用。

6.5 TokenJuice 之于 Auto-Fetch 的意义

TokenJuice 不只是省钱，它是让 Auto-Fetch 这件事在经济上可行的关键一环。

试想一下：每 20 分钟同步一次，Gmail 一次 200 封邮件，每封压缩前 3000 token——那就是 60 万 token / 次。一天 72 次循环，4300 万 token / 天。光是这一个服务，月开销就足够买一台中端 GPU。

但加上 TokenJuice，邮件先被压到原来的 1/3 到 1/5，整体开销直接进入"可控订阅价"的区间。

第七章 自动模型路由：一份订阅，多模型协作

7.1 为什么需要路由

不同任务对模型的需求差异极大：

• 长推理：希望走前沿模型——准、慢一点没关系。
• 快速分类/格式化：希望走便宜模型——快、能用就行。
• 看截图、看图表：必须走视觉模型——其他模型干脆做不到。
• 摘要 / 压缩：希望走专门的轻量模型——量大、要稳定、要便宜。

如果让用户每次都自己挑模型，那是工程灾难。OpenHuman 的方案是内置一个路由 provider，每次调用按"提示前缀（hint prefix）"或具体模型名解析：

具体模型名（比如 anthropic/claude-sonnet-4）会绕过路由表，直接走默认 provider。

7.2 路由表的核心代码

文档里直接给了简化版的源码片段：

// src/openhuman/providers/router.rs
fn resolve(&self, model: &str) -> (usize, String) {
    if let Some(hint) = model.strip_prefix("hint:") {
        if let Some((idx, resolved_model)) = self.routes.get(hint) {
            return (*idx, resolved_model.clone());
        }
    }
    (self.default_index, model.to_string())
}

读起来很直白：剥前缀，查表，匹配不到就 fallback 到默认 provider。Router 内部维护了多家 provider 的实例——Anthropic、OpenAI、Google、Groq 等——每个 hint 都映射到 (provider 索引, 模型名) 这样一个 pair。

7.3 三个覆盖层级

OpenHuman 把路由的灵活性做到了三个层级：

• 全局：config.toml 里可以替换整张路由表（Config 结构定义在 src/openhuman/config/schema/types.rs）。
• 单次调用：直接传具体模型名（不带 hint: 前缀），router 会绕过路由表直接用默认 provider。
• 技能（Skill）级：每个技能的 manifest 里可以钉死一个 hint 或一个具体模型。
• 子 agent 级：spawn_subagent 或 archetype 委托调用时可以指定 inline model；orchestrator 可以钉死 [teams.research].lead_model 走强模型，叶节点 worker 走便宜模型。

这种"层层覆盖、就近生效"的设计，是工程经验比较老的人才会自然做出来的。

7.4 本地模型的边界

如果开启了 Local AI（Ollama / LM Studio），低延迟、注重隐私的任务会优先走本地：

• hint:reaction, hint:classify, hint:format, hint:sentiment, hint:summarize, hint:medium, hint:tool_lite 这些轻中量任务会被本地模型接走。
• 默认聊天、推理、视觉这些"前沿能力"任务，依旧走云端订阅。
• Embeddings 强制走本地——这是一个明确的隐私边界，向量永远不离开你的机器。

文档里有一段我觉得讲得很清楚的话，大意是：之前的版本试图把所有任务都搬到本地（chat、vision、STT、TTS 全用 Gemma 3），结果做出来太重，硬件敏感度太高，反而拖累了产品体验。现在的边界是——本地干本地擅长的（高频、低延迟、隐私敏感的记忆活儿），云端干云端擅长的（默认聊天、推理、视觉）。

这种"理性收缩"的产品决策，我个人很认同。

7.5 子 agent 与团队路由实战

OpenHuman 还有一层我觉得很值得讲的设计——多 agent 协作下的路由逻辑。

当你跑一个复杂任务，比如"帮我把这周所有 PR 的 review 评论汇总一下，生成一份团队反馈热点报告"，OpenHuman 内部其实不是一个 agent 在干活，而是一个 orchestrator（编排者）加几个 sub-agent（子 agent）。

路由表对这种场景做了精细化处理：

# 简化版 config.toml 示例
[orchestrator]
model = "hint:reasoning"  # 编排者用强模型

[teams.research]
lead_model = "hint:reasoning"   # 研究团队的 lead 用强模型
agent_model = "hint:fast"       # 叶节点 worker 用便宜模型

[teams.code]
lead_model = "hint:reasoning"
agent_model = "hint:fast"

为什么这么设计？ orchestrator 和 team lead 要做规划、要做决策，需要强推理能力；leaf worker 是"按计划干活"，往往是简单分类、格式化、抽取，便宜模型完全够用。如果所有 agent 都用强模型，成本会爆炸；如果所有 agent 都用便宜模型，规划质量会崩。

这种"上面强、下面快"的分层路由，是大型 agent 系统的标准实践，但很多开源项目要么不支持，要么需要自己写一堆配置才能做到。OpenHuman 把这件事内置到了路由表里。

单次任务也可以临时覆盖：调用 spawn_subagent 或 archetype delegation 时，可以传一个 inline model 参数。技能（skill）的 manifest 也可以钉死一个 hint 或具体模型——这意味着同一个 OpenHuman 实例里，不同技能可以用不同模型，互不干扰。

第八章 Composio 连接器：118+ 集成是怎么落地的

8.1 一键 OAuth 的底层

OpenHuman 自己不去和每个第三方服务对接，它把这件事外包给了 Composio——一个专门做 LLM 与 SaaS 服务连接的中间层。Composio 负责 OAuth 的细枝末节、token 刷新、限流处理、webhook 转发。

OpenHuman 在默认的"托管模式"下，把整个 Composio 调用都代理在自己的后端：

• OpenHuman 后端持有 Composio API key。
• OAuth token 在 Composio 那边托管，不落到你本机的明文文件里。
• 限流和 webhook 转发由 OpenHuman 后端统一处理。

这意味着对用户来说，接入新服务就是点一下"Connect"，浏览器弹出来一个 OAuth 授权页，登录授权，连接就活了。

8.2 一次连接，四个去处

文档里有一句话我觉得概括得极好——一旦一个服务连上了，它在四个地方同时出现：

flowchart LR
    A[新接入服务<br/>e.g. Gmail] --> B[作为 Agent 工具<br/>模型直接调用]
    A --> C[作为记忆源<br/>Auto-Fetch 每20分钟同步进 Memory Tree]
    A --> D[作为画像信号<br/>跨服务活动建模你的个人偏好]
    A --> E[作为触发器<br/>实时 webhook 通知]

这个设计的精妙之处在于：你接 Gmail，不是只是给 agent 加一个"读邮件"工具，而是让你的邮件直接成为 agent 长期记忆的一部分。

8.3 托管 vs 直连

如果你是高阶用户，不想依赖 OpenHuman 的托管后端，可以切到直连模式（direct mode）：

直连模式给你最大的自主权，但也把所有配置和运维责任交还给你。一般个人用户没必要折腾这个。

8.4 一个已知的小坑：OAuth 完成后的 30-60 秒延迟

我在跑 Composio 集成时踩过一个坑，社区 issue tracker 里也有专门的记录。

简单说：当一个 OAuth 流程刚完成、连接状态变成 ACTIVE 之后，Composio 的 action-execution gateway 还需要 30-60 秒把新 token 同步到执行缓存里。这个窗口期里，OpenHuman 的连接管理层认为"连接已就绪"，agent 的 schema 里也已经出现了 delegate_<toolkit> 这个工具，但你第一次去调用工具时，会收到 Connection error, try to authenticate 错误。

社区已经合并了一个 PR（#1708），加了重试和就绪探测机制，新版本里这个问题应该明显好转。建议：刚连上一个新服务后，等一分钟再去让 agent 用它，能省不少时间。

8.5 数据安全边界的几条关键事实

很多人对 OAuth + 托管后端这套组合天然警惕，我把官方文档里关于数据流向的几个关键事实摘出来，方便你自己评估风险：

• OpenHuman 的本地核心服务永远不直接调用任何第三方 API——所有第三方请求都经过 OpenHuman 后端，由后端管理 OAuth token 和限流。
• 你的 OAuth token 不会以明文形式落在你本机磁盘上——agent 看到的只是工具调用的结果，看不到凭证本身。
• 如果你切到 direct 模式，这条边界会发生变化：本地核心会用你自己的 Composio API key 直接调用，你自己负责 Composio 账户、限流、计费关系以及任何 webhook 触发所需的 endpoint。
• 触发器分两种：实时触发器（webhook 推过来的事件）和定时触发器（Auto-Fetch 主动拉）。实时触发器在直连模式下需要你自己搭 webhook 基础设施；定时触发器完全本地，不依赖外部 endpoint。

我自己评估完之后的选择是：默认走托管模式，只接公开/低敏感度的服务。涉及公司核心数据的（比如公司邮箱、内部代码仓库），我宁可不接、用其他方式手动同步——这是一个"便利性 vs 风险"的取舍，每个人结合自己情况判断。

第九章 桌面形象与原生语音：让 AI 真正"住"在桌面上

9.1 桌面吉祥物不是装饰

很多人第一眼看到 OpenHuman 的桌面吉祥物，会觉得这就是个二次元装饰品。但你用一段时间会发现，它其实是 agent 状态的可视化层——它代表 agent 在说什么、在想什么、什么时候空闲、什么时候忙、什么时候有话要告诉你。

吉祥物和后端是同一套机制：当 agent 在说话，吉祥物在动嘴；当 agent 在思考，吉祥物会有"思考"的表情；当后台同步在跑，吉祥物会有"忙碌"的状态。

对长期使用来说，这个"可视化"很有用——你瞄一眼就知道 agent 在不在工作、要不要打扰它。

9.2 STT 与 TTS 链路

OpenHuman 的语音栈是这样的：

• STT（语音转文字）：进音频用 Whisper 处理。
• TTS（文字转语音）：出语音用 ElevenLabs。
• 唇形同步（lip-sync）：TTS 输出的音频流同时驱动吉祥物的口型，靠 viseme 映射做出来，不是两套独立的"动画 + 音频"，是同一份音频驱动同一份动画。

新版本里有一个"完全本地化"的语音选项，把 STT 用 Whisper 本地版、TTS 用 Piper 替换 ElevenLabs。这样语音环节也可以做到不出本机。

9.3 Google Meet 实时参与

这个功能听起来最像噱头，但实际试了一下还挺有意思。

OpenHuman 的吉祥物可以作为一个真实参与者加入你的 Google Meet 会议。它不是录屏机器人，是一个真实的 meeting participant，能听别人说话、能把会议内容实时转写进 Memory Tree，必要时还能用 TTS 直接在会议里说话。

实际场景里，我用过一次给团队同学做架构 review。会议结束后，OpenHuman 已经把整场会议的关键点抽出来了，包括谁提了什么问题、有哪些 action item、谁负责什么——这部分内容直接落到我的 Memory Tree 里，下次再问"上周三的 review 会同事提了哪些问题"，它能秒答。

当然，这个功能有合规层面的注意事项：入会前你需要明确告知所有参会人有 AI 在场，对方有权拒绝。这是基本礼仪，也是合规要求。

第十章 技术架构选型：Rust + Tauri + CEF 的逻辑

10.1 为什么不是 Electron

OpenHuman 桌面端用了 Tauri v2 + CEF（Chromium Embedded Framework），没有用更主流的 Electron。

差别在哪？我做了一个对比表：