Claude Code 在 VPS 上管理 Obsidian vault 的設定與限制

Claude Code 為何能處理 Obsidian vault

Obsidian vault 是一般資料夾，因此 Claude Code 能以處理程式碼儲存庫的相同方式處理它。Obsidian 說明文件將 vault 定義為檔案系統上的資料夾，其中包含筆記、附件，以及存放 Obsidian 自有設定的設定資料夾。筆記本身採用 Markdown；Obsidian 網站表示，它「會將筆記以純文字 Markdown 檔案儲存在本機」。中間不需要資料庫，也不需要匯出步驟。

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

但要注意，筆記不是程式碼。測試失敗時，你會知道 agent 破壞了 build。可是，沒有任何機制能在 agent 悄悄改寫 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 自身的設定，例如快速鍵、佈景主題和社群外掛，以及 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 年 11 月確認）。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、Ultra、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 window，實際遵循的情況也會較不一致。請在工作階段中執行 /context，並檢查 Memory files 下方的清單，以確認檔案已載入。自 v2.1.277 起，Claude Code 也能讀取 AGENTS.md；但預設只有在目前工作目錄及其上層沒有 CLAUDE.md 時才會讀取，因此同時包含兩者的 vault 只會載入 CLAUDE.md。如果你已為其他工具保留 AGENTS.md，請參閱 AGENTS.md 與 CLAUDE.md 的關係。包含數千則筆記的 vault 會遇到與大型儲存庫相同的限制，詳見 在 Claude Code 中管理 context。

權限規則，避免檔案被大量改寫

將下列內容儲存為 .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 *)"
    ]
  }
}

這個檔案有 4 點值得了解，因為每一點都曾讓人誤判。

• 規則依序先套用 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 自身的檔案編輯維持封鎖狀態，直到你核准計畫；但這不會讓工作階段變成唯讀。Auto mode 是 v2.1.283 起內建的初始模式，因此通常可以使用。啟用時，useAutoModeDuringPlan 設定（預設為開啟）會讓 auto mode 分類器在規劃期間檢查 shell 命令，而不是詢問你。它核准的命令，例如在資料夾中執行 sed -i，可能會在計畫建立前修改筆記。你的 deny 和 ask 規則仍然有效。在已啟用 bypass permissions 的互動式終端機工作階段中，例如使用 --allow-dangerously-skip-permissions 啟動的工作階段，plan mode 完全不會強制執行其封鎖規則：Claude 在規劃期間嘗試執行的檔案編輯或 shell 命令會直接執行，不會提示；只有明確的 ask 規則，以及已識別的 rm 和 rmdir 關鍵路徑移除操作仍會提示。acceptEdits 的行為相反，會接受所有檔案編輯而不詢問，也會接受 vault 中常見的檔案系統命令，例如 mv、cp、rm 和 sed。對 vault 而言，關閉下方設定後，plan 仍是誠實的預設值。

若要讓 Claude 在規劃期間對內建唯讀集合以外的每個 shell 命令都提示，請關閉該設定，並在未啟用 bypass permissions 的情況下啟動工作階段，因為在已啟用該權限的工作階段中，這項設定不會產生任何效果。Repository 無法替你關閉這項設定，因此應將設定放在 vault 內的 .claude/settings.local.json，或放在 ~/.claude/settings.json 以涵蓋所有專案，而不是放在共用的 .claude/settings.json：

{
  "useAutoModeDuringPlan": false
}

Read 和 Edit 規則使用 gitignore 模式語法。Read(/90-archive/**) 開頭的斜線會將模式錨定在定義該設定的設定檔所繫結的目錄。對於 vault 的 .claude/settings.json 或 .claude/settings.local.json 中的規則，該目錄是工作階段的主要工作目錄，也就是你啟動 claude 時所在的資料夾；這不一定是 repository 根目錄。如上方所示從 vault 根目錄啟動時，該規則會比對 vault 頂層的 90-archive/，不會比對其他位置。同一規則放在 ~/.claude/settings.json 時，會錨定於 ~/.claude，改為封鎖 ~/.claude/90-archive/，因此 vault 規則應放在 vault 自身的設定中。若省略斜線，deny 規則會比對目前目錄下任何深度、名稱為 Private 的目錄；對於名為 Private 的資料夾，通常需要的就是這種寫法。規則觸發時，工具會回傳 File is covered by a Read deny rule in your permission settings。

有一項限制必須明確說明。這些規則涵蓋 Claude 的內建檔案工具、它在 Bash 中識別的檔案命令，例如 cat、head、tail、sed 和 tee，以及 shell 重導向的目標。規則不涵蓋未指定檔案名稱的讀取命令，例如從上層資料夾執行的 grep -r，也不涵蓋自行開啟檔案的 script，因此簡短的 Python script 仍可能改寫規則原本要保護的筆記。若要在作業系統層級封鎖所有 process，必須使用 Claude Code 的 sandbox，並另外啟用。第一道防線因此是檔案位置，而不是設定：如果某項內容絕不能被模型讀取，就不要將它放在 vault 根目錄下。Deny 規則是第二層防線。在 VPS 上安全執行 Claude Code 說明主機層級的做法，auto mode 與權限設定 則詳細說明各種模式。

Git 是 vault 的復原按鈕

vault 沒有測試套件，但版本控制並不是完整的安全網。Claude Code 會自動為檔案編輯工具所做的變更建立檢查點，而 /rewind 可以獨立於 Git 還原這些受追蹤的 vault 變更。只有透過 shell 指令變更的檔案不會受追蹤；若 Claude 先使用檔案工具編輯某個檔案，之後再由 shell 變更該檔案，這些變更仍可復原。Git 應保留為獨立的歷史記錄，同時涵蓋追蹤範圍以外的變更。在 agent 首次存取 vault 前，先將 vault 建立為 repository。

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"

請在開始工作前提交，不要等到工作結束後才提交。以乾淨的工作樹開始，完成後產生的差異就只會是 agent 所做的工作。每次進行會編輯檔案的提示前，git status 都應輸出 nothing to commit, working tree clean。

git diff --stat
git restore .

git diff --stat 會列出有未暫存變更的受追蹤檔案，以及每個檔案變更的行數；使用 git status --short 也能查看新檔案和已暫存的變更。如果清單比預期長，git restore . 會捨棄受追蹤檔案的未暫存變更，並從 index 還原這些檔案。它不會處理未追蹤的新檔案或已暫存的變更。如果已經提交，git revert <sha> 會建立新的提交，反轉先前的提交。

git 與同步功能整合時有一個陷阱。如果 Syncthing 分享 vault 資料夾，它會連同其他內容一起複製 .git；兩台機器同時寫入 git index 時，會在 repository 內產生衝突檔案。只在伺服器上使用 git，並將 .git 加入 vault 根目錄中的 .stignore 檔案：

.git
.obsidian/workspace*.json

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

這些是提示，不是腳本。每個提示的設計都能在之後使用 git diff --stat 和 git status --short 檢查結果。

重建索引備註

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 應只列出 1 個檔案。如果列出多個檔案，請執行 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 中進行文字搜尋，這類工作正是此工具最擅長處理的項目。除了 1 個報告檔案外，這項工作只會讀取內容，不會修改其他檔案。因此，在你仍在了解代理如何處理筆記時，這是適合優先嘗試的工作。

將會議內容轉成工作項目

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 和 git status --short 視為實際變更紀錄。

問題排查

讀取時出現 File is covered by a Read deny rule in your permission settings。 某條 deny 規則比對到你想讀取的路徑。deny 規則中未錨定的單一目錄層級模式會在任意深度比對，因此 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 會改寫內部連結。外部重新命名通常會被視為刪除舊檔案並建立新檔案，因此在伺服器上重新命名筆記後，指向舊名稱的連結會無法解析。移動筆記但不變更名稱時，只要名稱仍然唯一，僅包含名稱的連結會保持有效；但包含舊路徑的連結會失效。因此，vault 的 CLAUDE.md 應包含「絕不重新命名或移動檔案」，而重新命名應在桌面應用程式中進行。

agent 編輯了你從未提及的筆記。 檢查 permissions.defaultMode。在 acceptEdits 中，每次檔案編輯以及 sed 等常用命令都會直接獲准，不會提示。將它設為 plan，Claude 自身的編輯就會等到你核准計畫後才執行，除非工作階段具備 bypass 權限。如果筆記仍在規劃期間變更，請檢查兩件事。某個 shell 命令可能已經執行：plan mode 會讓 auto mode 分類器核准命令，除非在本機或使用者設定中，useAutoModeDuringPlan 設為 false。另一種可能是工作階段啟動時具備 bypass 權限，例如使用 --dangerously-skip-permissions 或 --allow-dangerously-skip-permissions 旗標，或在使用者設定中設為 bypassPermissions 預設模式；此時檔案編輯與 shell 命令都會在規劃期間直接執行，不會提示。請不要使用這些選項，重新啟動 claude。

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 的伺服器上執行工作，並處理你透過 Claude Desktop 應用程式連接的資料夾；Cowork 與 Claude Code 的比較方式會說明哪一個較適合這類 vault。

vault 必須是 git repository 嗎？

Claude Code 本身不需要 vault 是 git repository；自動 checkpoint 及 /rewind 也能還原受追蹤檔案的編輯內容。Git 仍會提供獨立的歷程，其中也包含僅由 shell 命令變更、checkpoint 不會追蹤的檔案。工作完成後使用 git diff --stat，檢視受追蹤檔案的未暫存變更；使用 git status --short，查看新檔案及已暫存的變更。git restore . 會復原受追蹤檔案的未暫存變更，但不會移除新的未追蹤檔案，也不會復原已暫存的變更。每次工作開始前先 commit，讓 diff 只顯示代理程式本次執行的變更。如果使用 Syncthing 共用資料夾，請將 .git 加入 .stignore，避免 repository 在裝置之間複製。