把 Router One 添加为 Copilot for Obsidian 的自定义 OpenAI 兼容 provider

开始之前：哪些 Copilot 功能会用到这个 provider

从社区插件安装或更新 Copilot，确认已安装的版本为 4.0.13 或更新；本指南按 4.0.13 核对。Copilot 4 要求 Obsidian 1.11.4 或更新版本（插件的最低应用版本），保存 BYOK Key 的 Obsidian Keychain 同样需要这个版本。下表只有前四行会用到这个 provider，其余功能使用各自的账户或服务，不会使用这把 Key。

把 Copilot for Obsidian 配置到 Router One base URL

打开 Settings → Copilot → BYOK，点「Add a provider」，再点对话框底部的「Add a custom provider」。请使用这个入口，不要改 OpenAI 条目的 URL：列表中的厂商条目绑定该厂商的模型元数据，并交给 opencode 内置的同名 provider；自定义 provider 则以通用 OpenAI 兼容 provider 的身份交给 opencode，指向你填写的 Base URL。在「Configure Custom OpenAI-compatible」中，「Display name」填 Router One，「API key」粘贴专用 Key；该字段标注为 optional，是因为有些自定义端点无需认证，而 Router One 必须提供 Key。「Base URL」填 https://api.router.one/v1。Copilot 在「Test」和模型发现时拼接 /models，聊天客户端拼接 /chat/completions，因此粘贴完整端点会让路径重复。「Enable CORS」保持默认的关闭状态：此时 Quick Chat、Quick Ask 和 Commands 用浏览器的原生 fetch 发送聊天请求，回复流式输出，点停止也能取消请求（按 Copilot 4.0.13 源码）；自 2026-10-02 起，api.router.one 会放行这类请求触发的 CORS 预检（见下文「Enable CORS：保持关闭」）。只有「Test」通过而 Quick Chat 仍发不出消息时才开启它，开启后回复会整段出现，不再流式输出。点「Test」：显示「Verified」表示 GET /v1/models 接受了这把 Key，返回的 ID 会出现在「Search available models」下方。勾选一两个聊天模型，或在「Model ID」中输入精确 ID 后点「Add」。输入框占位符显示的是不带前缀的 gpt-5.5，但请从 /models 复制完整目录 ID，有前缀的要保留前缀，例如 anthropic/claude-sonnet-5 或 openai/gpt-5.5。最后点「Save」。新增的聊天模型会自动对 Quick Chat 和 opencode 启用；在 Basic → Agents → Quick Chat（移动端为 Basic → Quick Chat models）中选择「Default model」，在 Command 中为 Quick Ask、Quick Command 和已保存的命令选择「Default quick command model」，安装 opencode 后，再到 Basic → Agents → opencode 中选择「Default model」：

Base URL

https://api.router.one/v1

# Settings → Copilot → BYOK → Add a provider → Add a custom provider
Display name:  Router One
API key:       sk-your-router-one-key       # saved in this device's Obsidian Keychain
Base URL:      https://api.router.one/v1    # not .../chat/completions
Enable CORS:   Off                          # default; replies stream and Stop cancels
Model ID:      anthropic/claude-sonnet-5    # full catalog ID, then Add
               openai/gpt-5.5
# Test → check chat models only → Save

# Basic → Agents → Quick Chat → Default model   (mobile: Basic → Quick Chat models)
# Command → Default quick command model   (Quick Ask, Quick Command, saved commands)
# Basic → Agents → opencode → Default model   (desktop; install opencode first)
# Each chat turn: POST https://api.router.one/v1/chat/completions

Enable CORS：保持关闭

按 Copilot 4.0.13 源码（2026-10-03 核对），Copilot 使用两种传输方式。「Test」、模型发现，以及每次打开 BYOK 时运行的 provider 检查，都通过 Obsidian 的 requestUrl API 发出，不受浏览器 CORS 规则限制。「Enable CORS」关闭时，Quick Chat、Quick Ask 和 Copilot Commands 从 Obsidian 窗口用原生 fetch 发送请求：回复流式输出，点停止会中止请求，因为 Copilot 把中止信号传给了流式调用。这类请求带 Authorization 头、JSON 请求体，以及 Copilot 内置 OpenAI SDK 自己的 X-Stainless-* 请求头，所以浏览器会先发一次 CORS 预检。自 2026-10-02 起，api.router.one 对预检返回 Access-Control-Allow-Origin: *，并放行预检所列的请求头（含 X-Stainless-*），聊天请求就能发出，回复流式输出；在此之前预检不放行这些请求头，所以本指南以前要求开启「Enable CORS」。点停止会关闭连接，Router One 把该请求记为 HTTP 499 client_cancelled，只按上游实际报告的用量计费（见 LLM 流式输出）。开启「Enable CORS」后，聊天请求改走 requestUrl：如 Copilot 自己的设置提示所说，回复要等全部生成后才出现；按 4.0.13 源码，这条路径不传中止信号，因此点停止并不会取消请求，它会一直生成到结束，并像其他已完成的请求一样计费。Copilot 的 Model Sources 文档（2026-10-03 核对）把开启它列为「Test 成功但 Quick Chat 发不出消息」时的处理方法，遇到这种情况再开启，例如网络代理去掉了 CORS 响应头。这个开关不影响 opencode Agent Chat，它是独立的本地进程，两种设置下都流式输出。该设置按 provider 保存，可在「More actions」→「Edit key」中修改；从 Copilot 3 迁移来的 provider 会保留原来的 CORS 选择。如果你按本指南的早期版本开启了「Enable CORS」，请在「More actions」→「Edit key」中关掉它，回复就会流式输出，点停止也能取消请求。

核对 Quick Chat 的请求数：消息、标题与重试

选中 Router One 模型后，Quick Chat 每条消息对应一次 stream 为 true 的 POST /v1/chat/completions。新对话默认把当前笔记作为上下文，所以长笔记会让每一轮都增加输入 tokens。按 4.0.13 源码，Copilot 对自定义 provider 的模型不发送 temperature、top_p 或输出上限，也不请求流式 usage，因此 Quick Chat 的 token 计数器通常不会显示；tokens 与费用请以控制台 → 日志为准。「Autosave Chat as Markdown」默认开启，Copilot 第一次保存对话笔记时，会让同一个模型生成简短标题，这至少多一次小请求。客户端对失败请求最多再重试三次，所以一条消息最多可能发出四次；按 Copilot 4.0.13 打包的 @langchain/core 1.2.8 源码，500 会重试，400 不会。还有一条命名规则：Quick Chat 会把以 gpt-5 开头的模型名称切换到 Responses API。目录中的 GPT 模型 ID 都带前缀，例如 openai/gpt-5.5，不符合这条规则，所以仍走 Chat Completions；照占位符输入不带前缀的名称（例如 gpt-5.5）时，请求会改发到 POST /v1/responses，Router One 对 GPT 系列原生提供该端点。

Agent Chat：opencode 自己组装请求

opencode 驱动的 Agent Chat 不复用 Quick Chat 的客户端。按 4.0.13 源码，Copilot 启动 opencode 时会传入一份生成的配置：把你的自定义 provider 注册为 @ai-sdk/openai-compatible provider，使用同样的 Base URL 和 Key，以完整目录 ID 列出每个对 opencode 启用的模型，并且对没有元数据的自定义 provider 模型只声明文本输入。之后 opencode 自己组装发往 POST /v1/chat/completions 的请求，会加上 tools、tool_choice 等它自己的参数，所以在 Quick Chat 里能回答的模型，在这里仍可能报错；先看错误点名的是哪个参数。需要发送图片时，请使用 Quick Chat：按同一份源码，它不会拦截这些模型的图片，而是以 image_url 内容发送；同时选用详情页列出图片输入的模型。修改 provider、Key 或已启用模型后，已打开的对话会显示「config has changed」提示；点「Reload」让 opencode 以新配置重启。

搜索与 Embedding 不经过网关

Copilot 4.0.6 及之后的版本没有可以指向 Router One 的 embedding 模型设置：该版本停用了 Vault QA，并移除了插件自带的索引；语义搜索和 Relevant Notes 现在由 Miyo 提供，它是在 Settings → Copilot → Miyo 中连接的独立本地优先应用，维护自己的索引。Router One 不提供 embeddings 端点，也不参与这部分索引。Miyo 或 Agent 文件工具找到的片段会进入发给所选模型的提示词，因此会在日志中计为输入 tokens。Copilot 托管模型和托管的 Copilot Plus 工具运行在 Brevilabs 服务上，需要 Copilot 许可证；本指南只覆盖 Quick Chat 中无需 Copilot 许可证的 Chat 模式（Router One 仍按请求计费）和 opencode Agent Chat。

Copilot for Obsidian 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Copilot for Obsidian 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。

Copilot for Obsidian 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在请求日志里核对 Copilot for Obsidian 的调用

先在 Copilot for Obsidian 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，要么请求没到达网关（客户端配置或网络问题），要么网关在调用模型之前就拒绝了它——Key 问题的 401、余额不足或 Key 达到 maxSpend 上限的 402、Key 或账户自身限额触发的 429，或模型 ID、端点不对的 400 / 404；在输出任何内容之前就失败的流式请求也可能没有日志。看客户端收到的状态码和错误消息就能区分是哪一种；先确认这一点，再判断是不是网关或上游故障。

常见问题