Obsidian × Claude Code
让笔记变成可编程知识库

我折腾了两个月，终于把 Obsidian + Claude Code 跑通了。不是那种「理论上可行」的方案，是每天真在用、回不去的工作流。这篇讲透底层逻辑，附完整配置 — 你跟着做就能复现。

痛点：知识在本地，AI 在云端

用 AI 做知识工作，最大的痛点不是 AI 不够聪明，而是喂料太累。

你有没有过这种体验：

• Obsidian 里记了几千条笔记，想让 AI 帮你分析，却要一条条复制粘贴
• 跟 ChatGPT 聊完一轮很爽，但产出散落在聊天记录里，下次找不到
• 想让 AI 基于你的知识库写东西，但它根本不知道你以前想过什么

核心矛盾：你的知识在本地文件系统里，AI 在云端对话框里，中间隔着一道复制粘贴的墙。

Obsidian CLI + Claude Code 的本质，就是把这道墙拆掉。

为什么是这两个工具

Obsidian CLI：不是插件，是 Obsidian 内置的命令行

很多人不知道，Obsidian 从 1.8 版本开始内置了完整的 CLI。不需要装任何第三方包，你的 Obsidian 本身就是一个命令行工具。

# 不是 npm install，是 Obsidian 自带的
obsidian search query="AI Agent"
obsidian daily:read
obsidian tags counts=true sort=count

它能做什么？80+ 个命令，覆盖 Obsidian 几乎所有功能：

• 搜索、读写、创建笔记
• 操作每日笔记（日记）
• 查标签、查反向链接、查孤立笔记
• 管理任务（todo/done 切换）
• 甚至可以用命令行安装插件、管理主题

关键点：它的输出是结构化的纯文本（支持 JSON / TSV / CSV），天然适合被程序和 AI 消费。

Claude Code：不是聊天机器人，是一个能操作文件系统的 AI Agent

Claude Code 跟 ChatGPT 网页版的本质区别：它跑在你的终端里，能直接读写你电脑上的文件。

这意味着：

• 它可以调用 obsidian search 在你的知识库里搜东西
• 搜到之后直接读取笔记内容
• 理解、分析、改写之后，直接写回你的 Obsidian Vault
• 全程不需要你复制粘贴任何东西

两者结合 = AI 获得了一个结构化的接口来操作你的整个知识库。

架构：为什么 Markdown 是关键粘合剂

这个闭环能成立，有一个容易被忽略的前提：Markdown 同时是人类可读格式和机器可解析格式。

• 你在 Obsidian GUI 里写的笔记，AI 可以直接读
• AI 生成的内容，你在 Obsidian 里直接看，不需要格式转换
• 没有数据库锁、没有私有格式、没有导入导出

这跟 Notion 的区别在于：Notion 的数据锁在它的数据库里，你必须通过 API 才能碰到。而 Obsidian Vault 就是一个文件夹，里面全是 .md 文件，任何工具都能直接操作。

Step 1 — 确认 Obsidian CLI 可用

前置条件：

• Obsidian 1.8+（内置 CLI 支持）
• Claude Code（Anthropic 官方 CLI 工具）
• macOS / Linux（Windows 需要 WSL）

验证 CLI# macOS 上 Obsidian 安装后自带 CLI
obsidian version

# 如果提示 command not found，添加 alias
# zsh 用户在 ~/.zshrc 中加：
alias obsidian="/Applications/Obsidian.app/Contents/MacOS/Obsidian"

# 验证 vault 已识别
obsidian vault
# 应该输出你的 vault 名称和路径

Step 2 — 在 CLAUDE.md 中注册 CLI 命令

Claude Code 每次启动都会读取 CLAUDE.md 配置文件。在里面写上 Obsidian CLI 的说明，等于给 AI 装了一个「知识库驱动」。

核心写法：告诉 AI 有哪些命令可用、什么场景该用哪个、输出格式选什么。不需要写全部 80 个命令，写你最常用的 10 个就够了。

CLAUDE.md 示例配置## Obsidian CLI 整合

当前 Vault 路径：/path/to/your/vault
文件数：8000+

常用命令：
- obsidian search query="关键词" format=json    # 精准搜索
- obsidian search:context query="关键词"         # 带上下文段落
- obsidian daily:read                            # 读今天的日记
- obsidian daily:append content="内容"           # 追加到今天的日记
- obsidian tags counts=true sort=count           # 查标签分布
- obsidian backlinks file="笔记名"               # 查反向链接
- obsidian tasks todo                            # 查未完成任务

使用策略：
1. 用户问"我之前记过 XXX 吗" → 用 obsidian search
2. 用户说"帮我记一下" → 用 obsidian daily:append
3. 需要了解知识结构 → 用 obsidian tags

写完这段，Claude Code 就「知道」你有一个知识库，并且知道怎么查询它。

Step 3 — 开始对话：用自然语言操作知识库

# 在你的 vault 目录下启动 Claude Code
claude

# 然后直接用自然语言
> "搜一下我之前记过的关于 AI Agent 的想法"
> "把今天的会议要点记到日记里"
> "看看我最近一周写了什么"

从此你跟它对话时：

• "我之前写过关于 RAG 的笔记吗？" — 它会自动调 obsidian search query="RAG"，然后读取搜到的笔记，告诉你写过什么
• "把这段总结记到今天的日记里" — 它直接调 obsidian daily:append
• "我最近关注什么话题比较多？" — 它查你的标签分布，分析你的兴趣趋势

真实工作流：不是 demo，是每天在用的

场景 1：跨笔记的知识整合

这是 AI + 知识库最强的场景。手动做极其痛苦，但 AI 做起来很自然：

执行链路示例你："把我所有标记了 #投资 的笔记整理一下，提炼出我的投资逻辑"

Claude Code 的执行链路：
1. obsidian search query="tag:#投资" format=json  → 找到 23 条笔记
2. 逐条读取笔记内容                                 → 理解每条的核心观点
3. 交叉分析，提炼模式                               → 发现你的决策倾向
4. 生成结构化报告                                   → 写入新笔记

你自己手动做这件事要多久？打开 23 条笔记，逐条阅读，在大脑里做交叉分析，再写总结 — 最少两个小时。AI 两分钟。

场景 2：从笔记到发布内容

写文章最累的不是写，是找素材和组织结构。

从散乱笔记到文章草稿你："我想写一篇关于 AI 编程的文章，先看看我之前积累了哪些相关的想法"

Claude Code：
1. obsidian search query="AI 编程"  → 搜到 8 条相关笔记
2. obsidian search query="Cursor"   → 搜到 5 条
3. obsidian search query="Copilot"  → 搜到 3 条
4. 读取全部内容，梳理出大纲
5. 基于你的笔记（不是它自己编的）组织成文章草稿
6. 写回你的 Vault

输出的文章里面的观点、案例、数据，全部来自你自己以前记的笔记。AI 做的是整合和组织，不是凭空生成。这个区别很关键 — 这样产出的内容才是「你的」，不是 AI 味。

场景 3：知识库维护（孤立笔记清理）

Obsidian 用久了一定有这个问题：大量笔记没有链接，变成信息孤岛。

自动发现并修复孤立笔记你："帮我检查一下哪些笔记是孤立的，看看能不能链接到其他笔记"

Claude Code：
1. obsidian orphans               → 列出所有没有反向链接的笔记
2. 逐条读取内容
3. obsidian search 查找语义相关的笔记
4. 建议可以添加的 [[wikilink]]

一个 8000+ 笔记的 Vault，手动做这件事可能需要一周。AI 跑完一轮大概 10 分钟。

进阶：自动记录 AI 对话日志

这是这套系统里我认为最有价值的一个功能：不管跟哪个 AI 聊天，对话结束后自动存档到 Obsidian。

为什么需要这个

每天可能跟多个 AI 工具对话 — Claude Code、ChatGPT、Gemini。每个对话都有干货，但之前全散落在各家的聊天历史里，过几天就找不到了。

解决方案

利用 Claude Code 的 SessionEnd Hook：每次退出对话时，自动触发一段脚本，把对话摘要追加到今天的 Obsidian 日记里。

~/.claude/settings.json（Hook 配置）{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "~/.claude/scripts/session-end-logger.sh 'Claude Code'"
        }]
      }
    ]
  }
}

这段配置的意思：每次 Claude Code 的会话结束（你退出或 /clear），自动运行 session-end-logger.sh 脚本。脚本读取会话摘要，调用 obsidian daily:append 写入今天的日记。

写入格式大概长这样：

自动写入的日志格式## [14:32] Obsidian CLI 调研 | #Claude #AI工具 #2026-05
AI: Claude Code | 轮次: 约 12 轮
摘要: 研究了 Obsidian CLI 的 80+ 命令，发现可以用命令行装插件。
      配置了 CLAUDE.md 让 AI 自动查询知识库。

效果：退出 Claude Code，今天的日记自动多一条记录。完全不需要手动操作。过两个月想找「我什么时候研究过 Obsidian CLI」，一搜就出来。

性能实测

在一个 8000+ 文件、3GB 的 Vault 上测试：

高价值命令速查

80+ 个命令不需要全记。以下是实测后最常用的，覆盖了 90% 的日常场景：

Obsidian CLI 常用命令# ── 搜索 ──────────────────────────────
obsidian search query="关键词" format=json        # 精准搜索，返回 JSON
obsidian search:context query="关键词"             # 搜索并返回上下文段落

# ── 读写 ──────────────────────────────
obsidian read file="笔记名"                        # 读指定笔记
obsidian daily:read                                # 读今日日记
obsidian create name="标题" path="文件夹/"         # 新建笔记
obsidian append path="路径.md" content="内容"      # 追加内容
obsidian daily:append content="内容"               # 追加今日日记

# ── 分析 ──────────────────────────────
obsidian tags counts=true sort=count format=json   # 标签统计
obsidian backlinks file="笔记名"                   # 反向链接
obsidian orphans                                   # 孤立笔记
obsidian unresolved                                # 坏掉的 wikilink
obsidian tasks                                     # 全库未完成任务

# ── 管理 ──────────────────────────────
obsidian property:set file="笔记" name="tags" value="[标签1, 标签2]"
obsidian plugin:install id=插件ID enable            # CLI 装插件

推荐插件（配合 AI 工作流）

这些插件不是必须的，但装了之后整个知识库的能力会上一个台阶：

一次性安装全部推荐插件obsidian plugin:install id=dataview enable
obsidian plugin:install id=templater-obsidian enable
obsidian plugin:install id=obsidian-git enable
obsidian plugin:install id=smart-connections enable
obsidian plugin:install id=obsidian-kanban enable

Vault 结构优化

知识库目录混乱，AI 搜起来效率也低。推荐按 PARA 方法（Projects / Areas / Resources / Archive）整理：

推荐的 Vault 目录结构My-Vault/
├── Projects/           ← 有明确截止日期的项目
│   ├── 项目A/
│   └── 项目B/
│
├── Areas/              ← 长期持续的领域
│   ├── 工作/
│   └── AI系统/
│
├── Memory_Logs/        ← AI 对话自动存档
│   └── daily/          （每天自动生成）
│
├── Resources/          ← 参考材料、读书笔记
├── Archive/            ← 归档（不删，放这）
└── CLAUDE.md           ← Claude Code 全局配置

配套 Dataview 查询

装了 Dataview 后，在任意笔记里粘贴以下代码块就能自动生成看板：

Dataview：查看本周 AI 对话记录```dataview
LIST
FROM "Memory_Logs/daily"
WHERE file.mtime >= date(today) - dur(7 days)
SORT file.mtime DESC
```

Dataview：查看进行中的项目文件```dataview
LIST file.mtime
FROM "Projects"
SORT file.mtime DESC
LIMIT 20
```

局限性（诚实说）

这套方案不是银弹，有几个明确的限制：

1. Obsidian 必须保持运行。CLI 依赖 Obsidian App 的后台进程，不能完全无头运行。
2. 冷启动有延迟。每次 CLI 调用约 2 秒加载时间，不适合写脚本做高频批量操作。
3. 不替代 GUI。可视化的图谱浏览、Canvas 画板、复杂的模板插件，这些依然需要打开 App。
4. 需要一定的终端基础。如果你完全不用终端，上手成本不低。
5. Claude Code 需要付费。这不是一个零成本方案，AI 的 API 调用有费用。

它不是要替代 Obsidian 的图形界面，而是给知识库加了一个 AI 可以调用的 API 层。GUI 用来人工浏览和编辑，CLI 用来让 AI 做批量的、跨笔记的操作。两者互补。

更深一层：这指向什么趋势

Obsidian CLI + Claude Code 这个组合，本质上是一个更大趋势的缩影：

本地文件 + AI Agent = 个人知识的操作系统

• 你的笔记不再是被动的存储，而是 AI 可以主动查询和操作的数据库
• AI 不再是一个你去「访问」的服务，而是一个常驻在你工作环境里的助手
• 知识管理从「手动整理」变成「人机协作」— 你负责输入和决策，AI 负责检索、关联和加工

这个方向上，Obsidian 只是一个入口。未来任何以本地文件为基础的工具（笔记、代码、文档），都可以用同样的模式接入 AI。

关键不是用什么工具，而是理解这个范式：让 AI 能结构化地访问你的个人数据，把「对话式 AI」升级为「工作流 AI」。

总结

整个流程回顾：

1. 确认 CLI 可用 — Obsidian 1.8+，终端能跑 obsidian version
2. 写 CLAUDE.md — 注册常用命令 + 使用策略，让 AI 知道怎么查知识库
3. 自然语言操作 — 搜索、整合、写入，全程不碰文件管理器
4. 配置自动日志 — SessionEnd Hook + obsidian daily:append，对话记录零成本归档
5. 优化结构 — PARA 目录 + Dataview 查询 + 推荐插件，让知识库自己会「说话」

这不是一个需要学一周才能上手的复杂系统。核心就三步：装 Obsidian、写 CLAUDE.md、开聊。剩下的按需迭代。

实测环境：macOS + Obsidian 1.12 + Claude Code (Claude Opus)