Obsidian 的代理客户端插件

日本語はこちら

将 AI 代理（Claude Code、Codex、Gemini CLI）直接引入 Obsidian。您可以在自己的笔记库中直接与 AI 助手聊天。

基于 Zed 开发的 Agent Client Protocol (ACP) 构建。

https://github.com/user-attachments/assets/1c538349-b3fb-44dd-a163-7331cbca7824

特性

• 笔记引用：使用 @notename 语法引用您的笔记
• 图片附件：可将图片粘贴或拖放到聊天窗口中
• 斜杠命令：使用代理提供的 / 命令
• 多代理支持：可在 Claude Code、Codex、Gemini CLI 和自定义代理之间切换
• 多会话：可在不同视图中同时运行多个代理
• 悬浮聊天：一个持久且可折叠的聊天窗口，方便快速访问
• 模式与模型切换：从聊天界面更改 AI 模型和代理模式
• 会话历史：恢复或分支之前的对话
• 聊天导出：将对话保存为 Markdown 笔记
• 终端集成：允许代理执行命令并返回结果
• MCP 支持：代理使用其配置的 MCP 服务器——无需在插件中进行额外设置

安装

通过 BRAT（推荐）

1. 安装 BRAT 插件
2. 进入 设置 → BRAT → 添加测试版插件
3. 粘贴：https://github.com/RAIT-09/obsidian-agent-client
4. 在插件列表中启用 Agent Client

手动安装

1. 从 发布页面 下载 main.js、manifest.json、styles.css
2. 将它们放置在 VaultFolder/.obsidian/plugins/agent-client/
3. 在 设置 → 社区插件 中启用该插件

快速入门

打开终端（macOS/Linux 上的 Terminal，Windows 上的 PowerShell），并运行以下命令。

1. 安装代理及其 ACP 适配器（例如 Claude Code）：

   curl -fsSL https://claude.ai/install.sh | bash   # 安装 Claude Code
   npm install -g @agentclientprotocol/claude-agent-acp   # 安装 ACP 适配器
   

2. 登录（如果使用 API 密钥则跳过）：

   claude
   

   按照提示使用您的 Anthropic 账户进行身份验证。

3. 查找路径：

   which node   # macOS/Linux
   which claude-agent-acp
   
   where.exe node   # Windows
   where.exe claude-agent-acp
   

4. 在设置中配置：

   • Node.js 路径：例如 /usr/local/bin/node
   • 内置代理 → Claude Code → 路径：例如 /usr/local/bin/claude-agent-acp（不是 claude）
   • API 密钥：添加您的密钥，或者如果您已通过 CLI 登录，则留空

5. 开始聊天：点击功能区中的机器人图标

设置指南

• Claude Code
• Codex
• Gemini CLI
• 自定义代理（OpenCode、Qwen Code、Kiro、Mistral Vibe 等）

完整文档

开发

npm install
npm run dev

用于生产构建：

npm run build

许可证

Apache License 2.0 — 详情请参阅 LICENSE。

星标历史

Obsidian Agent Client 快速上手指南

将 Claude Code、Codex、Gemini CLI 等 AI 智能体直接集成到 Obsidian 中，在笔记库内即可与 AI 助手对话。本插件基于 Zed 的 Agent Client Protocol (ACP) 构建。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows, macOS, 或 Linux
• 核心依赖：
  • Node.js：必须安装（用于运行 ACP 适配器）。
  • Obsidian：最新版本。
  • AI 智能体 CLI：至少安装一种支持的智能体（如 Claude Code, Codex, Gemini CLI 等）。
• 网络环境：由于涉及 npm 包下载和 AI 服务连接，建议配置合适的网络环境或使用国内镜像源加速 npm 安装。

安装步骤

1. 安装 Obsidian 插件

推荐使用 BRAT 插件安装（便于更新），也可手动安装。

方式一：通过 BRAT 安装（推荐）

1. 在 Obsidian 中搜索并安装社区插件 BRAT。
2. 进入 设置 -> BRAT -> Add Beta Plugin。
3. 粘贴仓库地址：https://github.com/RAIT-09/obsidian-agent-client
4. 点击添加，然后在社区插件列表中启用 Agent Client。

方式二：手动安装

1. 从 Releases 页面 下载 main.js, manifest.json, styles.css。
2. 将文件放入笔记库目录：VaultFolder/.obsidian/plugins/agent-client/（若文件夹不存在请新建）。
3. 在 Obsidian 设置 -> 社区插件 中启用 Agent Client。

2. 安装并配置 AI 智能体 (以 Claude Code 为例)

打开终端（macOS/Linux 使用 Terminal，Windows 使用 PowerShell），执行以下步骤：

步骤 A：安装智能体及 ACP 适配器

# 安装 Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# 安装 ACP 适配器 (建议使用国内镜像源加速，如未配置全局镜像可添加 --registry 参数)
npm install -g @agentclientprotocol/claude-agent-acp

步骤 B：登录认证

claude

按提示完成 Anthropic 账号认证（若使用 API Key 可跳过此步，后续在插件设置中填写）。

步骤 C：获取执行路径 我们需要找到 node 和适配器可执行文件的路径。

macOS / Linux:

which node
which claude-agent-acp

Windows:

where.exe node
where.exe claude-agent-acp

请记录上述命令输出的完整路径。

3. 插件配置

1. 进入 Obsidian 设置 -> Agent Client。
2. Node.js path：填入上一步获取的 node 路径（例如：/usr/local/bin/node 或 C:\Program Files\nodejs\node.exe）。
3. Built-in agents -> Claude Code -> Path：填入适配器路径（注意：是 claude-agent-acp 的路径，不是 claude 的路径）。
4. API key：如果之前未通过 CLI 登录，在此处填入您的 API Key；若已登录可留空。

基本使用

配置完成后，即可开始在 Obsidian 中使用 AI 智能体。

1. 启动聊天：点击 Obsidian 左侧侧边栏的 机器人图标。
2. 引用笔记：在输入框中输入 @ 加上笔记名称（例如 @ProjectPlan），即可将当前笔记内容作为上下文发送给 AI。
3. 发送消息：输入自然语言指令，例如“总结这篇笔记的核心观点”或“根据笔记内容生成一个待办列表”。
4. 高级功能：
   • 图片交互：直接拖拽图片到聊天窗口进行分析。
   • 斜杠命令：输入 / 查看并使用智能体提供的特定命令。
   • 多会话：可开启多个独立的聊天视图，同时运行不同的任务。
   • 导出对话：聊天结束后，可将对话记录保存为 Markdown 笔记。

提示：更多智能体（如 Codex, Gemini CLI）的配置方法请参考插件设置中的对应选项或官方文档。