1. 为什么我要把 Obsidian 交给 Claude Code 管先说清楚 claude-obsidian 是什么它是一套跑在 Claude Code 里的技能Skills集合把 Obsidian 笔记库变成可被 AI 自动整理、自动打双向链接、自动归档来源的「第二大脑」。适合谁适合笔记已经攒了几百篇、但标签乱成一锅粥、双链基本靠手敲、每次想找半年前那条结论都要翻半天的个人知识管理用户。我自己的 vault 大概 600 多篇笔记之前的状态是文件夹按年份分标签有十几种写法#ai、#AI、#人工智能 混着用双链只在写的时候顺手加过两个月自己都忘了链到哪去了。真正让我下决心改造的是某次要写一篇关于 RAG 检索的稿子明明记得三个月前记过一段 BM25 的对比结果搜了二十分钟没找到——那一刻我意识到笔记不是记下来就属于你了能被重新调用的才叫知识。claude-obsidian 解决的就是这个「重新调用」的问题。它的核心思路是四步闭环保留来源 → 锚定声明 → 连接知识 → 重新使用。翻译成人话就是每篇笔记先记清楚从哪来的再把里面的关键结论标出来然后自动挂进已有的知识网络最后维护一套可检索的索引。这四步不是一次性的是每写一篇新笔记就跑一遍。它和普通 Obsidian 插件的区别在于插件通常只做单点功能比如自动打标签而 claude-obsidian 是一整套工作流由 Claude Code 驱动通过 15 个技能覆盖初始化、摄取、查询、维护、折叠、检索等环节。你可以把它理解成给 vault 配了一个不知疲倦的图书管理员你只管往里扔材料整理和归档它来做。还有一个我特别看重的点本地优先。你的 vault 就是普通的 Markdown 文件夹索引数据放在.claude-obsidian/目录下不依赖任何插件缓存也不会偷偷把你的笔记传到云端。任何要联网的操作都需要你显式确认。对于把笔记当命的人来说这个设计比多几个花哨功能重要得多。下面我按「从零搭建 → 配置 → 验证 → 排障」的顺序把整套流程拆成可复制的步骤。你跟着做大概四十分钟能跑通第一个自动归档。2. 前置准备TaoToken 接入与 Claude Code 环境claude-obsidian 本身是跑在 Claude Code 里的技能包所以第一步是把 Claude Code 的环境配好。这里我用 TaoToken 作为模型接入层原因是它同时提供 Anthropic 兼容接口和 OpenAI 兼容接口配置起来不用折腾网络Base URL 和 Key 一次配好后面切模型也方便。先说清楚要准备的三件套这是后面所有配置的基础配置项值说明Base URLhttps://taotoken.net/api注意不要加 UTM 参数这是 API 端点API Key在控制台生成形如sk-...只显示一次记得存好Model IDclaude-sonnet-4-5或你账号可用的 Claude 模型用于驱动技能执行第一步去 TaoToken 控制台创建 API Key。打开 https://taotoken.net/api-keys 登录后点创建把生成的 Key 复制到本地一个安全的地方。这个 Key 后面要写进 Claude Code 的配置文件别弄丢。第二步确认你本地已经装了 Claude Code。如果没装用 npm 装npm install -g anthropic-ai/claude-code装完验证一下版本claude --version能打印出版本号就说明 CLI 就位了。第三步配置 Claude Code 走 TaoToken 的接口。Claude Code 读取的是环境变量最稳妥的方式是写进 shell 配置文件。我用的是 zsh所以编辑~/.zshrc如果你用 bash就编辑~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-5保存后重新加载source ~/.zshrc这里有个坑要提前说ANTHROPIC_BASE_URL后面不要带斜杠也不要带任何查询参数就写https://taotoken.net/api。我一开始手滑写成了带 UTM 的官网地址结果请求一直 404排查了半小时才发现是 URL 写错了。第四步验证 Claude Code 能不能正常对话。随便找个空目录运行claude进入交互界面后输入一句「你好确认一下连接」如果模型正常回复说明接入层通了。如果报 401多半是 Key 写错或者没生效回到第三步检查环境变量。第五步准备 Obsidian vault。如果你已经有 vault直接用它如果没有新建一个空文件夹当 vault比如~/Documents/my-brain。claude-obsidian 对已有 vault 是兼容的它会通过 adopt 流程检测现有结构不会破坏你已有的笔记。到这里前置环境就齐了。接下来进入正题把 claude-obsidian 装进 vault 并配置。3. 可复制配置目录结构、settings 与技能安装这一节是整篇的核心我会把目录结构、配置文件、技能安装命令全部给全你直接复制改路径就能用。先看 claude-obsidian 期望的 vault 目录结构。它不强制你改变现有笔记的位置但会新建几个自己的工作目录my-brain/ ├── .claude-obsidian/ # 索引与事务数据不要手动改 │ ├── index/ # BM25 检索索引 │ ├── snapshots/ # 写入前的 SHA-256 快照 │ └── bundles/ # 变更集暂存 ├── .claude/ # Claude Code 技能目录 │ └── skills/ # 15 个技能装在这里 ├── sources/ # 原始材料归档PDF、网页快照等 ├── notes/ # 你的笔记主体 └── .obsidian/ # Obsidian 自己的配置保持原样关键点是.claude-obsidian/和.claude/skills/这两个目录前者存索引和事务数据后者装技能。sources/用来放原始材料这样每条笔记都能追溯到出处。接下来配置 Claude Code 的项目级设置。在 vault 根目录创建.claude/settings.json{ permissions: { allow: [ Read(./**), Write(./notes/**), Write(./sources/**), Write(./.claude-obsidian/**) ], deny: [ Read(./.obsidian/workspace.json), Write(./.obsidian/**) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_MODEL: claude-sonnet-4-5 } }这个配置做了两件事一是限定 Claude Code 只能写notes/、sources/和.claude-obsidian/三个目录避免它误改你的 Obsidian 配置二是把模型接入信息固化到项目里这样你在 vault 目录下启动 Claude Code 时自动生效不用每次依赖全局环境变量。注意deny里我挡掉了.obsidian/workspace.json这个文件记录的是你当前打开的标签页和面板布局被 AI 改了会很烦。.obsidian/整个目录都设成只读更保险。然后是技能安装。claude-obsidian 的技能是 Markdown 格式的指令文件放在.claude/skills/下。每个技能一个子目录里面是SKILL.md。以wiki-ingest为例结构是.claude/skills/ ├── wiki/ │ └── SKILL.md ├── wiki-ingest/ │ └── SKILL.md ├── wiki-query/ │ └── SKILL.md ├── wiki-lint/ │ └── SKILL.md └── ...其余 11 个技能如果你是从项目仓库克隆的直接用安装脚本cd ~/Documents/my-brain git clone https://github.com/你的来源/claude-obsidian.git /tmp/claude-obsidian cp -r /tmp/claude-obsidian/skills/* .claude/skills/装完后确认技能数量ls .claude/skills/ | wc -l应该输出 15。如果少于 15说明复制不完整重新执行 cp 命令。接下来配置知识组织模式。claude-obsidian 支持四种模式Generic、LYT、PARA、Zettelkasten。模式配置写在.claude-obsidian/config.json{ mode: zettelkasten, id_format: timestamp, link_style: wikilink, source_required: true, high_risk_min_sources: 2 }几个参数解释一下mode选你习惯的组织方式我选 zettelkasten 是因为它强调笔记间的关联而非层级适合研究型场景id_format用 timestamp 生成稳定标识符link_style用 wikilink 就是 Obsidian 原生的[[双链]]语法source_required设为 true 表示每篇笔记必须有来源high_risk_min_sources设为 2 表示涉及事实断言的声明至少要有两个独立来源才被接受。模式切换只影响新笔记的路由规则不会重构你已有的内容所以选错了也不用慌改配置就行。最后给一个笔记模板放在.claude-obsidian/templates/note.mdclaude-obsidian 摄取新笔记时会套用--- id: {{timestamp}} title: {{title}} source: {{source_url}} created: {{date}} tags: [] status: draft --- # {{title}} ## 核心结论 !-- 每条结论后面用 ^[source: xxx] 标注来源 -- ## 证据与出处 ## 关联笔记 !-- 双链由 wiki-connect 技能自动补全 --这个模板的 frontmatter 里有source字段配合source_required: true能保证每篇笔记都可追溯。status字段方便你区分草稿和定稿。配置到这一步就齐了。下一节我们实际跑一次摄取验证自动归档效果。4. 验证请求从一篇材料到自动归档的完整跑通配置写完不验证等于没配。这一节我带你跑一次完整的摄取流程从扔一篇材料进去到笔记自动生成、双链自动挂上、索引自动更新全程看结果。第一步准备一篇原始材料。我在sources/下放一个 Markdown 文件模拟从网页剪藏的内容cat sources/bm25-intro.md EOF # BM25 检索算法简介 BM25 是一种基于概率的检索排序函数广泛用于全文搜索引擎。 它考虑了词频TF和逆文档频率IDF并对文档长度做了归一化。 核心公式涉及三个参数k1 控制词频饱和度b 控制长度归一化强度。 典型取值 k11.2~2.0b0.75。 相比 TF-IDFBM25 在长文档上的表现更稳定因为它对词频做了饱和处理 避免某个词出现太多次就无限拉高分数。 EOF第二步在 vault 根目录启动 Claude Codecd ~/Documents/my-brain claude第三步调用wiki-ingest技能摄取这篇材料。在 Claude Code 交互界面输入/wiki-ingest sources/bm25-intro.md技能执行时你会看到它分几步走先读取源文件计算 SHA-256 快照然后并行生成笔记草稿接着做冲突检查最后一次性写入。整个过程大概十几秒。第四步检查生成的笔记。摄取完成后notes/下应该多了一个文件文件名类似20250115143022-bm25检索算法简介.md。打开看内容--- id: 20250115143022 title: BM25 检索算法简介 source: sources/bm25-intro.md created: 2025-01-15 tags: [检索, 算法] status: draft --- # BM25 检索算法简介 ## 核心结论 BM25 是基于概率的检索排序函数广泛用于全文搜索引擎。^[source: bm25-intro.md] 它考虑词频和逆文档频率并对文档长度做归一化。^[source: bm25-intro.md] 典型参数 k11.2~2.0b0.75。^[source: bm25-intro.md] ## 证据与出处 - 原始材料[[bm25-intro]] ## 关联笔记 - [[TF-IDF 检索]] - [[全文搜索引擎]]注意几个细节每条结论后面都自动加了^[source: ...]的来源标注关联笔记里的双链是wiki-connect技能根据已有笔记自动挂的——如果你 vault 里本来就有TF-IDF 检索这篇它就会链上如果没有它会留空或者创建占位。第五步验证索引更新。运行查询技能/wiki-query BM25 参数它应该返回刚才那篇笔记的相关段落并附上来源。如果返回空说明索引没建好检查.claude-obsidian/index/目录下有没有生成索引文件。第六步跑一次 lint 检查死链和孤立笔记/wiki-lint输出会列出所有指向不存在笔记的链接以及没有任何入链的孤立笔记。这一步对维护 vault 健康度很有用建议每周跑一次。第七步验证事务安全。故意制造一次冲突手动改一下刚才生成的笔记然后再次运行/wiki-ingest sources/bm25-intro.md。claude-obsidian 会检测到目标文件的 SHA-256 和快照不一致报冲突而不是静默覆盖。你会看到类似这样的提示Conflict detected: notes/20250115143022-bm25检索算法简介.md Snapshot hash: a3f2... Current hash: 7b1c... Action: skipped, no changes applied这说明事务机制在工作。它宁可跳过也不覆盖你的手动修改这个设计我很喜欢。跑完这七步整套自动归档流程就验证通过了。从材料到笔记到双链到索引全自动完成你只需要审一遍内容。5. 常见报错排查401、local proxy failed 与 reading choices配置和验证过程中最容易踩的坑我按真实报错整理成对照表你遇到直接查。报错一401 UnauthorizedAPI Error: 401 - {error:{type:authentication_error,message:invalid x-api-key}}原因通常是三种Key 写错、Key 没生效、Base URL 和 Key 不匹配。排查顺序先确认ANTHROPIC_API_KEY环境变量里没有多余空格或换行再确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api而不是官网地址最后去控制台确认这个 Key 还有效、没被删。改完环境变量记得source一下或者重开终端。报错二local proxy failedError: local proxy failed to connect: dial tcp 127.0.0.1:xxxx: connect: connection refused这个报错说明 Claude Code 在尝试连一个本地代理端口但你本地并没有跑那个代理。常见于之前配过其他工具、残留了HTTP_PROXY或HTTPS_PROXY环境变量。检查一下env | grep -i proxy如果有输出把这些变量清掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后重开 Claude Code。TaoToken 的接口是直连的不需要任何本地代理。报错三reading choices of undefinedTypeError: Cannot read properties of undefined (reading choices)这个报错一般出现在用 OpenAI 兼容格式调用、但返回体结构不对的时候。如果你在 claude-obsidian 里混用了 OpenAI 格式的配置检查一下是不是把ANTHROPIC_BASE_URL和 OpenAI 的 endpoint 搞混了。Claude Code 走的是 Anthropic 格式Base URL 就写https://taotoken.net/api不要在后面拼/v1/chat/completions之类的路径。另外确认 Model ID 是 Claude 系列别填成 GPT 的模型名。报错四OAuth token expired / invalid_grantOAuth error: invalid_grant - token has expired如果你之前用 Claude Code 登录过官方账号本地可能残留了 OAuth 凭证和现在的 API Key 模式冲突。清理一下凭证缓存rm -rf ~/.claude/credentials.json然后重新用环境变量方式启动。注意这一步会清掉你之前的登录态如果还有别的项目依赖那个登录先备份。报错五技能找不到 / skill not foundError: skill wiki-ingest not found in .claude/skills/说明技能没装全或者目录结构不对。确认.claude/skills/wiki-ingest/SKILL.md这个路径存在文件名大小写要完全一致。如果是从仓库复制的检查有没有漏掉隐藏文件。重新执行一遍复制命令最省事。报错六写入被拒绝 / permission deniedError: Write operation denied by settings.json permissions这是.claude/settings.json里的权限配置在起作用。检查你要写的目录有没有在allow列表里。比如你想让 Claude Code 写notes/下的子目录Write(./notes/**)里的**要确保能匹配到。如果路径写成了Write(./notes)就只能写notes/根目录下的文件子目录写不了。排查这类问题的通用思路是先看报错里的关键词401 看 Keyproxy 看环境变量choices 看接口格式OAuth 看凭证skill 看目录permission 看 settings定位到具体环节再动手。别一上来就重装大部分问题改一行配置就解决了。6. 把 vault 变成可长期维护的知识资产跑通之后claude-obsidian 真正的价值在日常使用里才体现出来。我现在的习惯是看到好材料先扔进sources/然后跑一次/wiki-ingest剩下的交给技能。每周花十分钟跑/wiki-lint清理死链每月跑一次/wiki-fold把相关笔记聚合成综述。如果你想让这套流程更顺手可以试试把常用技能串成一条命令。比如在.claude/skills/下建一个daily-ingest技能把摄取、连接、索引更新三步打包每天下班前跑一次当天的材料就自动归档了。模型接入这块TaoToken 的 Coding Plan 适合长期跑这类 Agent 工作流因为 claude-obsidian 的摄取和折叠操作会频繁调用模型按量计费容易失控包月更省心。你可以在 https://taotoken.net/coding-plan 看具体方案。如果只是想先验证模型效果用模型对话页面 https://taotoken.net/chat 试几句也行。接入文档在 https://taotoken.net/doc 配置细节都在里面。最后说个我踩过的坑一开始我贪心想让 claude-obsidian 一次性整理整个 600 篇的 vault结果跑了很久还中途失败。后来改成按文件夹分批摄取每次 20 到 30 篇稳定多了。事务机制虽然能回滚但大批量操作还是分批更可控。知识库是长期资产慢慢养比一次到位靠谱。