obsidian-agent-client

你有没有想过，在 Obsidian 里写笔记的时候，旁边的 AI 助手不是简单的问答机器人，而是能真正「帮你写代码、改文件、执行终端命令」的编程 Agent？

这正是 Obsidian Agent Client 正在做的事——它把 Claude Code、Codex、Gemini CLI 等主流 AI Coding Agent，直接搬进了你的双链笔记工作流。

背景：为什么需要把 Agent 装进笔记软件？

笔记软件和编程工具，长期以来是两条平行线。程序员写代码用 VS Code、JetBrains，AI 助手（Claude Code、GitHub Copilot）也深度集成在这些 IDE 里。而 Obsidian 作为知识管理工具，更多是用于记录、整理思考。

但 AI 编程 Agent 的能力远不止「写代码」——它能阅读文件、搜索仓库、执行 Shell 命令、理解项目上下文。如果你同时在维护一套笔记体系（比如项目文档、设计决策记录、技术调研），把 Agent 引入笔记环境，就能让两者产生联动：笔记内容可以被 Agent 读取，Agent 的工作结果可以沉淀为笔记。

Agent Client Protocol（ACP） 是由 Zed 编辑器团队提出的开放协议，定义了一套标准接口，让任何 AI Agent 和任何客户端应用之间可以互通。Obsidian Agent Client 正是基于这一协议，将 Obsidian 打造成 ACP 协议的「终端」之一——不管你用的是 Claude Code、OpenAI Codex 还是 Google Gemini CLI，只要适配了 ACP，都能无缝接入。

这个插件的作者是 GitHub 用户 RAIT-09，2024 年开始维护，目前已有 2,163 颗 GitHub Stars，Apache-2.0 开源许可。

核心功能：不止是聊天窗口

把 Obsidian Agent Client 理解为一个「带 AI 编程能力的 Obsidian 聊天面板」只是表面。它的真正价值在于以下这些细节设计：

@笔记引用（Note Mentions）：在对话中输入 @notename，Agent 就能读取对应笔记的完整内容，作为上下文参考。例如，你在笔记里记录了项目 API 设计文档，调用 Agent 修复一个 Bug 时，可以让 Agent 直接「看见」这份设计文档，确保修改与原始意图一致。这比在对话里复制粘贴内容要优雅得多。

图片附件：支持拖拽或粘贴图片到聊天窗口，Agent 能理解图像内容。适合 UI 设计评审、截图标注等场景。

MCP（Model Context Protocol）支持：Agent 自身配置的 MCP 服务器可以直接在插件中生效，无需在插件层单独配置 MCP。这意味着如果你已经在 Claude Code 中配置了数据库 MCP、文件系统 MCP，切换到 Obsidian 中依然可用。

多 Agent 与多会话：可以同时运行多个 Agent（Claude Code、Codex、Gemini CLI 等），每个 Agent 独立一个会话窗口，互不干扰。不同项目的代码审查可以并行进行，互不串台。

会话导出与分支：对话可以导出为 Markdown 笔记保存到 vault，也可以「分叉」出一个新会话，在保留历史对话的同时探索其他解决路径。

浮动聊天面板：以可折叠悬浮窗口形式存在，随叫随到，不占用主编辑器空间。

技术架构：分层清晰，职责明确

根据项目的 ARCHITECTURE.md，代码组织遵循清晰的四层结构：

src/
├── types/        # 类型定义，无业务逻辑依赖
├── acp/          # ACP 协议层，封装 SDK，所有外部依赖在此收敛
├── services/     # 业务逻辑层，纯 TypeScript，无 React 依赖
├── hooks/        # React 层，组合 services，驱动 UI
└── ui/           # React 组件层

这是一个非常标准的插件架构：

• 协议隔离：ACP SDK 只在 acp/ 层使用，其他层完全不知道 ACP 的存在，方便后续替换为其他协议（如 MCP）而不影响业务逻辑。
• 服务层纯化：所有业务逻辑（会话管理、消息存储、笔记读取）都在 services/，是天然的可测试单元。
• Hooks 组合：useAgent 作为 Facade 组合多个子 Hook，符合 React 自定义 Hook 的最佳实践。

主力技术栈：TypeScript + React 18 + CodeMirror 6（编辑器内嵌），构建工具使用 esbuild，样式独立为 CSS 文件（50KB+ 样式表，UI 相当丰富）。生产代码通过 esbuild 打包为单文件 main.js，注入 Obsidian 运行时。

上手体验：从安装到跑起来要多久？

实测下来，整个流程分三步，15 分钟左右可以完成：

第一步：安装 Obsidian 桌面版（要求 ≥ 1.7.2），在社区插件市场搜索「Agent Client」安装并启用。插件会在左侧边栏显示一个机器人图标，点击打开聊天面板。

第二步：安装一个 ACP 适配的 Agent。例如 Claude Code：

curl -fsSL https://claude.ai/install.sh | bash
npm install -g @agentclientprotocol/claude-agent-acp
claude  # 按提示登录

第三步：在插件设置中填写 Node.js 路径和 ACP 适配器路径，填入 API Key（或留空走 CLI 认证），保存后即可开始对话。

门槛不算高，但需要动手配置。如果你是 Obsidian 重度用户，同时在用 Claude Code/Gemini CLI 等工具，那么这个插件的价值最明显——笔记和代码工作流真正打通。

需要注意的是：这是一个桌面独占插件（isDesktopOnly: true），不支持 Obsidian 移动端。如果你习惯在手机上查看笔记，这个插件帮不上忙。

局限与争议

1. 强依赖外部 Agent：插件本身只是「管道」，真正能力来自 Claude Code、Codex 等。如果这些 Agent 本身有局限（比如上下文窗口限制、工具调用稳定性），在 Obsidian 中同样会遇到。插件并没有尝试做额外增强。

2. 协议碎片化：ACP 协议还比较新，主流 Agent 的 ACP 适配器质量参差不齐。目前 Claude Code 的适配器（@agentclientprotocol/claude-agent-acp）成熟度较高，但 Codex、Gemini CLI 的适配器还在活跃开发中，功能可能有差异。

3. MCP vs ACP 的取舍：项目维护者在 CONTRIBUTING.md 中明确说明，MCP 相关功能应该由 MCP Server 本身提供，而不是在插件层做兼容。这意味着如果你需要用某个 MCP 工具，需要先确认该 Agent 已支持对应 MCP，而不是期望插件来处理。

4. 安全风险：Agent 在 Obsidian 环境中可以读取 vault 内的所有笔记内容，如果 Agent 执行命令权限过大，潜在风险不可忽视。插件提供了权限确认弹窗（permission-handler.ts），但用户仍需对 Agent 的操作范围保持警惕。