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

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

从社区插件安装或更新 Copilot，确认已安装的版本为 4.0.10 或更新；本指南按 4.0.10 核对。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」：「Test」不依赖它，但关闭时 Quick Chat、Quick Ask 和 Commands 会用浏览器的原生 fetch 发送聊天请求，这类请求可能被 CORS 预检拦下（原因见下文「为什么 Quick Chat 需要开启 Enable CORS」）；开启后，回复会整段出现，不再流式输出。点「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」，安装 opencode 后，再到 Basic → Agents → opencode 中选择「Default model」：

# 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:   On                           # Quick Chat, Quick Ask, Commands; replies arrive whole
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)
# Basic → Agents → opencode → Default model   (desktop; install opencode first)
# Each chat turn: POST https://api.router.one/v1/chat/completions

为什么 Quick Chat 需要开启 Enable CORS

Copilot 使用两种传输方式。「Test」、模型发现，以及每次打开 BYOK 时运行的 provider 检查，都通过 Obsidian 的 requestUrl API 发出，不受浏览器 CORS 规则限制。「Enable CORS」关闭时，Quick Chat、Quick Ask 和 Copilot Commands 从 Obsidian 窗口用原生 fetch 发送请求，Copilot 内置的 OpenAI SDK 还会加上自己的 X-Stainless-* 请求头。浏览器会先用 CORS 预检请求核对这些请求头，而截至 2026-09-23，api.router.one 的预检响应不允许这些请求头，所以聊天请求根本不会发出：这就是「Test」能通过、Quick Chat 却连不上的原因。开启「Enable CORS」后，这些聊天请求改走 requestUrl：回复要等全部生成后才出现；4.0.10 的源码注明这条路径无法中止，因此点停止并不会取消请求，它会一直生成到结束，并像其他已完成的请求一样计费。这个开关不影响 opencode Agent Chat，它是独立的本地进程，仍然流式输出。该设置按 provider 保存，可在「More actions」→「Edit key」中修改。

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

选中 Router One 模型后，Quick Chat 每条消息对应一次 stream 为 true 的 POST /v1/chat/completions。新对话默认把当前笔记作为上下文，所以长笔记会让每一轮都增加输入 tokens。在本地按 4.0.10 客户端参数复现时，请求体只包含 model、messages 和 stream：Copilot 对自定义 provider 的模型不发送 temperature、top_p 或输出上限，也不请求流式 usage，因此 Quick Chat 的 token 计数器通常不会显示；tokens 与费用请以 Dashboard → Logs 为准。「Autosave Chat as Markdown」默认开启，Copilot 第一次保存对话笔记时，会让同一个模型生成简短标题，这至少多一次小请求。客户端对失败请求最多再重试三次：复现中 500 共发送四次、400 只发送一次；Retry-After 不超过 60 秒的 429（网关限流返回的 429 可能带这个响应头）也会在等待后重试，所以一条消息最多可能发出四次。还有一条命名规则：Quick Chat 会把以 gpt-5 开头的模型名称切换到 Responses API。目录中的 GPT 模型 ID 都带前缀，例如 openai/gpt-5.5，不符合这条规则，所以仍走 Chat Completions；照占位符输入不带前缀的名称（例如 gpt-5.5）时，请求会改发到 POST /v1/responses，Router One 对 GPT 系列原生提供该端点，Trace 中也会显示这条路径。

Agent Chat：opencode 自己组装请求

opencode 驱动的 Agent Chat 不复用 Quick Chat 的客户端。Copilot 启动 opencode 时会传入一份生成的配置，把你的自定义 provider 注册为 @ai-sdk/openai-compatible provider，使用同样的 Base URL 和 Key，并以完整目录 ID 列出每个已启用的模型。用这样的配置在本地运行 opencode 1.18.31 时，model 字段保留了斜杠，所有请求（包括 openai/gpt-5.5）都发往 POST /v1/chat/completions。会话的第一条消息产生了两次请求：一次标题请求和一次主请求；opencode 文档说明，标题会优先使用更便宜的 small_model，没有时回退到主模型。两次请求都带有 stream_options.include_usage 和 max_tokens 32000（因为 Copilot 不为自定义模型传递输出上限），主请求还加上了 tools 和 tool_choice，使用 openai/gpt-5.5 时还带有 reasoning_effort。Copilot 不会为自定义 provider 的模型声明图片输入；按 Copilot 源码中的注释，opencode 会在发送前去掉发给这类模型的图片。需要发送图片时，请使用 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 文件工具找到的片段会进入发给所选模型的提示词，因此会在 Logs 中计为输入 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 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 Copilot for Obsidian 的调用

先在 Copilot for Obsidian 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题