OmniRoute Obsidian 上下文源完整指南配置、22 个 MCP 工具与 WebDAV 双向同步【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 将 Obsidian 笔记库Vault作为一个上下文源接入内置 MCP Server让 Agent 能搜索、读取、写入、修补笔记并触发桌面↔手机双向同步。本文基于 docs/frameworks/OBSIDIAN_CONTEXT.md 展开逐节验证了其声明的 REST 设置接口、SQLite 配置存储、WebDAV 凭据管理和 22 个 MCP 工具在源码中的真实实现读完你可以独立完成配置、通过 API 脚本化管理连接并理解客户端的重试、超时与错误分类机制。一、整体定位Obsidian 作为 Context SourceOmniRoute 通过 Obsidian 桌面端内的Local REST API社区插件与笔记库对话。插件在本地暴露一个 REST 接口OmniRoute 的客户端封装它再把能力以 MCP 工具的形式开放给 Agent。集成能力覆盖全文搜索与 JSON Logic 结构化搜索读取/写入/追加/外科式修补/删除/移动笔记列出 Vault 目录树、获取文档大纲heading → 行号、笔记元数据frontmatter/标签/链接/字数读取当前活跃文件、按日期获取 daily/weekly/monthly 周期笔记列出并执行 Obsidian 命令自动化插件与命令可选的 WebDAV 桌面↔手机双向 Vault 同步。文档声明的事实来源Source of truth分布在以下文件中本文的每个结论都在这些源码中逐一核对过文件职责src/lib/obsidian/api.tsLocal REST API 客户端重试、超时、错误分类 同步服务器客户端src/lib/db/obsidian.tstoken / base URL / vault 路径 / WebDAV 凭据的 SQLite 持久化含加密src/lib/obsidianSync.tsWebDAV Vault 同步的启用/禁用与凭据生成open-sse/mcp-server/tools/obsidianTools.ts22 个 MCP 工具的完整定义src/app/api/settings/obsidian/route.ts设置 REST API保存/校验/断开src/app/api/settings/obsidian/webdav/route.tsWebDAV 同步 REST APIopen-sse/mcp-server/server.ts工具注册与 scope 强制执行的接线点二、前置条件与端口陷阱配置之前必须先满足一个硬性前提Obsidian 桌面端已安装并正在运行 Local REST API 插件。其 REST 接口默认监听HTTP127.0.0.1:27123这也是 OmniRoute 的默认 base URL见 src/lib/obsidian/api.ts 中的DEFAULT_OBSIDIAN_BASE_URL。这里有一个高频踩坑点文档与源码都反复强调端口27123HTTP才是 Local REST API 的默认接口端口27124是插件另一个独立的 MCP/HTTPS 端点被设置路由显式拒绝。若从其他设备连接使用http://tailscale-ip:27123。设置路由在 src/app/api/settings/obsidian/route.ts 中用正则/:27124(?:\/|$)/拦截含 27124 端口的 URL并返回明确指引URL uses port 27124, which is the MCP endpoint (HTTPS, self-signed cert). The Obsidian Local REST API uses plain HTTP on port 27123. Please use http://ip:27123 instead.三、配置存储SQLitekey_value表而非环境变量OmniRoute没有为 Obsidian 提供任何环境变量——token 与 base URL 全部存于 SQLitekey_value表namespace 为obsidian由 src/lib/db/obsidian.ts 读写。token 落盘前会经过 src/lib/db/encryption.ts 的加密该模块以aes-256-gcm算法加密见文件第 30 行ALGORITHM常量读取时解密失败则回退为明文兼容decrypt(parsed) ?? parsed见 src/lib/db/obsidian.ts保证旧数据的向后兼容。配置键一览Key用途是否加密api_keyLocal REST API 的 bearer token是base_urlREST base URL默认http://127.0.0.1:27123否vault_pathVault 目录绝对路径供 WebDAV 同步否webdav_username自动生成的 WebDAV 用户名同步用否webdav_password自动生成的 WebDAV 密码同步用是webdav_enabled是否启用 WebDAV 同步否所有 setter 均使用INSERT OR REPLACE幂等写入且异常被视为非致命持久化失败时 token 仍在内存中可用。读取侧统一做 JSON 解析 类型校验取不到就返回默认值base_url默认http://127.0.0.1:27123webdav_enabled默认false。四、通过 REST API 配置连接配置入口有两个Endpoint 仪表盘Context Sources标签页的ObsidianSourceCard或直接调用设置 REST API所有方法都需要仪表盘鉴权。OmniRoute 默认服务端口为 20128# 保存并校验 Local REST API tokenPOST 会先调用 status 端点做连通性/鉴权校验 curl -X POST http://localhost:20128/api/settings/obsidian \ -H Content-Type: application/json \ -d {token:obsidian-rest-api-key,baseUrl:http://127.0.0.1:27123} # 查看连接状态返回 connected、hasToken、baseUrl、vaultPath curl http://localhost:20128/api/settings/obsidian # 断开连接清除已存 token curl -X DELETE http://localhost:20128/api/settings/obsidian从 src/app/api/settings/obsidian/route.ts 源码可以确认 POST 的完整校验链isAuthenticated(request)鉴权未通过返回 401Zod schema{ token: string(1..5000), baseUrl?: url }严格解析.strict()多余字段直接 400baseUrl缺省时沿用已存值命中 27124 端口正则时返回 400 并给出纠正提示用待保存的 token 构造客户端调用checkStatus()若响应中authenticated false则拒绝保存Token validation failed: invalid token校验通过后才调用setObsidianToken/setObsidianBaseUrl落盘——先验证后持久化避免存下无效凭据。GET 返回{ connected, hasToken, baseUrl, vaultPath }其中connected的定义是 token 非空见 src/lib/db/obsidian.ts 的getObsidianConfigDELETE 则直接clearObsidianToken()。WebDAV 同步 REST APIsrc/app/api/settings/obsidian/webdav/route.ts 管理可选的 WebDAV 同步由 src/lib/obsidianSync.ts 驱动# 为某个 Vault 目录启用 WebDAV 同步自动生成用户名/密码 curl -X POST http://localhost:20128/api/settings/obsidian/webdav \ -H Content-Type: application/json \ -d {vaultPath:/home/me/MyVault} # 查询 WebDAV 同步状态凭据仅在启用时返回 curl http://localhost:20128/api/settings/obsidian/webdav # 禁用 WebDAV 同步清除凭据 由 OmniRoute 管理的 .stignore curl -X DELETE http://localhost:20128/api/settings/obsidian/webdavenableObsidianVaultSync()src/lib/obsidianSync.ts的源码细节值得注意先path.resolve并校验路径存在且是目录否则返回 400 错误通过crypto.getRandomValues从 62 字符字母数字表中随机生成12 位用户名和24 位密码密码以密文落盘禁用时若 Vault 目录中的.stignore文件包含# Managed by OmniRoute标记才会删除它——即只清理自己管理的内容不碰用户自己的忽略规则。此外源码中有一处文档未展开的安全细节GET 状态接口虽然对所有已登录调用方开放但明文 WebDAV 密码只返回给真正的管理级主体dashboard 会话或 manage scope key匿名开放模式下只能拿到密码是否已设置的布尔标记——代码注释明确标注这是 GHSA-62vw 的修复见 src/app/api/settings/obsidian/webdav/route.ts。按 API Key 作用域的上下文源可选Obsidian 配置可以按 API key 隔离getObsidianConfigForApiKey(apiKeyId)src/lib/db/obsidian.ts先从api_key_context_sources表src/lib/db/apiKeyContextSources.ts查该 key 自己的 token/base URL/vault 路径当该 key 配置存在且enabled且 token 非空时返回source: api_keybaseUrl/vaultPath缺省时回退到全局值否则整体回退到全局配置source: global。这意味着同一个 MCP Server 可以为不同调用方指向不同的 Vault——比如多用户部署时每人读写自己的笔记库。五、REST 客户端实现细节重试、超时与错误分类src/lib/obsidian/api.ts 中的obsidianFetch()是所有调用的底座文档声明的行为在源码中逐条可验证超时每次请求创建AbortController30 秒TIMEOUT_MS 30000未响应即 abort并抛ObsidianTimeoutError若调用方自带 signal则用combineSignals合并两者任一触发都会中止。重试与退避MAX_RETRIES 2即最多 2 次尝试、1 次重试退避间隔为2^retryCount * 200ms首次重试前等 200ms。仅对ObsidianServerError5xx和网络层错误如fetch failed重试ObsidianAuthError401/403和ObsidianNotFoundError404不重试——认证错误重试没有意义。类型化错误分类classifyObsidianError()把 HTTP 状态映射为ObsidianAuthError/ObsidianNotFoundError/ObsidianServerError5xx/ 通用 Error上层可以按类型做差异化处理。友好的连不上提示网络层失败时抛出带操作指引的错误信息明确写出REST API 用 HTTP 27123 端口不要用 27124那是 MCP 的 HTTPS 端点走 Tailscale 时用http://tailscale-ip:27123src/lib/obsidian/api.ts。Vault 相对路径编码encodePath()对路径按/分段后逐段encodeURIComponent保证含空格或特殊字符的笔记路径安全如notes/my note.md→notes/my%20note.md。客户端暴露的方法与 Local REST API 端点一一对应几个非显而易见的映射值得记住结构化搜索使用专用 Content-Typeapplication/vnd.olrapi.jsonlogicjson访问POST /search/文档大纲通过Accept: application/vnd.olrapi.document-mapjson获取笔记元数据frontmatter/标签/链接/字数不含正文通过Accept: application/vnd.olrapi.notejson获取——同一个GET /vault/{path}用 Accept 头切换返回形态外科式修补用PATCH /vault/{path}请求头携带Operationappend/prepend/replace、Target-Typeheading/block/frontmatter、Target可选Create-Target-If-Missing: true移动笔记使用 HTTPMOVE方法加Destination头注意这是 Local REST API 对 WebDAV MOVE 语义的扩展用法周期笔记按/periodic/{period}/或/periodic/{period}/{year}/{month}/{day}/取对应日期的 daily/weekly/monthly 笔记省略日期则为今天。六、22 个 MCP 工具全景全部定义在 open-sse/mcp-server/tools/obsidianTools.ts注册接线在 open-sse/mcp-server/server.ts每个工具都包一层withScopeEnforcement(toolName, handler, toolDef.scopes)参数先经各自的 zod schema 校验如query长度 1–500、contextLength20–500 默认 100结果统一 JSON 序列化后以content: [{type: text, ...}]返回。token/base URL每次调用时实时解析按 API key 优先、再全局因此配置改动无需重启 MCP Server 即生效。读取类工具scoperead:obsidian工具说明obsidian_check_status检查 Local REST API 是否可达且已认证obsidian_search_simple全文搜索笔记内容返回带文件路径的片段contextLength控制上下文宽度默认 100 字符obsidian_search_structured用 JSON Logic 表达式搜索and/or/regex/路径过滤器obsidian_read_note按 vault 相对路径读笔记可只取特定 heading/block/frontmatterobsidian_list_vault列出 Vault 中的文件与目录条目树path缺省为根目录obsidian_get_document_map获取笔记的 heading → 行号映射obsidian_get_note_metadata获取 frontmatter、标签、链接、字符/字数不读正文obsidian_get_active_file获取 Obsidian 中当前活跃文件的路径与内容obsidian_get_periodic_note获取某日期缺省今天的 daily/weekly/monthly 周期笔记obsidian_get_tags列出 Vault 全部标签及出现频率obsidian_list_commands列出可用 Obsidian 命令 ID配合obsidian_execute_commandobsidian_sync_statusOmniRoute 同步服务器状态running、vault 名、端口、uptime、上次同步结果obsidian_sync_conflicts列出未解决的同步冲突path、冲突路径、检测时间写入类工具scopewrite:obsidian工具说明obsidian_write_note创建或整体覆盖一篇笔记Markdown 内容obsidian_append_note追加内容到笔记末尾或追加到指定 heading/blockobsidian_patch_note在 heading、block 或 frontmatter 字段上做 append/prepend/replace 手术式修改obsidian_delete_note从 Vault 永久删除一篇笔记obsidian_move_note在 Vault 内移动或重命名笔记obsidian_execute_command按命令 ID 执行 Obsidian 命令obsidian_open_file在 Obsidian 中打开文件不存在则创建obsidian_sync_trigger立即触发一次桌面↔手机双向同步obsidian_sync_resolve_conflict解决同步冲突保留local手机版、remote桌面版或keep-both两个要点obsidian_patch_note是写入工具中参数最丰富的zod schema 强制operation ∈ {append, prepend, replace}、targetType ∈ {heading, block, frontmatter}、target非空并可选createTargetIfMissing缺省 false对应请求头Create-Target-If-Missing。它适合在已有笔记的某标题下追加日志这类场景而不动其余内容。四个obsidian_sync_*工具不走 Local REST API而是访问 OmniRoute 的本地同步服务器默认http://127.0.0.1:27781见 src/lib/obsidian/api.ts 的DEFAULT_SYNC_SERVER_URL并且额外要求配置了同步鉴权 token处理器先用getSyncToken()从key_value表namespacesync键omniroute_sync_token取专用 token取不到才回退到 Obsidian REST token。createSyncServerClient的四个方法分别映射/vault/sync/status、/vault/sync/trigger、/vault/sync/conflicts、/vault/sync/resolve冲突解决支持local/remote/keep-both三种策略。七、Scope 与鉴权读写分离由 MCP Server 的 scope 机制强制执行读取工具声明scopes: [read:obsidian]写入工具声明scopes: [write:obsidian]注册时统一经withScopeEnforcement()包裹open-sse/mcp-server/server.ts执行模型与 Notion 上下文源完全一致——受OMNIROUTE_MCP_ENFORCE_SCOPEStrue门控允许集取自OMNIROUTE_MCP_SCOPES或该 API key 的 scope 上下文。完整传输与 scope 语义见 docs/frameworks/MCP-SERVER.md。工具侧的 API key 识别由extractApiKeyId(extra)完成只接受authInfo.clientId为非空且不是anonymous/env-key的值其余一律按无 key处理走全局配置。八、设置端点速查方法路径用途GET/api/settings/obsidian返回{ connected, hasToken, baseUrl, vaultPath }POST/api/settings/obsidian保存并校验 token拒绝 27124 端口DELETE/api/settings/obsidian断开连接清除已存 tokenGET/api/settings/obsidian/webdavWebDAV 同步状态 凭据仅启用时密码仅对管理级主体返回POST/api/settings/obsidian/webdav为指定 Vault 目录启用 WebDAV 同步DELETE/api/settings/obsidian/webdav禁用 WebDAV 同步需要明确的是这些都是仪表盘设置路由不是代理端点——笔记库本体始终经由 Local REST API即配置的base_url和上述 MCP 工具访问仓库中不存在面向公开的/v1Obsidian 代理端点。九、典型使用模式基于笔记库的回答obsidian_search_simple/obsidian_search_structured定位 →obsidian_read_note取全文让 Agent 基于真实笔记作答而不是凭空生成。笔记写作与日志obsidian_write_note/obsidian_append_note记录 Agent 输出或摘要用obsidian_get_periodic_note先取今日 daily note再用obsidian_patch_note在特定标题下追加避免整篇重写。Vault 导航写入前先用obsidian_list_vault、obsidian_get_document_map、obsidian_get_tags摸清结构减少无效读写。Obsidian 自动化obsidian_list_commands发现命令 IDobsidian_execute_command驱动插件/命令obsidian_open_file把某篇笔记直接拉到 Obsidian UI 中。手机同步先启用 WebDAV 同步POST webdav 端点再用obsidian_sync_trigger触发、obsidian_sync_status查看结果、obsidian_sync_conflictsobsidian_sync_resolve_conflict处理冲突。十、延伸阅读MCP Server — 传输方式、scope 强制执行、完整工具清单。Notion Context Source — 另一个内置上下文源scope 执行模型与 Obsidian 一致。Memory System — 持久会话记忆属于自动注入的互补上下文层与本文工具按需拉取的模式形成对照。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OmniRoute Obsidian 上下文源完整指南：配置、22 个 MCP 工具与 WebDAV 双向同步
OmniRoute Obsidian 上下文源完整指南配置、22 个 MCP 工具与 WebDAV 双向同步【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 将 Obsidian 笔记库Vault作为一个上下文源接入内置 MCP Server让 Agent 能搜索、读取、写入、修补笔记并触发桌面↔手机双向同步。本文基于 docs/frameworks/OBSIDIAN_CONTEXT.md 展开逐节验证了其声明的 REST 设置接口、SQLite 配置存储、WebDAV 凭据管理和 22 个 MCP 工具在源码中的真实实现读完你可以独立完成配置、通过 API 脚本化管理连接并理解客户端的重试、超时与错误分类机制。一、整体定位Obsidian 作为 Context SourceOmniRoute 通过 Obsidian 桌面端内的Local REST API社区插件与笔记库对话。插件在本地暴露一个 REST 接口OmniRoute 的客户端封装它再把能力以 MCP 工具的形式开放给 Agent。集成能力覆盖全文搜索与 JSON Logic 结构化搜索读取/写入/追加/外科式修补/删除/移动笔记列出 Vault 目录树、获取文档大纲heading → 行号、笔记元数据frontmatter/标签/链接/字数读取当前活跃文件、按日期获取 daily/weekly/monthly 周期笔记列出并执行 Obsidian 命令自动化插件与命令可选的 WebDAV 桌面↔手机双向 Vault 同步。文档声明的事实来源Source of truth分布在以下文件中本文的每个结论都在这些源码中逐一核对过文件职责src/lib/obsidian/api.tsLocal REST API 客户端重试、超时、错误分类 同步服务器客户端src/lib/db/obsidian.tstoken / base URL / vault 路径 / WebDAV 凭据的 SQLite 持久化含加密src/lib/obsidianSync.tsWebDAV Vault 同步的启用/禁用与凭据生成open-sse/mcp-server/tools/obsidianTools.ts22 个 MCP 工具的完整定义src/app/api/settings/obsidian/route.ts设置 REST API保存/校验/断开src/app/api/settings/obsidian/webdav/route.tsWebDAV 同步 REST APIopen-sse/mcp-server/server.ts工具注册与 scope 强制执行的接线点二、前置条件与端口陷阱配置之前必须先满足一个硬性前提Obsidian 桌面端已安装并正在运行 Local REST API 插件。其 REST 接口默认监听HTTP127.0.0.1:27123这也是 OmniRoute 的默认 base URL见 src/lib/obsidian/api.ts 中的DEFAULT_OBSIDIAN_BASE_URL。这里有一个高频踩坑点文档与源码都反复强调端口27123HTTP才是 Local REST API 的默认接口端口27124是插件另一个独立的 MCP/HTTPS 端点被设置路由显式拒绝。若从其他设备连接使用http://tailscale-ip:27123。设置路由在 src/app/api/settings/obsidian/route.ts 中用正则/:27124(?:\/|$)/拦截含 27124 端口的 URL并返回明确指引URL uses port 27124, which is the MCP endpoint (HTTPS, self-signed cert). The Obsidian Local REST API uses plain HTTP on port 27123. Please use http://ip:27123 instead.三、配置存储SQLitekey_value表而非环境变量OmniRoute没有为 Obsidian 提供任何环境变量——token 与 base URL 全部存于 SQLitekey_value表namespace 为obsidian由 src/lib/db/obsidian.ts 读写。token 落盘前会经过 src/lib/db/encryption.ts 的加密该模块以aes-256-gcm算法加密见文件第 30 行ALGORITHM常量读取时解密失败则回退为明文兼容decrypt(parsed) ?? parsed见 src/lib/db/obsidian.ts保证旧数据的向后兼容。配置键一览Key用途是否加密api_keyLocal REST API 的 bearer token是base_urlREST base URL默认http://127.0.0.1:27123否vault_pathVault 目录绝对路径供 WebDAV 同步否webdav_username自动生成的 WebDAV 用户名同步用否webdav_password自动生成的 WebDAV 密码同步用是webdav_enabled是否启用 WebDAV 同步否所有 setter 均使用INSERT OR REPLACE幂等写入且异常被视为非致命持久化失败时 token 仍在内存中可用。读取侧统一做 JSON 解析 类型校验取不到就返回默认值base_url默认http://127.0.0.1:27123webdav_enabled默认false。四、通过 REST API 配置连接配置入口有两个Endpoint 仪表盘Context Sources标签页的ObsidianSourceCard或直接调用设置 REST API所有方法都需要仪表盘鉴权。OmniRoute 默认服务端口为 20128# 保存并校验 Local REST API tokenPOST 会先调用 status 端点做连通性/鉴权校验 curl -X POST http://localhost:20128/api/settings/obsidian \ -H Content-Type: application/json \ -d {token:obsidian-rest-api-key,baseUrl:http://127.0.0.1:27123} # 查看连接状态返回 connected、hasToken、baseUrl、vaultPath curl http://localhost:20128/api/settings/obsidian # 断开连接清除已存 token curl -X DELETE http://localhost:20128/api/settings/obsidian从 src/app/api/settings/obsidian/route.ts 源码可以确认 POST 的完整校验链isAuthenticated(request)鉴权未通过返回 401Zod schema{ token: string(1..5000), baseUrl?: url }严格解析.strict()多余字段直接 400baseUrl缺省时沿用已存值命中 27124 端口正则时返回 400 并给出纠正提示用待保存的 token 构造客户端调用checkStatus()若响应中authenticated false则拒绝保存Token validation failed: invalid token校验通过后才调用setObsidianToken/setObsidianBaseUrl落盘——先验证后持久化避免存下无效凭据。GET 返回{ connected, hasToken, baseUrl, vaultPath }其中connected的定义是 token 非空见 src/lib/db/obsidian.ts 的getObsidianConfigDELETE 则直接clearObsidianToken()。WebDAV 同步 REST APIsrc/app/api/settings/obsidian/webdav/route.ts 管理可选的 WebDAV 同步由 src/lib/obsidianSync.ts 驱动# 为某个 Vault 目录启用 WebDAV 同步自动生成用户名/密码 curl -X POST http://localhost:20128/api/settings/obsidian/webdav \ -H Content-Type: application/json \ -d {vaultPath:/home/me/MyVault} # 查询 WebDAV 同步状态凭据仅在启用时返回 curl http://localhost:20128/api/settings/obsidian/webdav # 禁用 WebDAV 同步清除凭据 由 OmniRoute 管理的 .stignore curl -X DELETE http://localhost:20128/api/settings/obsidian/webdavenableObsidianVaultSync()src/lib/obsidianSync.ts的源码细节值得注意先path.resolve并校验路径存在且是目录否则返回 400 错误通过crypto.getRandomValues从 62 字符字母数字表中随机生成12 位用户名和24 位密码密码以密文落盘禁用时若 Vault 目录中的.stignore文件包含# Managed by OmniRoute标记才会删除它——即只清理自己管理的内容不碰用户自己的忽略规则。此外源码中有一处文档未展开的安全细节GET 状态接口虽然对所有已登录调用方开放但明文 WebDAV 密码只返回给真正的管理级主体dashboard 会话或 manage scope key匿名开放模式下只能拿到密码是否已设置的布尔标记——代码注释明确标注这是 GHSA-62vw 的修复见 src/app/api/settings/obsidian/webdav/route.ts。按 API Key 作用域的上下文源可选Obsidian 配置可以按 API key 隔离getObsidianConfigForApiKey(apiKeyId)src/lib/db/obsidian.ts先从api_key_context_sources表src/lib/db/apiKeyContextSources.ts查该 key 自己的 token/base URL/vault 路径当该 key 配置存在且enabled且 token 非空时返回source: api_keybaseUrl/vaultPath缺省时回退到全局值否则整体回退到全局配置source: global。这意味着同一个 MCP Server 可以为不同调用方指向不同的 Vault——比如多用户部署时每人读写自己的笔记库。五、REST 客户端实现细节重试、超时与错误分类src/lib/obsidian/api.ts 中的obsidianFetch()是所有调用的底座文档声明的行为在源码中逐条可验证超时每次请求创建AbortController30 秒TIMEOUT_MS 30000未响应即 abort并抛ObsidianTimeoutError若调用方自带 signal则用combineSignals合并两者任一触发都会中止。重试与退避MAX_RETRIES 2即最多 2 次尝试、1 次重试退避间隔为2^retryCount * 200ms首次重试前等 200ms。仅对ObsidianServerError5xx和网络层错误如fetch failed重试ObsidianAuthError401/403和ObsidianNotFoundError404不重试——认证错误重试没有意义。类型化错误分类classifyObsidianError()把 HTTP 状态映射为ObsidianAuthError/ObsidianNotFoundError/ObsidianServerError5xx/ 通用 Error上层可以按类型做差异化处理。友好的连不上提示网络层失败时抛出带操作指引的错误信息明确写出REST API 用 HTTP 27123 端口不要用 27124那是 MCP 的 HTTPS 端点走 Tailscale 时用http://tailscale-ip:27123src/lib/obsidian/api.ts。Vault 相对路径编码encodePath()对路径按/分段后逐段encodeURIComponent保证含空格或特殊字符的笔记路径安全如notes/my note.md→notes/my%20note.md。客户端暴露的方法与 Local REST API 端点一一对应几个非显而易见的映射值得记住结构化搜索使用专用 Content-Typeapplication/vnd.olrapi.jsonlogicjson访问POST /search/文档大纲通过Accept: application/vnd.olrapi.document-mapjson获取笔记元数据frontmatter/标签/链接/字数不含正文通过Accept: application/vnd.olrapi.notejson获取——同一个GET /vault/{path}用 Accept 头切换返回形态外科式修补用PATCH /vault/{path}请求头携带Operationappend/prepend/replace、Target-Typeheading/block/frontmatter、Target可选Create-Target-If-Missing: true移动笔记使用 HTTPMOVE方法加Destination头注意这是 Local REST API 对 WebDAV MOVE 语义的扩展用法周期笔记按/periodic/{period}/或/periodic/{period}/{year}/{month}/{day}/取对应日期的 daily/weekly/monthly 笔记省略日期则为今天。六、22 个 MCP 工具全景全部定义在 open-sse/mcp-server/tools/obsidianTools.ts注册接线在 open-sse/mcp-server/server.ts每个工具都包一层withScopeEnforcement(toolName, handler, toolDef.scopes)参数先经各自的 zod schema 校验如query长度 1–500、contextLength20–500 默认 100结果统一 JSON 序列化后以content: [{type: text, ...}]返回。token/base URL每次调用时实时解析按 API key 优先、再全局因此配置改动无需重启 MCP Server 即生效。读取类工具scoperead:obsidian工具说明obsidian_check_status检查 Local REST API 是否可达且已认证obsidian_search_simple全文搜索笔记内容返回带文件路径的片段contextLength控制上下文宽度默认 100 字符obsidian_search_structured用 JSON Logic 表达式搜索and/or/regex/路径过滤器obsidian_read_note按 vault 相对路径读笔记可只取特定 heading/block/frontmatterobsidian_list_vault列出 Vault 中的文件与目录条目树path缺省为根目录obsidian_get_document_map获取笔记的 heading → 行号映射obsidian_get_note_metadata获取 frontmatter、标签、链接、字符/字数不读正文obsidian_get_active_file获取 Obsidian 中当前活跃文件的路径与内容obsidian_get_periodic_note获取某日期缺省今天的 daily/weekly/monthly 周期笔记obsidian_get_tags列出 Vault 全部标签及出现频率obsidian_list_commands列出可用 Obsidian 命令 ID配合obsidian_execute_commandobsidian_sync_statusOmniRoute 同步服务器状态running、vault 名、端口、uptime、上次同步结果obsidian_sync_conflicts列出未解决的同步冲突path、冲突路径、检测时间写入类工具scopewrite:obsidian工具说明obsidian_write_note创建或整体覆盖一篇笔记Markdown 内容obsidian_append_note追加内容到笔记末尾或追加到指定 heading/blockobsidian_patch_note在 heading、block 或 frontmatter 字段上做 append/prepend/replace 手术式修改obsidian_delete_note从 Vault 永久删除一篇笔记obsidian_move_note在 Vault 内移动或重命名笔记obsidian_execute_command按命令 ID 执行 Obsidian 命令obsidian_open_file在 Obsidian 中打开文件不存在则创建obsidian_sync_trigger立即触发一次桌面↔手机双向同步obsidian_sync_resolve_conflict解决同步冲突保留local手机版、remote桌面版或keep-both两个要点obsidian_patch_note是写入工具中参数最丰富的zod schema 强制operation ∈ {append, prepend, replace}、targetType ∈ {heading, block, frontmatter}、target非空并可选createTargetIfMissing缺省 false对应请求头Create-Target-If-Missing。它适合在已有笔记的某标题下追加日志这类场景而不动其余内容。四个obsidian_sync_*工具不走 Local REST API而是访问 OmniRoute 的本地同步服务器默认http://127.0.0.1:27781见 src/lib/obsidian/api.ts 的DEFAULT_SYNC_SERVER_URL并且额外要求配置了同步鉴权 token处理器先用getSyncToken()从key_value表namespacesync键omniroute_sync_token取专用 token取不到才回退到 Obsidian REST token。createSyncServerClient的四个方法分别映射/vault/sync/status、/vault/sync/trigger、/vault/sync/conflicts、/vault/sync/resolve冲突解决支持local/remote/keep-both三种策略。七、Scope 与鉴权读写分离由 MCP Server 的 scope 机制强制执行读取工具声明scopes: [read:obsidian]写入工具声明scopes: [write:obsidian]注册时统一经withScopeEnforcement()包裹open-sse/mcp-server/server.ts执行模型与 Notion 上下文源完全一致——受OMNIROUTE_MCP_ENFORCE_SCOPEStrue门控允许集取自OMNIROUTE_MCP_SCOPES或该 API key 的 scope 上下文。完整传输与 scope 语义见 docs/frameworks/MCP-SERVER.md。工具侧的 API key 识别由extractApiKeyId(extra)完成只接受authInfo.clientId为非空且不是anonymous/env-key的值其余一律按无 key处理走全局配置。八、设置端点速查方法路径用途GET/api/settings/obsidian返回{ connected, hasToken, baseUrl, vaultPath }POST/api/settings/obsidian保存并校验 token拒绝 27124 端口DELETE/api/settings/obsidian断开连接清除已存 tokenGET/api/settings/obsidian/webdavWebDAV 同步状态 凭据仅启用时密码仅对管理级主体返回POST/api/settings/obsidian/webdav为指定 Vault 目录启用 WebDAV 同步DELETE/api/settings/obsidian/webdav禁用 WebDAV 同步需要明确的是这些都是仪表盘设置路由不是代理端点——笔记库本体始终经由 Local REST API即配置的base_url和上述 MCP 工具访问仓库中不存在面向公开的/v1Obsidian 代理端点。九、典型使用模式基于笔记库的回答obsidian_search_simple/obsidian_search_structured定位 →obsidian_read_note取全文让 Agent 基于真实笔记作答而不是凭空生成。笔记写作与日志obsidian_write_note/obsidian_append_note记录 Agent 输出或摘要用obsidian_get_periodic_note先取今日 daily note再用obsidian_patch_note在特定标题下追加避免整篇重写。Vault 导航写入前先用obsidian_list_vault、obsidian_get_document_map、obsidian_get_tags摸清结构减少无效读写。Obsidian 自动化obsidian_list_commands发现命令 IDobsidian_execute_command驱动插件/命令obsidian_open_file把某篇笔记直接拉到 Obsidian UI 中。手机同步先启用 WebDAV 同步POST webdav 端点再用obsidian_sync_trigger触发、obsidian_sync_status查看结果、obsidian_sync_conflictsobsidian_sync_resolve_conflict处理冲突。十、延伸阅读MCP Server — 传输方式、scope 强制执行、完整工具清单。Notion Context Source — 另一个内置上下文源scope 执行模型与 Obsidian 一致。Memory System — 持久会话记忆属于自动注入的互补上下文层与本文工具按需拉取的模式形成对照。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
