如何在VPS上安全运行Claude Code管理Obsidian库

Claude Code 为什么适用于 Obsidian 库

Obsidian 库是一个 Markdown 文件目录，因此 Claude Code 可以像处理代码仓库一样处理它。Obsidian 官方网站称，它“将笔记以纯文本 Markdown 文件的形式存储在本地”；Obsidian 帮助文档将库定义为“Obsidian 在本地文件系统中存储笔记的目录”。中间没有数据库，也不需要导出步骤。

这一点就是两者能够配合使用的根本原因。Claude Code 原本就能读取目录、搜索文本、直接编辑文件并运行 shell 命令。库会向它提供 Markdown 文件、每个文件顶部的 YAML front matter、笔记之间的链接，以及具有实际含义的目录树。将捕获内容移入其他目录和重新构建索引，都是普通的文件操作。不需要使用 Obsidian 插件，运行代理的机器上也不必启动 Obsidian。

问题在于，笔记不是代码。测试失败时，你可以知道代理破坏了构建；但如果代理悄悄改写了 40 条笔记，没有任何机制会告诉你。本指南的大部分内容，都是为了重新建立这层安全保障。

在 VPS 上运行 vault 的优势

在笔记本电脑上对 vault 运行 Claude Code 是可行的。对于只需运行五分钟的任务，这通常是正确选择。将 vault 迁移到服务器后，您可以合理地交给它处理更多任务。

• 会话不会随笔记本电脑结束。在服务器的 tmux 会话中启动代理后，即使合上笔记本电脑盖，长时间任务也会继续运行。
• 只要能够建立 SSH 连接，就可以从任何位置访问 vault，包括手机。
• 代理运行在一台不是您日常使用的机器上，因此即使出现错误，也只会影响一台可以重装的服务器。
• 同步会继续在服务器上运行，因此代理编辑的副本，就是几秒钟后手机打开的副本。

持久会话最为重要，其配置方式与在 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 行跳过它的原因：在计算机之间复制该目录会不断产生变更，但没有实际用途。

将保管库同步到笔记本电脑和手机

Syncthing 可在不让第三方持有文件的情况下，让服务器副本与您的设备保持同步。请从项目自有的 apt 软件源安装。

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

将其作为与您的用户账户关联的系统服务运行：

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，说明安装程序已将二进制文件放在 ~/.local/bin/claude，但该目录不在 PATH 中。将该目录添加到 shell 配置文件，然后打开新的 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，说明知识库的约定

Claude Code 会在每次会话开始时，从当前工作目录及其所有上级目录加载 CLAUDE.md。在代码仓库中，一半的约定可以直接从代码中看出。在知识库中则不同：文件内容不会说明 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 的关系。包含数千条笔记的知识库会遇到与大型代码仓库相同的限制，在 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 *)"
    ]
  }
}

需要了解该文件的四点，因为每一点都曾导致问题。

• 规则按先拒绝、再询问、后允许的顺序评估，并由第一个匹配项决定。规则的具体程度不会改变顺序，因此宽泛的拒绝规则中不能包含允许列表例外。
• Read 拒绝规则还会阻止对同一路径使用 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/，不会匹配其他位置。省略斜杠后，拒绝规则会匹配 vault 下任意深度、名称相同的目录；对于名为 Private 的文件夹，这通常才是所需行为。规则生效时，工具会返回 File is covered by a Read deny rule in your permission settings。

有一个限制需要明确说明。这些规则覆盖 Claude 的内置文件工具，以及它在 Bash 中识别的文件命令，例如 cat、head、tail 和 sed。但它们无法覆盖自行打开文件的脚本。因此，第一道防线是文件位置，而不是配置：如果某个文件绝不能被模型读取，就不要将它放在 vault 根目录下。拒绝规则是第二层防线。在 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 索引时，会在代码库中产生冲突文件。仅在服务器上使用 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.

链接审计需要在整个知识库中进行文本搜索，这正是该工具最擅长、速度最快的工作类型。除生成一个报告文件外，它不会修改其他内容。因此，在你还在了解代理如何处理笔记时，这是适合作为第一项任务的工作。

将会议记录转换为任务

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> 模式重命名同时编辑的其中一侧。您在服务器上让代理编辑笔记，同时又在笔记本电脑上打开同一笔记时，就会发生这种情况。每次只在一个位置编辑，并在切换前等待同步完成。

代理移动笔记后，链接失效。 在 Obsidian 内部发生重命名时，Obsidian 会重写内部链接。它无法识别其他进程执行的重命名，因此代理在服务器上移动文件后，所有链接仍会指向旧名称。因此，保管库的 CLAUDE.md 中应包含“永不重命名或移动文件”的规定，重命名操作也应在桌面应用中完成。

代理编辑了您从未提及的笔记。 检查 permissions.defaultMode。在 acceptEdits 中，每次文件编辑都会直接通过，不会提示确认。将其设置为 plan 后，会话将以只读模式启动，直到您批准计划。

FAQ

使用 Claude Code 处理 vault 是否需要安装 Obsidian 插件？

不需要。Obsidian 会将笔记以纯文本 Markdown 文件的形式存储在普通文件夹中，因此 Claude Code 可以使用常规文件工具读取和编辑这些文件。无需在 Obsidian 中安装任何内容，Obsidian 也不必保持运行。代理直接处理这些文件，而 Obsidian 只是能够读取这些文件的多个程序之一。

如何阻止 Claude Code 读取 vault 中的私密笔记？

将私密笔记保存在 vault 目录之外。这是可靠的措施，因为权限规则只适用于 Claude 内置的文件工具和它识别的 Bash 文件命令，不适用于自行打开文件的脚本。作为第二层防护，请在 .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 .，是撤销这些变更的最低成本方式。每次任务开始前先提交，这样 diff 中只会显示代理本次执行的修改。如果 Syncthing 共享该文件夹，请将 .git 添加到 .stignore，避免 repository 在设备之间复制。