Obsidian Everywhere

在 44 秒内了解远程库桥接

远程设置指南

远程请求 → 语义搜索 → 图谱上下文 → 受保护的编辑 → 挂载丢失后恢复。

---

Obsidian Everywhere 围绕三个理念构建：

1. 笔记是图谱和语义知识库，而不是一堆文本文件。 反向链接、n 跳邻域、最短路径、PageRank、全文搜索和本地多语言嵌入，可将主题转化为聚焦且受令牌预算限制的上下文。
2. 无论 Agent 在哪里运行，都应该能使用你的库。 远程库桥接通过经过身份验证的 Streamable HTTP，提供同一图谱及其受保护的写入工具。在另一台服务器上运行的 Claude Code 或 Codex 进程，可以搜索、推理、追加内容并重组仍保留在你自己设备上的库。
3. 版本控制操作应比文件写入受到更严格的限制。 如果库本身或其中一个已配置文件夹已是 Git 仓库，自选的 Git 工具可以检查状态、有限范围的差异和本地历史记录。提交和推送都必须先预览、明确确认，并使用短时有效的一次性批准 ID。

本地路径始终是真实数据来源。Obsidian Everywhere 不会创建托管副本、遥测服务或强制要求的云账户；可选的 Git 推送仅会发布到操作者已配置的仓库。远程访问是由你运行的传输方式，而不是库同步产品。

目录

• 在 44 秒内了解远程库桥接
• 功能
• 三种核心工作流
• 库 Git
• 不使用你的库也能试用
• 为什么选择 Obsidian Everywhere？
• 它究竟运行在哪里？
• 快速入门
• 配置
• 开发
• 项目状态
• 贡献
• 许可证

功能

vault (.md files)
  │  parse · watch
  ▼
SQLite index (FTS5)  ⇄  in-memory graph (graphology)
  │                       n-hop · shortest path · PageRank
  ▼
41 core MCP tools + 0–5 opt-in Git tools
  │
  ▼
local stdio  ·  authenticated remote HTTP  ·  OAuth HTTP

• 🧩 图谱 + 语义上下文引擎 — Markdown 解析器（维基链接、嵌入、frontmatter、嵌套标签、标题、块引用）、带全文搜索的 SQLite 索引，以及用于 n 跳遍历、最短路径和 PageRank 的内存中 graphology 层。get_context_bundle 会将一个主题及其最有用的邻居打包到指定的 token 预算中。
• 🌍 远程 Vault Bridge — 外部服务上的 Agent 可通过经过身份验证的 Streamable HTTP 使用同样的搜索、图谱、上下文和受保护的编辑工具。可使用专用网络或 ngrok 等 HTTPS 隧道；Vault 本身始终保留在你控制的机器上。
• 📎 全 Vault 文件读取 — Markdown 以及文本、代码和数据文件、PDF、DOCX、PPTX、XLSX、OpenDocument、EPUB、RTF 和常见图像均可建立索引并供使用，无需上传到转换服务。内容提取采用惰性方式、会缓存且受大小限制，并可通过 search_files 搜索。
• 🧠 可选的本地语义搜索 — semantic_search 和使用 method: "semantic" 的 get_related 会完全在你的机器上运行多语言嵌入模型（multilingual-e5-small），无需 API 密钥、云账户或运行 Ollama 进程。通过 npm install @huggingface/transformers@^4.2.0 安装可选运行时；模型只会下载一次（约 120MB，缓存在 ~/.obsidian-everywhere/ 下），之后即可完全离线运行。默认禁用此功能，以确保服务内存低于 200 MiB；有额外可用内存时，可通过 OBSIDIAN_EVERYWHERE_ENABLE_SEMANTIC=true 启用。
• 🛡️ 安全写入和可靠挂载 — 支持部分编辑、先试运行的批量操作、回滚快照、可恢复删除，以及可选择启用的 Beta 挂载保护。如果可移动驱动器、NAS 共享或容器挂载消失，索引会保留、写入会被阻止，并在挂载恢复后执行完整协调。
• 🌱 可审查的 Git 检查点（默认关闭） — 检查 Vault 或一个已配置仓库文件夹的状态、有界差异和本地历史记录。更高权限模式支持提交所选文件，以及由操作员固定目标的 HTTPS 推送；这两种操作均需先预览并通过一次性审批，有效期为五分钟。
• 🛠️ 41 个核心 MCP 工具，显式启用 Git 后最多 46 个 — 结构化读取、附件提取、图谱导航、语义检索、安全生命周期操作、持久化的 Obsidian 设置，以及明确的运行状况报告。

三个核心工作流

1. 将带有链接的 Vault 转化为聚焦的 AI 上下文

精确搜索可找到你写下的词语。语义搜索即使在措辞或语言不同的情况下，也能找到相同的想法。随后，图谱遍历会说明匹配笔记之间的关系。get_context_bundle 会将这些信号组合成有界的上下文包，而不是将整个 Vault 倾倒给模型。

2. 从外部服务使用和编辑这些上下文

在本地 Vault 旁运行 Obsidian Everywhere，通过专用网络或 HTTPS 隧道公开其 HTTP 端点，并在远程 MCP 客户端中注册该 URL。远程 Agent 可以读取和搜索本地 Vault，然后使用相同的受保护工具创建、追加、移动、标记或清理笔记。每次写入成功后，服务都会在返回前重新建立索引，因此下一次远程工具调用即可看到更改。

完整的 ngrok 操作流程请参阅 使用 ngrok 的 Remote Vault Bridge 教程。

3. 使用 Git 审查 Vault 更改并创建检查点

当知识库或其中某个实际文件夹包含自己的 .git 目录时，Agent 可以检查与你在本地检查到的相同仓库状态，然后根据明确指定的文件列表创建提交。将 OBSIDIAN_EVERYWHERE_GIT_REPO_PATH 设置为相对于知识库的文件夹路径，或保留默认值 . 以使用知识库根目录。推送是一项独立且限制更严格的功能：它只能通过由操作人员固定的 HTTPS 目标，将当前 HEAD 发布到其现有上游分支。它绝不会拉取、获取、切换分支、构造自由格式的 refspec，或接受任意 Git 参数。

先将 OBSIDIAN_EVERYWHERE_GIT_MODE=read 设为初始模式；只有在查看 知识库 Git 指南 中的安全模型后，才切换到 commit 或 push。

完整工具列表

读取

工具	功能
vault_overview	笔记数量、热门标签、PageRank 中心笔记、最近修改的笔记——用于快速了解概况
vault_status	挂载可用性、索引新鲜度、写入可用性和上次完整协调时间
search_notes	支持标签／文件夹筛选的全文搜索（包含三元组回退机制，可匹配仅靠 unicode61 会遗漏的 CJK 子串——参见 DECISIONS.md D9）；每条结果附有链接数量和标签
search_files	搜索文件名、知识库相对路径，以及从 PDF、Office／OpenDocument、EPUB、RTF、文本／代码／数据文件和其他附件中提取的本地文本
semantic_search	通过本地嵌入模型进行可选的语义搜索（multilingual-e5-small，不使用外部服务）；默认的低内存模式下已禁用
read_note	结构化内容／frontmatter／链接／标签，并支持按行分页；可选按标题范围读取
read_file	读取任意知识库文件：提取文档文本并可选择页面／幻灯片／工作表，或为具备相应能力的 MCP 客户端提供原生图像内容；准确的磁盘路径可自动修复轻微的监视器延迟
list_notes	明确列出指定文件夹中的笔记并支持分页；还可为每篇笔记列出指定的 frontmatter 字段（例如 status、project）
list_folder	列出直接子文件夹、笔记和附件
regex_search	使用 JavaScript 正则表达式搜索，并提供文件、行号和摘录
get_backlinks	列出所有链接到指定笔记的笔记，并提供链接所在的句子
get_neighborhood	列出指定笔记周围明确的 n 跳节点／边（将链接视为无向链接）
get_context_bundle	杀手级功能。 将中心笔记和按优先级排列的 1 跳邻居打包进令牌预算
list_tags	完整的嵌套标签层级及其数量
get_notes_by_tag	列出带有指定标签的笔记（支持嵌套标签）
find_orphans	查找没有入链或出链的笔记
find_unresolved	查找无法解析到任何笔记的链接，并按目标分组
find_path	查找两个笔记之间最短的关联路径，并为每一跳提供一行摘要
get_related	查找尚未直接链接的相似笔记——默认使用共享标签／邻居的 Jaccard 相似度，也可使用 method: "semantic" 进行嵌入相似度搜索
get_hotkeys / get_obsidian_settings	已持久化的快捷键命令 ID、Templates 文件夹和核心插件设置
validate_base	对 .base 文件或围栏 Base 区块进行静态 YAML／结构验证

写入

工具	功能
create_note	创建新笔记（含 frontmatter）；立即重新索引，下次工具调用即可看到该笔记
apply_template	根据模板创建笔记，并替换 {{date}}/{{time}}/{{title}}（Obsidian 核心 Templates 变量）
append_to_note	向笔记追加内容，可选在指定标题下追加；如果找不到该标题，则安全失败
move_note / rename_note / delete_note	生命周期操作，包括重写入站链接、反向链接保护措施，以及可恢复的废纸篓
replace_text / patch_section	带保护措施的精确文本编辑和限定标题范围的编辑
update_frontmatter / remove_frontmatter_field	修改属性，而不替换笔记正文
bulk_update_frontmatter / bulk_remove_frontmatter_field	对文件夹（或整个库）中的每篇笔记执行相同操作；先试运行，并支持回滚
add_tags / remove_tags	为单篇笔记添加或移除 frontmatter 标签
rename_tag	在整个库的 frontmatter 和行内 #tag 文本中重命名标签；先试运行，并支持回滚
bulk_replace / rollback_bulk_edit	先试运行，再执行文件夹范围/正则替换，并提供快照和回滚
set_hotkey / set_templates_folder	更新持久化的 Obsidian 设置（可能需要重新加载库）

Vault Git — 仅在明确启用时注册

工具	最低 Git 模式	功能
git_status	read	安全的工作区状态信息（相对于所选仓库），以及本地领先/落后信息；不执行 fetch
git_diff	read	安全受跟踪路径的限量补丁，以及 head 模式下明确指定的未跟踪路径；外部 diff 驱动程序、textconv 和子模块均保持禁用
git_log	read	最近的本地提交历史，可选限定为一个安全文件
git_commit	commit + 常规写入门控	先预览，再使用有效期为五分钟的一次性审批 ID，仅提交明确选择的安全文件
git_push	push + 常规写入门控	先预览，再通过由操作员固定的 HTTPS 目标，将已批准的当前 HEAD 推送到其现有上游

生效配置	已注册工具数
Git off，禁用常规写入	22
Git off，启用常规写入	41
Git read，禁用常规写入	25
Git read，启用常规写入	44
Git commit，禁用常规写入	25
Git commit，启用常规写入	45
Git push，禁用常规写入	25
Git push，启用常规写入	46

如果禁用了常规写入门控，即使配置的 Git 模式更高，git_commit 和 git_push 也不会注册；三个 Git 读取工具仍然可用。因此，OAuth 要求 Git 模式达到足够级别，并设置 OAUTH_ENABLE_WRITE_TOOLS=true，才能执行提交或推送。

stdio 和 bearer-token HTTP 传输默认启用常规写入工具；公共 OAuth 连接器传输默认禁用（设置 OAUTH_ENABLE_WRITE_TOOLS=true 即可启用）——请参阅配置和 DECISIONS.md D15。所有传输默认都独立禁用 Git。

Vault Git

Vault Git 是一个可选的检查点与发布层，适用于已位于库中的仓库。它不是同步引擎，也绝不会初始化仓库。库所在机器上必须安装 Git。操作员通过 OBSIDIAN_EVERYWHERE_GIT_REPO_PATH 选择唯一一个仓库；该路径必须是安全的、相对于库的真实目录，默认为 .。所选目录必须是普通仓库的精确根目录，并且包含真实的本地 .git 目录。库的其余部分仍会被索引，并可供常规图谱、搜索和笔记工具使用。

例如，位于 /Volumes/SanDisk/jwhong 的库可以保留整个库的上下文，同时让 Git 工具仅操作 /Volumes/SanDisk/jwhong/DSLab：

export OBSIDIAN_VAULT_PATH=/Volumes/SanDisk/jwhong
export OBSIDIAN_EVERYWHERE_GIT_REPO_PATH=DSLab
export OBSIDIAN_EVERYWHERE_GIT_MODE=read

在该配置下，Git 工具的路径输入和输出均相对于 DSLab；普通笔记和文件工具的路径仍相对于知识库根目录。所有 Git 工具都会拒绝父级仓库发现、关联工作树、子模块根目录、经符号链接指向的仓库路径，以及不安全的外部或经符号链接指向的对象／引用／日志／核心元数据布局（包括备用对象存储）。知识库、所选仓库和 .git 目录的规范身份会在启动时记录，并在每次运行 Git 子进程前重新检查；替换目录或引入符号链接后，服务会安全失败，直到操作员验证挂载并重启服务。 提交和推送还会拒绝分离分支、浅历史、稀疏检出、工作树级 Git 配置、嫁接／替换引用，以及正在进行的历史操作。

使用提供的 Compose 文件时，为 bearer 服务设置 OBSIDIAN_VAULT_HOST_PATH=/Volumes/SanDisk/jwhong 和 OBSIDIAN_EVERYWHERE_HTTP_GIT_REPO_PATH=DSLab。OAuth 服务有独立的输入项 OBSIDIAN_EVERYWHERE_OAUTH_GIT_REPO_PATH； 两个服务专用的仓库路径默认均为 .。

请选择足以覆盖工作流的最小权限：

OBSIDIAN_EVERYWHERE_GIT_MODE	添加的工具	网络访问
off（默认）	无	无
read	git_status、git_diff、git_log	无；历史记录和领先／落后状态仅限本地
commit	读取工具 + 在启用常规写入时提供 git_commit	无
push	读取／提交工具 + 在启用常规写入时提供 git_push	仅可推送到已批准的现有上游

推送模式还要求操作员提供以逗号分隔的映射，将每个允许的上游远程名称映射到一个精确且不含凭据的 HTTPS 目标地址。继续使用上面的 DSLab 示例：

export OBSIDIAN_EVERYWHERE_GIT_MODE=push
export OBSIDIAN_EVERYWHERE_GIT_REPO_PATH=DSLab
export OBSIDIAN_EVERYWHERE_GIT_ALLOWED_PUSH_REMOTES=origin=https://github.com/owner/repo.git

只有在整个知识库都是仓库时，才使用 OBSIDIAN_EVERYWHERE_GIT_REPO_PATH=.。

所选分支必须已跟踪映射远程上的普通分支，并且该远程解析出的唯一推送 URL 必须与固定映射完全一致。URL 属于操作员配置，而非 MCP 工具输入；凭据、查询、片段、调用方选择的分支和调用方选择的 refspec 均会被拒绝。 Git 必须使用知识库所在机器上已配置的凭据，以非交互方式向该精确 URL 进行身份验证。

目标引用取自分支现有的上游映射，而非本地分支名称。例如，本地 main 跟踪 origin/release 时，只能推送到 release；调用方不能替换为其他分支。

提交和推送刻意设计为两个步骤：

git_status
git_diff
git_commit { action: "preview", message: "docs: update project notes", paths: ["Projects/Atlas.md"] }
  → inspect the plan and explicitly approve it
git_commit { action: "execute", approvalId: "<UUID from preview>" }

git_push { action: "preview" }
  → inspect the exact HEAD, upstream, and outgoing count; explicitly approve it
git_push { action: "execute", approvalId: "<UUID from preview>" }

批准 ID 在五分钟后过期、只能使用一次，并且在审查过的仓库状态发生变化时失效。预览不会创建提交，也不会连接网络。隐藏、排除和敏感路径会被省略或阻止；提交只会选择最终条目为常规文件的精确变更路径，以及已删除路径；钩子、签名、clean 筛选器（包括 Git LFS）、子模块和疑似机密均会被拒绝。 推送审查最多包含 100 个待推送提交和 200 个变更 Blob；每个文件／Blob 的内容上限为 8 MiB，总内容上限为 32 MiB；还会扫描提交消息和合并结果。提交消息必须为单行，并会进行机密扫描；提交批准会绑定到精确的拟议树。

推送执行会使用所显示的 HTTPS 目标地址字面值，以及针对已审查上游引用的精确 OID 租约。该租约是比较并交换保护机制，并非任意强制推送的许可；如果远程引用已删除、前进或重置，推送将失败，而不会覆盖该引用。 推送还会拒绝仓库本地凭据助手、URL 重写、http.* 传输设置，以及所选远程的代理覆盖。可信的 HTTPS 凭据和所需的任何网络策略，都应配置在仓库之外的知识库所在机器用户级或系统级 Git 配置中。 这里有意不提供 git_exec 或自由形式命令工具。向远程 Agent 传递原始 Git 参数，实质上就是一种远程代码执行原语：Git 别名可以展开为 shell 命令，钩子会执行程序，diff/textconv 驱动程序会运行辅助程序，SSH 传输会启动命令，凭据助手也可能调用可执行文件。少量参数固定的固定命令才是安全边界，而非无关紧要的 API 选择。

启用提交或推送之前，请先阅读完整的设置说明、操作限制和故障排除指南：使用 Git 支持的知识库。

不使用你的知识库进行试用

先运行内置演示。它会创建一个临时示例知识库，展示图谱方向和未解析链接发现，预览安全的批量编辑，然后移除示例。它绝不会读取或更改你的笔记。

npx -y obsidian-everywhere demo

准备好连接真实知识库时，可为 Codex、ChatGPT Desktop、Claude Code 和 Claude Desktop 生成可复制的配置：

npx -y obsidian-everywhere init /absolute/path/to/your/vault
npx -y obsidian-everywhere doctor /absolute/path/to/your/vault

init 只会打印配置，不会编辑客户端的全局设置。 doctor 会检查 Node.js、权限、Obsidian 元数据、SQLite、解析和图谱引擎，但不会打印笔记内容。添加 --share 可在将诊断信息粘贴到 issue 之前隐藏知识库路径。

为什么选择 Obsidian Everywhere？

有几款不错的 Obsidian MCP。选择与你的工作方式相匹配的架构，不要想当然地认为某个服务在所有方面都胜出。

	Obsidian Everywhere	obsidian-mcp-server	Local REST API	TurboVault
安装	npx	npx	Obsidian 社区插件	cargo install / 二进制文件
已发布工具	41 个核心工具；启用 Git 选项后最多 46 个	14 个	16 个	74 个
Obsidian 必须保持打开	否	是	是	否
最佳图谱功能	PageRank、最短路径、n-hop、未解析链接	结构化读取中的出站链接	实时 Obsidian 元数据/搜索	多跳、中心性、聚类、建议
安全编辑	局部编辑；批量编辑支持试运行、快照和回滚	精细编辑及 frontmatter/标签管理	实时标题/块/frontmatter 修补	冲突哈希、审计回滚、基于 Git 的批处理
实时应用命令/当前文件	仅已保存的设置	是	是	否
远程传输	stdio、私有网络上的 bearer HTTP 或 HTTPS 隧道、OAuth 2.1	stdio、带 JWT/OAuth 的 HTTP	带 API 密钥的 HTTP	stdio、HTTP、WebSocket、TCP
最适用场景	从无头知识库获取图谱和语义上下文，包括带防护的远程访问和编辑	丰富的、由应用驱动的 CRUD 和 Omnisearch	直接控制正在运行的 Obsidian 应用	最大功能广度、多知识库和高级分析

此比较依据各项目于 2026-07-20 发布的文档核对。空白或范围较窄的单元格表示“文档中未说明”，而非项目永远无法支持。如果你需要活动文件状态或命令面板执行功能，请选择基于插件的服务。如果你需要一个无头、单命令的图谱服务，具备按 Token 预算控制的上下文、带防护的清理功能和范围严格受限的 Git 检查点，那么 Obsidian Everywhere 正是为这一需求而设计的。

默认情况下，所有内容都在本地运行。无需账户、API 密钥、托管知识库或遥测。

请参阅 docs/architecture.md 了解构建方式，参阅 docs/deploy.md 了解部署拓扑，并参阅 docs/ngrok-remote.md 阅读完整的外部服务教程。使用 Git 支持知识库的运维人员还应阅读 docs/git-vault.md。

实际上在哪里运行？

obsidian-everywhere 进程需要直接访问你知识库中的 .md 文件（以便解析文件、监视变更等）——因此它必须始终运行在知识库文件实际存放的那台机器上（“知识库所在机器”：很可能是你的笔记本电脑）。你使用哪台客户端机器并不重要——服务端始终运行在知识库所在机器上；只有客户端的连接方式会改变。

使用 MCP 客户端的位置	所需配置
与知识库所在机器相同	stdio。 无需其他配置——Codex、ChatGPT Desktop、Claude Code/Desktop 或其他本地客户端都会直接启动服务。
你控制的另一台机器（实验室/工作服务器、另一台笔记本电脑、SSH 主机）	通过 Tailscale 等私有网络使用 Bearer-token HTTP，或使用 ngrok 等 HTTPS 隧道。
claude.ai（网页应用或移动应用）	OAuth HTTP + 公共 HTTPS URL（通过 Cloudflare Tunnel）。claude.ai 运行在 Anthropic 的云端，而非你的网络中，因此无法访问 Tailscale 或 localhost——它需要一个真正的公共地址。

你可以同时运行其中多个配置（例如，在笔记本电脑上运行 stdio，并且为工作服务器运行 Bearer-token HTTP）——它们是彼此独立的进程，都会为同一个知识库建立索引。

快速入门

最快的安装方式无需克隆或构建。请在知识库所在机器上运行此命令（即 .md 文件所在的位置）：

npx -y obsidian-everywhere /absolute/path/to/your/vault

MCP 客户端通常会使用以下某种配置为你启动此命令。

不确定路径和运行时是否已就绪？运行此隐私安全诊断：

npx -y obsidian-everywhere doctor /absolute/path/to/your/vault

选项 A — Codex CLI 和 ChatGPT Desktop，与知识库在同一台机器上（stdio）

Codex CLI、Codex IDE 扩展和 ChatGPT Desktop 的 Codex 体验共用同一 MCP 配置（官方 MCP 文档）。添加一次服务即可：

codex mcp add obsidian-everywhere -- npx -y obsidian-everywhere /absolute/path/to/your/vault
codex mcp list

然后重启 ChatGPT Desktop（或 IDE 扩展）。在 ChatGPT Desktop 中，你也可以通过 Settings → MCP servers → Add server 添加，选择 STDIO，并输入相同的命令和参数。在 Codex 中输入 /mcp，确认预期工具已连接：启用普通写入且关闭 Git 时为 41 个，或参见 知识库 Git 中记录的条件计数。

若要改用项目范围的配置，请将以下内容添加到受信任项目的 .codex/config.toml；使用 ~/.codex/config.toml 可使其全局可用：

[mcp_servers.obsidian-everywhere]
command = "npx"
args = ["-y", "obsidian-everywhere", "/absolute/path/to/your/vault"]
startup_timeout_sec = 30

请使用知识库的绝对路径。GUI 应用可能不会继承与你的终端相同的 PATH；如果找不到 npx，请将 command 替换为 command -v npx 的绝对路径。

选项 A′ — Claude Code，与知识库在同一台机器上（stdio）

仍在知识库所在机器上：

claude mcp add obsidian-everywhere -- npx -y obsidian-everywhere /path/to/your/vault

或者使用环境变量代替位置参数：

OBSIDIAN_VAULT_PATH=/path/to/your/vault claude mcp add obsidian-everywhere -- npx -y obsidian-everywhere

选项 A″ — Claude Desktop，与知识库在同一台机器上

在知识库所在机器上的 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "obsidian-everywhere": {
      "command": "npx",
      "args": ["-y", "obsidian-everywhere", "/absolute/path/to/your/vault"]
    }
  }
}

选项 A‴ — Google Antigravity CLI（agy）

添加到全局 Antigravity MCP 配置文件（~/.gemini/config/mcp_config.json）：

{
  "mcpServers": {
    "obsidian-everywhere": {
      "command": "npx",
      "args": ["-y", "obsidian-everywhere", "/absolute/path/to/your/vault"]
    }
  }
}

选项 B — 在另一台设备上使用 Codex、ChatGPT Desktop 或 Claude

选择一种安全方式连接到存储库的设备：

• **私有网络：**使用 Tailscale，并按照以下步骤操作。
• **公共 HTTPS 隧道：**使用只读优先的 ngrok Remote Vault Bridge 教程。切勿直接暴露 本地明文 HTTP 端口。

步骤 1 — 在两台设备之间设置私有网络，如果你选择了 Tailscale：

# on BOTH the vault machine and the MCP client machine
curl -fsSL https://tailscale.com/install.sh | sh   # or: brew install tailscale (macOS)
tailscale up                                        # opens a browser to log in / join your "tailnet"
tailscale status                                    # confirm both machines can see each other

从 tailscale status 中记下存储库设备的 Tailscale 主机名/IP （类似 my-macbook.tailnet-name.ts.net 或 100.x.y.z）。

步骤 2 — 在存储库设备上启动服务：

openssl rand -hex 32
# Save that output in a password manager, then use the same value on both machines.
export OBSIDIAN_EVERYWHERE_TOKEN="<saved token>"
OBSIDIAN_VAULT_PATH=/path/to/vault \
  npx -y --package obsidian-everywhere obsidian-everywhere-http

保存好令牌，步骤 3 会用到。（如需让服务持续运行，而不是在前台终端中运行，请参阅 docs/deploy.md 中的 LaunchAgent 设置；如果存储库设备是服务器，也可以通过 docker-compose.yml 在 Docker 中运行。）

步骤 3 — 使用步骤 1 中存储库设备的 Tailscale 地址，从另一台设备（例如实验室服务器）连接。对于 Codex（以及共用的 ChatGPT Desktop 配置），请将令牌保存在环境变量中：

export OBSIDIAN_EVERYWHERE_CLIENT_TOKEN="<the token from step 2>"
codex mcp add obsidian-everywhere \
  --url http://<vault-machine-tailscale-name>:3737/mcp \
  --bearer-token-env-var OBSIDIAN_EVERYWHERE_CLIENT_TOKEN

确保启动 ChatGPT Desktop 时该环境变量可用，然后重启它。或者，如果你的应用版本提供相应字段，也可以使用 Settings → MCP servers 添加 Streamable HTTP URL 和 bearer 凭据。

对于 Claude Code：

claude mcp add --transport http obsidian-everywhere \
  http://<vault-machine-tailscale-name>:3737/mcp \
  --header "Authorization: Bearer <the token from step 2>"

现在，第二台设备可以访问在第一台设备上建立索引的存储库。完整操作指南（Docker、LaunchAgent）： docs/deploy.md。

选项 C — claude.ai 网页版/移动应用（自定义连接器、OAuth）

这需要一个公共 HTTPS 端点——claude.ai 的服务器无法访问你的 Tailscale 网络或 localhost。完整的 Cloudflare Tunnel 操作指南，请参阅 docs/deploy.md。服务器可通过 https://your-domain 访问后：

1. claude.ai → Settings → Connectors → Add custom connector
2. 服务器 URL：https://your-domain/mcp
3. claude.ai 会自动发现 OAuth 流程并显示此服务器的登录 页面——输入你配置的 OAUTH_LOGIN_SECRET。

**只有在确实想让 claude.ai 网页版/移动应用读取你的存储库时，才需要这样做。**如果你只使用 Claude Code（在本地或从另一台设备使用），完全可以跳过此步骤——选项 A/B 已完全满足需求，无需使用 Cloudflare/OAuth。

配置

环境变量	使用方	含义
OBSIDIAN_VAULT_PATH	all	Vault 路径（或作为 CLI 位置参数传入）
OBSIDIAN_EVERYWHERE_DB	all	SQLite 索引路径覆盖值。文件名因传输方式而异：index-stdio.db、index-http.db 或 index-oauth.db。通常默认使用 <vault>/.obsidian-everywhere/<filename>；如果直接启动的 macOS 进程所用 Vault 位于 /Volumes/ 下，则改用 ~/.obsidian-everywhere/ 下按 Vault 区分的文件，以避免在外部文件系统上出现不安全的 SQLite WAL 行为。Compose 会设置自己的显式 /vault/.obsidian-everywhere/ 路径。
OBSIDIAN_EVERYWHERE_TOKEN	http-cli.js	静态 bearer 令牌
PORT	http-cli.js、oauth-http-cli.js	HTTP 端口（默认分别为 3737 / 3738）
OAUTH_ISSUER_URL	oauth-http-cli.js	公共 HTTPS 源站（例如你的 Cloudflare Tunnel 主机名）
OAUTH_LOGIN_SECRET	oauth-http-cli.js	单用户登录密钥
OBSIDIAN_EVERYWHERE_READONLY	cli.js、http-cli.js	设为 true 可禁用所有写入工具（默认：启用写入工具）
OBSIDIAN_EVERYWHERE_ENABLE_SEMANTIC	all	安装可选的 @huggingface/transformers peer 后选择启用。默认禁用，因为模型的 RSS 内存占用可能超过 500 MiB；图谱、FTS 和附件搜索仍可用。
OBSIDIAN_EVERYWHERE_MAX_ATTACHMENT_MIB	all	本地提取时源附件的大小上限（默认 64，范围为 1–1024）。调高该值可能导致内存占用超过 200 MiB 的目标。
OBSIDIAN_EVERYWHERE_MAX_PDF_MIB	all	PDF 专用提取上限（默认 48，并受附件上限约束）。
OBSIDIAN_EVERYWHERE_MAX_ARCHIVE_ENTRY_MIB	all	从 Office/OpenDocument/EPUB 归档中读取的未压缩 XML/HTML 条目大小上限（默认 32）。
OBSIDIAN_EVERYWHERE_MOUNT_GUARD	all entrypoints	选择启用 Beta 挂载丢失保护和自动协调
OBSIDIAN_EVERYWHERE_MOUNT_SENTINEL	all entrypoints	可选的相对 Vault 身份路径，例如 .obsidian/app.json
OBSIDIAN_EVERYWHERE_MOUNT_RECHECK_MS	all entrypoints	运行时挂载探测间隔（默认 5000）
OAUTH_ENABLE_WRITE_TOOLS	oauth-http-cli.js	设为 true 可在公共连接器上启用所有写入工具（默认：关闭）
OBSIDIAN_EVERYWHERE_GIT_MODE	直接进程和容器环境	Git 功能：off（默认）、read、commit 或 push。commit/push 仍需要通过传输方式自身的常规写入门控。
OBSIDIAN_EVERYWHERE_GIT_REPO_PATH	直接进程和容器环境	一个安全的、相对于 Vault 的真实目录，其中包含仓库；默认值为 .。Git 工具路径相对于此目录，而普通工具路径仍相对于 Vault。
OBSIDIAN_EVERYWHERE_GIT_ALLOWED_PUSH_REMOTES	直接进程和容器环境	以逗号分隔的精确 name=https://host/path.git 映射，例如 origin=https://github.com/owner/repo.git；在 push 模式下必需。URL 不得包含凭据、查询参数或片段。
OBSIDIAN_EVERYWHERE_HTTP_GIT_MODE / OBSIDIAN_EVERYWHERE_HTTP_GIT_REPO_PATH / OBSIDIAN_EVERYWHERE_HTTP_GIT_ALLOWED_PUSH_REMOTES	提供的 Docker Compose .env	Bearer 服务输入，在其容器内映射到三个通用 Git 变量；模式默认值为 off，仓库路径默认值为 .。
OBSIDIAN_EVERYWHERE_OAUTH_GIT_MODE / OBSIDIAN_EVERYWHERE_OAUTH_GIT_REPO_PATH / OBSIDIAN_EVERYWHERE_OAUTH_GIT_ALLOWED_PUSH_REMOTES	提供的 Docker Compose .env	独立的 OAuth 服务输入，在其容器内进行映射；模式默认值为 off，仓库路径默认值为 .。OAuth 的 commit/push 仍需要 OAUTH_ENABLE_WRITE_TOOLS=true。

Obsidian Everywhere 不会修改用户 Vault 的 .gitignore。内置的 Vault Git 会拒绝隐藏的 .obsidian-everywhere 路径；但是，如果索引目录 位于你也使用普通 Git 管理的仓库中，请将 .obsidian-everywhere/ 添加到该仓库自己的 .gitignore 中。 Git 配置独立于语义搜索和普通笔记工具。 对于 stdio 和 bearer HTTP，OBSIDIAN_EVERYWHERE_READONLY=true 会同时移除普通写入工具和 Git commit/push。对于 OAuth，commit/push 需要同时设置 OBSIDIAN_EVERYWHERE_GIT_MODE=commit|push 和 OAUTH_ENABLE_WRITE_TOOLS=true。在上述所有非 off 模式下，git_status、git_diff 和 git_log 始终是只读工具。

直接启动的 CLI、HTTP、OAuth 和 LaunchAgent 进程会读取通用 Git 变量名。 提供的 docker-compose.yml 会刻意使用上文中服务专用的 HTTP/OAuth .env 输入项，这样为某个对外服务启用 Git 就不会悄然为另一个服务启用 Git。

开发

npm run dev:stdio          # tsx, no build step
npm run dev:http
npm run dev:oauth-http
npm test                   # vitest, runs against fixtures/test-vault
npm run typecheck
npm run lint
npm run format:check
npm run memory:smoke      # asserts the default attachment workload stays below 200 MiB RSS

fixtures/test-vault/ 是一个包含 30 多篇笔记的测试资料库，涵盖解析器需要处理的各种链接和解析边缘情况（管道别名、标题和块链接、嵌入、嵌入 frontmatter 的 wikilink、嵌套标签、不同文件夹中的同名文件、未解析的链接、排除代码块，以及韩文文件名／标签／wikilink）。src/**/*.test.ts 中的每项测试都会使用它运行。

项目状态

当前发布系列包含图谱和可选的本地语义上下文引擎、全部三种传输方式（stdio、bearer HTTP、OAuth HTTP）、41 个核心 MCP 工具、受保护的部分写入和批量写入，以及 Codex、ChatGPT Desktop 和 Claude 的客户端配置。Remote Vault Bridge 是一条一等部署路径。其可选启用的挂载保护仍处于 Beta 阶段，目前正在收集有关可移动驱动器、NAS 共享和容器挂载的跨平台反馈。另行选择启用的 Vault Git 工具提供 read、commit 和 push，作为逐步扩大的、受审查门控的能力，而不是通用 Git shell。

欢迎帮助测试真实的远程资料库设置，请前往 Beta Issue #18， 或在讨论 #19中提问。欢迎使用一次性资料库；请勿分享笔记内容、令牌或私人主机名。

贡献

欢迎提交 Bug 报告、功能请求和 PR——开发环境设置、测试约定，以及测试资料库与测试套件的关系，请参阅 CONTRIBUTING.md。安全问题： 请参阅 SECURITY.md，不要公开提交议题。

许可证

MIT——请参阅 LICENSE。