企业官网建设流程全解析

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 一次配好，后面切模型也方便。

先说清楚要准备的三件套，这是后面所有配置的基础：

第一步，去 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，就编辑~/.bashrc：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key" export ANTHROPIC_MODEL="claude-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.md，claude-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 控制长度归一化强度。 典型取值 k1=1.2~2.0，b=0.75。 相比 TF-IDF，BM25 在长文档上的表现更稳定，因为它对词频做了饱和处理， 避免某个词出现太多次就无限拉高分数。 EOF

第二步，在 vault 根目录启动 Claude Code：

cd ~/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] 典型参数 k1=1.2~2.0，b=0.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 Unauthorized

API 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 failed

Error: 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 undefined

TypeError: 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_grant

OAuth error: invalid_grant - token has expired

如果你之前用 Claude Code 登录过官方账号，本地可能残留了 OAuth 凭证，和现在的 API Key 模式冲突。清理一下凭证缓存：

rm -rf ~/.claude/credentials.json

然后重新用环境变量方式启动。注意这一步会清掉你之前的登录态，如果还有别的项目依赖那个登录，先备份。

报错五：技能找不到 / skill not found

Error: skill 'wiki-ingest' not found in .claude/skills/

说明技能没装全或者目录结构不对。确认.claude/skills/wiki-ingest/SKILL.md这个路径存在，文件名大小写要完全一致。如果是从仓库复制的，检查有没有漏掉隐藏文件。重新执行一遍复制命令最省事。

报错六：写入被拒绝 / permission denied

Error: Write operation denied by settings.json permissions

这是.claude/settings.json里的权限配置在起作用。检查你要写的目录有没有在allow列表里。比如你想让 Claude Code 写notes/下的子目录，Write(./notes/**)里的**要确保能匹配到。如果路径写成了Write(./notes)就只能写notes/根目录下的文件，子目录写不了。

排查这类问题的通用思路是：先看报错里的关键词（401 看 Key，proxy 看环境变量，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 篇，稳定多了。事务机制虽然能回滚，但大批量操作还是分批更可控。知识库是长期资产，慢慢养比一次到位靠谱。