如何在 VPS 上用 Claude Code 管理 Obsidian vault

Claude Code 為何適合處理 Obsidian vault

Obsidian vault 是由 Markdown 檔案組成的資料夾，因此 Claude Code 可以像處理程式碼儲存庫一樣處理它。Obsidian 官方網站表示，它會「將筆記以純文字 Markdown 檔案的形式儲存在本機」，而 Obsidian 說明文件將 vault 定義為「Obsidian 在本機檔案系統中儲存筆記的資料夾」。中間沒有資料庫，也不需要先執行匯出。

這項特性正是兩者能搭配使用的原因。Claude Code 原本就能讀取目錄、搜尋文字、直接編輯檔案，以及執行 shell 命令。vault 提供 Markdown 檔案、每個檔案開頭的 YAML front matter、筆記之間的連結，以及具有實際意義的目錄樹。重新歸檔擷取內容和重建索引，都是一般的檔案操作。不需要使用 Obsidian 外掛，執行代理程式的電腦上也不必啟動 Obsidian。

但筆記不是程式碼。測試失敗時，你可以知道代理程式破壞了建置流程。代理程式若悄悄改寫 40 篇筆記，卻沒有任何機制會通知你。本指南大多在說明如何重新建立這層安全防護。

在 VPS 上執行 vault 的優點

在筆記型電腦上的 vault 中執行 Claude Code 沒有問題。對於五分鐘的工作，這也是正確的做法。但將 vault 移到伺服器後，能合理交辦的工作範圍會改變。

• 工作階段不會受筆記型電腦影響。先在伺服器的 tmux 工作階段中啟動 agent，即使闔上筆電上蓋，長時間工作仍會繼續執行。
• 只要能建立 SSH 連線，就能從任何地方存取 vault，包括手機。
• agent 會在不是日常使用的電腦上執行，因此即使發生錯誤，也只會影響一台可重新建置的主機。
• 同步作業會在伺服器上持續執行，因此 agent 編輯的副本，就是手機幾秒後開啟的副本。

持久工作階段最重要，而且設定方式與在 VPS 的 tmux 中執行 Claude Code相同。如何從手機連線到該工作階段，請參閱使用手機操作 Claude Code。當一個長時間的重新歸檔工作已占用一個工作階段，而你在旁邊再啟動第二個工作階段後，一個工作階段可以將工作交給另一個工作階段，不必再手動轉述結果。

將 vault 放到伺服器

為 vault 建立專用目錄。使用 rsync 從筆電上傳現有的 vault；這個指令要在筆電上執行，不是在伺服器上執行。

rsync -av --exclude '.obsidian/workspace*.json' \
  ~/Documents/notes/ you@your-vps:vaults/notes/

接著檢查伺服器上收到的內容：

ls -a ~/vaults/notes
du -sh ~/vaults/notes

你應該會看到頂層資料夾和 .obsidian 目錄。.obsidian 包含 vault 自身的設定，包括 app.json 和 workspace.json。workspace.json 記錄目前開啟的窗格，因此你每次在桌面應用程式中移動窗格時，它都會變更。這就是 rsync 那行略過它的原因：在不同電腦之間複製這個檔案會持續產生變更，但沒有實際用途。

將 vault 同步到筆電與手機

Syncthing 可在不讓第三方代管檔案的情況下，讓伺服器副本與各裝置保持同步。請從專案自己的 apt repository 安裝。

sudo mkdir -p /etc/apt/keyrings
sudo curl -L -o /etc/apt/keyrings/syncthing-archive-keyring.gpg https://syncthing.net/release-key.gpg
echo "deb [signed-by=/etc/apt/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable-v2" \
  | sudo tee /etc/apt/sources.list.d/syncthing.list
sudo apt-get update
sudo apt-get install syncthing

將其以隸屬於使用者帳戶的 system service 執行：

sudo systemctl enable syncthing@$USER.service
sudo systemctl start syncthing@$USER.service
systemctl status syncthing@$USER.service

status 應回報 active (running)。Web 介面預設監聽 127.0.0.1:8384，因此不會暴露到網際網路，也不需要為此設定防火牆規則。請從筆電透過 SSH 轉送連接埠來存取：

ssh -L 8384:127.0.0.1:8384 you@your-vps

保持該連線開啟，接著在瀏覽器中開啟 http://127.0.0.1:8384，將 ~/vaults/notes 新增為資料夾，並與筆電配對。Syncthing 支援 Linux、macOS、Windows 與 Android。官方 Android 應用程式已於 2024 年底停止發布版本，目前常用的社群版本是 F-Droid 上的 Syncthing-Fork（截至 2026 年 8 月查核）。Syncthing 自己的 FAQ 表示：「目前的 Syncthing 團隊沒有計畫在可預見的未來正式支援 iOS」，因此 iPhone 需要使用第三方用戶端，或改用完全不同的工具。如果您希望將檔案保留在已經執行的伺服器後方，Syncthing 與 Nextcloud 的比較說明了兩者之間的取捨。

在 vault 旁安裝 Claude Code

curl -fsSL https://claude.ai/install.sh | bash
claude --version

安裝成功時，會輸出類似 2.1.211 (Claude Code) 的版本資訊。如果 shell 回應 claude: command not found，表示安裝程式已將 binary 放在 ~/.local/bin/claude，但該目錄不在 PATH 中。將它加入 shell profile，然後開啟新的 shell。claude doctor 會輸出安裝與設定診斷資訊，但不會啟動工作階段。這是最快確認問題所在的方法。

Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。免費的 Claude.ai 方案不包含存取權限。請在 vault 內啟動它，因為工作目錄就是它的檔案工具預設可存取的位置：

tmux new -s vault
cd ~/vaults/notes
claude

先按 Ctrl-b 分離，再按 d，工作階段會繼續執行。之後可用 tmux attach -t vault 重新連線。如果 Claude 工作階段本身已結束，而不只是被分離，claude --resume 會將它恢復；恢復工作階段並尋找其文字記錄 說明這些文字記錄在伺服器上的位置，方便你查看代理程式實際對筆記執行了哪些操作。

撰寫 CLAUDE.md，說明 vault 的規範

Claude Code 會在每次工作階段開始時，從工作目錄及其上層的每個目錄載入 CLAUDE.md。在程式碼儲存庫中，有一半的規範可直接從程式碼看出來。但在 vault 中並非如此：檔案內容不會說明 00-inbox/ 是暫存區，也不會說明已封存的筆記不可修改。請將這些規範寫下來，否則代理程式會自行猜測。

# Vault conventions

## Layout
- `00-inbox/` holds unfiled captures. Only I write here.
- `10-notes/` holds permanent notes, one idea per file.
- `20-daily/` holds daily notes named `YYYY-MM-DD.md`.
- `90-archive/` is frozen. Never edit anything under it.

## Rules
- Every note opens with an H1 that matches its filename.
- Front matter holds `tags` and `created` only. Do not invent fields.
- Link by note name using Obsidian double bracket links. No paths, no `.md`.
- Never rename or move a file. Ask me instead.
- Never edit more than five files in one go without listing them first.

將檔案控制在 200 行以內。Claude Code 文件將此列為目標，因為較長的檔案會占用更多上下文視窗，也較難持續遵循。請在工作階段中執行 /context，並檢查 Memory files 下的清單，以確認檔案已載入。Claude Code 讀取 CLAUDE.md，而不是 AGENTS.md；如果你已為其他工具維護其中一個檔案，請參閱 AGENTS.md 與 CLAUDE.md 的關係。包含數千則筆記的 vault，會遇到大型儲存庫相同的限制；在 Claude Code 中管理上下文將詳細說明這些限制。

權限規則，避免大量改寫

將以下內容儲存為 .claude/settings.json，放在 vault 中。

{
  "permissions": {
    "defaultMode": "plan",
    "deny": [
      "Read(/90-archive/**)",
      "Edit(/90-archive/**)",
      "Bash(rm *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(mv *)"
    ],
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  }
}

關於這個檔案，有四點值得注意。每一點都曾讓人誤判。

• 規則的評估順序是先 deny，再 ask，最後 allow，並由第一個符合的規則決定結果。規則的具體程度不會改變這個順序，因此廣泛的 deny 規則無法在其中包含 allow-listed 例外。
• Read deny 規則也會封鎖同一路徑上的 Edit 和 Write 工具，包括在該路徑建立新檔案。加入相符的 Edit 規則不會增加成本，還能涵蓋 Read 規則無法處理的那個內建工具。
• Claude Code 只會依據 Edit(path) 和 Read(path) 規則檢查檔案路徑。若寫入 Write(...) 或 Glob(...) 路徑規則，規則會被接受，但永遠不會套用，並在啟動時回報為檔案權限檢查無法比對的規則。原本要使用 Write(...) 時，請改用 Edit(...)。
• 將 permissions.defaultMode 設為 plan 時，Claude 會讀取檔案並執行唯讀命令，但在你核准計畫前不會編輯筆記。acceptEdits 的行為相反，會接受所有檔案編輯而不詢問。對 vault 而言，plan 才是符合實際情況的預設值。

Read 和 Edit 規則使用 gitignore 模式語法。Read(/90-archive/**) 開頭的斜線會將模式限定在專案根目錄，因此只會比對 vault 頂層的 90-archive/，不會比對其他位置。省略斜線時，deny 規則會比對 vault 下任何層級中同名的目錄。對於名為 Private 的資料夾，這通常才是你要的行為。規則生效時，工具會回傳 File is covered by a Read deny rule in your permission settings。

有一項限制必須明確說明。這些規則涵蓋 Claude 的內建檔案工具，以及它在 Bash 中辨識的檔案命令，例如 cat、head、tail 和 sed。但規則不涵蓋自行開啟檔案的腳本。因此，第一道防線是檔案位置，而不是設定：如果某個檔案絕不能讓模型讀取，就不要將它放在 vault 根目錄下。deny 規則是第二層防線。在 VPS 上安全執行 Claude Code 說明主機層級的安全措施；自動模式與權限設定 則進一步說明各種模式。

Git 是資料庫中的復原按鈕

資料庫沒有測試套件，因此版本控制就是完整的安全網。在代理程式接觸資料庫前，先將資料庫設為儲存庫。

cd ~/vaults/notes
git init
printf '.obsidian/workspace*.json\n.trash/\n*.sync-conflict-*\n' >> .gitignore
git add -A
git commit -m "Vault before the agent touches it"

請在開始工作前提交變更，不要等到工作結束後才提交。以乾淨的工作樹開始，產生的差異就只會是代理程式的變更，不會混入其他內容。每次執行會修改內容的提示前，git status 都應輸出 nothing to commit, working tree clean。

git diff --stat
git restore .

git diff --stat 會列出每個已變更的檔案，以及各檔案移動的行數。如果清單比預期更長，git restore . 會捨棄工作樹中所有尚未提交的變更，讓資料庫回到工作開始前的狀態。如果已經提交，git revert <sha> 會建立新的提交，以反轉舊提交。

git 與同步功能搭配使用時有一個陷阱。如果 Syncthing 分享資料庫目錄，它也會同步 .git 以及其他所有內容；兩台機器同時寫入 git index 時，會在儲存庫中產生衝突檔案。只在伺服器上使用 git，並將 .git 加入資料庫根目錄中的 .stignore 檔案：

.git
.obsidian/workspace*.json

值得交給代理程式處理的3項工作

這些是提示詞，不是腳本。每一項的結果都能在事後以 git diff --stat 驗證。

重建索引筆記

Read every file in 10-notes/ and rewrite 10-notes/index.md so it lists each
note under its primary tag, sorted alphabetically within each tag, using the
one-line summary from each note's front matter. Change no file except
index.md. Show me the plan before you write anything.

限制條件寫在提示詞中，也是你要驗證的內容。git diff --stat 應只列出一個檔案。如果列出多個檔案，請執行 git restore .，並將範圍說得更明確。

找出孤立項目與失效連結

List every note in 10-notes/ that no other note links to, and every link in
the vault that points at a file that does not exist. Write the results to
90-reports/orphans.md and edit nothing else.

連結稽核是對整個 vault 進行文字搜尋，這類工作正是此工具最擅長、速度最快的工作。除了產生一個報告檔案之外，不會修改任何內容。因此，在你還在了解代理程式如何處理筆記時，這是適合優先嘗試的工作。

將會議內容整理成工作項目

Read 00-inbox/2026-08-19-standup.md. For each action item, create one file in
10-notes/tasks/ named after the action, with front matter holding owner, due
and status. Leave the source file untouched. List the files you created.

既有內容不會被修改，因此復原方式是刪除新建立的檔案。這項特性比提示詞中的任何措辭都更能確保工作適合安全嘗試。

每次都要讀取差異內容。CLAUDE.md 是模型讀取的指引，不是用戶端強制執行的規則。因此，請將 git diff --stat 中的檔案清單視為實際發生內容的紀錄。

發生什麼問題

讀取因 File is covered by a Read deny rule in your permission settings 失敗。 某個拒絕規則比對到您想讀取的路徑。拒絕規則中的未錨定單一區段目錄模式，會在任何深度比對，因此 Read(archive/**) 也會封鎖 10-notes/archive/。在模式開頭加上斜線，將比對固定在單一位置。

Claude Code 啟動時警告某項規則不會經過檔案權限檢查。 您為某個檔案檢查不會查詢的工具撰寫了路徑規則。將 Write(90-archive/**) 替換為 Edit(90-archive/**)，警告就會消失。

檔案名稱中出現 sync-conflict。 Syncthing 會在雙方同時編輯時，依照 <filename>.sync-conflict-<date>-<time>-<modifiedBy>.<ext> 的模式重新命名其中一側。當 agent 在伺服器上編輯記事，而您同時在筆電上開啟相同記事時，就會發生這種情況。一次只在一個位置編輯，並在切換前等待同步完成。

agent 移動記事後，連結失效。 在 Obsidian 內重新命名時，Obsidian 會改寫內部連結。它無法看見其他程序執行的重新命名，因此 agent 在伺服器上移動檔案後，所有連結都會指向舊名稱。因此，vault 的 CLAUDE.md 必須加入「不得重新命名或移動檔案」的規則，重新命名也應在桌面應用程式中執行。

agent 編輯了您從未提及的記事。 檢查 permissions.defaultMode。在 acceptEdits 中，所有檔案編輯都會直接核准，不會顯示提示。將其設定為 plan，工作階段就會以唯讀模式開始，直到您核准計畫。

FAQ

使用 Claude Code 搭配 vault 時，需要安裝 Obsidian 外掛嗎？

不需要。Obsidian 會將筆記儲存為一般資料夾中的純文字 Markdown 檔案，因此 Claude Code 可使用一般檔案工具讀取及編輯這些檔案。Obsidian 內不會安裝任何元件，Obsidian 也不必保持執行。代理程式會操作這些檔案，而 Obsidian 只是能讀取這些檔案的多個程式之一。

如何阻止 Claude Code 讀取 vault 中的私人筆記？

將私人筆記放在 vault 目錄之外。這是可靠的做法，因為權限規則涵蓋 Claude 的內建檔案工具及其可識別的 Bash 檔案指令，但不涵蓋自行開啟檔案的 script。作為第二層防護，針對 .claude/settings.json 中的路徑，同時加入 Read 和 Edit deny 規則。要求 Claude 開啟該處的一個檔案，以測試規則：遭封鎖的讀取會回傳 File is covered by a Read deny rule in your permission settings。

Claude Code 會破壞我的 Obsidian 連結嗎？

有可能，但只有一種特定情況。你在 Obsidian 內重新命名筆記時，Obsidian 會更新內部連結；但它看不到其他程序執行的重新命名。代理程式在伺服器上移動檔案後，連結仍會指向舊名稱。在 CLAUDE.md 中告訴代理程式不得重新命名或移動檔案，並在桌面應用程式中執行重新命名。編輯筆記內容是安全的，因為連結以純文字形式儲存在檔案中。

我可以對筆記型電腦上的 vault 執行這項操作，而不是使用 VPS 嗎？

可以。CLAUDE.md、權限規則及 git 使用習慣都相同。伺服器額外提供的是即使闔上筆電上蓋仍能持續的工作階段，以及從任何能建立 SSH 連線的裝置存取工作階段的能力。如果這兩點都不是目前工作的需求，請在本機執行。如果你不想維護任何機器，Cowork 會在 Anthropic sandbox 中，針對你連接的資料夾執行；Cowork 與 Claude Code 的比較說明哪一種較適合這類 vault。

vault 必須是 git repository 嗎？

Claude Code 要運作不需要，但為了自身安全，建議使用。vault 沒有測試套件，因此工作完成後執行 git diff --stat，是確認實際變更內容最便宜的方法；執行 git restore .，則是復原變更最便宜的方法。每項工作開始前先 commit，讓 diff 只顯示代理程式所做的變更。如果 Syncthing 共用此資料夾，請將 .git 加入 .stignore，避免 repository 在裝置之間複製。