EngramQuest

Obsidian 工作流程

Obsidian 搭配 Claude Code:設定、安全,以及真正好用的外掛

重點整理

  • Claude Code 不需要任何外掛就能處理 Obsidian vault:在 vault 資料夾啟動它,它會直接改 Markdown 檔,Obsidian 會自動跟上變更。[1]
  • 把 Claude 接上 Obsidian 有三種方式:在 vault 資料夾跑 Claude Code、在 Obsidian 裡開 agent 面板(Claudian、Agent Client),或透過 MCP 橋接到執行中的 Obsidian(Local REST API with MCP)。[11][12][9]
  • vault 的規則寫進 CLAUDE.md,Claude Code 每次開工都會先讀;Anthropic 建議每份檔案控制在 200 行以內。[2]
  • 讓 agent 改筆記之前先用 git 管理 vault:Claude Code 的 /rewind 追蹤不到只被 shell 指令改過的檔案,官方文件也說 checkpoint 不能取代版本控制。[4]
  • EngramQuest 把 skills 裝進 .claude/skills,讓 Claude Code 把筆記做成教材、閃卡、任務、記憶地圖和教學影片;skills 只寫進自己的資料夾,從不修改你的原始筆記。[17]

Obsidian 的 vault 其實就是一個裝著 Markdown 檔的資料夾,所以 Claude Code 可以直接讀、搜尋、修改你的筆記。[1] 這篇整理三種連接方式、一份寫給筆記(不是程式)用的 CLAUDE.md、怎麼讓每次修改都能還原,以及值得加裝的外掛。

Claude Code 能處理 Obsidian vault 嗎?

可以。Obsidian 的 vault 是你電腦上一個放著 Markdown 純文字檔的資料夾,其他程式改了檔案,Obsidian 會自動重新整理。[1] Claude Code 本來就是用來讀、搜尋、修改資料夾裡檔案的工具,所以不裝外掛也能直接處理 vault。

在 vault 裡,它最擅長五類工作:

  • 找資料與摘要: 在幾百篇筆記裡找某個主題,整理你寫過什麼,附上檔名。
  • 重整結構: 拆開太長的筆記、合併重複的、替一批筆記補標題或屬性。
  • 建立連結: 建議相關筆記之間的 [[wikilink]],或草擬一篇把它們串起來的 MOC(map of content)。
  • 學習材料: 從你寫好的筆記整理出問題、閃卡和大綱。
  • 日常維護: 找出壞掉的連結、空白筆記,或漏掉標籤的筆記。

有兩個限制最好先知道。第一,Claude Code 看到的是檔案,不是 Obsidian 這個 App:它不知道你現在開著哪篇筆記,Obsidian 內部的功能(指令、關係圖、查詢結果)它也看不到,除非加一座橋。第二,它改的是真正的檔案,一句沒想清楚的指令就會改到真正的筆記。這篇後面的內容就是在處理這兩件事。

Claude Code 和 Obsidian 有哪幾種接法?

共三種,差別在 Claude 在哪裡執行、能碰到什麼。分類方式是我們整理的,每一列的事實則來自連結的專案。

把 Claude 接上 Obsidian vault 的三種方式(查證日期 2026 年 11 月 19 日)
方式怎麼運作Claude 能碰到什麼需要什麼
1. 在 vault 資料夾跑 Claude Code在 vault 開終端機執行 claude,或用 Terminal 外掛在 Obsidian 裡開內建終端機[13]資料夾裡的所有檔案,加上 shell 指令已安裝並登入 Claude Code
2. Obsidian 裡的 agent 面板Claudian 把 Claude Code 等 agent 嵌進 Obsidian,以 vault 為工作目錄;Agent Client 可以跟 Claude Code、Codex、Gemini CLI 等 ACP agent 對話[11][12]vault 檔案,加上你用 @ 提到的筆記;Agent Client 會自動帶入目前開著的筆記桌面版 Obsidian;已安裝並登入 agent
3. 橋接到執行中的 ObsidianLocal REST API with MCP 在 Obsidian 裡跑一個 MCP server;mcp-obsidian 是建在同一套 REST API 上的獨立 MCP server[9][10]透過 App 存取筆記、搜尋、標籤、目前開著的檔案和 Obsidian 指令Obsidian 必須開著;外掛的 API key;在 AI 工具裡設定 MCP

Claude Desktop 沒有終端機,所以要透過 MCP 碰 vault。一條路是檔案系統 MCP server,例如官方的 @modelcontextprotocol/server-filesystem,它只能存取你指定的資料夾。[16] 另一條路是 Local REST API 的橋接;它的 README 說 Claude Desktop 要透過 mcp-remote 連線,因為 Claude Desktop 不直接支援遠端 HTTP MCP server。[9]

Obsidian 1.12 也推出了官方命令列。到 設定 → 一般 → 命令列介面 打開後,像 obsidian search query="..." 或 obsidian backlinks file=<名稱> 這類指令在任何終端機都能用,Claude Code 就能直接向 Obsidian 要反向連結和標籤,不必自己解析檔案。Obsidian 要在執行中;沒開的話,第一個指令會把它啟動。[6]

用 Claude Code 搭配 Obsidian 不一定要裝外掛:在 vault 資料夾啟動 Claude Code,它就會直接修改 Markdown 檔。外掛帶來的是方便(在 Obsidian 裡的對話面板)或更大的能力(透過 MCP 使用 Obsidian 自己的指令)。[1][9]

怎麼替 Obsidian vault 設定 Claude Code?

從 vault 的根目錄啟動 Claude Code,給它一份寫著 vault 規則的 CLAUDE.md,把會重複做的流程寫成 skills。共五步:

  1. 先備份。 把 vault 變成 git repository(或裝下面提到的 Git 外掛),先 commit 一次,之後每次修改都能比對、還原。
  2. 從 vault 根目錄啟動。 切到含有 .obsidian 的那個資料夾,執行 claude。Claude Code 會從啟動的資料夾、以及往上直到 repository 根目錄的每一層載入 .claude/skills/ 裡的 skills;[3] 在 vault 外面啟動,就看不到 vault 裡的 skills。
  3. 寫 CLAUDE.md。 Claude Code 每次開工都會先讀 CLAUDE.md。放在 vault 根目錄或 .claude/CLAUDE.md,也可以執行 /init 讓它先起草一份。如果你已經為其他 AI 工具寫了 AGENTS.md,沒有 CLAUDE.md 時 Claude Code 會直接讀它,或在 CLAUDE.md 裡寫一行 @AGENTS.md 匯入。[2]
  4. 把重複的工作寫成 skills。 一個 skill 就是 .claude/skills/<名稱>/ 資料夾,裡面的 SKILL.md 用 description 告訴 Claude 什麼時候該用它。請求符合時 Claude 會自動載入,也可以輸入 /<名稱> 直接叫用。[3]
  5. 一開始保守一點。 按 Shift+Tab 切到 plan mode(規劃模式)。Claude 會先讀檔、提出修改計畫,你核准之前它不會動手改。[5]

一份寫給筆記、不是寫給程式的 CLAUDE.md

網路上的 CLAUDE.md 範例大多是給軟體專案的。vault 需要的規則不一樣:新筆記放哪、連結長什麼樣、什麼絕對不能碰。下面是一個起點。盡量寫短:Anthropic 建議每份 CLAUDE.md 不超過 200 行,太長會吃掉更多 context,也更不容易被遵守。[2]

放在 vault 根目錄的 CLAUDE.md(起點範本)

# Vault 規則

這個資料夾是 Obsidian vault,筆記都是 Markdown 檔。

## 寫筆記
- 相關筆記用 [[wikilink]] 連結,不要用 Markdown 連結。
- 新筆記放在 Inbox/,除非我指定資料夾。
- 沿用現有的屬性(tags、source、created),不要自己發明新的。
- 照我的寫法:句子短,標題最多到 ###。

## 絕對不要
- 除非我點名那個檔案,否則不要改名、搬移或刪除既有筆記。
- 不要修改 .obsidian/ 裡的任何東西。
- 不要把 API key、token 或密碼寫進筆記。

## 大量修改之前
- 先列出會動到的所有檔案,等我確認。

「不要改名」這條在 vault 裡比在程式專案裡更重要。在 Obsidian 裡替檔案改名時,Obsidian 可以自動更新所有內部連結;[8] 其他程式直接在磁碟上改名,不保證會經過這個功能,指向舊檔名的連結就可能斷掉。想讓 Claude 幫忙重新整理筆記,就請它先列出搬移清單,再到 Obsidian 裡動手,或改用在 App 內部運作的橋接方式。

怎麼避免 Claude Code 弄壞你的筆記?

在修改發生之前就讓它可以還原:vault 用 git 管理、Obsidian 的檔案復原保持開啟、大量修改先用 plan mode 看過。Claude Code 自己的復原功能有幫助,但不是什麼都救得回來。

安全網涵蓋什麼漏掉什麼
Git(命令列或 Git 外掛)所有檔案、每一次 commit 過的修改,都有差異比對和歷史;外掛還能定時自動 commit 與同步,並在 Obsidian 裡提供版本控制、歷史和差異檢視[14]還沒 commit 的修改。README 也說手機版支援非常不穩定。[14]
Claude Code checkpoint(/rewind,或連按兩下 Esc)這個 session 裡 Claude 用自己的檔案工具做的修改[4]只被 shell 指令改過的檔案、大部分 subagent 的修改,以及 Claude Code 以外的變更[4]
Obsidian 檔案復原(核心外掛)筆記的快照,預設至少間隔 5 分鐘、保留 7 天[7]它不是完整備份,快照也只存在拍下它的那台裝置上[7]
Plan mode 與權限確認Claude 先提計畫,你核准後才動手[5]效果取決於你有沒有認真看計畫

讓 Claude Code 修改 Obsidian vault 之前,先把 vault commit 進 git。Claude Code 的 /rewind 只還原它用自己檔案工具做的修改,Anthropic 的文件也明說 checkpoint 不能取代版本控制。[4]

還有兩個好習慣。不要把密碼、金鑰寫進筆記,因為同步中的 vault 會把它複製到每台裝置和每個遠端。試新的大量修改指令時,先只對一個資料夾跑,看過差異再擴大範圍。如果你用 Local REST API 橋接,它會拒絕讀寫 Obsidian 的 .obsidian 設定資料夾,REST 和 MCP 都一樣。[9]

哪些 Obsidian 外掛適合搭配 Claude Code?

有用的外掛大致負責四種工作:讓 Claude 在 Obsidian 裡執行、把它橋接進 App、讓它的修改安全,或把它的產出變成你真的會用的東西。下表每一列都對照過該專案的 README;除了 mcp-obsidian(它是 MCP server,不是外掛),其餘都在 Obsidian 官方社群外掛清單上。[19]

適合搭配 Claude Code 的 Obsidian 外掛(最後查證 2026 年 11 月 19 日)
外掛用途搭配 Claude Code 能做什麼要注意的地方
ClaudianAgent 面板把 Claude Code(以及 Codex、OpenCode 等 agent)嵌進 vault:讀寫檔案、搜尋、bash、skills、斜線指令、@ 提及和 MCP server[11]只支援桌面版;需要 Obsidian 1.13.0 以上;需要相容的訂閱或 API 供應商[11]
Agent ClientAgent 面板跟 Claude Code、Codex、Gemini CLI 或任何 Agent Client Protocol agent 對話;筆記修改以逐字差異顯示,每個動作都可以要求你核准[12]直接沿用 agent 既有的 MCP server 和 skills,外掛本身不用設定[12]
Terminal執行 CLI在 Obsidian 裡開內建終端機,不用切視窗就能跑 claude[13]Windows 上建議(非必要)先安裝 Python[13]
Local REST API with MCP橋接內建 MCP server:讀取、建立、局部修改和搜尋筆記,讀取目前開著的檔案、列出標籤、執行 Obsidian 指令[9]用 claude mcp add --transport http 加上 API key 就能接進 Claude Code[9]
mcp-obsidian橋接獨立的 MCP server,提供 search、get_file_contents、patch_content 等工具,透過 Local REST API 運作[10]需要 Python 3.11 以上,用 uvx 執行;Local REST API 必須開著[10]
Git安全定時自動 commit 與同步,加上版本控制、歷史和差異檢視[14]桌面版最可靠;README 說手機版非常不穩定[14]
Excalidraw圖解提供給 coding agent 用的原生 CLI 和可攜式 agent skill,本機 agent 能建立、檢查、編輯和輸出繪圖[15]agent CLI 需要 Obsidian 1.12.2 以上並開啟命令列介面[15]
EngramQuest(本站開發)學習把 skills 裝進 .claude/skills/,讓 Claude Code 做出能在 Obsidian 裡打開的教材、閃卡、任務、記憶地圖和教學影片[17]免費安裝和使用;AI 可選;外掛本身從不呼叫 AI[17]

Agent 面板和橋接外掛做的事,有一部分 Claude Code 在終端機裡本來就做得到。想一直待在 Obsidian 裡,或你用的是 Claude Desktop,再挑一個裝。想看依用途分類(對話、搜尋、寫作、本機模型)的完整 AI 外掛清單,請看 Obsidian AI 插件推薦。

在 vault 裡可以請 Claude Code 做什麼?

指令裡寫清楚資料夾、要的產出和限制(「不要修改」「先給我看」),效果最好。下面是我們平常會用的寫法,資料夾名稱換成你自己的。

一般 vault 指令(範例)

讀 Projects/論文/ 裡的所有筆記,列出我重複提過的論點,附上檔名。不要修改任何檔案。

找出 Reading/ 裡沒有任何對外 [[連結]] 的筆記。每一篇建議最多三篇應該連過去的既有筆記。先給我清單,不要直接改。

建立 Topics/統計 MOC.md:把所有標了 #統計 的筆記依子主題分組連結起來,每個連結用一行說明它的位置。

讀 生物/細胞膜.md,寫五個我應該能憑記憶回答的問題,放在旁邊一篇新筆記裡。不要寫答案。

如果裝了 EngramQuest 的 skills,下面是外掛說明裡直接建議的句子,把主題或筆記名稱換成你的就好:[17]

EngramQuest 指令(取自外掛內建說明)

我想學 SEO,幫我建一套課程
把我英文單字的筆記做成 Review Deck
把微積分的筆記做成 Quest Map
幫 作業系統概論.md 建立 Memory Map
把架設網站做成教學影片

外掛的 README 還提到一個控制出卡方式的技巧:在筆記裡把重點答案用 ==螢光標記== 或 粗體 標出來,再在 CLAUDE.md 加一條規則。[17]

取自 EngramQuest README 的 CLAUDE.md 規則

IMPORTANT: When building a Review Deck, every highlighted ==text== must become a review card.

怎麼用 Claude Code 把筆記變成教材和閃卡?

裝一組 skills,告訴 Claude Code 要做什麼、存在哪裡,然後用一句話提出要求。EngramQuest 做的就是這件事。EngramQuest 由本站的經營者 powen 開發,閱讀這一段時請把這點放在心上。

  1. 從社群外掛安裝 EngramQuest,打開 設定 → EngramQuest → AI Skills,在 Claude Code 那一列按安裝。skills 會放進 .claude/skills/,資料夾名稱像 engram-quest-review-deck,外掛更新時會跟著更新(可以關閉)。[17]
  2. 在 vault 裡啟動 Claude Code,說出你要的東西,例如 把 Note.md 變成 quest-map medium 或 用標 math 的筆記建一副 review deck。[17]
  3. 點左側 ribbon 的 EngramQuest 圖示打開 Hub,做好的課程、卡組、任務或地圖就在對應的頁面。
EngramQuest 的教材頁:一套由 Claude Code 用 lesson-academy skill 做出的課程,每一課都標出已完成、進行中或未開始。
EngramQuest 的教材頁:一套由 Claude Code 用 lesson-academy skill 做出的課程,每一課都標出已完成、進行中或未開始。

AI 的產出放在自己的資料夾,例如閃卡在 engram-review/ai-cards/,課程和任務在 engram-quest/lessons/ 與 engram-quest/quests/,skills 從不修改你的原始筆記。[17] 外掛本身從不呼叫 AI:生成由 Claude Code 用你現有的方案完成,不用另外訂閱,也沒有 API 費用。[17] 教學影片是唯一只能用 Claude Code 做的功能,由 animated-course skill 在你的電腦上算圖,按安裝時才從專案的 GitHub Releases 下載。[17]

AI 一直是選配。替筆記加上 #flashcards/主題 標籤,自己寫 Q: 和 A: 卡片,它們就會出現在 Review Deck,完全不用 AI。[17] 支援哪些 AI 工具、各自的 skills 資料夾、Claude Desktop 的設定提示,都在 Claude Code 頁面;開始的三個步驟在 使用指南;從學習目標一路到複習的完整示範,請看 在 Obsidian 用 AI 學習。

讓 Claude Code 代勞,會不會反而學不會?

會,如果 Claude 直接給出你本來該自己想出來的答案。一項以近千名高中數學學生為對象的實地實驗中,不設限地使用 GPT-4 讓練習成績提高了 48%;但拿掉 AI 之後,這些學生的成績比從沒用過的學生低了 17%。加上引導限制的家教版本則大致避開了這個傷害。[18] 這只是一個學科的一項研究,但方向很清楚。

放到 vault 裡,結論很實際:用 Claude Code 整理筆記、做出練習(問題、卡片、任務),回想的部分自己來。Claude 寫的摘要是 Claude 的思考;你憑記憶答出來的問題才是你的。有沒有 AI 都能用的六步驟方法,請看 怎麼用 Obsidian 學習;負責排複習的工具比較,請看 Obsidian 閃卡外掛推薦。

用 Claude Code 做練習,而不是取代練習:一項刊在 PNAS 的實地實驗發現,不設限使用 GPT-4 的學生在拿掉 AI 後,成績比從沒用過的學生低 17%。[18]

常見問題

用 Claude Code 搭配 Obsidian 一定要裝外掛嗎?

不用。Obsidian vault 就是裝著 Markdown 檔的資料夾,在 vault 資料夾啟動 Claude Code 就能直接處理。Claudian、Agent Client 或 Local REST API with MCP 這類外掛,提供的是 Obsidian 裡的對話面板,或通往執行中 App 的橋接。

Claude Desktop 能修改我的 Obsidian 筆記嗎?

可以,透過 MCP。接上只限 vault 資料夾的檔案系統 MCP server,或透過 mcp-remote 連到 Local REST API with MCP 外掛;EngramQuest 的外掛說明裡也有一段給 Claude Desktop 的一次性設定提示。

CLAUDE.md 要放在 Obsidian vault 的哪裡?

放在 vault 根目錄(或 .claude/CLAUDE.md),並從那個資料夾啟動 Claude Code。它每次開工都會讀這份檔案,所以只放隨時都適用的規則。

Claude Code 會弄壞 Obsidian 的連結嗎?

如果它直接在磁碟上改名或搬移筆記,就有可能,因為 Obsidian 自動更新連結是跟在 App 裡改名綁在一起的。在 CLAUDE.md 加一條禁止改名、搬移筆記的規則,並用 git 管理 vault。

手機上的 Obsidian 能用 Claude Code 嗎?

不能直接用:Claude Code 和 agent 面板都在桌面上執行,Claudian 也註明只支援桌面版。在電腦上做好的內容,會隨 vault 同步到手機。

EngramQuest 替 Claude Code 多了什麼?

一組 skills,讓 Claude Code 做出教材、用 FSRS 排程的 Review Deck 閃卡、Quest Map 練習任務、Memory Map 和教學影片,並在 Obsidian 裡的 EngramQuest Hub 打開。免費安裝和使用,AI 可選。

參考資料

文中每一個研究說法都對應到下列來源;預印本會特別標示。

  1. Obsidian (2026). How Obsidian stores data. Obsidian Help. Checked 19 November 2026. obsidian.md/help/data-storage
  2. Anthropic (2026). How Claude remembers your project (CLAUDE.md, AGENTS.md and imports). Claude Code documentation. Checked 19 November 2026. code.claude.com/docs/en/memory
  3. Anthropic (2026). Extend Claude with skills. Claude Code documentation. Checked 19 November 2026. code.claude.com/docs/en/skills
  4. Anthropic (2026). Checkpointing. Claude Code documentation. Checked 19 November 2026. code.claude.com/docs/en/checkpointing
  5. Anthropic (2026). Permission modes (plan mode). Claude Code documentation. Checked 19 November 2026. code.claude.com/docs/en/permission-modes
  6. Obsidian (2026). Obsidian CLI. Obsidian Help. Checked 19 November 2026. obsidian.md/help/cli
  7. Obsidian (2026). File recovery (core plugin). Obsidian Help. Checked 19 November 2026. obsidian.md/help/plugins/file-recovery
  8. Obsidian (2026). Internal links. Obsidian Help. Checked 19 November 2026. obsidian.md/help/links
  9. Coddington, A. (2026). Local REST API with MCP: README. GitHub, coddingtonbear/obsidian-local-rest-api. Checked 19 November 2026. github.com/coddingtonbear/obsidian-local-rest-api
  10. Pfundstein, M. (2026). MCP server for Obsidian (mcp-obsidian): README. GitHub, MarkusPfundstein/mcp-obsidian. Checked 19 November 2026. github.com/MarkusPfundstein/mcp-obsidian
  11. Tu, Y. (2026). Claudian: README. GitHub, YishenTu/claudian. Checked 19 November 2026. github.com/YishenTu/claudian
  12. RAIT-09 (2026). Agent Client Plugin for Obsidian: README. GitHub, RAIT-09/obsidian-agent-client. Checked 19 November 2026. github.com/RAIT-09/obsidian-agent-client
  13. polyipseity (2026). Terminal for Obsidian: README. GitHub, polyipseity/obsidian-terminal. Checked 19 November 2026. github.com/polyipseity/obsidian-terminal
  14. Vinzent03 (2026). Git Plugin for Obsidian: README. GitHub, Vinzent03/obsidian-git. Checked 19 November 2026. github.com/Vinzent03/obsidian-git
  15. Zsolt Viczián (2026). Excalidraw for Obsidian: README (section "Native CLI for coding agents"). GitHub, zsviczian/obsidian-excalidraw-plugin. Checked 19 November 2026. github.com/zsviczian/obsidian-excalidraw-plugin
  16. Model Context Protocol (2026). Filesystem MCP Server (@modelcontextprotocol/server-filesystem): README. GitHub, modelcontextprotocol/servers. Checked 19 November 2026. github.com/modelcontextprotocol/servers/tree/main/src/filesystem
  17. EngramQuest (2026). EngramQuest: README (v2.0.x) and in-plugin guide. GitHub, bahfahh/engram-quest. Checked 19 November 2026. github.com/bahfahh/engram-quest
  18. Bastani, H., Bastani, O., Sungu, A., Ge, H., Kabakcı, Ö., & Mariman, R. (2025). Generative AI without guardrails can harm learning: Evidence from high school mathematics. Proceedings of the National Academy of Sciences, 122(26), e2422633122. doi.org/10.1073/pnas.2422633122
  19. Obsidian (2026). obsidian-releases: community-plugins.json (the official community plugin list). GitHub, obsidianmd/obsidian-releases. Checked 19 November 2026. github.com/obsidianmd/obsidian-releases

關於這篇文章

powen 是 EngramQuest 的開發者。EngramQuest 是免費的 Obsidian 外掛,把筆記變成教材、教學影片、練習任務和 FSRS 閃卡。這裡的文章由 AI 協助蒐集資料與起稿;引用的每一篇研究都對照過原始論文,外掛的細節來自外掛本身的文件與原始碼。

EngramQuest 如何運用記憶科學

把學到的留下來。

Obsidian 桌面版與手機版皆可免費使用。AI 可選。

免費社群插件 · 會打開 Obsidian。沒有反應? 從插件目錄安裝 (在新分頁開啟)