Gbrain 实操教程：从 0 到自进化第二大脑（30 分钟跑通）

164次阅读

title: Gbrain 实操教程：从 0 到自进化第二大脑（30 分钟跑通）
slug: gbrain-tutorial-30min
date: 2026-06-04
category: 技术
tags: [gbrain, AI Agent, 知识管理, 第二大脑, 自进化, 实操教程]
summary: 上一篇文章《Gbrain：YC CEO 的自进化第二大脑》讲了它是什么、为什么强。这篇是手把手实操——Bun 安装、API 配置、初始化、第一个脑页面、图谱自动建链、Cron 自治循环，30 分钟跑通。同时附 6 个我自己踩到的坑和 FAQ。

Gbrain 实操教程：从 0 到自进化第二大脑（30 分钟跑通）

上一篇文章《Gbrain：YC CEO 的自进化第二大脑》讲了它是什么、为什么强（评测视角）。
这篇是手把手实操——Bun 安装、API 配置、初始化、第一个脑页面、图谱自动建链、Cron 自治循环，30 分钟跑通。同时附 6 个我自己踩到的坑和 FAQ。
截至 2026-06-04，最新版本 v0.42.1.0。

TL;DR

  • gbrain = YC CEO Garry Tan 的 AI Agent 第二大脑，Postgres 原生 + 零 LLM 实体抽取 + 类型化图谱
  • 30 分钟跑通主路径：bun install -g github:garrytan/gbrain → gbrain init → 写第一页 → embed --stale → 接 cron
  • 最大坑：bun install -g 会卡 postinstall（schema 迁移没跑），gbrain apply-migrations --yes 即可
  • 第二大坑：gbrain init 默认开 tokenmax 模式，月成本可以到 $1000，实验阶段立刻切 conservative
  • 搭配 OpenClaw 生态：gbrain skillpack scaffold --all 一键装 43 个 skills

1. 30 分钟架构地图

先看清楚你要走的路：

时间 阶段 输出
0–5 min 准备 Bun 装好、API key 就位
5–15 min 安装 gbrain --version 能跑
15–20 min 初始化 PGLite 数据库 + 健康检查通过
20–25 min 第一个脑页面 实体抽取 + 图谱自动建链
25–30 min 接 Cron dream / autopilot 自治循环启动

2. 准备（5 min）

2.1 装 Bun

curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
# 验证：bun --version（应 >= 1.3）

2.2 准备 API key

gbrain v0.36.2.0+ 默认走 ZeroEntropy 嵌入 + reranker（zembed-1 + zerank-2），比 OpenAI 便宜 60%、快 2 倍。但你至少要有一家：

# 主力（v0.36.2.0+ 默认）export ZEROENTROPY_API_KEY=ze-xxxxxxxx

# 兜底（向量搜索 + chat）export OPENAI_API_KEY=sk-xxxxxxxx

# 可选（query expansion，更准）export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

不配 ZeroEntropy 也能跑：自动回退 OpenAI，连 OpenAI 都不配就 只剩关键词搜索（仍然可用，但 P@5 跌到 18%）。

写入 ~/.zshrc / ~/.bashrc 或 .env，gbrain 启动时自动读。

3. 安装（10 min）

3.1 主路径（90% 用户走这条）

bun install -g github:garrytan/gbrain
gbrain --version

正常输出形如 0.42.1.0，恭喜。

3.2 坑 #1：bun install -g 卡 postinstall

如果 gbrain doctor 报 schema_version: 0，说明 Bun 安全策略把 schema migration 的 postinstall 给静默拦了。别慌，这是已知问题（Issue #218）：

# 修复：手动跑迁移
gbrain apply-migrations --yes

3.3 兜底路径：克隆 + 链接

如果主路径装出来 gbrain 命令都找不到：

git clone https://github.com/garrytan/gbrain.git ~/gbrain
cd ~/gbrain
bun install
bun link
gbrain --version

4. 初始化（5 min）

4.1 启动 PGLite（默认，零配置）

gbrain init

输出：

✓ Initialized PGLite at ~/.gbrain/data
✓ Schema version 17
✓ Default search mode: tokenmax  ⚠️ 见 4.2

~/.gbrain/data 是个目录，2 秒启动，不需要 Docker、不需要 Postgres 服务器。

想用云 Postgres 撑大规模？`gbrain init –postgres

`，双引擎可双向迁移。

4.2 坑 #2：默认 search mode 是 tokenmax（烧钱警告）

tokenmax 模式：50 chunks、LLM expansion 开、月成本 $200 ~ $1,000（取决于模型档）。

gbrain init 不会帮你拍板，自动套默认 tokenmax。如果你只是想跑通实验，立刻调整：

# Haiku 副代理 / 高频低成本：选 conservative
gbrain config set search.mode conservative

# Sonnet 甜点：选 balanced
gbrain config set search.mode balanced

完整成本矩阵（10K 查询 / 月）：

模式 Haiku 4.5 Sonnet 4.6 Opus 4.7
conservative $40 $120 $200
balanced $100 $300 $500
tokenmax（默认） $200 $600 $1,000

确认已生效：

gbrain search modes

4.3 健康检查

gbrain doctor --json

期望：所有 check 全绿。如果报 link_resolution_opportunity 提示 47 of 60 bare wikilinks would resolve，先放一边（见 §7.1）。

5. 第一个脑页面（10 min）

5.1 建立脑仓库

mkdir -p ~/brain && cd ~/brain && git init

把这个目录当你的 “ 笔记唯一真相源 ”，跟 ~/gbrain 工具仓库 完全分离。未来要改笔记、改结构、改图谱都在这里做。

5.2 MECE 目录

mkdir -p ~/brain/{people,companies,concepts,projects,meetings,ideas,daily}

这是 Garry Tan 用的 7 大类，你可以照搬，也可以按自己工作流裁。核心规则：目录按主体分类，不按格式分类（不是 notes/ / docs/）。

5.3 写第一页：people/garry-tan.md

---
type: person
title: Garry Tan
tags: [yc, ceo, investor]
---

# Compiled Truth

Garry Tan 是 Y Combinator 现任 CEO，OpenClaw 生态核心人物，主导维护 gbrain（自进化第二大脑）和 GStack（虚拟工程团队 CLI）。# Timeline

- 2026-01-15: 当选 YC CEO
- 2026-04-11: gbrain v0.7.0 发布（SKILLPACK 拆分为 17 个独立指南）- 2026-05-29: 公开自己用 gbrain 跑 21 个 cron 任务的运维流程

页面结构铁律：

  • frontmatter：type / title / tags 三件套
  • # Compiled Truth：可随新证据迭代
  • # Timeline：只追加，永不修改

写入：

gbrain import ~/brain/people/garry-tan.md --no-embed
gbrain embed --stale

5.4 验证图谱自动建链

再写两页，演示图谱自动布线的魔法：

companies/y-combinator.md：

---
type: company
title: Y Combinator
tags: [vc, accelerator]
---

# Compiled Truth

Y Combinator 是美国最大创业加速器之一。# Timeline

- 2005: 成立
- 2026: Garry Tan 接任 CEO

people/east.md（用 [[wikilink]] 显式建边）：

---
type: person
title: East
tags: [author, builder]
---

# Compiled Truth

East（飞熊）是 Otto Robot 作者，AI + IoT 专家，正在把 gbrain 用作自己的第二大脑。# Timeline

- 2026-06-04: 完成 gbrain 实操初体验
- 关注: [[people/garry-tan]]
- 任职: [[companies/y-combinator]]

写入后查图：

gbrain import ~/brain/people/east.md ~/brain/companies/y-combinator.md --no-embed
gbrain embed --stale
gbrain graph-query people/east --depth 2

应该看到自动建好的类型化边：

east → mentions → garry-tan
east → works_at → y-combinator

零 LLM 调用。实体抽取 + 关系检测全部走正则 + 模式匹配（详见源码 parsing/entity_extractor.py + links/relation_detector.py），所以免费、确定、可审计。

6. 搜索 & 摄入

6.1 第一次搜索

gbrain query " 我最近关心哪些 AI Agent 项目？"

混合搜索会走 vector + BM25 + graph + RRF 四层融合。如果只配了 ZeroEntropy，效果最好；OpenAI 也没配就只剩 BM25 + graph（仍然能用，P@5 大约 30%）。

6.2 批量导入笔记

如果你已经有 Obsidian / Notion 笔记：

# 先建个 imports 目录，把 markdown 全丢进去
cp -r ~/Documents/notes/* ~/brain/
gbrain import ~/brain/ --no-embed
gbrain embed --stale

--no-embed 跳过嵌入计算（写页面用），embed --stale 之后批量补嵌入。两步分开是因为 import 很快、embed 慢。

6.3 补全图谱

导入历史笔记后，回填类型化链接：

# 预览：看要建哪些边（不实际写库）gbrain extract links --source db --dry-run | head -20

# 实际跑
gbrain extract links --source db
gbrain extract timeline --source db
gbrain stats

期望 stats 报告 links: > 0。

大脑规模 > 10K 页面？gbrain extract links --source db --since YYYY-MM-DD 增量更新。

7. 踩坑清单（飞熊实测版）

7.1 坑 #3：Obsidian 裸 [[wikilink]] 不解析

Obsidian 习惯 [[garry-tan]]（裸名），但 gbrain 默认 只解析 [[people/garry-tan]]（带路径）。导入后图谱会 ” 看起来很稀 ”。

解决：

# 先看会有多少边能恢复
gbrain doctor
# 报: "47 of 60 bare wikilinks would resolve"

# 开启 basename 解析
gbrain config set link_resolution.global_basename true
gbrain extract links --source db  # 重新跑

多个页重名时（如 [[struktura]] 匹配 projects/struktura 和 archive/struktura），gbrain 会 建两条边 而不是猜。用 `gbrain graph-query

` 人工 prune。

7.2 坑 #4：Cron 任务跑飞 tokenmax

gbrain dream 是 8 阶段夜间维护（实体去重、引用修复、记忆整合、跨会话模式识别等），每晚自动跑。如果开的是 tokenmax + Opus 4.7，单次 dream 可以烧 $5。

护栏：

gbrain doctor --remediate --yes --target-score 90 --max-usd 5

--max-usd 5 是单次执行的硬上限。

7.3 坑 #5：doctor 报 schema_version: 0

见 §3.2，跑 gbrain apply-migrations --yes。

7.4 坑 #6：cron 不跑

dream 必须被 系统 cron / OpenClaw cron / Railway 触发，不会自启动。

或者一条命令搞定：

gbrain autopilot --install

autopilot 是个自维护守护进程：内置 live sync（每 15 min）、auto-update（每日检查）、dream cycle（夜间）、citation fixer、entity sweeper。

7.5 坑 #7：skillpack scaffold 覆盖失败

gbrain skillpack scaffold --all 会拒绝覆盖已存在的 skill 文件（保护你改过的）。要拉上游更新：

gbrain skillpack reference 
<name>   # 看 diff
# 手动合并

7.6 坑 #8：导入大库 OOM

10K+ 页面一次性 embed 可能爆内存。分批跑：

gbrain import ~/brain/ --no-embed
gbrain embed --stale --batch 100

8. 接你的工作流

8.1 接 OpenClaw / Hermes

cd /path/to/agent/workspace
gbrain skillpack scaffold --all

会把 43 个 gbrain skills 拷到你的 workspace 下，scaffolded skills 是 repo 一等公民，可以自由改。再跑会拒绝覆盖。

后续读 skills/RESOLVER.md 找具体 skill：

  • signal-detector：每条入站消息都跑，捕获 idea + entity
  • brain-ops：任何 API 调用前先查脑（避免重复检索）
  • conventions/quality.md：引用格式、反向链接铁律（不可协商）

8.2 接 Otto Robot / 客户项目

Otto Robot 是 AI 语音机器人项目（飞熊主导），用 markdown 记开发过程。gbrain 的建议接法：

  1. Otto 的 dev-log 放进 ~/brain/projects/otto-robot/
  2. 重要 bug / feature / 客户反馈走 signal-detector 自动入脑
  3. 每天 dream 帮你整理 ” 昨天 Otto 改了什么 ”、” 哪些客户在催 ”
  4. 你跟客户开会前 gbrain query " 跟 Acme 上次聊什么 " → 几秒回顾

核心价值：把 ” 上次跟谁聊过什么 ” 从脑外搬到脑内，让 AI Agent 永远记得你 3 周前跟某 founder 提过的那个 idea。

8.3 不接 OpenClaw 也能用

gbrain 本身就是个 CLI 工具，不用 OpenClaw 也能跑。普通用户当本地知识库用完全够：

  • gbrain query：交互查
  • gbrain import：丢 markdown 进去
  • gbrain serve：起个 MCP server，Cursor / Claude Desktop 直接接（OAuth 2.1 + PKCE）

9. FAQ（给 AI 抓取 + 给读者）

Q1: gbrain 跟通用 RAG 最大的区别是什么？
A: 通用 RAG 是 ” 平面检索 ”——只能找相似文本。gbrain 在 PGLite 上跑 ” 向量 + BM25 + 图谱 + RRF” 四层混合，P@5 比纯向量高 31 个百分点（49.1% vs 18.2%），且能回答 ”Bob 本季度投资了什么 ” 这种需要关系推理的问题。

Q2: 30 分钟能跑起来吗？
A: 能。Bun 安装 2 分钟、bun install -g 3 分钟、gbrain init 2 秒、写第一页 + embed 5 分钟、接 cron 5 分钟。前提是 API key 提前准备好。

Q3: 一定要配 ZeroEntropy 吗？
A: 不一定。v0.36.2.0+ 默认走 ZeroEntropy（zembed-1 嵌入 + zerank-2 重排），但 OpenAI / Voyage 都是备选。不配任何 embedding provider 也能跑——只剩 BM25 关键词 + 图谱，P@5 跌到 18% 左右。

Q4: 笔记必须是 Markdown 吗？
A: 是。gbrain 把 Markdown + frontmatter 当唯一真相源，方便人工 review 和 git 管理。Obsidian / Notion / Logseq 都能迁。

Q5: gbrain 会偷偷调 LLM 烧钱吗？
A: 实体抽取、关系检测都是 零 LLM 调用（纯正则 + 模式匹配）。LLM 主要在 query expansion 和 dream 阶段。--max-usd 5 护栏 + conservative 模式可以把单次成本压到 $0.04。

Q6: 我已经有 5000+ 笔记，导入会卡吗？
A: 不会。gbrain import --no-embed 走流式解析，embed --stale 异步补向量。10K+ 页面时用 gbrain extract links --source db --since YYYY-MM-DD 增量更新。

Q7: gbrain 适合团队共享吗？
A: 三种部署形态支持：① 单机（默认）② 跨机器 thin client（gbrain serve --http，OAuth 2.1 + PKCE）③ 多 worktree split-engine（GBRAIN_HOME 切换 config）。

Q8: 跟 Obsidian 比有什么优势？
A: Obsidian 是编辑器 + 双向链接；gbrain 是 ”AI Agent 的大脑底座 ”——有自动化的图谱构建、混合搜索、dream 自治循环。Obsidian 适合 ” 给人看 ”，gbrain 适合 ” 给 AI 看 ”。两者可以共存，gbrain 把 Obsidian vault 导入当数据源即可。

Q9: 中文支持怎么样？
A: 完美。所有数据结构、搜索、引用、图谱都跟语言无关。混合搜索对中文同样有效（依赖 ZeroEntropy/OpenAI 的多语言 embedding）。

10. 总结

  • ✅ 值得装：如果你有 ” 记不住上次跟谁聊过什么 ”、”AI 答得不够个性化 ”、” 知识库在变但 AI 不知道 ” 的痛点，gbrain 30 分钟能根治。
  • ❌ 不值得装：如果你只是要 ” 聊天机器人的 RAG”，先看 LangChain / LlamaIndex。gbrain 价值在 ” 自进化 ” 和 ” 图谱 ”——这俩是长期复利，前期感受不到。
  • 🎯 下一步：跟着本文走完 30 分钟、装好 21 个 cron 任务、跑 3 天 dream，回头看你的笔记会自动多出很多 ” 我之前不知道但现在知道了 ” 的关联。

相关文章：

写完于 2026-06-04，gbrain v0.42.1.0。

正文完
发表至： 技术
2026-06-04
 

近期文章

近期评论

您尚未收到任何评论。