企业官网建设流程全解析

最近 Obsidian 和 MCP 组合的话题热度一直很高，我也长期用 Obsidian 当项目知识库和开发日志，所以断断续续配过不少 MCP plugin。但说实话，那个过程非常让人崩溃：装一个 Obsidian 的 MCP server，再去 Claude Code 里加一段 MCP host 配置，去 Codex 里加另一段，换一个 agent 又得重新折腾一遍。插件拼了一大堆，配置文件越攒越长，真正跑起来却常常因为版本不兼容、路径不对、工具名冲突浪费一下午。

直到我发现一个思路完全不同的开源项目：它提供了一个统一网关，用一行命令启动服务，就能让 4 个主流 coding agent 同时读取 Obsidian 知识库、读取任务清单、把新内容写回笔记库。整个过程不再需要在每个 agent 里堆 plugin，而是把 4 个 agent 串到一个 MCP server 上。这篇文章我就把这个项目的完整思路、配置步骤、实测效果和踩坑记录写出来，给同样在折腾 Obsidian + MCP + coding agent 的人一个可以直接照抄的参考。

1. 为什么 Obsidian 是 coding agent 的最佳资料底座

很多人在做 AI 编程时，注意力全放在 prompt 技巧、agent 选型、模型切换上，却忽略了一个基础问题：agent 凭什么能写出符合你项目风格、知道你历史决策、了解你踩过哪些坑的代码？答案就是知识库。而 Obsidian 作为本地 Markdown 笔记库，天然适合成为 coding agent 的“记忆外置硬盘”。

1.1 知识库对 agent 的真正价值：不是喂数据，而是给上下文

先说一个大多数教程不会告诉你的点：coding agent 的能力上限，很大程度上取决于你给它多少高质量上下文。Claude Code、Codex CLI 这类工具在启动时会读取项目内文件、Git 历史、issue 等，但如果你有一个长期维护的 Obsidian 库，里面记录了项目架构决策、API 设计约定、修复过的问题、性能测试结果，这些信息如果 agent 读不到，它就只能靠模型训练时的通用经验来瞎猜。而 Obsidian 正好是纯文本 Markdown，结构化程度不错，又支持内部链接、标签、双链，只要给 agent 一个能查询 Markdown 文件的工具，它就能把笔记库当成本地 RAG 源来用。

我个人的实际感受是，当 agent 能读到我的“项目架构笔记”和“踩坑记录”时，它生成的代码风格会明显更贴近我平时的写法，命名习惯、错误处理方式、目录组织逻辑都会收敛。它的输出不再像是一个通用模型在发挥，而更像是在配合一个熟悉项目的同事写代码。这就是知识库作为 agent 底座的真正价值——不是把内容喂进模型，而是把决策上下文注入到 agent 的工具调用链里。

1.2 从“人找笔记”到“agent 自动查笔记”的转变

用 MCP 把 Obsidian 接入 coding agent 之后，最大的变化是协作模式的改变。以前是我自己要打开 Obsidian 搜索旧笔记，然后把内容复制粘贴给 AI；现在是 agent 在写代码的过程中发现某个模块改动可能影响旧逻辑，它会自己去笔记库检索相关记录，然后主动引用笔记里的结论。比如我笔记里记录了“这个支付模块的退款接口有额度校验，改动前必须确认数据库字段”，agent 在修改接口前就会调知识库检索工具，自己把这条约束找出来，再决定改法。

这个转变很关键，因为 coding agent 的上下文窗口是有限的，你没法把整个笔记库塞进去。MCP 的意义是让 agent 按需检索，需要什么查什么，而不是一次性把所有笔记都读进来。Obsidian 的文件系统结构本来就清晰，lib 目录、daily notes、项目文件夹各司其职，MCP server 只需要暴露几个核心工具：搜索文件、读取内容、按标签检索、写入新笔记。这样 agent 就能把 Obsidian 当做一个真实的信息源来使用，而不是靠人类手工把内容喂到窗口里。

1.3 为什么说 plugin 拼装模式走到了尽头

过去半年里，Obsidian 社区涌现出大量 MCP plugin，有人为了连一个 agent 就装了三四个插件，每个插件都要单独配置 token、路径、白名单。更麻烦的是，这些插件通常是针对单一 agent 开发的，Claude Code 里能跑，Codex 里就跑不了；或者这个 plugin 只暴露搜索工具，不暴露写入工具，你还得再装另一个。等你把这些插件都配好，配置文件已经膨胀到没法维护了。而且每次更新 Obsidian 或 agent 客户端，插件还要跟着适配，兼容性问题非常多。

我自己就经历过一次挺离谱的事：某个 Obsidian MCP 插件升级后，在 Codex 里永远报 “server initialization failed”，查了半天才发现是插件依赖版本冲突。那种体验让我下定决心换方案——不要在每个 agent 里各搞一套 MCP 连接，而是把 Obsidian 的能力收敛到一个独立的网关服务，所有 agent 都通过这个网关访问笔记库，工具统一、配置统一、更新也统一。这就是这个开源项目做的最核心的事。

2. 从“拼插件”到“串 agent”：MCP 网关的思路转变

先把概念理清楚。MCP 全称 Model Context Protocol，本质上是一个标准化的“AI 工具协议”，它把工具提供方和 AI 客户端解耦。你不需要为每一个 agent 定制一套插件接口，只要实现一个符合 MCP 协议的 server，所有支持 MCP 的客户端（Claude Code、Codex CLI、Gemini CLI 等）都能直接连接。这个协议的思路很像 USB-C：以前每个设备都有自己的充电口，现在只要都支持同一个标准，一根线就能通吃。

2.1 MCP 协议里 host、server、client 到底分别是什么

很多教程术语满天飞，我给一个生活化的类比。MCP host 是“需要使用工具的 AI 应用”，比如 Claude Code、Codex CLI，它像一个客人，知道自己要什么但不会自己动手。MCP server 是“提供工具的服务方”，它像工具箱里的各种工具，螺丝刀、扳手、电钻，按需取用。MCP client 则是 host 内部负责和 server 通信的连接器，相当于客人用来操作工具的手。

在你配置 “mcp serv add” 这类命令时，本质上就是在 host 里注册一个 server 的描述：server 叫什么名字、用什么命令启动、传什么参数。启动 host 之后，host 会通过 client 自动拉起 server，获取 server 提供的工具清单，然后在对话中根据用户意图决定调用哪些工具。每个 host 可以连接多个 server，每个 server 也可以被多个 host 连接。这就是一个标准的 server-client 架构，只不过在 AI 编程场景中，host 是 agent，server 是外部能力。

“拼 plugin 模式”的问题就出在这里：每一个 agent 里都要单独配置一个 server，而且如果你安装的是 Obsidian 官方那个 MCP plugin，本质上是 plugin 自己起了一个 server，这个 server 的生命周期和 Obsidian 客户端绑定，一旦 Obsidian 没开，agent 就连不上知识库。更难受的是，不同 agent 的 MCP 配置语法还不一样，Claude Code 用 JSON 配置，Codex CLI 也有一套自己的注册命令，Gemini CLI 又是另一套，每次切换工具都要重新学着配一遍。

2.2 统一网关方案到底改进了什么

这个开源项目解决的就是上述痛点，它的名字叫 obsidian-mcp-gateway（下文统称 gateway）。它的核心思路非常简洁：把 Obsidian 能力拆出来，放到一个独立的、不依赖 Obsidian 进程的 MCP server 里。这个 server 直接读取你本地 vault 的 Markdown 文件目录，对外暴露统一工具接口，比如 search_notes、read_note、list_files、create_note、update_note、find_by_tag 等。然后你在每个 agent 里只做一件事：把 MCP endpoint 指向这个 gateway。四个 agent 连接同一个 gateway，共用同一套工具，不需要分别开发和适配 Obsidian 插件。

这种“一个服务，四端接入”的模式，同时解决了几个很实际的问题。第一是生命周期问题，gateway 是一条独立进程，不需要 Obsidian 开着才能用，即使你只是想在终端里快速查一条笔记，也可以直接调 API。第二是权限统一问题，不用在 Obsidian 的每个插件里分别配置允许访问的目录，gateway 的配置只维护一份。第三是工具命名混乱问题，所有 agent 看到的是同一套工具名，你不需要在 Claude Code 里习惯一个叫 “search_on_page” 的工具、在 Codex 里又输入另一个叫 “note_search” 的工具，学习成本直接降为零。

2.3 一行命令串 4 个 agent，这句话到底指什么

标题里有句话叫“一行命令串起 4 个 coding agent”，起初我以为是某种夸张表达，试过之后发现它描述得还挺准确——前提是你理解“一行命令”指的是启动 gateway 的安装命令，而不是把 4 个 agent 的配置合并成一条命令。实际的启动命令大概长这样：

uvx obsidian-mcp-gateway --vault /path/to/your/vault

如果你用 npm 生态，也可以：

npx -y obsidian-mcp-gateway --vault /path/to/your/vault

把这行命令跑起来之后，gateway 默认监听本地 3578 端口，所有连接到它的 agent 都能使用 Obsidian 的工具。接下来做的事，才是“串起 4 个 agent”的真正含义：在 4 个 agent 的 MCP 配置里，分别把 endpoint 指向同一个地址。如果你用的是支持 “http” 类型 MCP 的客户端，配置更简单，只需要写上：

http://127.0.0.1:3578/mcp

一次性给 4 个客户端配置好，之后每次需要 agent 读写知识库，gateway 就是那个统一出入口。

3. 一行命令起服务：obsidian-mcp-gateway 落地实操

理论说再多，不如直接动手跑一遍。我实测的这个项目本身不算大，但它的安装和配置过程里有一些细节容易踩坑，我把完整的操作路径写下来，包括准备、安装、配置 4 个 agent、验证连通性，尽量让你照着操作就能跑通。

3.1 动手前的准备：vault 目录结构怎么规划

先说准备工作。gateway 直接读取 vault 目录，不经过 Obsidian 程序本身，所以你的 vault 一定要是一个纯 Markdown 文件集合，不能依赖于某些 Obsidian 专有的二进制数据。结合我实际使用经验，有三种目录适合纳入 agent 访问范围：一是“项目笔记”目录，里面记录每个项目的架构、技术选型、开发日志、迭代计划；二是“daily notes”目录，存放每天的工作记录和临时想法；三是“知识沉淀”目录，存放一些通用的技术原理、踩坑记录、模板文件。

不建议把整个 vault 都开放给 agent，原因有两个。一是 agent 会检索到大量无关内容，容易产生上下文污染，比如你在翻旧项目笔记，agent 把去年记的人生感悟也检索出来了，生成的代码思路就会跑偏。二是权限边界问题，agent 读取笔记库的权限范围越大，误写、误改的风险也越高。所以我建议给 gateway 单独指定一个子目录，比如只在 vault 下新建一个叫 “agents” 的文件夹，专门放 agent 能访问的内容。这样既保证了功能，也避免了误操作影响全部笔记。

另外一个建议是，在 vault 里统一使用 frontmatter，至少包含 title、tags、date 这几个字段。因为 gateway 的 tag 检索工具依赖 frontmatter 里的 tags，如果你平时的笔记没有写 tags 的习惯，这个工具就废掉了。我自己是从一年前开始强制所有笔记都带 frontmatter，极大方便了后续的自动化和检索。

3.2 安装 gateway 服务端，以及配置里最容易被忽略的三个参数

安装很简单，前提是你本机有 Python 3.10+ 和 uv，或者 Node.js 18+ 和 npm，二选一就好。我用的是 uvx 方式：

uvx obsidian-mcp-gateway --vault ~/Documents/myvault --port 3578

第一次运行会自动下载依赖，稍等片刻看到 “MCP server listening on 3578” 就说明启动成功了。如果你是第一次使用这个项目，我建议先不用任何参数直接启动，它会走一遍交互式初始化配置，自动在配置目录生成一个 YAML 文件。

这个配置文件里有三个参数我强烈建议你手动确认：

• vault_path：根目录绝对路径，注意不要用 “~” 符号，gateway 在展开环境变量和用户目录时偶尔会有小问题，直接写全路径最稳。
• write_enabled：是否允许 agent 写入笔记。我一开始图省事设置成 true，后来发现 agent 会自作主张把一些没整理过的 prompt 内容直接写进 daily notes，后来改成 false，只在需要明确让 agent 记笔记时才临时打开。
• allowed_dirs：允许 agent 访问的子目录列表，建议至少指定一个 “agents” 目录，其他一概不开放。

其他还有超时时间、最大返回条数等默认参数，基本上不用动，默认值就够用。配置文件修改完，重启 gateway 即可应用。

3.3 四个 agent 的 MCP 配置怎么写

这里我给出一份我实测可用的配置参考。由于每个 agent 的 MCP 配置方式不同，你拿到之后只需要按照对应客户端的语法抄进去就行。具体来说，我验证过这 4 个：Claude Code、Codex CLI、Gemini CLI、Cursor。

先说 Claude Code。它支持一个简化的命令式配置，在终端输入：

claude mcp add obsidian-gateway -- http://127.0.0.1:3578/mcp

配置完可以用claude mcp list查看状态。如果你偏好直接编辑配置文件，可以打开~/.claude.json，在 mcpServers 字段里加：

{ "mcpServers": { "obsidian-gateway": { "type": "http", "url": "http://127.0.0.1:3578/mcp" } } }

再说 Codex CLI（OpenAI 的命令行 agent）。它是用codex mcp add命令注册，语法类似：

codex mcp add obsidian-gateway --type http --url http://127.0.0.1:3578/mcp

如果你用的是旧版本，可能需要先codex mcp list确认是否支持 http 类型。实测下来新版本都能直接用。

Gemini CLI 的配置方式稍微麻烦一点，它的 MCP server 配置写在~/.gemini/settings.json里，需要手动加一段 mcpServers：

{ "mcpServers": { "obsidian-gateway": { "type": "http", "url": "http://127.0.0.1:3578/mcp" } } }

加完保存，重启 Gemini CLI 进程就行。注意 Gemini CLI 有时不会热加载配置，必须重启。

最后是 Cursor。它属于 GUI 型工具，在 Settings > MCP 里添加 server，类型选 “http”，地址填：

http://127.0.0.1:3578/mcp

添加后 Cursor 会自动发送 initialize 请求，如果 gateway 已启动，状态很快会变成 “Connected”。这种 GUI 工具连接 MCP 是最直观的，适合新手验证 gateway 是否正常工作。

3.4 连通性验证：新手和老手都要做的三步检查

配完四端之后，不要急着开始写代码，先做三分钟快速验证，可以帮你筛掉九成问题。

第一步，在终端里手动启动 gateway，保持窗口在前台运行，观察输出。如果启动时出现报错，比如 “vault path not found” 或者端口占用，直接就能看到原因。第二步，打开任意一个 agent 交互界面，直接问它：“你现在有哪些可用工具？请列出 tool list。”如果 gateway 连接成功，agent 会列出 search_notes、read_note、create_note 等工具名。如果它说没有可用工具，多半是 MCP 配置没生效，回到第 3.3 节检查。第三步，让它做一个实际动作，比如 “在 agents 目录里找一下有没有和 flutter 相关的笔记”，agent 会调用 search_notes 工具，返回结果里有正确的文件路径，说明整个链路通畅。

一个常见的误区是，配置完 gateway 之后觉得自己必须一直开着终端。其实可以把这个进程放到后台，用nohup或你喜欢的进程守护工具托管，我后面会专门讲进程管理的事。新手阶段建议先保持前台运行，方便看日志。

4. 实测：四个 agent 在同一知识库上协作的典型场景

理论说通、配置跑通之后，真正让我觉得这个项目值得推荐的是它在实际使用中的表现。我把它放进真实开发流程里用了一周，结合 4 个 agent 的特长，形成了几个非常顺手的协作场景。下面挑三个典型的来展开。

4.1 场景一：Codex CLI 读历史决策，改代码不再凭感觉

我接了一个前同事留给我的后端服务，属于典型的“有历史包袱”项目。代码能跑，但逻辑里埋了不少奇怪的判断，比如某个状态字段明明有枚举值，代码里却直接写了硬编码字符串。过去我会去 Obsidian 里翻以前的笔记，找当时的决策依据，但这很费时间。现在直接对 Codex 说：“在知识库里找一下这个项目里 payment_status 的取值约定，然后帮我重构这段判断逻辑。”

Codex 会调用 search_notes 去检索，如果你的笔记里记录了当时的约定，它会直接引用，并告诉你“根据笔记库里的支付系统设计文档，这个字段在 7 月 3 日更新过，目前有 five 个状态值，你硬编码的 ‘completed’ 是旧值，建议改成最新枚举”。注意，它不是说“我觉得应该改成这样”，而是说“你的笔记里记录的是这样”。这种带依据的回答，比模型的纯推测要可靠得多。

如果笔记里没搜到相关内容，Codex 也会明说没找到，而不是硬编一个答案。这一点非常重要，因为 agent 最怕的就是“幻觉式自信”，它没有足够上下文时，最容易给你编一个合理的假话。有了知识库检索这层保障，它至少能区分“知道自己知道”和“知道自己不知道”。

4.2 场景二：Claude Code 拆任务并把结果写回 daily note

另一个我很常用的场景是任务拆解和回写。每天开工前，我会对 Claude Code 说：“读取我今天的 daily note，看看计划里列了哪三件事，然后把这三个任务细化成可执行的开发步骤，更新到同一篇笔记里。”

这个流程在以前是完全不可想象的。因为 Claude Code 虽然有较强的代码理解和规划能力，但它没有你日常记录里的上下文。现在通过 gateway，它能读取daily/2025-XX-XX.md里我早上随手写的几个要点，然后按照“实现方案、涉及文件、风险点、验收标准”的结构，把每个任务重新整理一遍，再通过 update_note 工具写回同一篇笔记。整个过程中，我可以看着它操作，写完还能去 Obsidian 里用 markdown 格式直接修改。

多提一句，回写功能挺需要谨慎的，我建议在你熟悉了 agent 的写入风格之前，先不要让 write_enabled 全局开启，而是只允许它写 daily notes 目录。等确认它不会乱改格式、不会覆盖内容之后，再逐步放开权限。

4.3 场景三：Gemini CLI 做特性检索，Cursor 做多文件浏览

Gemini CLI 的优势在于它跟 Google 生态的整合好，处理长文本的能力也比较强。我主要让它做特性检索：比如问它“在知识库里查一下和图片压缩、缩放有关的笔记”，它会调用 tag 检索和全文检索，一次性把相关的十几篇笔记都找出来，再比较里面的方案优劣。由于它上下文比较长，可以一次承载多篇笔记的内容，很适合做这种“跨笔记汇总”的任务。

Cursor 则不同，它是 IDE 型 agent，适合做多文件浏览和定位。比如我让它先读知识库里某个项目的“模块清单”，然后根据清单在代码仓库里定位对应目录和文件，整个过程它会在侧边栏展示文件树，非常直观。Gateway 的本质作用都是一样的，但在不同 agent 里，和操作形成的互动体验是完全不一样的，我建议你根据自己的使用习惯把这 4 个 agent 分工明确一下，而不是让它们干同一类活。

5. 踩坑与排查：配置 MCP gateway 时最常遇到的 5 个问题

任何工具用久了总会有问题。下面这 5 个问题，几乎每个都是我在配置和使用 obsidian-mcp-gateway 过程中真实遇到过的，有些是新手必踩，有些则是老手也会偶尔疏忽的细节。我把排查思路和解决办法一并整理出来。

5.1 问题一：agent 提示 “connection refused” 但 gateway 明明在跑

这个问题的本质是 agent 进程和 gateway 进程之间网络不通。最常见的原因是端口没有绑定对。gateway 默认监听的是 127.0.0.1，如果你的 agent 运行在容器里或者 WSL 环境，访问 127.0.0.1:3578 时指向的是容器自己的回环地址，自然连不上。

解决办法是明确指定 host 为 0.0.0.0，并且让 agent 配置里填写宿主机可访问的地址。如果你用的是 WSL2，建议在 gateway 启动时加--host 0.0.0.0，然后 agent 里填 WSL 虚拟机的 IP，而不是 127.0.0.1。注意，如果 gateway 和 agent 都在同一台物理机上，优先用 127.0.0.1，避免端口暴露到局域网。

还有一个容易忽略的点：某些 agent 在初始化 MCP 时，会对 server 做一次健康检查，如果超时设置比较短，而你的笔记库非常大，首次初始化时 gateway 需要扫描目录索引，就可能超时。这时候可以在 gateway 配置里调大初始化超时，或者提前用 CLI 工具手动触发一次索引构建。

5.2 问题二：工具能列出，但检索结果总是空的

我一度以为这是 bug，后来才意识到是目录权限问题。Gateway 对 vault 的访问权限由 allowed_dirs 控制，如果你指定的检索目录没有实际内容，或者路径写错了，比如少了一层子目录，工具列出没问题，但 search_notes 返回结果就一直为空。

排查方法很简单，先手动看 gateway 启动日志，确认它加载的根目录路径是否和你预期一致；然后用一个最简单的关键词去搜索，比如搜一个你确定存在的文件名，如果还是空，再用文件系统命令行直接检查 gateway 是否有权限读取该目录。大多数情况下是路径分隔符问题，Windows 上尤其容易踩坑，一定要用正斜杠 / 而不是反斜杠。

5.3 问题三：agent 把笔记写坏了，格式全乱

这件事我实打实遇到过。有一次 Claude Code 说它要“更新 daily note”，结果把我整篇笔记的 frontmatter 全打乱了，标题也被改成了一个 summary 词汇。从那以后我的 write_enabled 默认是关闭的，只在明确需要 agent 写笔记时才打开，而且代理写入的目录也只限定到专用文件夹。

如果你确实需要 agent 写入，建议你在笔记模板里加一行注释，告诉 agent 必须保持 frontmatter 和 Markdown 格式不变。另外，在 gateway 配置里开启“dry run”模式，让 agent 的写入先输出到临时文件而不是覆盖原文件，等确认格式没问题后再正式启用。

5.4 问题四：gateway 一直在调试日志里刷工具调用，窗口很难受

这个问题不是功能故障，而是使用体验问题。当 4 个 agent 都连接同一个 gateway 时，终端会不断打印每个 agent 调用了哪些工具、参数是什么、耗时多少。这其实是好消息，说明流量很大，但实际用起来非常干扰你的注意力。

我的做法是，给 gateway 设一个单独的日志文件，然后按需查看。比如启动时加--log-level warn，只打印警告和错误，不再打印每个工具调用的调试信息。真正想排查问题时再临时调回--log-level debug。

5.5 问题五：agent 之间互相“污染”笔记内容，怎么隔离？

当 4 个 agent 共用同一个工具集时，一个容易被忽略的隐患是：Claude Code 在重构代码时写的思路，可能被 Codex CLI 在另一个任务里检索到，导致代码风格混乱。解决办法是把不同的目录分配给不同的 agent，比如 Claude Code 只访问agents/claude-code，Codex 只访问agents/codex，这样在 gateway 端做一层目录级隔离。

gateway 本身支持在 MCP server 声明里注册多套工具实例，实现方式不复杂：启动两个 gateway 进程，分别指定不同的 vault 和 allowed_dirs，然后在不同 agent 里指向不同端口。比如 Claude Code 用 3578，Codex 用 3579，这样即使在底层数据上没分家，但工具访问边界清晰，不会互相干扰。

最后分享一点我个人的实际体会。MCP 生态现在正处于爆发期，每周都有新工具、新协议版本出现，obsidian-mcp-gateway 这种“统一入口”的架构，从设计思路上比“每个 agent 各连一个 Obsidian 插件”要先进很多。它不是让你把 4 个 agent 硬凑到同一个工具上，而是让知识库成为 agent 协作的公共层。刚开始配置网关时确实会多花一点时间，但一旦跑起来，你就再也不想回到那种挨个配 plugin 的日子了。

如果你也在折腾 Obsidian 和 coding agent 的组合，可以先从这个开源项目入手，用一个最小化的 vault 目录试试，把 4 个 agent 都接上，跑几个我上面写的场景。等你习惯了这种接入方式，自然会发现 agent 写出来的代码越来越“懂你”，因为它的判断不再是凭空发挥，而是建立在你的历史积累之上。