Codex 操作 Obsidian 的能力分层：MCP、Skills 与 CLI 如何分工

从任务类型出发，梳理 Codex 操作 Obsidian 时 MCP、Skills 与 CLI 的职责边界、组合方式和选择顺序。

CodexObsidianMCP工作流

如果把 Codex 接入 Obsidian 只理解成“装好 MCP 就够了”，通常很快就会遇到新的问题：为什么已经能读写笔记了，还需要 Skills？为什么有些场景下又会提到 obsidian-cli？

这篇文章尝试把这些能力放到同一个框架里理解。基础安装步骤先放到一边，重点讨论：当 Codex 开始真正操作 Obsidian 时，MCP、Skills 与 CLI 分别负责什么、适合解决哪些问题，以及它们如何组成一个分层协作体系。

为什么容易混淆

在使用 Codex 操作 Obsidian 时，最容易混淆的问题是：接入之后到底该依赖哪一层能力。

明明已经配置了 Obsidian MCP，为什么还需要 Skills？既然已经能读写笔记，obsidian-cli 又能带来什么？如果没有先把这几层能力分清楚，就很容易在工具已经可用的情况下，仍然不知道该如何组织一套稳定、可维护的工作流。

本文尝试回答四个问题：

这些能力分别负责什么；
它们适合解决哪些任务；
在什么场景下应当优先使用哪一种能力；
它们如何组合成一套更高效的 Obsidian 工作流。

先看任务，再看工具

要理解 MCP、Skills 和 CLI 的分工，应先看任务类型，再看工具名称。

在实际使用中，Codex 与 Obsidian 的交互任务大致可以分成六类。

内容读取

读取单篇或多篇笔记；
搜索关键词、标签或属性；
读取图片、PDF 和其他附件。

内容整理

重构笔记结构；
合并重复内容；
提炼总结；
补充说明、示例和参考来源。

结构维护

管理标签和 frontmatter；
新建索引页或总览页；
调整目录归类；
维护跨文件链接。

特殊文件

编辑 .base；
编辑 .canvas；
维护图片、PDF 和附件嵌入。

应用控制

操作正在运行的 Obsidian；
执行命令面板命令；
查询 Base 的实际运行结果；
移动或重命名正式笔记，并让 Obsidian 自动维护内部链接。

开发与调试

重载插件或主题；
查看错误和控制台输出；
截图、检查 DOM 与 CSS；
在 Obsidian 应用上下文中运行 JavaScript。

从这些任务出发就可以看出：Codex 操作 Obsidian 并不依赖某一个万能入口，而是依赖多个层次的能力配合。

MCP：能力入口

最简单的理解是：MCP 是能力入口层。

没有 MCP 时，Codex 往往只能根据用户提供的文本进行回答；接入 MCP 后，代理才能直接访问 vault 中的内容，并执行实际操作。

在 Obsidian 场景里，MCP 往往承担这些能力：

读取和搜索笔记；
新建、覆写、追加或精确替换内容；
更新 frontmatter 和标签；
移动或重命名文件；
读取 .base、.canvas 等特殊文件；
读取目录、统计信息与附件路径。

也就是说，MCP 解决的是一个基础问题：Codex 能不能真正操作你的 Obsidian vault。 把整个能力体系抽象一下，MCP 就像为代理接上了一双能够伸进 vault 的“手”：它决定能力有没有接进来，却不会替代理决定任务应当怎样组织。

Skills：格式与工作流知识

如果说 MCP 解决的是“能不能操作”，那么 Skills 解决的就是“怎样操作得更符合目标格式和长期维护习惯”：前者提供工具接口，后者提供格式知识、语法规则与工作流经验。换句话说，Skills 不负责赋予新权限，它们负责让代理在已有权限下做得更稳。可以用一个简单的类比来理解：

MCP 像“手”；
Skills 像“经验和方法”。

在 Obsidian 这种高度依赖文件格式与约定写法的环境里，这一点尤其重要：

.md 不只有标准 Markdown，还包含 wikilinks、embeds、callouts 等 Obsidian Flavored Markdown；
.base 是带有结构和语法约束的视图定义；
.canvas 虽然使用 JSON，却遵循特定的 JSON Canvas 规范。

因此，在已有 MCP 的前提下，Skills 的价值主要体现在：

降低格式错误概率；
提高结构化修改的稳定性；
使用更贴近 Obsidian 原生习惯的写法；
让整理后的结果更适合长期维护。

`obsidian-markdown`

对大多数 Obsidian 工作流来说，Markdown 仍然是最核心的内容载体。obsidian-markdown 关注的重点不是标准 Markdown 本身，而是 Obsidian 增加的能力，例如：

wikilinks 与自定义显示文本；
指向标题或块的链接；
笔记、图片与 PDF embeds；
frontmatter、tags 与 aliases；
callouts、脚注和 Mermaid。

它适合整理普通笔记、建立索引、补充内部链接，以及把图片和 PDF 自然地组织进正文。在这个场景里，MCP 负责搜索、读取和写回，obsidian-markdown 负责告诉代理应该怎样组织链接、嵌入与属性。

`obsidian-bases`

.base 文件承载结构化视图定义，需要理解 filters、views、properties、formulas 和 summaries。obsidian-bases 的价值在于让代理不只是能编辑文本，还能理解 Base 的结构与常见错误。

它适合：

创建和调整 Base 视图；
修改筛选逻辑；
增加公式字段；
修复 YAML 或公式错误；
为表格、卡片、列表等视图维护属性。

`json-canvas`

.canvas 文件内部包含 nodes、edges、groups、布局信息和唯一 ID。json-canvas 帮助代理把它当作有规则的结构化格式处理，减少节点 ID 冲突、连线指向不存在节点或字段缺失等问题。

它提升的是 Canvas 文件级编辑的稳定性和规范性，并不替代 Obsidian 的图形化画布界面。

如果希望暂时离开 Obsidian 的具体场景，进一步理解 Skill 的目录结构、加载机制，以及它与 Prompt、Tool、MCP 的概念边界，可以继续阅读：AI Agent 的 Skill 是什么：结构、运行机制与概念边界。

如果还想继续追问“跨任务保留的背景应当放在哪里”，则可以阅读 Codex Memories 是什么：记忆、规则与实时上下文如何分工，进一步区分长期记忆、项目规则与实时上下文。

CLI：应用控制

如果说 MCP 更偏文件与知识库层，那么 obsidian-cli 更偏运行中的 Obsidian 应用层。

根据 Obsidian 官方 CLI 文档，它可以搜索和读写笔记、执行命令、查询 Base、管理插件，并提供截图、DOM 检查和控制台等开发能力。它要求 Obsidian 应用正在运行，并可通过 vault=<name> 指定目标 vault。

例如，只返回候选路径的搜索可以写成：

obsidian vault="My Vault" search query="Codex" limit=5

CLI 还有一个很重要的价值：当任务依赖 Obsidian 应用本身的内部行为时，它通常比外部文件级工具更合适。

以正式笔记的重命名与移动为例。官方文档明确说明，当 vault 已开启“自动更新内部链接”时，通过 CLI 执行 move 或 rename 会让 Obsidian 同步维护 wikilinks。外部工具直接改变文件路径时，则不应默认期待相同行为。

工具能否改动文件，与这次改动是否经过 Obsidian 应用本身，并不是同一个问题。

CLI 比较适合这些任务：

操控运行中的 Obsidian；
查询视图的实际运行结果；
开发或调试插件、主题；
验证界面、截图和错误状态；
重命名或移动正式笔记，并维护内部链接；
在大范围搜索初筛时减少返回载荷。

三层如何协作

这三类能力更适合被理解为一个分层体系，而不是互相替代的选项。

flowchart TB
  Task[具体任务] --> MCP[MCP：能力入口]
  MCP --> Skills[Skills：格式与工作流知识]
  Skills --> CLI[CLI：运行中应用控制]
  CLI --> Result[稳定、可维护的结果]
  Task -. 仅需文件级读写 .-> MCP
  Task -. 依赖应用内部行为 .-> CLI

MCP 提供文件与数据访问能力，解决“能不能操作”；
Skills 提供格式与工作流知识，解决“怎样操作更稳”；
CLI 提供运行中应用控制能力，解决“能不能让 Obsidian 自己完成这次操作”。

没有 MCP，Codex 很难真正进入 vault；只有 MCP、没有 Skills，结构化文件虽然能改，却更容易改得不稳；CLI 并非每个任务都需要，但在依赖应用内部行为的场景里，它会明显提高结果的可靠性。

怎样选择能力组合

任务	建议能力
搜索初筛、快速定位候选笔记	`obsidian-cli`
结构化搜索、摘要片段与后续精读	MCP
整理普通 Markdown 笔记	MCP + `obsidian-markdown`
管理标签、属性与内部链接	MCP + `obsidian-markdown`
编辑 `.base`	MCP + `obsidian-bases`
编辑 `.canvas`	MCP + `json-canvas`
处理图片、PDF 与附件嵌入	MCP + `obsidian-markdown`
正式笔记重命名或移动，并维护内部链接	`obsidian-cli`
查询 Base 实际结果	`obsidian-cli`
插件或主题开发与调试	`obsidian-cli`

这里尤其值得强调两点。第一，搜索并不一定只该交给 MCP。如果目标只是快速定位候选笔记，CLI 返回路径列表即可；如果需要结构化命中信息、摘要片段和后续精读，再使用 MCP 更合适。

第二，重命名和移动不只是“文件路径改掉就行”。如果任务依赖 Obsidian 自动维护内部链接，就应该让 Obsidian 应用本身参与这次操作。

除了逐项匹配任务，也可以按使用深度把常见配置归纳为三档。

基础组合

适合基础读写、结构化检索和简单整理。

知识库维护组合

MCP
obsidian-markdown
obsidian-bases
json-canvas

这组配置覆盖普通笔记整理、跨文件链接、属性维护、Base 与 Canvas 编辑，适合长期维护一个 Obsidian 仓库。

运行时增强组合

MCP
合适的 Skills
obsidian-cli

当任务需要查询视图实际结果、操控正在运行的 Obsidian、验证显示效果或维护内部链接时，CLI 会带来明显收益。

实践提醒

1. 安装或更新 Skill 后，优先在新任务中使用

新安装或更新后的 Skill 不一定会被已经运行的旧任务自动识别。安装完成后，换一个新任务再使用通常更稳妥。

2. 新任务中说明已经部署的能力

即使 MCP 服务与 Skills 已经配置完成，代理也不一定会自动意识到应该优先使用它们。说明已经部署的工具和期望的处理方式，能够减少不必要的试探。

3. 先分清“初筛”与“精读”

只想拿到候选路径时，轻量搜索更划算；需要上下文、frontmatter 和完整内容时，再进入结构化读取。

4. 特殊文件先理解格式，再批量修改

.base 和 .canvas 都是结构化文件。把它们当普通文本批量替换，风险会明显更高。

5. 图片与 PDF 不只是附件名

图片、图表和 PDF 往往承载正文无法替代的信息。整理时只维护引用语法还不够，还需要理解附件内容与正文之间的关系。

6. 长资料整理后，可以加入独立审查

当代理同时承担资料理解、结构设计、附件处理和正文改写时，容易沿着自己刚形成的结构继续验证。把审查交给另一个只读角色，专门寻找遗漏、误译和过度概括，可以减少这种自检盲区。

结语

真正高效的 Obsidian 工作流，不必一开始就把所有能力都装满。先明确任务类型，再补上对应层次的能力，往往更容易得到稳定结果。

如果把 Codex 操作 Obsidian 的能力体系压缩成一句话，可以概括为：

MCP 是能力入口；
Skills 是格式与工作流增强层；
CLI 是应用控制增强层。

对于大多数内容整理和知识维护场景来说，MCP + 合适的 Skills 已经足够；当任务进一步延伸到运行时控制、视图验证、内部链接维护或插件开发时，obsidian-cli 的价值才会真正显现出来。