Claude Code + Obsidian 搭建个人知识库：让 AI 记住你踩过的每一个坑

从零搭建 Obsidian 本地知识库并与 Claude Code 双向打通的完整实操。覆盖：Obsidian 初始化 → vault 目录结构 → Local REST API + MCP 集成 → 自定义 skill → 已有文档迁移。每节含原理说明 + 可复制的配置。

1. 为什么要搭这个

开发中沉淀的历史决策、踩坑记录、设计依据、Code Review 结论，这类信息外网搜不到。它们散落在企业微信文档、内网 Wiki、聊天记录和脑子里。三个月后再遇到同一个问题，你只记得"这个我修过"，但修法忘了。

目标很直接：本地建一个"第二大脑"，把这些结构化存起来，并且能被 Claude Code 检索到。这样 AI 回答你的问题时，用的是你自己的历史，而不是通用互联网知识。

方案选型

方案	优点	缺点	结论
Obsidian（本地 md + wikilink 图谱）	数据本地、不锁生态、图谱关联、插件丰富	需自己维护同步、无在线协作	选这个
Notion / 飞书 / 语雀	在线协作好、UI 漂亮	锁生态、导出难、外网依赖、检索 API 受限	不选
纯 git markdown 仓库	版本控制好、纯文本	无 wikilink 图谱、无 MOC 索引、检索靠 grep	不选
Logseq	大纲式、本地优先	大纲风格不适合长文档复盘	不选

核心诉求：本地优先（数据自主）+ wikilink 图谱（关联检索）+ markdown 纯文本（不锁生态）+ 能被 Claude Code 通过 API 读写。

跑了一段时间后的实际效果，关系图谱长这样（高亮的是 Claude Code 主题笔记簇，笔记之间靠 wikilink 自动连边）：

2. Obsidian 安装与初始化

原理

Obsidian 是本地优先的 markdown 编辑器。vault = 一个普通文件夹，所有笔记是 .md 文件，所有配置在 .obsidian/ 子目录。数据完全自主，可被任意编辑器或 git 操作。

实操

1. 下载安装 Obsidian（macOS：obsidian.md）
2. 启动后选「Open folder as vault」（不要选 “Create new vault”，会新建空文件夹）
3. 选择目标文件夹，例如 ~/Documents/knowledge_base
4. 进入设置 → 核心插件，按需关闭不用的（如"日记"“白板”）

关键约束

• vault 路径固定后不要随便挪：后面的 skill 里会写死这个路径，挪了要同步改
• vault 路径不要含空格和中文（避免某些插件路径解析问题）
• 一个 vault 够用，不要按项目分多个 vault，跨项目检索会失效

3. vault 目录结构

原理

数字前缀目录 + MOC（Map of Content）索引页，是 Obsidian 社区成熟的组织法。数字前缀保证目录排序稳定；MOC 是人工策展的入口，比纯关键词搜召回更准。

为什么不用 Zettelkasten 原子化：工程复盘适合"一篇文档讲清一件事"（一个系统设计、一次排障、一次 Code Review），不适合"一个原子笔记一个观点"。后者会产生大量碎片笔记，反而不利于理解。

目录

<vault-path>/
├── 00-Index/           # MOC 索引页
├── 10-Design/          # 设计文档
├── 20-Troubleshooting/ # 排障记录
├── 30-CodeReview/      # Code Review 报告
├── 40-RiskAssessment/  # 风险评估
├── 50-Snippets/        # 代码片段/技巧
├── 60-DailyLog/        # 日常记录
├── 90-Templates/       # 模板
└── 99-Attachments/     # 附件（图片/PDF，按笔记名建子目录）

模板

90-Templates/ 放 6 个模板，对应 6 类笔记：

模板	用途	关键字段
Design.md	系统设计	背景/总体架构/核心类/数据流/边界约束
Troubleshooting.md	排障	现象/环境/根因/排查/修复/验证/教训
CodeReview.md	CR 报告	按团队规范
RiskAssessment.md	风险评估	按团队规范
Snippet.md	代码片段	场景/代码/用法
DailyLog.md	日常	日期/事项

模板用 Templater 语法占位符：<% tp.file.title %>（标题）、<% tp.date.now("YYYY-MM-DD") %>（日期）。

MOC 索引页

每个分类一个 00-Index/XXX-MOC.md，再加 Home.md 作总入口。MOC 里每行一个笔记：

- [[笔记名]] — 一句话摘要

vault CLAUDE.md（这步最关键）

在 vault 根目录放一个 CLAUDE.md，规定 Claude Code 在 vault 里读写笔记的规范：

• frontmatter 必填：type / tags / project / date / status
• 命名规则：中文优先、不用空格、不用日期前缀、文件名唯一
• wikilink 语法：[[笔记名]] 不带 .md，不用相对路径
• 附件引用：![[filename.png]]，不用标准 markdown ![](path)
• MOC 维护：新建笔记后主动追加到对应 MOC
• 不要做的事：不擅自删原文、不加自己的评论、不引入 Zettelkasten

这是 Claude Code 在 vault 里的"宪法"，每次读写都会先读它。没有它，AI 写出来的笔记格式会飘。

一个现实偏差

vault CLAUDE.md 里我写了"必备插件：Templater、Local REST API；可选：Dataview"。但实际只装了 Local REST API：

• Templater：作用是给人工新建笔记时自动替换 <% tp.* %> 占位符。Claude Code 写笔记时直接替换占位符，不依赖它，所以不装也能跑
• Dataview：用于在笔记里动态查询其他笔记的元数据（如列出所有 status=active 的笔记）。当前没用上，需要时再装

结论：文档里的"必备 Templater"应该改成"可选（人工新建笔记用，Claude Code 不依赖）"。

4. Claude Code 集成（核心）

目标：Claude Code 能读 vault（检索历史笔记）、能写 vault（沉淀新笔记）。

4.1 Local REST API 插件

原理

Obsidian 是桌面应用，Claude Code 要读 vault 必须通过 HTTP API。obsidian-local-rest-api 插件在本地起两个服务：

• https://127.0.0.1:27124 —— HTTPS（自签证书）
• http://127.0.0.1:27123 —— HTTP（insecure，明文）

Claude Code 通过这个 API 读写 vault 文件、解析 wikilink。

实操

1. Obsidian → 设置 → 第三方插件 → 关闭安全模式
2. 浏览 → 搜 obsidian-local-rest-api → 安装 → 启用
3. 插件设置：
   • HTTPS 端口：27124
   • 启用 insecure server：勾选（端口 27123）
   • API key：点"生成新密钥"，记下这个 key（后面要用）
   • 证书：插件自动生成自签证书，不用管
4. 验证：

   curl -k -H "Authorization: Bearer <your-api-key>" \
     https://127.0.0.1:27124/
   

   返回 Obsidian 版本信息即成功。

注意

• API key 是本地密钥，泄漏了别人能读写你的 vault，不要进 git
• 自签证书：curl 要加 -k 忽略校验，mcp-obsidian 内部已处理
• 插件要 Obsidian 开着才工作，Obsidian 关了 API 就没了

4.2 mcp-obsidian 配置

原理

mcp-obsidian 是 MCP（Model Context Protocol）server，桥接 Claude Code 和 Obsidian Local REST API。Claude Code 通过 MCP 协议调用它的工具（mcp__obsidian__read_file / search / patch_file 等），不用直接发 HTTP 请求。

配在哪

位置	路径	作用
全局	<home>/.claude/settings.json	所有项目都能查 vault
vault 级	<vault-path>/.claude/settings.json	在 vault 目录里开 Claude Code 时自动加载

两处都配其实是冗余的，全局一处即可。vault 级配置的好处是不依赖全局配置，在 vault 目录里开 CC 时自动生效。两处都配不会冲突（API key 一致）。

实操

前置依赖：uvx 来自 uv（Python 包管理器）

brew install uv
# 或 pip install uv

配置：

"mcpServers": {
  "obsidian": {
    "command": "uvx",
    "args": ["mcp-obsidian"],
    "env": {
      "OBSIDIAN_API_KEY": "<your-obsidian-api-key>",
      "OBSIDIAN_HOST": "127.0.0.1",
      "OBSIDIAN_PORT": "27124"
    }
  }
}

验证：重启 Claude Code session，调用 mcp__obsidian__* 工具能返回 vault 内容。

4.3 自定义 kb-lookup skill

原理

skill 是 markdown 指令包（SKILL.md + frontmatter），告诉 Claude Code 在什么时机、用什么方法查 vault。

kb-lookup 走"显式触发"：用户说"查一下 / 沉淀过 / 之前怎么处理"才跑，不自动跑。这点很重要，否则每次对话都去查 vault，上下文会被污染。

三步查询法

1. 判断是否需要查：用户显式说"查一下"等信号 → 直接查；没明说但问题涉及项目特定历史决策 → 先问用户要不要查
2. 先读 MOC：按问题类型选 MOC（设计 → Design-MOC、排障 → Troubleshooting-MOC），从索引行挑候选笔记
3. 关键词搜补漏 + 图遍历：MOC 没命中时用 mcp__obsidian__search 搜关键词；命中后读正文，跟随 [[wikilink]] 跳关联笔记（最多 1-2 跳）

实操

skill 文件路径：<home>/.claude/skills/kb-lookup/SKILL.md

frontmatter 写明触发条件（description 字段是 Claude Code 判断是否调用的依据）：

---
name: kb-lookup
description: 查本地 Obsidian 知识库（vault 路径 <vault-path>）。当用户问及项目历史决策、过往踩坑、设计依据、Code Review 结论、可复用代码片段，且这些信息外网搜不到时调用。
---

正文写三步法 + “不要做的事”：

• 不绕开 mcp-obsidian 直接 Read 文件（会丢 wikilink 解析）
• 不修改 vault 内容（写笔记走 vault CLAUDE.md 流程）
• 不一次跟太多 wikilink 跳数
• 不在回答里贴大段原文

调用方式

• 显式：/kb-lookup <关键词>，或"用 kb-lookup 查 X"
• 隐式：用户说"之前怎么处理的 X" → Claude Code 自动判断是否调用

4.4 写入流程（vault CLAUDE.md 驱动）

原理

Claude Code 在 vault 里写笔记时，读 vault 根的 CLAUDE.md 拿规范，按 frontmatter 必填字段 + 模板 + MOC 维护规则操作。vault CLAUDE.md 是写入的唯一权威。

触发信号

满足任一即主动建议新建笔记（先问用户确认，不擅自动手）：

• 用户说"记下来 / 沉淀 / 整理成笔记"
• 排障完成（有根因 + 修复 + 验证）
• 设计评审完成
• Code Review 出报告
• 学到可复用片段或技巧

流程

1. 选 type → 决定目录和模板
2. 复制模板：90-Templates/<Type>.md → <对应目录>/<主题>.md
3. 填 frontmatter：type / tags（2-5 个小写英文）/ project / date / status
4. 替换占位符：<% tp.file.title %> → 实际标题，<% tp.date.now("YYYY-MM-DD") %> → 实际日期
5. 搬运内容：只搬运用户的内容 + 补 frontmatter 和路径修正，不加自己的评论、总结、修饰，不擅自删用户原文
6. 附件：图片放 99-Attachments/<笔记名>/，正文用 ![[filename.png]] 引用
7. 追加 MOC：在 00-Index/XXX-MOC.md 加一行 - [[笔记名]] — 一句话摘要

更新 vs 新建

• 同一问题的后续发现 → 追加到原笔记"后续/补充"段，不新建
• 同一系统的新模块 → 新建，但在原设计笔记"关联"段加 wikilink
• tags / frontmatter 不全 → 直接补，不用问

5. 已有文档迁移

分层处理

别想着把所有历史文档都精加工，二八法则：

层级	处理方式	占比预估	存放
核心文档（设计决策、踩坑、架构）	结构化重组：补 frontmatter + 进对应目录 + 加 MOC + wikilink	20-30%	10-Design 等
存档文档（会议纪要、通知、参考材料）	原样存档：最小 frontmatter + source 字段	70-80%	60-DailyLog 或 70-Archive

平台差异

平台	导出方式	图片处理
企业微信文档	无 API，手动复制或用 Obsidian Web Clipper 浏览器插件抓取	插件自动下载到本地
Confluence	HTML/XML 导出；单篇"导出为 Word"再 pandoc 转 md	导出时含图，需手动拆出
MediaWiki	Special:Export 或 pandoc	同上
自建 Wiki	看有无导出按钮；没有就复制粘贴	手动另存
通用招	MarkDownload 浏览器插件一键转 markdown	自动下载

关键约束

• 图片必须下载到本地：企业微信、Wiki 的图片 URL 会过期或要登录，不能保留外链
• 图片放 99-Attachments/<笔记名>/，正文用 ![[图片名.png]] 引用
• 存档文档也要补 source 字段：记录原链接，方便回溯
• 涉密文档先确认合规性：内部代码和设计文档进个人 vault 前先确认合规
• 图片命名：Web Clipper 下载的图名是随机串，重要图片建议重命名

推荐工具

工具	用途	装在哪
Obsidian Web Clipper	浏览器一键抓网页/Wiki 转 md + 下载图片	Chrome/Safari 扩展
MarkDownload	备选浏览器插件，markdown 导出	Chrome 扩展
pandoc	命令行格式转换（HTML/Word → md）	brew install pandoc

6. 踩坑与经验

1. 文档写了"必备 Templater"但实际没装也能跑。Templater 是人工新建笔记用的，Claude Code 直接替换占位符不依赖它
2. mcp-obsidian 配两处是冗余的。全局一处即可，vault 级是冗余但方便在 vault 目录开 CC 时自动加载
3. Local REST API 的自签证书：curl 要 -k，mcp-obsidian 内部已处理，不用管
4. 文件名必须唯一。wikilink 靠文件名解析，重名会解析错。中文优先，不用空格不用日期前缀
5. 不引入 Zettelkasten 原子化。工程复盘适合"一篇讲清一件事"，不适合"一个原子笔记一个观点"
6. vault 路径不要随便挪。skill 里写死了路径，挪了要同步改
7. Obsidian 关了 API 就没了。Local REST API 依赖 Obsidian 进程，后台退出 Obsidian 后 Claude Code 查 vault 会报连接拒绝。这是最常见的"突然不好用了"
8. skill 的 description 决定它会不会被调用。写得含糊，Claude Code 就不会触发；要把用户可能说的原话（“之前怎么处理的”、“沉淀过吗”）写进去
9. 环境里 WebSearch 不可用时，可以用 chrome-devtools MCP 控制真实浏览器补联网能力

7. 小结

整套链路拆开看只有四件事：Obsidian 装好并固定 vault 路径 → 目录结构 + 模板 + MOC 打底 → Local REST API + mcp-obsidian 把读写通道接上 → 用 CLAUDE.md 和 skill 把"什么时候查、怎么写"固化成规范。

真正决定好不好用的不是插件，是规范文件：CLAUDE.md 管写入，SKILL.md 管查询。这两个文件写清楚了，AI 每次沉淀出来的笔记格式一致、能被检索到，知识库才会越用越值钱；写含糊了，就是一堆 AI 生成的散装 markdown。