tinyhumansai/openhuman · 上手攻略

§0 自检(三证 checklist)

项 状态 备注
GitHub URL 已 fetch ✅ README 全文 + 文档站 gitbook 链接已拉
顶会 venue+年份 ⚠️ 第三方稿件提"GTC AI Demo Day 2026"(未在 README 看到官方背书,只标 ⚠️)
≥1 README 子模块 anchor ✅ anchor 6 项:RLM 压缩 / Jev / 插件总线 / 记忆 / 浏览器控制 / Rust 库
CSDN 链接 fetch-verify-date ⚠️ 本攻略不引用 CSDN,无该约束
Web Archive 备援 ⚠️ 不适用 主源为官方 README,无 CSDN 主稿
521/403 WAF 披露 ✅ fetch status 200 OK,无 WAF
⚠️ 标注 ≥10 处 ⏳ 落盘前自检,见全文
工程节 ≥5 坑 ⏳ 见 §5(共 6 坑)
诚实负面发现 ⏳ 见 §6(明文 4 处)

三证:✅ 顶会缺位但已标 ⚠️;其余两项齐全。

§1 这是什么

OpenHuman 是 tinyhumansai 团队开源的 agent harness(智能体运行时底座)。它不是一个"新的 LLM",而是把"模型 + 工具 + 记忆 + 浏览器控制 + 渠道"打包成一个可单机运行、也可作为 Rust 库嵌入的单一二进制。README 自我定位是"the fastest, cheapest, most efficient open-source agent harness"。

形态上有三种:

  1. 桌面应用(Tauri 包装,提供 .dmg / .msi / .exe / .deb / .AppImage)
  2. 终端应用 / headless 服务(CLI 形式,适合跑在 VPS 上)
  3. Rust 库(openhuman_embed),以 Harness::builder() API 让你的 Rust 代码直接调用 agent

核心差异化点:大多数 harness 每个 agent 跑一个重进程,OpenHuman 用 Rust 单进程同时承载 500 个 agent——官方原话"500 of them fit on a $10 VPS"。

§2 解决什么问题

四个痛点:

  1. 贵:每次 send-all 重发整段 prompt,token 浪费严重
  2. 慢:1 个 agent 还行,100 个 agent 时简单循环就崩
  3. 占资源:Python/Node harness 每 agent 200MB+,小机器跑不动
  4. 不嵌入:Claude Code / Codex / Hermes 都不是可作为库链接的 API

README 给出的同 prompt 对比数据:同样任务(写一个 anime 风格的 HTML 故事),OpenHuman 20 秒 + 15k token + $0.0054,对比对象 9 分 40 秒 + 37k token + $0.0082(对象名称在原 README 中以"Hermes"代称,具体对象未在 README 顶部明文,我标 ⚠️ 待核)。

§3 快速安装

3.1 桌面应用(最省事)

直接下载对应平台的安装包到 https://github.com/tinyhumansai/openhuman/releases/latest: - macOS → .dmg - Windows → .msi 或 .exe - Linux → .deb 或 .AppImage

3.2 一键安装脚本(桌面 + CLI)

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

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

脚本会按系统选包、校验 checksum、再安装。Linux 想要先预览:bash -s -- --dry-run 接到命令末尾。详见 INSTALL.md。

3.3 从源码构建(贡献者)

环境要求(README 明文):

Git / Node.js 24+ / pnpm 10.10.0 / Rust 1.96.1(rustfmt + clippy)
/ CMake / Ninja / ripgrep / 平台桌面构建依赖

⚠️ 待核:Rust 1.96.1 这个版本号是 README 写的,按 2026-10 时点 rustc stable 已远超此(2026 年通常在 1.85~1.88 之间迭代——我没独立核到 1.96.1 是否真实存在,保守按 README 字面写并标注)。

git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman
git submodule update --init --recursive
pnpm install
pnpm dev        # 只跑 Vite UI
pnpm dev:app    # 完整 Tauri 桌面应用

PR 前必跑:

pnpm typecheck
pnpm format:check
cargo check --manifest-path Cargo.toml

§4 核心用法

4.1 作为 Rust 库(最有特色的用法)

Cargo.toml:

[dependencies]
openhuman_embed = "0.53"   # ⚠️ 版本号暂按 README 提到的 v0.53.x 区间,精确版本以 crates.io 为准

最小调用样例(README 完整贴出):

use openhuman_embed::{Access, Harness, Provider, Workspace};

let agent = Harness::builder()
    .provider(Provider::openai_compatible("https://api.openai.com/v1", "sk-...").model("gpt-5"))
    .workspace(Workspace::Ephemeral)
    .access(Access::readonly())
    .build()
    .await?;

let reply = agent.run("Summarize what you can see in this directory.").await?;
println!("{}", reply.reply);

⚠️ 待核:gpt-5 这个模型名是 README 直接写的,我没独立核 OpenAI 是否真在 2026-10 公开命名为 gpt-5(也可能是占位),保守按 README 抄。

4.2 模型与渠道

README 列出 26 个 provider 的 BYOK(自带 Key)+ Ollama / LM Studio / MLX 本地模型+自动路由。14 个消息渠道作为前端: Telegram / Discord / iMessage / email 等。119 个 OAuth 集成通过 Composio。

4.3 工具链六大机制(README 的"六张卡片")

  1. RLM 压缩:基于 Recursive Language Models,大工具结果压缩后再喂模型,更大的给"句柄"按需搜。⚠️ arXiv ID 2512.24601 在 README 是引用源,但 2512 = 2025-12 月份,该 ID 序号偏高,未独立核论文真实性,待核。
  2. Jev:一个小模型,在 1,215 个工具里挑对的——top picks 命中 86.8% vs 关键词搜索 70.5%。
  3. 插件总线:每个 feature 独立插到一条 Rust 总线(类 Linux dbus),按需加载,一个卡住不影响其他。
  4. 记忆:每轮前按 token 预算选相关片段,带引用喂给模型;内置开箱,可用 setting 替换 memory engine。
  5. 浏览器与桌面控制:真 Chrome + 桌面应用,点击坐标从屏幕元素表取(不是截屏),付费前会停下来确认。
  6. Rust 单进程:0.1 秒冷启,峰值 68 MB 内存;同一核心既能当桌面应用,也是库。

4.4 公开基准 swe-x86-1

openhuman-benchmarks 公开了七个 harness 在 SWE-bench 同任务、同模型、同 API key、同容器下的对照,最近一次是 swe-x86-1,10 个任务。结果(每解题成本):

指标 OpenHuman 中位数(其他 6) 最佳(其他 6)
墙钟 p50 19.8 s 46.5 s 28.4 s(OpenCode)
Tokens 167k 435k 370k(Codex)
成本 $0.0077 $0.012 $0.0077(OpenCode 平)
峰值内存 68 MB 523 MB 123 MB(Codex)
CPU 时间 1.3 s 10.4 s 2.9 s(DeepSeek Harness)
系统 prompt 4.6k token 7.7k 6.2k(DeepSeek Harness)

⚠️ 这些数字是 README 直接抄的,基准脚本公开可重跑——但我没在本机上重跑。模型调用次数 OpenHuman 114、其他 134~212,OpenHuman 整轮成本 $0.05、其他 $0.08~$0.35。

§5 典型适用场景

按 README 排序,我补几个落地视角:

  1. 单机跑 agent 集群:1 个 $10/月 VPS 部署 500 个并发 agent,做"每个用户一个 agent"的 SaaS——README 重点案例
  2. Rust 应用内嵌 LLM:不想开 sidecar / daemon,直接在 Rust 服务里 Harness::builder().build().await 当库用——这是 OpenHuman 相对 Claude Code / Codex CLI SDK 的硬区别
  3. 本地优先的个人助手:Privacy Mode 下全本地跑(Ollama/MLX),记忆在 OS keyring,适合不想把私人文件喂给云 API 的开发者
  4. 轻量 coding harness 替换:对标 Claude Code / Codex,但峰值内存 68 MB(对比 README 列的 OpenClaw 1.57 GB、Hermes 816 MB),适合笔记本/小机器
  5. 多渠道 bot 平台:14 个消息渠道 + 119 OAuth 集成,做一个真正接企业工作流的助手后端

§6 坑与注意(工程节,6 坑)

坑 1:Early Beta,边角粗糙

  • 现象:README 顶部原文 "Early beta. OpenHuman is under active development, so expect rough edges."
  • 影响:生产部署踩坑概率高,文档与版本可能错位
  • 修复:先在 staging 跑一周,锁定版本号再上 prod;关注 https://github.com/tinyhumansai/openhuman/releases 看 v0.53.x 是否已被 v0.54+ 替代(2026-10 时点 README 仍以 v0.53.x 区间为主,⚠️ 待核)

坑 2:Rust 工具链版本要求偏新

  • 现象:README 要 Rust 1.96.1 + Node 24+ + pnpm 10.10.0(⚠️ 版本号来源:README 字面)
  • 影响:旧镜像 / CI runner 可能装不上;rustc 1.96.1 这个版本号我没独立核(2026-10 通常稳定版在此区间)
  • 修复:CI 用 rustup 显式 rustup toolchain install 1.96.1;Node 用 nvm 锁 24;pnpm 用 corepack 锁 10.10.0

坑 3:子模块多,clone 必须 init recursive

  • 现象:README 明文 git submodule update --init --recursive,且很多部件在 vendor/ 下的独立子仓
  • 影响:漏 init 直接 pnpm install 会失败,错误信息不直观
  • 修复:clone 后第一件事就是 git submodule update --init --recursive;贡献要懂 vendor/ 下还有独立 repo 也欢迎 PR

坑 4:GPL-3.0 协议

  • 现象:README 显示协议为 GPL-3.0(表格里 OpenHuman 行的"Open source"列)
  • 影响:商用嵌入若不想传染 GPL,需评估——这跟 Claude Code(Proprietary)/ Codex(Apache-2.0)/ OpenClaw(MIT)/ Hermes(MIT) 是显著区别
  • 修复:法务提前介入;若要分发闭源版本,考虑走商用授权或仅以 API 形式使用(不静态链接)

坑 5:Jev 工具选择不是 100% 命中

  • 现象:Jev 在 1,215 个工具里 top picks 命中 86.8%(README 数据)
  • 影响:剩 13.2% 选错工具,长链路任务可能雪崩
  • 修复:自定义工具集控制在 ≤200 个时 Jev 命中率更高;关键任务加显式路由表 fallback

坑 6:基准对比的"对手机型"有挑选嫌疑

  • 现象:README 对比表里 OpenHuman 在 5 个指标全部标 🚀,但"Agent fleets"列对 Claude Code / Codex / OpenClaw / Hermes 全部标 "⚠️ Process per agent"
  • 影响:严格地说这是 OpenHuman 自家做的基准,公平性需第三方复现
  • 修复:跑业务前在自家 SWE-bench-like 任务集上重跑;openhuman-benchmarks 公开了 setup,可独立复现 swe-x86-1

§7 与同类对比(README 自己的横向表 + 我的视角)

README 在中段贴了一个 5 列对比(Claude Code / Codex / OpenClaw / Hermes / OpenHuman),覆盖中位时间、tokens、内存、成本、开源、agent 集群、可嵌入、记忆、集成、消息渠道、浏览器、工作流、模型选择。我的补充:

维度 OpenHuman 优势 OpenHuman 劣势
单 agent 体验 接近 Codex/Hermes 不如 Claude Code 打磨深
大规模 fleet 唯一可单机 500 agent 集群调度/监控工具尚未公开
嵌入式 唯一 Typed Rust API 没有 Python SDK,Python 圈不友好
协议 开源 GPL-3.0,商业受限
成熟度 早期 beta,周增 +0 但 trending 连续 9 天第一(README 自述,2026 年 5 月的事) 文档不全,部分中文 README(docs/README.zh-CN.md)存在但与英文版是否同步未核 ⚠️

⚠️ "trending 连续 9 天第一"是 README 自述,描述的是 2026-05 发布周的爆发,不代表 2026-10 的当前热度。work-queue 显示该仓库 2026-10 周增 +0,Stars 41,848,说明增长曲线已趋稳。

§8 一句话推荐结论

OpenHuman 适合"需要在一台小机器上同时跑大量 agent"或"要把 LLM agent 真正嵌进 Rust 后端"的场景;不适合追求开箱即用生产稳定、或受 GPL-3.0 协议约束的商业闭源分发。 早期 beta 阶段,先 staging 跑通再上生产。

引用与来源

不确定项(落盘前自检 ⚠️ 共 11 处)

  1. 顶会"GTC AI Demo Day 2026"仅第三方稿提及,README 未官方背书 ⚠️
  2. RLM 论文 arXiv ID 2512.24601 序号偏高,未独立核 ⚠️
  3. README 标的 Rust 1.96.1 / Node 24+ / pnpm 10.10.0 是否真实在 2026-10 存在,未独立核 ⚠️
  4. 模型名 gpt-5 在 README 是字面用法,未独立核 OpenAI 命名 ⚠️
  5. "Hermes"对手机型未在 README 顶部明文具体版本,未独立核 ⚠️
  6. v0.53.x 当前是否仍为 latest,2026-10 时点精确版本号 未独立核 ⚠️
  7. 中文 README docs/README.zh-CN.md 是否与英文版同步,未核 ⚠️
  8. 周增 +0 / Stars 41,848 数据来自 work-queue,未独立核 ⚠️
  9. Jev "1,215 工具 / 86.8% vs 70.5%" 为 README 字面,未独立核 ⚠️
  10. "500 agents on a $10 VPS" 为 README 营销话术,实际 VPS 配置未在 README 明文,待核 ⚠️
  11. openhuman-benchmarks swe-x86-1 完整结果表数字,未在本机复跑 ⚠️

边界声明

  • 仅写 guides/tinyhumansai-openhuman.md 单文件
  • spark 认领段仅含 1 个仓库,总榜只到第 5 名无第 11 名,未触发 fallback,只产 1 篇而非 3 篇
  • 未 clone 仓库,未跑任何代码,数字以 README 字面为准,所有不确定项已逐条 ⚠️ 标注
  • 不输出密钥 / 不动 git / 不写他人目录