让 Claude Code 住进你的笔记库：Claudian 完全指南

这篇假设你已经装好了 Obsidian，会写笔记，但没接触过命令行、也没用过编程类 AI 工具。 读完并跟着做完，你会有一个能真正动手整理你笔记库的助手——不是给你一段文字让你自己复制粘贴，是它直接把三十篇笔记改好。

全文约 45 分钟，动手部分约 25 分钟。 第九章往后是进阶功能，第一次读建议直接跳过，用熟了再回来。

这是 Obsidian 系列三篇的第二篇：

1. 《不是又一个笔记软件：Obsidian 从下载到真正用起来》
2. 本篇——让 AI 住进笔记库
3. 《Obsidian 里的无限画布：Excalidraw 完全指南》

零、一句话看懂

一句话：Claudian 把编程智能体装进 Obsidian 的侧边栏，你的笔记库就是它的工作目录。

拆开说三层：

• 前台是 Obsidian 里的一个面板，你在里面说人话
• 后台是 Claude Code——一个真正能读写文件、执行命令的智能体（也支持 Codex、OpenCode 等）
• 它的活动范围就是你的库那个文件夹

所以它能做的事，不是”回答关于笔记的问题”，而是：

• 读：打开任何笔记，看得懂 [[wikilink]] 和属性
• 写：新建、改写、重命名、批量补 frontmatter
• 搜：全库检索，跨几十篇笔记归纳
• 跑：执行命令，比如跑一个批量出图的脚本

一、它和”AI 侧边栏”的根本区别

Obsidian 生态里的 AI 插件分两类，很多人一上来就选错，然后觉得”AI 也没多有用”。

1.1 检索型：把库做成索引，回答你的提问

代表是 Copilot 这类插件。它把你全库的内容做成向量索引，你问”我去年写过关于定价的什么”，它检索、总结、给你一段带出处的回答。

**它的输出永远在聊天框里。**你要用，得自己复制出来、自己粘进笔记、自己排版。

1.2 动手型：直接读写文件

Claudian 属于这类。你说”把 日记/ 下这三十篇里提到的书名提取出来，建一张索引表”——

它会：打开那三十个文件 → 提取书名 → 新建一篇《读书索引.md》→ 写进去 → 告诉你建好了。

你在 Obsidian 里刷新一下，文件就在那儿。

1.3 所以怎么选

两个都装完全没问题，它们不冲突。翻旧笔记用检索型，重构库结构、批量改写、生成新内容用动手型。

二、动手之前：你需要准备什么

这一章是新手掉队率最高的地方。九成人卡在这儿，卡的原因永远是同一个：面板装好了，但没给它凭证。

要跑起来需要四步，缺一不可：

1. 装 Claudian 插件（Obsidian 里）
2. 装 Claude Code（终端里，一条命令）
3. 给它凭证（订阅账号 或 API Key）
4. 在插件里选好模型

2.1 第一步：装插件

设置 → 第三方插件（新版叫”社区插件”）→ 浏览 → 搜索 Claudian → 安装 → 启用。

作者是 Yishen Tu，插件 ID 是 realclaudian——注意别搜错，市场里 AI 类插件很多。

装完右侧栏会多一个图标，点开就是对话面板。这时候你已经能打开它了，但一说话就会报错——因为后台还没有。

2.2 第二步：装 Claude Code

这一步要开终端。别怕，就一条命令。

• macOS：按 Cmd + 空格，输入 终端，回车
• Windows：按 Win 键，输入 PowerShell，回车

然后粘贴这条命令，回车：

npm install -g @anthropic-ai/claude-code

如果提示 npm: command not found（找不到命令），说明你电脑上还没有 Node.js。去 nodejs.org 下载安装包装一下，装完重开终端再来一次。

装完输入 claude --version，能打印出版本号就成功了。

2.3 第三步：给它凭证（最关键）

有两条路，选一条就行。

路线 A：官方订阅

如果你有 Claude 的 Pro 或 Max 订阅，在终端里输入 claude，它会引导你在浏览器里登录一次。登录完这台电脑就一直记着，不用管 API Key。

• 优点：不用算钱，包月用到饱
• 缺点：要有官方订阅，且订阅有用量上限

路线 B：API Key

按量计费，用多少花多少。Key 可以来自 Anthropic 官方 API，也可以来自第三方中转站。

这条路的细节——什么是 API、Key 从哪来、中转站怎么选、怎么避免踩坑——我在另外两篇里写透了，这里不重复：

• 《AI API 是什么？如何接入 Codex、Claude Code》
• 《中转站怎么选、CC Switch 与 Codex++ 怎么配》

给新手的建议：如果你只是想试试，先用中转站充个几十块，比直接开订阅便宜得多，跑通了再决定要不要包月。

2.4 第四步：在插件设置里确认几件事

打开 Obsidian 设置 → Claudian，重点看这几项：

• 模型：选一个。日常整理笔记用中档模型就够，复杂重构再换强的。
• 媒体文件夹（Media folder）：填你放图片附件的文件夹，比如 attachments。填了之后，笔记里的 ![[图片.png]] 它才知道去哪儿找，才能真的”看”到图。留空的话它只会去库根目录找。
• 排除标签（Excluded tags）：带这些标签的笔记不会被自动当作上下文加载。适合放隐私内容，一行一个，不带 #。
• 界面语言：可以切简体中文。

2.5 跑通的标志

在面板里输入一句最简单的：

库里现在有多少篇 md 文件？

它应该会搜一下然后给你一个数字。能答出这个数，说明四步全通了。

答不出来的话，看报错：

• 提示找不到 CLI → 第二步没装好，或路径要手填
• 提示鉴权失败 / 401 → 第三步凭证的问题
• 提示模型不存在 → 设置里的模型名和你的凭证不匹配（中转站常见）

三、界面导览

打开面板之后，你会看到这么几块。

3.1 输入框和发送

底部是输入框。默认按回车就发送。

如果你习惯用回车换行，设置里有一项 “需要 Command/Ctrl + Enter 发送”，打开之后回车变成换行，Cmd/Ctrl + Enter 才发送。写长指令的人建议打开。

3.2 标签页和会话

面板支持多个标签页，每个标签页是一条独立的对话。命令面板（Cmd/Ctrl + P）里有这几个命令：

• Open chat view — 打开对话面板
• New tab — 新开一个标签页
• New session (in current tab) — 当前标签页里重开一段新会话
• Close current tab — 关掉当前标签页
• Inline edit — 在笔记里直接就地改（第五章讲）

3.3 关联笔记

面板会跟当前打开的笔记建立关联。你在编辑器里打开哪篇，它就默认知道你在说哪篇。

这意味着大部分时候你不用说”帮我改 XX 笔记”，直接说”帮我把这篇的结构理一下”就行。

3.4 模式开关（三档）

面板上有一个模式切换，这是全文最该记住的控件，第七章会展开。先记住有三档：

• Safe（安全）——默认。改文件之前会先问你
• PLAN（计划）——只分析、只出方案，一个字都不改
• YOLO——全自动，什么都不问

四、第一次对话：三个真实任务

别一上来就让它干大活。按这个顺序试三个，你会很快建立起对它能力边界的直觉。

4.1 任务一：整理一篇乱笔记

找一篇你随手记的、结构很乱的笔记，打开它，然后在面板里说：

把这篇笔记重新组织一下：加上二级标题分段，把重复的内容合并，保留所有原始信息不要删。改完告诉我你动了哪些地方。

为什么这个任务适合第一次：范围小（一个文件）、可验证（你自己就能看出好没好）、可回退（改砸了 Cmd+Z 或者关掉不保存）。

注意最后那句”告诉我你动了哪些地方”。养成这个习惯，你才能知道它到底干了什么。

4.2 任务二：给一批旧笔记补属性

这是 Claudian 真正开始比人快的地方。

把 日记/ 文件夹下 2026 年 7 月的所有笔记，都补上 frontmatter：title 用一级标题的内容，date 用文件名里的日期，tags 里加上 日记。已经有 frontmatter 的不要覆盖，只补缺的字段。

先只给三篇试水：把上面的 2026 年 7 月 换成具体的三个文件名，跑一遍，检查结果，确认无误再放全量。

这个”先试三篇”的习惯能救你很多次。

4.3 任务三：从网页内容生成笔记

Obsidian 有个核心插件叫网页阅读器（Webviewer），能在 Obsidian 里直接开网页。开着它看文章，选中一段文字，然后在 Claudian 面板里说：

把我选中的这段整理成一篇读书笔记，放到 零散/ 下面，文件名用文章标题，末尾加上原文链接。

它能直接拿到你选中的内容——不需要你复制粘贴。

五、上下文机制：它到底看得见什么

**这一章是全篇的核心。**你和它对话的质量，九成取决于它手里有什么信息。

5.1 它看得见的五种东西

一、当前关联的那篇笔记 你在编辑器里打开的那篇，自动带上。

二、你用 @ 点名的文件 在输入框里打 @，会弹出文件列表，选一个或几个。这是最精确的给上下文方式。

三、你在编辑器里选中的那段文字 选中之后再提问，它拿到的是”这段”，而不是整篇。要改一小块时特别好用。

四、你在网页阅读器里选中的内容 上一章任务三用的就是这个。

五、它自己搜索、自己打开的文件 你说”库里所有提到 X 的笔记”，它会自己去搜、自己去读。这是它和检索型插件的关键差别——它能主动扩展自己的上下文。

5.2 它看不见的五种东西（同样重要）

一、你脑子里的背景和偏好 “帮我整理一下”——按谁的标准整理？它不知道。所以要么在指令里说清，要么写进第八章的 CLAUDE.md。

二、没提到、也没被搜到的旧笔记 它不是把你全库都读进去了。它只看到你给的 + 它搜到的。

三、其他软件里的内容 浏览器里开着的网页（除非用 Obsidian 内置的网页阅读器）、微信里的聊天记录、你桌面上的 Word——都看不见。

四、上一个会话里说过的话 新会话是全新的开始。这是好事（干净），也要记住（该交代的背景要重新交代）。

五、库以外的目录 默认它只能在库里活动。想让它看库外的东西（比如你的代码项目），要用”外部上下文”单独授权，见第九章。

5.3 一条能立刻用上的经验

提问最省力的顺序：先给上下文，再说要干什么。

对比这两句：

• ❌ “帮我把那篇讲定价的笔记改一下结构”——它得先猜哪篇，再猜怎么改
• ✅ 先用 @ 点名文件，或者选中要改的段落，然后说”把这部分改成三个小标题分段”

第二种方式又快又准，还便宜（因为它不用到处搜）。

六、Inline edit：不用切面板的改写

命令面板里那个 Inline edit，是日常用得最顺手的功能。

用法：在笔记里选中一段文字 → 触发 Inline edit → 输入你的要求 → 它直接在原地改。

适合的场景：

• 这段话太啰嗦，压缩成一半
• 把这段改成列表
• 这段翻译成英文
• 这几行代码加上注释

它和面板对话的区别：面板适合”多轮讨论、跨文件的活”，Inline edit 适合”这一段，就地改，改完就走”。

建议给它配一个快捷键（设置 → 快捷键 → 搜 Inline edit），用起来跟按加粗一样自然。

七、权限与安全：先划红线，再放它干活

7.1 三档模式

面板上那个模式开关，三个档位的实际含义：

Safe（安全）——默认，也是你 90% 时间该待的档 读文件、搜索、新建笔记它会直接做；但修改已有文件、删除、重命名、执行命令之前，会先弹出来问你。你看一眼它要改什么，点同意或拒绝。

PLAN（计划）——只说不做 它会分析、会给你一整套方案，但一个字都不会改。

这个档位被严重低估了。大改动之前先在 PLAN 模式下过一遍，看看它打算怎么干，觉得靠谱再切回 Safe 让它执行。这个习惯能挡掉绝大多数”它理解错了我的意思”。

YOLO——全自动，什么都不问 它想干什么就干什么，不再征求你同意。

什么时候用它？**当你已经在 PLAN 模式下确认过方案、并且刚刚做过备份的时候。**跑一个几十个文件的批量任务，一个一个点同意会点到手软，这时候 YOLO 是合理的。

其余任何时候，别用。

7.2 它的默认边界

它的活动范围就是你的库这个文件夹。库以外的目录，默认碰不到，必须你手动授权（第九章）。

这个边界是实打实的，不是靠”提示词里让它别乱来”实现的。

7.3 三条自保规矩

这三条我建议你直接抄进 CLAUDE.md。

一、大批量改动之前，先做一次备份。

如果你配了 Git（篇一第 10.10 节），就是一次 commit。没配 Git 的话，把整个库文件夹复制一份，改名叫”改之前”。

三十秒的事，能救你一晚上。

二、第一次让它批量改，先只给三篇试水。

确认它理解对了你的意思，再放全量。这条在第四章说过，值得再说一遍。

三、它说”已完成”不等于做对了。

大模型会犯的错里，最危险的一类不是”做不到”，而是”做了但做歪了，还很自信”。

抽查两篇再收工。花一分钟。

八、给它立规矩：CLAUDE.md

8.1 为什么需要这个

你每次都要交代”用简体中文”、“改之前先问我”、“这个库的日记都放在 日记/ 下”——重复第三次的时候你就该把它写下来了。

在库的根目录建一个叫 CLAUDE.md 的文件，把这些规矩写进去。以后每次对话它都会自动读。

8.2 三层优先级

规矩分三层，越靠上越优先：

1. 你这一句话里的指令——正在说的这句，压倒一切
2. 库级 CLAUDE.md——放在库根目录，管这个库里的所有会话
3. 全局 CLAUDE.md——在 ~/.claude/CLAUDE.md，管你所有项目的通用偏好

分层的意义在于：**通用偏好写全局，库的具体情况写库级，临时要求直接说。**不要把同一条规矩写在两个地方，冲突的时候你自己都搞不清哪条生效。

8.3 一份可以直接抄的库级模板

在库根目录新建 CLAUDE.md，填这些：

# 这个库是什么

我的个人笔记库。内容以读书笔记、项目记录、日记为主。

# 目录约定

- `日记/` — 每天一篇，文件名格式 2026-07-22.md
- `项目/` — 每个项目一篇，进行中的加 #active 标签
- `零散/` — 未归类的想法，随时可能被我搬走
- `attachments/` — 所有图片附件统一放这里

# 写作约定

- 所有笔记用简体中文
- 笔记之间用 [[wikilink]] 关联，不要用相对路径链接
- frontmatter 必须有 title、date、tags 三个字段

# 红线

- 不要删除任何文件，需要删除时先问我
- 不要动 `归档/` 文件夹里的任何东西
- 批量修改超过 5 个文件之前，先列出清单让我确认

**别一次写太多。**先写五六条你最常重复的，用一阵子，觉得它老是搞错某件事，再补一条。

8.4 全局该写什么

全局那份 (~/.claude/CLAUDE.md) 放的是和具体库无关的偏好，比如：

• 说简体中文
• 先给结论，再给理由
• 不确定的时候直说，别编
• 不要写没验证过的东西

九、进阶功能（用熟了再看）

下面这些第一次读可以完全跳过。等你用了两周、开始觉得”每次都要重复交代同一件事”的时候，再回来。

9.1 外部上下文：让它看库以外的东西

面板里有一个”选择外部上下文”的入口，可以授权一个库以外的文件夹。

典型场景：你的笔记库里记着某个项目的设计思路，而项目代码在另一个文件夹。授权之后，你可以让它对照着代码来更新笔记。

授权是显式的、可撤销的。没有授权的目录，它访问不到。

9.2 Commands and Skills：把常用指令存成一条命令

存在库里的 .claude/commands/ 和 .claude/skills/ 文件夹，用 /名字 触发。

比如你每周都要写周报，可以把”从本周日记里提取要点、按项目分组、生成周报”这一整套指令存成 /周报，以后打三个字就够了。

9.3 Subagents：给不同的活配不同的助手

存在 .claude/agents/ 里，每个 Markdown 文件定义一个专用助手，可以单独指定它用什么模型、能用哪些工具、什么权限。

典型用法：配一个”只读”的检索助手（不给它写权限，专门用来翻旧笔记），再配一个”整理”助手。

9.4 MCP：接入外部工具

存在 .claude/mcp.json 里。MCP 是一套标准协议，让 AI 能调用外部服务——查数据库、调 API、控制浏览器。

新手完全用不到，知道有这么个东西就行。

9.5 其他提供方

Claudian 不只支持 Claude Code，设置里还能启用 Codex、OpenCode、Pi 等其他智能体。

如果你已经有 OpenAI 的订阅、或者想用别家的模型，可以在这里切。机制和上面讲的完全一样，只是后台换了个引擎。

十、一个真实工作流

说一个我自己在用的，你能直接照搬。

场景：维护一个教程库，每篇文章要配十几张示意图，图要能改、改完要能重新导出、还要能发到网站上。

做法：

1. 我用大白话跟 Claudian 描述每张图要讲什么
2. 它写一个 Python 脚本，脚本里存着所有图的文案和布局
3. 跑一次脚本，同时产出 Excalidraw 源文件（存进库里能手改）和 PNG（正文和网站用）
4. 想改文案，改脚本里那一行，重跑，两样同时更新

关键收益：图和源文件永远同步，不会出现”图改了源没改”。这套做法第三篇会细讲。

这个流程里 AI 做的事，不是”帮我想图里写什么”（那是我的活），而是”把我的想法翻译成能重复执行的脚本”。

这也是我对这类工具的整体判断：它最强的地方不是替你思考，是替你把想清楚的事精确地、可重复地做出来。

十一、翻车速查

面板打得开，一说话就报错 九成是凭证问题。看第 2.3 节。报错里有 401 就是 Key 或余额，有 model not found 就是模型名对不上。

提示找不到 Claude CLI 先在终端里输 claude --version 确认装没装上。装上了但插件找不到，就手动填路径（第 2.2 节）。

它改错了文件，怎么回退

• 刚改完还没关：在 Obsidian 里 Cmd/Ctrl + Z
• 已经关了：核心插件”文件恢复”里有历史快照
• 大批量改砸了：如果配了 Git，一条命令回退；没配的话，希望你做了备份

它说改了，但我看不到变化 Obsidian 有时候不会立刻刷新外部改动。切一下标签页，或者关掉笔记重开。

回答越来越飘，或者答非所问 会话太长了。新开一个会话（New session），把必要的背景重新说一遍。

它老是搞错同一件事 别每次都手动纠正——写进 CLAUDE.md（第八章）。

费用比预期高 三个原因，按概率排：会话开太久没重开、让它读了太多不必要的文件、用了最贵的模型干最简单的活。 对策：勤开新会话、多用 @ 精确点名、日常任务换中档模型。

十二、接下来

用熟这个工具的路径，我建议是这样：

• 第一周：只用 Safe 模式，只干单文件的活，建立信任
• 第二周：开始批量任务，养成”先 PLAN 再执行”和”先试三篇”的习惯
• 第三周：写你的 CLAUDE.md，把重复交代的话固化下来
• 之后：需要什么学什么，第九章那些进阶功能，用到了再翻回来

本系列另外两篇：

• 不是又一个笔记软件：Obsidian 从下载到真正用起来
• Obsidian 里的无限画布：Excalidraw 完全指南

前置知识（凭证那一步卡住了就看这两篇）：

• AI API 是什么？如何接入 Codex、Claude Code
• 中转站怎么选、CC Switch 与 Codex++ 怎么配