文档

Obsidian Copilot

Copilot 的 BYOK 选项卡通过三个字段接入自定义的 OpenAI 兼容提供商。文档对由此生成的模型可以出现在哪些界面有明确说明，本页也会保留这种准确性，不会声称整个插件都支持这些模型。

Settings → Copilot → BYOK → Add a custom provider：填写 Display name、密钥和 https://api.kunavo.com/v1 — 始终支持 Quick Chat；当提供商显示在 opencode 下时支持 Agent Chat。

Settings → Copilot → BYOK → Add a provider → Add a custom provider

Display name             Kunavo
API key                  sk-kn-...
Base URL                 https://api.kunavo.com/v1
Enable CORS              off — see the note below before turning it on
Model ID → Add           claude-sonnet-5
                         claude-haiku-4-5
Search available models  discovery reads GET /v1/models; typed ids also work
Save                     needs at least one model and a routable endpoint

此处的基础 URL 保留 /v1 后缀，文档是通过示例而非文字说明这一点的：文档只说 “自定义的 OpenAI 兼容提供商必须有一个 Base URL”，但随附的两个 OpenAI 兼容模板默认 URL 都以 /v1 结尾——Ollama 对应 http://localhost:11434/v1，LM Studio 对应 http://localhost:1234/v1；文档还补充说 “模型发现使用端点的 /v1/models 响应”。如果发现结果为空，首先应重新检查这两点。

BYOK 提供商并不能接入插件的每个部分，文档对此说得很直接：“添加密钥不会更改 Claude Code 或 Codex 提供的模型。”文档自己的表格明确列出，BYOK 模型可用于 Quick Chat；Agent Chat 则仅在使用 opencode 后端且“提供商在那里显示时”才可使用——这是一个条件，而非通用规则；此外，“opencode 无法路由的模型不会显示在 opencode 列表中，但仍可能在 Quick Chat 中使用。”如果你运行的是 Claude 或 Codex 后端，则应改用相应 CLI 自身的环境变量进行配置：参见 /docs/integrations/claude-code。

启用 CORS是一种取舍，不应一直将其当作修复方案开启。文档写道：“如果 Test 成功，但 Quick Chat 无法发送消息，请编辑提供商并启用 Enable CORS。此后，响应会在完成后显示，而不是逐个 token 流式显示。”文档还指出，此开关不会改变 opencode 路由，因此为了修复 Quick Chat 而启用它，会让你在此处失去逐个 token 的输出，其他地方则不受影响。

Copilot 4.x 不需要嵌入模型提供商：其语义搜索已迁移到独立服务 Miyo，BYOK 对话框中也没有此类字段。这正合适，因为 Kunavo 不提供嵌入模型，本页也不会暗示 Kunavo 提供此类模型。

Kunavo 尚未对该插件进行运行时测试。上述每个字段和引述均于下方所列日期从 Copilot 自己的文档中查阅；发布配置页面不等于实际测试。将工作流迁移到该插件之前，请先通过 Quick Chat 发送一项真实任务。

还没有密钥？创建 Kunavo 账户，创建一个密钥（以 sk-kn- 开头），并充值 $10 起——调用费用从该余额中扣除，失败的调用不会收费。随后，控制台会打开 Obsidian Copilot 设置页面。

分步操作

在 /app/keys 创建密钥并复制——它只会显示一次。
在 Obsidian 中，打开 设置 → Copilot → BYOK，然后点击 添加提供商。
选择 添加自定义提供商，而不要选择命名提供商或 Self Host 模板。
按上述内容填写 显示名称、API 密钥 和 基础 URL。暂时关闭 启用 CORS。
至少添加一个模型——在 模型 ID → 添加 下输入 id，或从 搜索可用模型中选择；该列表由 GET /v1/models 填充。点击测试，然后点击保存；只有在模型和可路由端点都已配置后，才能保存。
在 Basic → Agents → Quick Chat 和 Basic → Agents → opencode 下配置这些模型的显示位置，每个位置都有各自的 默认模型。默认情况下，新添加的聊天模型会同时为两者启用。

已于 2026年9月21日对照 Copilot 的“模型来源与 BYOK”页面检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

这是简要版本。完整教程——包括模型选择、真实会话成本和失败模式——见实际由哪个 Copilot 后端支付 token 费用。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 Obsidian Copilot 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

模型 ID	Kunavo 输入 / 输出	它在 Obsidian Copilot 中的位置
`claude-haiku-4-5`	$0.70 / $3.50	Quick Chat，全天候针对笔记处理简短提问
`claude-sonnet-5`	$1.40 / $7.00	Agent Chat 中的 opencode 后端——默认工作模型
`claude-opus-5`	$3.50 / $17.50	跨多条笔记进行长篇综合分析，误读的代价很高
`gpt-5-6-sol`	$2.00 / $12.00	使用同一密钥和同一提供商条目，获得来自另一模型系列的第二意见

计费方式是从预付余额中按 token 扣费，无月费——参见计费。对于重复上下文——这正是编辑器或聊天客户端发送内容的大部分——提示缓存对账单的影响大于模型选择。

常见问题

Obsidian Copilot 的 API 密钥应填在哪里？

前往“设置” → Copilot → BYOK → 添加提供商，然后针对内置列表中没有的端点选择“添加自定义提供商”。对话框需要填写显示名称、API 密钥、基础 URL、可选的启用 CORS 开关，以及至少一个模型；模型可以通过 id 添加，也可以从发现的列表中选择，然后点击“保存”。Copilot 文档称，提供商密钥保存在该设备的 Obsidian Keychain 中，而非 vault 的 data.json 文件中，因此同步 vault 不会将凭据带到另一台电脑。

Obsidian Copilot 的基础 URL 末尾需要加 /v1 吗？

使用带 /v1 的格式——Kunavo 对应 https://api.kunavo.com/v1。文档没有用一句话明确说明这条规则；它说明自定义的 OpenAI 兼容提供商必须有 Base URL，模型发现使用端点的 /v1/models 响应，并且随附的两个 OpenAI 兼容模板默认值分别为 http://localhost:11434/v1 和 http://localhost:1234/v1。这两个默认值都带有该后缀，这是文档对此给出的最有力依据。基础 URL 错误通常会导致模型列表为空或 Test 失败，而不是出现身份验证错误。

Obsidian Copilot 能否使用 OpenRouter 或 Kunavo 这样的网关，而不是供应商密钥？

Quick Chat 可以，Agent Chat 则有条件支持。Copilot 自己的文档将 BYOK 描述为“直接连接到 AI 提供商、兼容网关或你电脑上的模型服务器”；“添加自定义提供商”接受任意 OpenAI 兼容基础 URL 和模型 id。其模型来源表随后明确列出，BYOK 模型可用于 Quick Chat；Agent Chat 则仅在使用 opencode 后端且“提供商在那里显示时”才可使用。Claude 和 Codex 后端完全不接受 BYOK 密钥——文档称，添加密钥不会更改它们提供的模型。

Obsidian Copilot 的 vault 搜索需要嵌入模型吗？

聊天提供商不需要提供。Copilot 4.x 不再运行插件内部索引：文档称，语义搜索和 Relevant Notes 由独立的本地或远程服务 Miyo 提供，BYOK 对话框也没有此类模型的字段。Kunavo 同样不提供嵌入模型，因此这里的任何内容都不应被理解为 Kunavo 提供此类模型——Copilot 中的聊天提供商条目只负责支付聊天费用，不负责其他用途。

Kunavo 密钥能否替代 Copilot Lite 或 Plus 许可证？

不能，两者是刻意区分的。Copilot 文档将许可证和 BYOK 视为不同的模型来源：许可证提供由 Brevilabs 根据你的套餐计费的 Copilot 托管模型；BYOK 则将请求发送到你自己的端点，费用由该提供商收取。这里的密钥不会补充许可证额度，不会解锁受限的 Copilot 托管模型条目，也不会更改受许可证限制的服务；反过来，即使没有许可证，也可以在免费套餐中使用 BYOK。