1. 为什么你的 AI Agent 读不懂 Obsidian 知识库

如果你同时用 Obsidian 和 Claude Code，大概率遇到过这种尴尬：让 Agent 帮你整理笔记，它把 [[双向链接]] 当成普通方括号文本，把 callout 语法 > [!note] 拆得七零八落，Bases 的 .base 文件它压根不认识。你明明有一个结构化的知识库，Agent 却像个刚学会认字的外行，只能做最粗暴的全文替换。

问题的根子不在模型能力，而在指令层缺失。Obsidian 有一套自己的方言：wikilinks、embeds、callouts、properties、Bases、JSON Canvas，这些格式在通用训练语料里占比极低，模型没有足够的先验去正确处理。你可以在系统提示词里手写一堆规则，但 context window 会被迅速吃满，而且每换一个 Agent 就要重写一遍。

obsidian-skills 这个项目就是冲着这个痛点来的。它由 Obsidian CEO kepano 维护，本质是一套「让 AI Agent 读懂并操控 Obsidian 的协议包」。它不造新工具，而是把 Obsidian 原生的五种数据格式和操作接口，封装成符合 Agent Skills 规范的标准技能包。装好之后，Claude Code、Codex、OpenCode 这些主流 Agent 不需要任何定制适配，就能直接操作你的 Vault。

适合谁用：重度 Obsidian 用户想把知识库变成「可编程资产」；开发者想研究 Agent Skills 规范怎么落地；以及任何受够了「Agent 把笔记格式搞乱」的人。这篇笔记我会把 SKILL.md 的配置片段、Agent 调用示例、本地验证读写检索的完整步骤都拆开讲，你照着做就能复现核心能力。

2. TaoToken 前置准备：给 Agent 接上稳定的模型通道

在折腾 obsidian-skills 之前，得先保证你的 Agent 有一个能稳定调用的模型后端。Claude Code 默认走 Anthropic 官方通道，但国内网络环境下经常遇到连接超时、401 鉴权失败、OAuth 回调卡住这些问题。我试过用 TaoToken 做统一接入层，把 Base URL 指向它的 API 端点，Agent 侧的配置几乎不用改。

TaoToken 在这里扮演的是「模型通道」角色，不是替代 Obsidian 或 Agent 本身。你需要准备三样东西：一个 API Key、正确的 Base URL、以及要调用的 Model ID。这三件套在后面的 Claude Code、Cline、Codex 配置里都会反复出现，先记牢。

获取 Key 的路径：打开 https://taotoken.net/api-keys ，登录后创建一个新 Key，复制保存。注意 Key 只在创建时完整显示一次，丢了就得重建。

Base URL 统一用 https://taotoken.net/api，不要加任何路径后缀。Model ID 根据你的场景选：做笔记整理和格式转换，Claude 系列的中档模型就够；如果要跑复杂的多技能编排，选推理能力更强的版本。具体可用模型列表在 https://taotoken.net/models 可以查到。

如果你只是想让 Agent 验证一下「能不能正确读写 Obsidian 格式」，用模型对话页面快速测一下就行： https://taotoken.net/chat 。但要做完整的知识库读写工作流，还是得在本地 Agent 里配置。

长期跑编码和 Agent 任务的话，Coding Plan 的额度模型更划算，不用每次调用都心疼 token： https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc ，里面有各客户端的详细配置说明。

这里有个坑要提前说：TaoToken 的 API 端点是给程序调用的，不是让你在浏览器里直接访问的。你把 https://taotoken.net/api 粘到地址栏会看到 404，这是正常的，别慌。

3. 可复制配置：SKILL.md 结构与 Agent 接入片段

obsidian-skills 的核心设计全在 SKILL.md 这个文件格式上。Agent Skills 规范定义了一个技能就是一个目录，核心文件结构长这样：

skill-name/
├── SKILL.md          # 必须有：YAML frontmatter + Markdown 指令正文
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── assets/           # 可选：模板资源

SKILL.md 的头部是 YAML frontmatter，用来声明元数据。下面是一个可以直接复制的 obsidian-markdown 技能配置片段：

---
name: obsidian-markdown
description: Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, and properties. Use when writing or modifying notes in an Obsidian vault.
license: MIT
compatibility: Requires Node.js for CLI features
allowed-tools: Bash(git:*) Read Write
---

# Obsidian Markdown 技能

你正在操作一个 Obsidian Vault。所有笔记使用 Obsidian Flavored Markdown。

## 核心语法规则

- 双向链接用 `[[笔记名]]`，带别名用 `[[笔记名|显示文本]]`
- 嵌入用 `![[笔记名]]` 或 `![[图片.png]]`
- Callout 用 `> [!note]`、`> [!warning]`、`> [!tip]` 开头
- Properties 写在文件顶部 YAML frontmatter 中

## 操作约束

- 写入前先 Read 目标文件，确认现有结构
- 不要破坏已有的 wikilinks 和 callouts
- 新建笔记时，文件名用中文或英文均可，但避免特殊字符

frontmatter 里的 name 字段有严格命名规则：只能小写字母、数字和连字符，不能有大写、前导连字符或连续连字符。写错了 Agent 加载时会直接跳过这个技能。可以用官方提供的 skills-ref validate 工具校验。

最巧妙的机制是渐进式加载。Agent 启动时只加载所有技能的 name + description，大约 100 tokens，用来做技能发现。只有被激活的技能才完整加载 SKILL.md 正文，建议控制在 5000 tokens 以内。脚本和资源按需加载。这个设计直接解决了 context window 浪费的问题，比早期「把所有说明塞进系统提示词」的做法工程化得多。

安装方式推荐用 NPX：

npx skills add https://github.com/kepano/obsidian-skills

Claude Code 手动安装的话，把仓库内容放到 Obsidian Vault 根目录的 .claude 文件夹下。OpenCode 手动安装要注意必须 clone 完整仓库，不能只复制 skills/ 子目录：

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

接下来是 Agent 侧的模型接入配置。Claude Code 的 settings 文件通常放在 ~/.claude/settings.json，加入以下片段：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://taotoken.net/api",
    "ANTHROPIC_API_KEY": "sk-你的Key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
  }
}

如果你用 Cline，配置在 VS Code 的 settings.json 里，走 OpenAI 兼容格式：

{
  "cline.apiProvider": "openai",
  "cline.openAiBaseUrl": "https://taotoken.net/api",
  "cline.openAiApiKey": "sk-你的Key",
  "cline.openAiModelId": "claude-sonnet-4-20250514"
}

Codex 用户改 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "sk-你的Key",
  "OPENAI_BASE_URL": "https://taotoken.net/api"
}

三件套记牢：Base URL 是 https://taotoken.net/api，Key 从 console 拿，Model ID 按场景选。任何一处写错都会导致 401 或连接失败。

4. 验证请求：在本地 Vault 跑通读写检索

配置好之后，别急着上复杂工作流，先用最小步骤验证 Agent 能不能正确操作 Obsidian 格式。我建议按「读 → 写 → 检索 → 生成」四步走。

第一步，验证读取。在 Vault 里建一个测试笔记 test-agent.md，内容包含各种 Obsidian 语法：

---
tags: [test, agent]
created: 2026-05-01
---

# 测试笔记

这是一个双向链接：[[另一篇笔记]]

> [!note] 提示
> 这是一个 callout 块。

- [ ] 待办事项一
- [x] 已完成事项

然后在 Claude Code 里输入：「读取 test-agent.md，告诉我里面有哪些 Obsidian 特有语法」。如果 Agent 能正确识别 wikilink、callout、properties 和任务列表，说明 SKILL.md 加载成功。

第二步，验证写入。让 Agent 执行：「在 test-agent.md 末尾追加一个 warning callout，内容是提醒我检查链接有效性」。检查文件，看它是否用了 > [!warning] 而不是普通引用块。

第三步，验证检索。输入：「在我的 Vault 里搜索所有包含 #test 标签的笔记，列出文件名」。这一步考验 Agent 是否理解 Obsidian 的标签检索逻辑，而不是简单 grep。

第四步，验证生成。让 Agent 新建一篇笔记：「创建一篇名为 agent-generated.md 的笔记，包含一个指向 test-agent.md 的双向链接，以及一个 tip callout」。检查生成的文件是否符合 Obsidian 方言。

如果四步都通过，说明基础能力已经跑通。这时候可以试更复杂的编排，比如：「用 defuddle 抓取这个网页 https://example.com/article ，转成 Markdown 后写入 Vault，然后更新我的读书笔记索引」。这个工作流会串联 defuddle、obsidian-markdown、obsidian-bases 三个技能。

验证模型本身是否正常响应，可以先用模型对话页面发一条测试消息： https://taotoken.net/chat 。如果那边正常但本地 Agent 报错，问题多半出在配置文件路径或 Key 上。

5. 常见报错排查：401、local proxy failed、reading choices

配置过程中最容易踩的坑集中在鉴权和网络层。下面是我遇到过的真实报错和对应解法。

401 Unauthorized：最常见。原因通常是 Key 写错、Key 过期、或者 Base URL 多了路径后缀。检查 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 是否完整复制，注意前后不要有空格。Base URL 必须是 https://taotoken.net/api，不能写成 https://taotoken.net/api/v1 或带其他后缀。如果 Key 是在 console 里刚创建的，确认没有误删。

local proxy failed / connection refused：Agent 尝试走本地代理但代理没启动。检查你的环境变量里有没有残留的 HTTP_PROXY、HTTPS_PROXY 设置。如果有，临时清掉再试：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

然后重启 Agent。如果公司网络有强制代理，需要在 Agent 配置里显式指定，而不是依赖环境变量。

Error reading choices / invalid response format：这个报错通常出现在 Cline 或 OpenAI 兼容客户端上，说明返回的 JSON 结构不符合预期。原因可能是 Model ID 写错了，或者 Base URL 指向了不兼容的端点。确认 Model ID 在 https://taotoken.net/models 列表里存在，且客户端用的是 OpenAI 兼容模式。

OAuth callback failed：Claude Code 首次登录时如果走 OAuth 流程，回调可能被拦截。解决办法是改用 API Key 模式，在 settings.json 里直接配 ANTHROPIC_API_KEY，跳过 OAuth。

技能未加载 / Agent 不认识 Obsidian 语法：检查 SKILL.md 的 frontmatter 格式。name 字段必须是小写字母数字加连字符，description 不能为空。用 skills-ref validate 校验一下。另外确认技能目录放在 Agent 能扫描到的路径下，Claude Code 是 Vault 根目录的 .claude 文件夹，OpenCode 是 ~/.opencode/skills/。

文件写入冲突：如果你同时开了多个 Agent 会话操作同一个 Vault，会出现文件竞争。项目目前没有文件锁机制，需要人工串行操作。养成「单 Agent 串行」习惯，别同时跑两个会话改同一篇笔记。

移动端不可用：obsidian-cli 和 defuddle 依赖 Node.js，iOS 和 Android 端跑不了。移动端只能用 markdown、bases、canvas 这三个格式类技能。如果你主要用移动端 Obsidian，暂时不用优先投入这个项目。

排障时如果怀疑是模型通道问题，可以去接入文档对照检查配置： https://taotoken.net/doc 。文档里有各客户端的完整配置示例，比对着改效率高很多。

6. 把知识库变成可编程资产：CTA 与长期工作流

跑通基础读写之后，obsidian-skills 的真正价值在于多技能编排。五个技能单独用只是工具，组合起来才是工作流。

一个完整的知识入库管道可以这样设计：用 defuddle 抓取网页并去噪转成干净 Markdown，用 obsidian-markdown 写入 Vault 并自动补全 wikilinks 和 properties，用 obsidian-bases 构建知识索引视图，最后用 json-canvas 生成可视化关系图。整个过程你只需要用自然语言描述目标，Agent 会自动调用对应技能。

比如这句指令：「帮我把最近两周的读书笔记整理成一张 Canvas 知识图，按主题分组，每个节点链接到原笔记」。Agent 会先检索带 #读书 标签的笔记，提取主题，然后生成 .canvas 文件。这在以前需要手动拖拽半小时，现在一句话搞定。

对开发者来说，Agent Skills 规范的「元数据轻量 + 指令渐进加载 + 工具白名单」三件套，是构建任何领域技能包的通用模板。如果你在维护 MCP Server 或 CLI 工具，同步提供一个 SKILL.md 是成本极低但覆盖面大的做法。

长期跑这类 Agent 工作流，token 消耗会累积。如果你的使用频率高，Coding Plan 的额度模型比按量付费更可控： https://taotoken.net/coding-plan 。需要管理多个 Key 或查看用量，去 console： https://taotoken.net/console 。API Key 创建入口： https://taotoken.net/api-keys 。

最后给一个实用建议：不要一上来就追求全自动。先把「读 + 写」两个动作跑稳，确认 Agent 不会破坏你的笔记格式，再逐步加入检索和生成。知识库是你的核心资产，让 Agent 操作之前，先用 Git 做好版本控制，出问题能回滚。单 Agent 串行操作，别贪快开多个会话。这套流程跑顺之后，你的 Obsidian 就从「手工维护的笔记软件」变成了「可编程的知识基础设施」。