[知识管理/技术调研] Obsidian Copilot 插件：Obsidian 生态排名Top的 AI 助手——基于Markdown文件+LLM模型构建本地化【个人知识库】

1 概述

产品介绍

  • Copilot for Obsidian 是一款运行于 Obsidian 笔记软件内部的 AI 助手插件，由开发者 Logan Yang（@logancyang）创立，现归属 Brevilabs LLC 公司运营。其核心定位是 "Agents for your Obsidian vault"——让前沿 AI Agent 直接在你的知识库中工作，实现研究、写作与知识管理的闭环。

  • 诞生背景与核心问题：

    • 传统 AI 工具（ChatGPT、Claude 等）将用户数据锁在其服务器上，模型切换成本高，定价和功能变更不可控；

    • Obsidian 用户的笔记以本地 Markdown 文件形式存在，却缺乏与 AI 深度交互的原生通道，只能通过复制粘贴在工具间切换；

    • Copilot 的解决思路是 "数据主权 + 模型自由 + Agent 原生"：笔记永远留在本地 vault，用户可自带 API Key（BYOK）、使用本地模型（Ollama）或订阅托管模型，并在 V4 版本中将 opencode、Claude Code、Codex 三大主流 Agent CLI 原生集成进 Obsidian。

  • URL：

效果预览

  • 先上个 Obsidian Copilot 插件 + Codex-ACP + Codex + 硅基流动 + DeekSeek 模型的效果图：

image

社区活跃情况

截止到 2026.8.25: 总体来看，开源社区还是有人在继续维护。

  • Commits & Pushes

image

  • Star History

image

  • 关注者分布

image

发展历程

时间 版本 关键事件
2023-04-13 v1.0.1 首个版本发布（尚未列入社区插件），基础 ChatGPT 对话功能
2023-05-04 — 正式列入 Obsidian 社区插件市场
2023-05~08 v2.x 快速迭代，扩展模型支持与上下文处理能力
2024 全年 v2.4.x+ 持续完善 Vault QA、自定义命令、多提供商接入
2025-08-26 v3.0.0 重大版本发布，全新聊天输入框、增强上下文引用（@/[[]]/#）、Projects 模式
2025-12 v3.1.x 新增 GitHub Copilot 提供商、AWS Bedrock 支持、自动文本选择到上下文
2026-01 v3.1.5 索引无关搜索（index-free search）显著改进、聊天历史排序优化
2026-05 v3.2.9-beta 正式宣布移动端支持，不再仅限桌面（minAppVersion 1.7.2）
2026-06-08 v3.3.0 Projects 以笔记形式存储于 vault 而非 data.json；包体积缩减 1.8MB（Cohere/Mistral 改用 OpenAI 兼容端点）
2026-08-12 v4.0.0 端到端重构：opencode、Claude Code、Codex 三大 Agent 原生运行；Miyo 本地文档处理器；Symposium 发布功能
2026-08-17 v4.0.1 清理 V3 遗留、合规与安全审查、用量计量面板、复用已有文件夹作为 Copilot 目录

关键数据：

  • 累计下载量：170 万+（1.7M，截至 2026-08）
  • 发布版本数：117 个 releases
  • 代码提交：1,078+ commits
  • 代码行数：约 103,363 行
  • Obsidian 社区评分：89/100
  • 荣誉：Best LLM Integration Award，官方自称 "No. 1 Obsidian AI Plugin"

主要功能

V4 核心：Agent Mode

Agent 模式是 Copilot V4 的主体验，支持多步骤自主工作：可检查笔记、调用工具、创建 Obsidian 文件、跨多轮对话持续执行，且权限由用户控制。

  • opencode（推荐）：Copilot 可自动下载管理，支持托管模型、自带 Key 或本地模型；
  • Claude Code：连接已有安装，Copilot 自动检测常见安装路径并复用 Claude Code 登录态；
  • Codex：通过 @agentclientprotocol/codex-acp 适配器连接，复用 Codex 登录；
  • 多 Agent 并行（Plus）：在一条 prompt 中同时 @claude @codex @opencode，各 Agent 并行处理后由 Copilot 合并结果。

Quick Chat（快速对话）

无需 Agent 的轻量对话模式，支持多种上下文注入，适用于简短问答。

Vault QA（全库问答）

基于 RAG（检索增强生成） 的全库问答：用自然语言提问，从所有笔记中检索相关片段并生成带引用的回答。所有 QA 模式均使用本地向量索引，不将数据发送到云端向量搜索服务。

Vault Search（库搜索）

  • 词法搜索（Lexical）：基于 MiniSearch/Orama 的关键词、标签、文件名精确匹配；
  • 语义搜索（Semantic / Miyo）：通过 Miyo 本地文档处理器实现按含义搜索，支持 PDF、EPUB 等非 Markdown 文档的本地解析与索引；
  • 索引管理：事件驱动的增量索引更新，支持文件夹排除规则。

Projects（项目）

为持续工作提供独立的指令集、可复用上下文和聊天历史。项目以 Markdown 笔记形式存储于 vault 中（v3.3.0 起），兼容 opencode、Claude、Codex 三种 Agent。

Skills（技能）

一次配置、跨 Agent 启用。Copilot 内置 Obsidian Markdown、Bases、Canvas、Obsidian CLI 等技能，用户也可自定义技能并一键启用给不同 Agent。

Custom Commands（自定义命令）

保存可复用 prompt，在 Agent 中用 / 触发，或暴露到编辑器右键菜单和命令面板。支持模板变量。

Quick Ask（快速提问）

选中笔记中的文本后不离场提问，可继续对话、替换文本、插入回答或复制。使用 Quick Chat 模型。

上下文引用（Context & Mentions）

通过类型提示（typeahead）系统直接引用：

  • @ 笔记、文件夹、标签、URL、工具；
  • [[]] 内部链接；
  • # 标签。

其他能力

  • 图片理解：分析笔记中嵌入的线框图、图表、截图、照片；
  • Web / YouTube 支持：联网搜索和 YouTube 字幕提取；
  • 多会话：为不同任务保持独立的 Agent 标签页；
  • 系统提示词（Personas）：内置及自定义系统提示词，每个 Persona 有独立记忆。

核心优势

  1. 数据主权与隐私优先：笔记始终是本地文件，本地 Miyo 索引留在设备上；使用本地模型（Ollama + 本地 embedding）时可完全离线运行，零数据外泄。
  2. 模型自由，不锁定提供商：支持 16+ LLM 提供商（OpenAI、Anthropic、Google、Groq、DeepSeek、xAI、AWS Bedrock、Cohere、Mistral 等），三种使用路径——Copilot 托管 / BYOK 自带 Key / 本地模型，已付费的 Claude 或 ChatGPT 订阅可直接复用。
  3. Agent 原生，紧跟前沿：V4 不再自研 Agent，而是将 opencode、Claude Code、Codex 三大业界主流 Agent CLI 原生集成，用户可享受各 Agent 的持续迭代而无需等待插件更新。
  4. 生态成熟，社区验证：170 万+ 下载、117 个版本、3 年持续迭代，是 Obsidian 生态下载量和活跃度最高的 AI 插件，获 Best LLM Integration Award。
  5. 功能覆盖全面：从最简单的选中文本提问（Quick Ask）到全库 RAG 问答（Vault QA），再到多步骤自主 Agent 工作流（Agent Mode），覆盖知识工作的全链路。
  6. 跨平台：桌面端（Windows/macOS/Linux）与移动端均支持，移动端可用 Quick Chat、自定义命令、Quick Ask。
  7. 可扩展架构：Skills、Commands、Projects 均以本地 Markdown 存储，用户可版本管理、分享、同步。

主要短板

  1. Agent 模式仅限桌面：由于 Agent 后端运行本地进程，移动端仅保留 Quick Chat 等轻量功能，重度 Agent 用户无法在手机上使用完整能力。
  2. V4 重构的迁移成本：V4 端到端重写后，部分 V3 功能（如旧版 Projects 模式、GitHub Copilot 提供商、V3 Chat）被清理或指向新路径，老用户需重新适应；虽然项目设置自动迁移，但仍有验证成本。
  3. 高级功能需付费：多 Agent 并行、Copilot 托管模型、云端工具、Symposium 发布等功能需要 Plus 及以上订阅；免费版虽功能完整但受限于自带 Key 或本地模型的能力。
  4. 本地语义搜索有配置门槛：Vault QA 和语义搜索需要用户自行配置 embedding 模型（如通过 Ollama 拉取 bge-m3、nomic-embed-text），对非技术用户有一定上手难度。
  5. 后端服务闭源：插件前端完全开源（AGPL-3.0），但支持托管功能的后端服务是闭源专有的，自托管能力有限。
  6. AGPL-3.0 许可证限制：对希望将其集成进商业产品的开发者有传染性约束，需注意合规。

局限性

  • 依赖 Obsidian 生态：作为 Obsidian 插件，无法脱离 Obsidian 独立运行；
  • 大规模 vault 性能：虽然 Miyo 语义搜索针对性能优化，但超大型 vault（数万笔记）的索引构建和检索仍受本地硬件限制；
  • Agent 工具调用的边界：Agent 对 vault 的写操作需用户确认（除非开启 auto-apply），复杂工作流的可靠性仍依赖底层 Agent 能力；
  • 免费 opencode Zen 模型的隐私警告：该提供商可能记录或用 prompt 训练，发送敏感内容前需审查其条款。

适用场景

  • 个人知识库问答：多年积累的笔记可通过自然语言检索并生成带引用的回答；
  • 研究与写作辅助：Agent 可自动检索 vault + 联网，整理资料并起草结构化笔记；
  • 笔记整理与关联发现：语义搜索发现手动标签遗漏的相关笔记；
  • 隐私优先的本地 AI 工作流：配合 Ollama + 本地 embedding 模型，实现——可完全离线的 AI 助手；
  • 多模型切换的研究场景：研究者可在同一界面快速切换 GPT、Claude、Gemini、DeepSeek 等模型对比输出；
  • 开发者知识管理：将架构文档、会议记录、代码片段纳入 vault，通过 Agent 进行跨文档推理。

同类竞品

插件 定位 核心差异
Smart Connections 以笔记为中心的语义关联 Connections 在当前笔记旁展示相关笔记；Lookup 按含义搜索；无需 API Key 即可用语义检索。适合"先找到对的笔记，再让 AI 处理"的工作流
Text Generator 编辑器内文本生成 最早的 Obsidian AI 插件之一，专注于写作时直接在编辑器中生成、改写、缩写文本，支持 100+ 提供商
Companion for Claude Claude 专用 Agent 单一 Agent（Claude），三个界面：聊天内 Agent 模式、Claude Code 的 MCP 桥接、云端会话；写前确认的护栏机制
Copilot Auto-Completion 类 GitHub Copilot 的行内补全 在编辑器中根据光标前后文本用 LLM 生成续写，支持 OpenAI、Azure、Ollama
BMO Chatbot 多模态聊天机器人 支持图片、语音、网页等多模态交互
AI Copilot（另一个同名插件） 轻量 AI 助手 支持 Personas、自动索引、Ollama 完全离线，功能相对简单

Copilot vs Smart Connections 核心决策点（来自官方对比）：

  • Copilot：以助手面板为产品中心，适合从"聊天/问答/命令/项目/Agent 工作流"切入；
  • Smart Connections：以当前笔记为记录系统，适合从"找到相关笔记 → 打包上下文 → 委派任务 → 结果回写笔记"切入。

发展趋势

开源社区活跃趋势

  • 版本迭代速度：2026 年以来保持每月至少一个小版本，重大版本（3.0、4.0）间隔约一年；
  • 贡献者：核心维护者为 @logancyang，重要贡献者包括 @Emt-lin（GitHub Copilot 集成、项目存储重构等）；
  • Issue/PR：当前开放 Issues 约 57-62 个，PR 约 26 个，社区活跃但核心开发集中在少数维护者；
  • GitHub Sponsors：有 50+ 位赞助者，包括个人和企业；
  • 下载趋势：累计 170 万+，作为 Obsidian 头部 AI 插件保持稳定增长。

技术趋势

  1. 从自研 Assistant 到原生 Agent 集成：V4 的最大战略转向是放弃自研 Agent，转而集成业界主流 Agent CLI（opencode/Claude Code/Codex），降低维护成本并紧跟 Agent 技术前沿；
  2. 本地优先深化：Miyo 本地文档处理器将 PDF/EPUB 解析也本地化，进一步强化"数据不出设备"的隐私主张；
  3. 多 Agent 协作：Plus 功能中的多 Agent 并行预示着未来知识工作可能由多个专长 Agent 协同完成；
  4. 移动端逐步补齐：从桌面-only 到正式支持移动端，未来可能将部分轻量 Agent 能力也带到移动端；
  5. 商业化推进：Brevilabs LLC 公司化运营，Plus/Pro 订阅、托管模型、Symposium 发布等付费功能持续扩展。

总结

Obsidian Copilot 正从"【Obsidian 里的 ChatGPT 对话框】"进化为"【Obsidian 知识库的多 Agent 操作系统】"，以【本地数据主权】和【模型自由】为护城河，在【个人知识管理 AI 赛道】保持领先。

2 工作原理与架构

概念术语

术语 含义
Vault Obsidian 的知识库，即一个包含 Markdown 文件及附件的本地文件夹
BYOK Bring Your Own Key，用户自带 API Key，直接调用模型提供商 API，不经 Copilot 后端
RAG Retrieval-Augmented Generation，检索增强生成，先从知识库检索相关片段再交由 LLM 生成回答
Embedding Model 嵌入模型，将文本转换为高维向量，用于语义相似度计算
Miyo Copilot V4 引入的本地文档处理器，负责 PDF/EPUB 解析、语义索引构建和搜索
Agent Mode V4 核心模式，外部 Agent CLI（opencode/Claude Code/Codex）在 Obsidian 内自主执行多步骤任务
ACP Agent Client Protocol，Agent 客户端协议，用于 Codex 等 Agent 的适配器连接
Projects 隔离的工作空间，包含独立指令、上下文和聊天历史，以 Markdown 笔记存储
Skills 可复用的 Agent 能力包，一次配置可跨 Agent 启用
Quick Chat 轻量对话模式，无需 Agent 后端进程
Vault QA 全库问答模式，基于 RAG 检索整个 vault 后生成带引用的回答
Lexical Search 词法搜索，基于关键词/标签/文件名的精确匹配
Semantic Search 语义搜索，基于向量相似度按含义检索
Composer Agent 建议文件变更时的内联 diff 审查界面，支持 Accept/Reject

架构与运行原理

整体架构分层

graph TB subgraph UI["用户界面层 (React + Tailwind + Radix UI)"] Chat["聊天窗口<br/>(Quick Chat / Agent Chat)"] Composer["Composer 内联 Diff"] Settings["设置面板<br/>(Models / BYOK / Agents)"] QuickAsk["Quick Ask 浮层"] end subgraph Core["核心业务层 (TypeScript)"] AgentMgr["Agent Manager<br/>(opencode / Claude Code / Codex)"] ChatMgr["Chat Manager<br/>(会话/历史/自动压缩)"] ProjectMgr["Project Manager<br/>(笔记化项目存储)"] CommandMgr["Command Manager<br/>(自定义命令 / 模板变量)"] SkillMgr["Skill Manager<br/>(跨 Agent 技能)"] end subgraph Search["检索与索引层"] Lexical["词法检索<br/>(MiniSearch / Orama)"] Miyo["Miyo 语义检索<br/>(本地向量索引 + PDF/EPUB 解析)"] IndexMgr["Index Manager<br/>(事件驱动增量索引)"] Chunk["ChunkedStorage<br/>(大文档分块)"] end subgraph LLM["LLM 抽象层 (LangChain)"] Providers["16+ 提供商<br/>OpenAI / Anthropic / Google / Groq / DeepSeek / xAI / Bedrock ..."] Embedding["Embedding 模型接入<br/>(本地 Ollama / 云端 API)"] end subgraph Storage["存储层"] Vault["Obsidian Vault<br/>(Markdown 笔记 / 项目 / 技能)"] Keychain["Obsidian SecretStorage<br/>(API Key 加密存储)"] LocalIndex["本地索引文件<br/>(Miyo / 词法索引)"] end UI --> Core Core --> Search Core --> LLM Search --> Storage Core --> Storage AgentMgr -->|"ACP / CLI"| ExternalAgents["外部 Agent 进程<br/>opencode / claude / codex"]

关键模块说明

1. Agent 集成层（V4 核心）

Copilot V4 不再内置 Agent 推理逻辑，而是通过以下方式连接外部 Agent CLI：

  • opencode：Copilot 可自动下载可执行文件并管理版本，通过子进程方式启动，支持 Copilot 托管模型、用户 BYOK 或本地 Ollama 模型；
  • Claude Code：自动检测系统中已安装的 claude CLI（常见安装路径），复用其登录态，通过 stdin/stdout 交互；
  • Codex：通过 @agentclientprotocol/codex-acp 适配器（Agent Client Protocol）连接，需用户先安装适配器；
  • 工具调用：Agent 通过 Obsidian 原生 API 实现 vaultSearch（搜索笔记）、readNote（读取笔记）、createNote（创建笔记）、webSearch（联网搜索）等工具，写操作默认需用户在 Composer 中确认。

2. 检索与索引层

Copilot 维护两套并行的检索系统：

  • 词法检索（Lexical）：基于 MiniSearch 和 @orama/orama 实现，支持关键词、标签（含层级标签如 #project/x）、文件名、正则匹配，无需 embedding 模型即可工作；

  • 语义检索（Semantic / Miyo）：V4 引入 Miyo 作为本地文档处理器：

    • 索引构建：扫描 vault 中的 Markdown 文件，按标题/段落分块（Chunk），通过配置的 embedding 模型（本地 Ollama 或云端 API）生成向量，存入本地二进制索引文件（含 manifest + 向量数据）；
    • 增量更新：IndexManager 通过事件驱动监听文件变更，仅对变更的 chunk 重新计算 embedding（通过 content hash 比对），未变更的 chunk 复用已有向量；
    • 文档解析：Miyo 本地解析 PDF、EPUB 等非 Markdown 格式，使其内容也可被语义检索；
    • 检索流程：用户提问 → 提问向量化 → 余弦相似度计算 → Top-K 相关 chunk 召回 → 连同元数据（来源文件路径、标题、位置）注入 LLM prompt。

  • Vault QA 模式：在语义检索基础上，将召回的笔记片段作为上下文，结合系统提示词和用户问题发送给聊天模型，生成带引用标注的回答。所有数据处理在本地完成，不经过云端向量服务。

3. LLM 抽象层

基于 LangChain（@langchain/core、@langchain/openai、@langchain/anthropic、@langchain/google-genai、@langchain/groq、@langchain/deepseek、@langchain/xai 等）统一封装 16+ 提供商：

  • 聊天模型和 embedding 模型分别配置；
  • 支持 OpenAI 兼容端点（v3.3.0 起 Cohere、Mistral 也改用兼容端点以减小包体积）；
  • API Key 存储于 Obsidian 的 SecretStorage（系统钥匙串），而非 vault 的 data.json，提升安全性；
  • 本地模型通过 Ollama（@langchain/ollama）接入，支持完全离线。

4. 项目与技能存储

  • v3.3.0 起，Projects 不再存储于插件的 data.json，而是作为 Markdown 笔记直接存放在 vault 中指定的 Copilot 文件夹，包含项目指令、上下文配置、聊天历史；
  • Skills 和 Custom Commands 同样以本地 Markdown 文件存储，用户可直接编辑、版本管理、通过 Git 同步。

5. 上下文组装机制

每次 LLM 调用前，Copilot 根据当前模式组装上下文：

  • 当前笔记上下文：光标前后字符、当前段落或整个章节；
  • 显式引用：用户通过 @/[[]]/# 引用的笔记、文件夹、标签、URL；
  • 检索结果：Vault QA 模式下召回的 Top-K 笔记片段；
  • 项目上下文：Projects 模式下项目配置的可复用上下文；
  • 对话历史：当前会话历史，超长时自动压缩（auto-compact）。

运行流程示例：Vault QA 全库问答

sequenceDiagram participant User as 用户 participant UI as Copilot UI participant Index as 本地语义索引 participant Emb as Embedding 模型 participant LLM as 聊天模型 participant Vault as Obsidian Vault User->>UI: 输入问题，切换到 Vault QA 模式 UI->>Emb: 将问题向量化 Emb-->>UI: 返回问题向量 UI->>Index: 向量相似度检索 (Top-K) Index-->>UI: 返回相关笔记片段 + 来源元数据 UI->>UI: 组装 prompt (系统提示 + 检索片段 + 问题) UI->>LLM: 发送生成请求 LLM-->>UI: 返回带引用的回答 UI-->>User: 展示回答，引用可点击跳转原笔记

插件的持久化设计

Obsidian Vault 库所在目录: .copilot/ / copilot / .agent/

  • .copilot/ / copilot / .agent/
    image

用户目录下: ~/.obsidian-copilot/

image

...

3 使用指南

安装部署

前置要求

  • Obsidian：v1.11.4 及以上（V4 要求）；
  • 操作系统：Windows / macOS / Linux（桌面端全支持），移动端支持 Quick Chat 等轻量功能；
  • Agent 模式：仅限桌面端，需要本地能运行子进程（opencode 自动下载，Claude Code/Codex 需预先安装）。

安装步骤（通用）

  1. 启用第三方插件：打开 Obsidian → 设置 → 第三方插件 → 关闭"安全模式"；
  2. 浏览社区插件：设置 → 第三方插件 → 浏览 → 搜索 "Copilot"；
  3. 安装并启用：找到 "Copilot"（作者 Logan Yang）→ 安装 → 启用；
  4. 打开设置：设置 → Copilot，进入配置面板。

模型配置 （必读）

路径S：基于ACP调用第三方Agents （亲测、推荐、必读）

选择外部的 Agents 的好处：全栈打通、All in one stack agent。
笔者的环境情况： Windows 10 + Obsidian v1.13.7 + Copilot 插件 v4.0.2

image

  • 1、插件的 Basic - Agents 选项卡

    • Default Backend 列表中可选择： Claude Code / Codex / OpenCode （假定笔者选的 Codex）
    • 选择 Codex 子选项卡：
      • Configure ： 配置 codex-acp （例如：D:\Program\Codex-ACP\v0.16.0\codex-acp.exe）

  • 补充： codex-acp 是什么？如何安装？

推荐文献: Agent Client Protocol：AI 编程时代的 LSP——编辑器与编码 Agent 的标准化桥接通信协议 - 博客园/数据知音

Releases 中有 codex-acp.exe 软件包。笔者选的是 codex-acp-0.16.0-x86_64-pc-windows-msvc.zip 这一版

Releases 中尚无 codex-acp.exe 软件包，用这个版本 Copilot 插件会报错，导致无法正常运行

image

  • 方式2： npx 安装 （不推荐、Obsidian Copilot插件亲测未成功）
> npx -y @agentclientprotocol/codex-acp 或 npm install @agentclientprotocol/codex-acp --registry=https://registry.npmmirror.com
> codex-acp --version
@agentclientprotocol/codex-acp 1.6.2

image

安装完成后， nodejs 的安装目录(如:D:\Program_Files\nodejs\node-v25.9.0-win-x64\及D:\Program_Files\nodejs\node-v25.9.0-win-x64\node_modules\@agentclientprotocol\codex-acp\node_modules\.bin\)下会新增类似下列这些的新程序文件。

codex-acp
codex-acp.cmd
codex-acp.ps1

此方式比较现代，只是 Obsidian Copilot 插件目前可能适配不足。
Obsidian Copilot插件若配置codex-acp-.cmd路径后，其界面报spawn EINVAL错误，这个错误在 Windows 上几乎可以确定原因：

  • 在Obsidian Copilit 的 Codex-Acp 的 Binary path 中填的是 npm 安装的 codex-acp.cmd 脚本，而 Copilot 用 child_process.spawn() 直接启动 .cmd 文件时没有设置 shell: true，导致 Windows 无法执行。
  • .cmd 是批处理包装脚本，不是真正的可执行文件，必须通过 cmd.exe 间接执行。目前解决方案是改用独立编译的 .exe 二进制。

路径 A：BYOK（自带 API Key）

Bring Your Own Key （用户自带的模型密钥）

  1. 设置 → Copilot → Models（BYOK）；
  2. 添加提供商（OpenAI、Anthropic、Google、Groq、DeepSeek 、硅基流动等）；
  3. 填入 API Key（存储于系统钥匙串，非 vault）；
  4. 选项卡中选择默认聊天模型和 embedding 模型；
  5. 验证连接后即可使用 Quick Chat 和 Vault QA。

路径 B：本地模型（Ollama，完全离线）

  1. 安装 Ollama；
  2. 拉取聊天模型和 embedding 模型：
    ollama pull qwen2.5:7b       # 聊天模型（示例）
ollama pull bge-m3            # embedding 模型（中文推荐）
# 或 ollama pull nomic-embed-text  # 英文轻量推荐
  3. 启动 Ollama 服务（默认 http://localhost:11434）；
  4. Copilot 设置 → Models → 添加 Ollama 提供商 → Base URL 填 http://localhost:11434；
  5. 选择聊天模型（如 qwen2.5:7b）和 embedding 模型（如 bge-m3）；
  6. 勾选 "Use vault context"，构建索引后即可离线使用。

路径 C：Copilot 托管模型（付费）

  1. 购买 Copilot Plus/Pro 订阅；
  2. 设置 → Copilot → Basic → 添加 Copilot 许可证；
  3. 在模型选择器中选择可用的托管模型；
  4. 用量可在仪表盘查看。

Agent Mode 配置（V4，桌面端）

  1. 设置 → Copilot → Basic → Agents；
  2. 选择 Agent 后端：
    • opencode：点击 "Download opencode"，Copilot 自动下载管理；
    • Claude Code：确保已安装 claude CLI 并登录，点击 "Auto-detect"；
    • Codex：先安装 @agentclientprotocol/codex-acp 适配器，再连接；
  3. 点击左侧 ribbon 栏的 Agent 图标，或运行命令 "Open Copilot Agent Chat Window"；
  4. 开始对话，Agent 可自主搜索 vault、联网、创建笔记，写操作前在 Composer 中确认。

Windows 特别说明

Agent Mode 在 Windows 上需注意：

  • opencode 自动下载的可执行文件可能被 SmartScreen 拦截，需信任；
  • Claude Code/Codex 的 CLI 路径若 Auto-detect 失败，可在设置中手动指定可执行文件路径；
  • 详细 Windows 配置见官方文档 Windows Setup for Agent Mode。

关键操作

常用命令（命令面板 Ctrl/Cmd+P）

命令 功能
Open Copilot Chat Window 打开 Quick Chat 窗口
Open Copilot Agent Chat Window 打开 Agent Mode 窗口
Copilot: Settings 打开 Copilot 设置
Copilot: Index Vault 手动触发全库索引构建
Copilot: Clear Index 清除索引
Copilot: Toggle Quick Ask 对选中文本快速提问

聊天输入语法

  • / 触发自定义命令（Custom Commands）；
  • @ 引用笔记、文件夹、标签、URL、工具、Agent；
  • [[]] 引用内部链接；
  • # 引用标签；
  • Agent 模式下 @claude @codex @opencode 可同时调用多 Agent（Plus）。

索引管理

  • 自动索引：默认在启动时和文件变更时自动增量更新；
  • 手动重建：命令面板 → Copilot: Index Vault；
  • 排除文件夹：设置 → Vault Search → Index Exclusions，添加不需要索引的文件夹；
  • 索引状态：设置中可查看 embedding 提供商、模型、chunk 数量、索引代数、向量维度。

Projects 使用

  1. 在 Agent Chat 或 Quick Chat 中创建 Project；
  2. 为 Project 设置专属系统指令和可复用上下文；
  3. Project 以 Markdown 笔记存储于 vault 的 Copilot 文件夹中，可直接编辑；
  4. 切换 Project 即切换独立的聊天历史和上下文。

Z FAQ

Q: Copilot 免费吗？不付费能用吗？

可以免费使用。 Copilot 插件本身开源（AGPL-3.0），免费版支持：

  • 使用自带 API Key（BYOK）连接任意支持的模型提供商；
  • 使用本地模型（Ollama）实现完全离线；
  • 连接已有的 Claude Code 或 Codex 账户使用 Agent Mode；
  • Quick Chat、Vault QA、Projects、自定义 Skills 和 Commands、Quick Ask、本地 Miyo 搜索。

付费（Plus/Pro）主要解锁：Copilot 托管模型、云端工具、多 Agent 并行、Symposium 发布等。你的模型提供商可能按其自身费率收费。

Q: 我的笔记数据会被上传到云端吗？

取决于你选择的模型路径。

  • 本地模型（Ollama）：完全离线，笔记和索引都在本地，零数据上传；
  • BYOK：提问和包含的上下文直接发送到你配置的模型提供商（如 OpenAI、Anthropic），Copilot 后端（Brevilabs）不接收；
  • Copilot 托管模型：请求发送到 Brevilabs 后端及其企业模型提供商处理，官方声明请求内容仅瞬时处理、不保留、不用于训练；
  • 本地索引：Miyo 语义索引和词法索引始终存储在本地设备，不上传任何云端向量搜索服务。

Q: Obsidian Copilot插件中的 BYOK / Miyo 到底是个什么东西？为什么命名这么奇怪？（必读）

image

  • 笔者的情况：没有使用 BYOK / Miyo，而是直接调用的 外部 Agent: Codex CLI（其内配置了 硅基流动的DeepSeek模型）

在 Obsidian Copilot 插件（V4.0+ 架构）中，BYOK 和 Miyo 分别代表了该插件在“模型调用”和“本地知识库检索”两个核心方向上的设计理念。以下是它们的具体含义和命名由来：

1. BYOK (Bring Your Own Key)

  • 是什么：BYOK 是 AI 领域的通用缩写，全称是 Bring Your Own Key（自带密钥）。在 Obsidian Copilot 中，它是一个模型管理选项卡。
  • 功能作用：允许用户输入自己申请的第三方大模型 API Key（如 OpenAI、Anthropic/Claude、Google 等），或者配置本地模型服务（如 Ollama、LM Studio）。使用该模式时，AI 的请求会直接通过你的账号和账单计费，而不是通过插件官方的账号。这是该插件免费版的核心使用方式。
  • 命名由来：沿用了云计算和 AI 行业的通用术语（类似于 BYOD - 自带设备）。名字直白硬核，精准面向开发者和高级用户。

2. Miyo

  • 是什么：Miyo 是 Obsidian Copilot 团队推出（并开源）的一个本地优先（Local-First）的知识服务/索引引擎。在 V4 版本中，插件将原本内置的向量索引和语义检索功能全部“外包”给了 Miyo。
  • 功能作用：它是一个独立的后台服务（可本地运行也可远程部署）。负责处理你的 Obsidian 笔记库的语义搜索（向量化索引）、文档解析（如 PDF、EPUB）等重负载计算任务。它的目标是把你的 Obsidian 知识库变成一个集中的工作区，甚至可以通过 MCP 协议给其他 AI 工具（如 Claude Desktop、ChatGPT）提供本地知识库检索能力。
  • 命名由来：这是一个产品专属造词（品牌名）。从官方定位来看，它取意于帮你打理“第二大脑（Second Brain）”的知识服务。名字简短、好记，带有一种拟人化助手的感觉。

3. 为什么命名这么奇怪？

结合最上面截图中的信息可以看出：

  1. Copilot License 区域的文案明确写道：“Pair it with Miyo and turn your vault into a centralized workspace for all your AI tools across devices.”（将它与 Miyo 配对，将你的保险库变成跨设备所有 AI 工具的集中工作区）。

  2. 这反映了 Obsidian Copilot V4 版本的架构大升级：从以前单体式的“【聊天】+【检索】”变成了“【Agent（智能体）】”架构。

  • BYOK 负责解决“算力/模型从哪来”的问题（用你自己的 Key）。
  • Miyo 负责解决“本地隐私数据怎么高效检索”的问题（本地索引引擎）。

这种“极客缩写 + 拟人化造词”的组合，在面向开发者和知识管理爱好者的开源工具中非常常见。

Q: Agent Mode 和 Quick Chat 有什么区别？

维度 Quick Chat Agent Mode
后端 插件内置，直接调用 LLM API 外部 Agent CLI 子进程（opencode/Claude Code/Codex）
能力 单轮/多轮对话，上下文注入 自主多步骤任务、工具调用、文件读写、联网搜索
平台 桌面 + 移动端 仅限桌面
适用场景 快速问答、文本改写、选中文本提问 研究、写作、跨笔记整理、复杂工作流
配置门槛 低，配置模型即可 较高，需安装/下载 Agent 后端

Q: Vault QA 检索效果不好怎么办？

可从以下方面优化：

  1. 检查索引状态：确认索引已完整构建，embedding 模型正常工作；
  2. 更换 embedding 模型：中文内容推荐 bge-m3，英文推荐 nomic-embed-text 或 bge-base-en-v1.5；
  3. 调整分块策略：过大的 chunk 会稀释语义，过小的 chunk 会丢失上下文；
  4. 优化笔记结构：使用清晰的标题层级、标签、内部链接，有助于检索和引用；
  5. 排除无关文件夹：在 Index Exclusions 中排除模板、附件、日志等无关内容；
  6. 使用 Miyo 语义搜索：相比纯词法搜索，语义搜索更能理解模糊查询。

Q: 移动端能用 Agent Mode 吗？

不能。 Agent Mode 仅限桌面端，因为其后端（opencode/Claude Code/Codex）需要运行本地子进程，移动端 Obsidian 不支持。移动端可用的功能包括：Quick Chat、自定义 Commands、Quick Ask、Vault QA（需配置模型）。

Q: 如何完全离线使用 Copilot？*

  1. 安装 Ollama 并拉取聊天模型（如 qwen2.5:7b）和 embedding 模型（如 bge-m3）；
  2. 在 Copilot 设置中添加 Ollama 提供商，Base URL 填 http://localhost:11434；
  3. 将默认聊天模型和 embedding 模型都设为 Ollama 本地模型；
  4. 构建本地索引；
  5. 断开网络后仍可使用 Quick Chat、Vault QA、Quick Ask、自定义命令。
    注意：Agent Mode 中的 opencode 若使用 Copilot 托管模型则需要网络，使用本地 Ollama 模型也可离线。

Q: Copilot 和 Smart Connections 怎么选？

  • 选 Copilot：如果你希望以 AI 助手为中心，主要工作流是聊天、问答、Agent 执行任务，需要多模型切换和完整的 Agent 能力；
  • 选 Smart Connections：如果你的首要问题是"找到相关笔记"，希望在当前笔记旁看到语义关联，再基于找到的笔记进行 AI 处理，且不想配置 API Key 就能用语义检索；
  • 两者可以共存，不少用户同时安装以互补。

Q: API Key 存在哪里？安全吗？

从 v3.1.x 起，API Key 存储于 Obsidian 的 SecretStorage（即操作系统的钥匙串/凭据管理器），而非插件的 data.json 文件。这意味着：

  • Key 不会随 vault 同步到 Git 或云盘；
  • 由操作系统级加密保护；
  • 不同设备需分别配置。

Q: V3 升级到 V4 后项目和设置还在吗？

项目和设置会自动迁移。 v3.3.0 已将 Projects 迁移为笔记存储，V4 首次加载时自动迁移现有项目和设置。但需注意：

  • V3 Chat 模式被移除，指向 opencode；
  • GitHub Copilot 提供商被移除（V4 聚焦三大 Agent）；
  • 旧版 vault 索引开关回归；
  • 建议升级前备份 vault，升级后验证项目和聊天历史加载正常。

Y 推荐文献

X 参考文献

posted @ 2026-08-25 11:16  数据知音  阅读(25)  评论(0)    收藏  举报