Claudian：将 Claude Code 嵌入 Obsidian 的侧边栏聊天插件
一、概述
1. 简介
A. 是什么
Claudian 是一款 Obsidian 插件，将 Claude Agent（基于 Claude Agent SDK）嵌入为侧边栏聊天界面。用户的笔记库（vault）成为 Claude 的工作目录，使其具备完整的代理能力：文件读写、搜索、bash 命令和多步骤工作流。
B. 为什么值得关注
- 将 AI 能力直接集成到笔记工作流中
- 无需切换应用即可在 Obsidian 内使用 Claude Code
- 支持完整的 Claude Agent SDK 功能集
C. 核心价值
- 在笔记环境中直接调用 AI 进行文件操作和代码执行
- 上下文感知的智能助手，自动关联当前笔记
- 支持多标签页、视觉识别、MCP 服务器集成等高级功能
2. 前置知识
A. 必备条件
- 已安装 Claude Code CLI
- Obsidian v1.8.9 或更高版本
- Claude 订阅或 API 密钥，或支持 Anthropic API 格式的自定义模型提供商（OpenRouter、Kimi、GLM、DeepSeek 等）
- 仅支持桌面端（macOS、Linux、Windows）
B. 推荐知识
- 熟悉 Obsidian 基础操作
- 了解 Claude Code 的基本使用方法
- 对 MCP（Model Context Protocol）有基本了解
二、环境准备
1. 系统要求
- 操作系统：macOS、Linux 或 Windows
- Obsidian 版本：v1.8.9+
- Claude Code CLI：已安装并配置
- 桌面环境（不支持移动端）
2. 安装步骤
方式一：从 GitHub Release 安装（推荐）
- 从最新发布版本下载
main.js、manifest.json和styles.css三个文件 - 在笔记库的插件文件夹中创建
claudian文件夹：
/path/to/vault/.obsidian/plugins/claudian/- 将下载的文件复制到
claudian文件夹中 在 Obsidian 中启用插件：
- 设置 → 社区插件 → 启用「Claudian」
方式二：使用 BRAT 安装
BRAT（Beta Reviewers Auto-update Tester）允许直接从 GitHub 安装和自动更新插件。
- 从 Obsidian 社区插件安装 BRAT 插件
- 在设置 → 社区插件中启用 BRAT
- 打开 BRAT 设置，点击「Add Beta plugin」
- 输入仓库 URL：
https://github.com/YishenTu/claudian - 点击「Add Plugin」，BRAT 将自动安装 Claudian
- 在设置 → 社区插件中启用 Claudian
方式三：从源码安装（开发模式）
- 将仓库克隆到笔记库的插件文件夹：
cd /path/to/vault/.obsidian/plugins
git clone https://github.com/YishenTu/claudian.git
cd claudian- 安装依赖并构建：
npm install
npm run build- 在 Obsidian 中启用插件
3. 验证安装
安装完成后，在 Obsidian 中：
- 检查功能区是否出现机器人图标
- 尝试打开聊天侧边栏
- 验证 Claude CLI 是否被正确识别
三、核心概念
1. 基本术语
A. Claudian Service
Claude Agent SDK 的包装器，负责与 Claude API 的通信和会话管理。
B. Slash Commands
可重用的提示词模板，通过 /command 触发，支持参数占位符、@file 引用和可选的内联 bash 替换。
C. Skills
可重用的能力模块，基于上下文自动调用，兼容 Claude Code 的技能格式。
D. MCP Servers
通过 Model Context Protocol 连接外部工具和数据源，支持 stdio、SSE 和 HTTP 三种模式。
E. Inline Edit
内联编辑模式，可直接在笔记中编辑选中文本或在光标位置插入内容，提供单词级差异预览。
2. 系统架构
graph TB
User[用户] --> Obsidian[Obsidian]
Obsidian --> Claudian[Claudian Plugin]
Claudian --> SDK[Claude Agent SDK]
SDK --> ClaudeAPI[Claude API]
Claudian --> Vault[笔记库 Vault]
Claudian --> MCP[MCP Servers]
Claudian --> Plugins[Claude Code Plugins]
Claudian --> FileSystem[文件系统]
Vault --> FileOps[文件读写操作]
MCP --> ExternalTools[外部工具]
Plugins --> Skills[技能扩展]
FileSystem --> Bash[Bash 命令执行]
3. 工作流程
sequenceDiagram
participant U as 用户
participant O as Obsidian
participant C as Claudian
participant S as Claude SDK
participant A as Claude API
U->>O: 打开聊天/选择文本
O->>C: 激活 Claudian
C->>C: 收集上下文（笔记、文件、选择）
C->>S: 发送消息和工具调用
S->>A: 请求 Claude
A-->>S: 返回响应和工具结果
S-->>C: 处理后的响应
C->>O: 更新 UI
C->>C: 执行文件操作/Bash 命令
C-->>U: 显示结果
四、功能特性
1. 完整的代理能力
Claudian 利用 Claude Code 的能力，在 Obsidian 笔记库中实现：
A. 文件操作
- 读取笔记内容
- 写入和编辑文件
- 搜索文件和内容
- 多步骤工作流自动化
B. Bash 命令执行
- 直接在笔记库中执行终端命令
- 支持脚本自动化
- 可配置命令阻止列表确保安全
C. 上下文感知
- 自动附加当前聚焦的笔记
- 使用
@提及其他文件 - 按标签排除笔记
- 包含编辑器选择内容（高亮）
- 访问外部目录获取额外上下文
2. 视觉识别支持
通过以下方式发送图像进行分析：
- 拖放图片到聊天界面
- 粘贴图片
- 输入文件路径
3. 内联编辑模式
A. 功能说明
- 选择文本 + 快捷键触发内联编辑
- 直接在笔记中编辑选中的文本
- 在光标位置插入内容
- 提供单词级差异预览
- 只读工具访问以获取上下文
B. 使用场景
- 快速修改段落内容
- AI 辅助润色文本
- 代码片段优化
4. 指令模式（#）
A. 功能说明
- 从聊天输入直接添加精细的自定义指令到系统提示词
- 在模态框中查看和编辑指令
- 指令会附加到默认系统提示词
B. 使用方法
在聊天输入中输入 # 即可进入指令模式，添加自定义指令。
5. 斜杠命令
A. 创建命令
- 在设置中创建可重用的提示词模板
- 通过
/command触发 - 支持参数占位符
- 支持
@file引用 - 可选的内联 bash 替换
B. 管理命令
- 在设置中导入/导出命令
- 可覆盖模型和允许的工具
6. 技能系统
A. 技能格式
- 兼容 Claude Code 的技能格式
- 添加
SKILL.md文件到~/.claude/skills/或{vault}/.claude/skills/ - 推荐使用 Claude Code 管理技能
B. 自动调用
- 基于上下文自动调用相关技能
- 扩展 Claudian 的能力
7. Claude Code 插件支持
A. 插件发现
- 自动从
~/.claude/plugins发现 - 支持每个笔记库的独立配置
- 用户范围的插件在所有笔记库中可用
- 项目范围的插件仅在匹配的笔记库中可用
B. 插件管理
- 通过设置启用/禁用插件
- 插件技能和斜杠命令无缝集成
- 推荐使用 Claude Code 管理插件
8. MCP 支持
A. 服务器配置
- 在设置中添加 MCP 服务器
- 支持 stdio、SSE、HTTP 三种模式
- 配置上下文保存模式
- 使用
@mcp-server在聊天中激活
B. @-提及下拉菜单
输入 @ 可查看：
- 活动的 MCP 服务器
- 外部上下文
- 笔记库文件
9. 高级模型控制
A. 模型选择
- 在 Haiku、Sonnet 和 Opus 之间选择
- 通过环境变量配置自定义模型
- 微调思考预算
B. 环境变量
- 在设置中配置自定义环境变量
- 支持环境变量片段保存和恢复
10. 安全特性
A. 权限模式
- YOLO 模式：无批准提示，所有工具调用自动执行
- Safe 模式：每次工具调用需要批准，Bash 需要精确匹配，文件工具允许前缀匹配
B. 安全措施
- 命令阻止列表（支持正则，平台特定）
- 笔记库限制（通过 realpath 符号链接安全检查）
- 允许的导出路径（默认：
~/Desktop、~/Downloads）
11. 多标签页支持
A. 功能特性
- 运行多个并发聊天会话
- 独立的流式响应
- 延迟服务初始化
- 可配置的标签页限制（3-10 个）
B. 性能优化
- 延迟初始化减少资源占用
- 独立会话管理
五、配置详解
1. 基本设置
A. 用户名
为个性化问候设置用户名称。
B. 排除标签
防止笔记自动加载的标签（如 sensitive、private）。
C. 媒体文件夹
配置笔记库存储附件的位置，用于嵌入式图像支持（如 attachments）。
D. 自定义系统提示词
附加到默认系统提示词的额外指令（指令模式 # 保存此处）。
E. 自动生成对话标题
在首次交换后切换 AI 驱动的标题生成。
F. 标题生成模型
用于自动生成对话标题的模型（默认：Auto/Haiku）。
G. Vim 风格导航映射
配置按键绑定，如 map w scrollUp、map s scrollDown、map i focusInput。
2. 快捷键设置
A. 内联编辑快捷键
触发选定文本内联编辑的快捷键。
B. 打开聊天快捷键
打开聊天侧边栏的快捷键。
3. MCP 服务器配置
A. 添加/编辑/删除服务器
- 配置 MCP 服务器连接参数
- 设置上下文保存模式
- 验证服务器连接
B. 服务器类型
- stdio：标准输入输出模式
- SSE：服务器发送事件模式
- HTTP：HTTP 请求模式
4. Claude Code 插件管理
A. 插件发现
- 自动扫描
~/.claude/plugins目录 - 显示可用的 Claude Code 插件
B. 插件启用/禁用
- 用户范围插件：所有笔记库可用
- 项目范围插件：仅在匹配的笔记库中可用
5. 安全设置
A. 加载用户 Claude 设置
加载 ~/.claude/settings.json（用户的 Claude Code 权限规则可能绕过 Safe 模式）。
B. 启用命令阻止列表
阻止危险的 bash 命令（默认：开启）。
C. 阻止的命令
阻止的命令模式（支持正则，平台特定）。
D. 允许的导出路径
笔记库外部可以导出文件的路径（默认：~/Desktop、~/Downloads）。支持 ~、$VAR、${VAR} 和 %VAR%（Windows）。
6. 环境变量设置
A. 自定义变量
Claude SDK 的环境变量（KEY=VALUE 格式）。
B. 环境变量片段
保存和恢复环境变量配置。
7. 高级设置
A. Claude CLI 路径
Claude Code CLI 的自定义路径（留空以自动检测）。
六、安全与权限
1. 访问范围
| 范围 | 访问权限 |
|---|---|
| 笔记库 | 完整读写（通过 realpath 符号链接安全） |
| 导出路径 | 仅写入（如 ~/Desktop、~/Downloads） |
| 外部上下文 | 完整读写（仅会话，通过文件夹图标添加） |
2. 权限模式
A. YOLO 模式
- 无批准提示
- 所有工具调用自动执行（默认）
B. Safe 模式
- 每次工具调用需要批准
- Bash 命令需要精确匹配
- 文件工具允许前缀匹配
3. 隐私与数据使用
A. 发送到 API 的内容
- 用户输入
- 附加的文件
- 图像
- 工具调用输出
- 默认发送到 Anthropic，通过
ANTHROPIC_BASE_URL自定义端点
B. 本地存储
- 设置和会话元数据存储在
vault/.claude/ - 会话消息存储在
~/.claude/projects/（SDK 原生） - 旧版会话存储在
vault/.claude/sessions/
C. 遥测
- 无遥测功能
- 仅跟踪用户配置的 API 提供商
七、故障排查
1. Claude CLI 未找到
A. 问题现象
遇到 spawn claude ENOENT 或 Claude CLI not found 错误。
B. 原因分析
插件无法自动检测 Claude 安装路径，常见于 Node 版本管理器（nvm、fnm、volta）。
C. 解决方案
步骤 1：找到 CLI 路径并在设置 → 高级 → Claude CLI 路径中设置。
| 平台 | 命令 | 示例路径 |
|---|---|---|
| macOS/Linux | which claude | /Users/you/.volta/bin/claude |
| Windows（原生） | where.exe claude | C:\Users\you\AppData\Local\Claude\claude.exe |
| Windows（npm） | npm root -g | {root}\@anthropic-ai\claude-code\cli.js |
注意：在 Windows 上，避免使用 .cmd 包装器。使用 claude.exe 或 cli.js。
替代方案：在设置 → 环境 → 自定义变量中，将 Node.js bin 目录添加到 PATH。
2. npm CLI 和 Node.js 不在同一目录
A. 问题检查
如果使用 npm 安装的 CLI，检查 claude 和 node 是否在同一目录：
dirname $(which claude)
dirname $(which node)B. 问题分析
如果不同，GUI 应用如 Obsidian 可能找不到 Node.js。
C. 解决方案
方案 1：安装原生二进制文件（推荐）
方案 2：在设置 → 环境中添加 Node.js 路径：PATH=/path/to/node/bin
3. 仍有问题
如果上述方法都无法解决问题，请在 GitHub 上提交 issue，包含以下信息：
- 平台
- CLI 路径
- 错误消息
八、项目架构
1. 目录结构
src/
├── main.ts # 插件入口点
├── core/ # 核心基础设施
│ ├── agent/ # Claude Agent SDK 包装器（ClaudianService）
│ ├── commands/ # 斜杠命令管理（SlashCommandManager）
│ ├── hooks/ # PreToolUse/PostToolUse 钩子
│ ├── images/ # 图像缓存和加载
│ ├── mcp/ # MCP 服务器配置、服务和测试
│ ├── plugins/ # Claude Code 插件发现和管理
│ ├── prompts/ # 代理的系统提示词
│ ├── sdk/ # SDK 消息转换
│ ├── security/ # 批准、阻止列表、路径验证
│ ├── storage/ # 分布式存储系统
│ ├── tools/ # 工具常量和实用程序
│ └── types/ # 类型定义
├── features/ # 功能模块
│ ├── chat/ # 主聊天视图 + UI、渲染、控制器、标签页
│ ├── inline-edit/ # 内联编辑服务 + UI
│ └── settings/ # 设置标签页 UI
├── shared/ # 共享 UI 组件和模态框
│ ├── components/ # 输入工具栏组件、下拉菜单、选择高亮
│ ├── mention/ # @-提及下拉菜单控制器
│ ├── modals/ # 批准 + 指令模态框
│ └── icons.ts # 共享 SVG 图标
├── i18n/ # 国际化（10 种语言环境）
├── utils/ # 模块化实用函数
└── style/ # 模块化 CSS（→ styles.css）2. 核心模块说明
A. Core 层
- agent：Claude Agent SDK 的核心包装器，负责与 Claude API 通信
- commands：斜杠命令的管理和执行
- mcp：MCP 服务器的配置、连接和管理
- plugins：Claude Code 插件的发现和集成
- security：权限控制和安全策略
B. Features 层
- chat：主聊天界面，包括消息渲染、会话管理、多标签页支持
- inline-edit：内联编辑功能，直接在笔记中编辑文本
- settings：插件设置界面
C. Shared 层
- components：可复用的 UI 组件
- mention：@-提及功能的下拉菜单
- modals：各种模态框（批准、指令编辑等）
九、使用场景
1. 笔记整理与优化
- AI 辅助整理笔记结构
- 自动生成摘要和标签
- 内容润色和改写
2. 代码开发
- 在笔记中直接编写和测试代码
- 代码审查和优化建议
- 自动化脚本执行
3. 知识管理
- 智能搜索笔记库
- 关联笔记推荐
- 知识图谱构建
4. 自动化工作流
- 批量处理笔记
- 自动生成报告
- 定时任务执行
十、路线图
1. 已完成功能
- Claude Code 插件支持
- 钩子和其他高级功能
- MCP 服务器集成
- 多标签页支持
- 视觉识别
2. 计划中功能
- 更多集成选项
- 性能优化
- 用户体验改进
十一、许可证
Claudian 采用 MIT 许可证开源。
十二、致谢
- Obsidian 团队提供插件 API
- Anthropic 提供 Claude 和 Claude Agent SDK