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

> https://router.one/zh/integrations/obsidian-copilot 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-23

Copilot for Obsidian（logancyang/obsidian-copilot，在社区插件中名为 Copilot）通过 Settings → Copilot → BYOK（自带 Key）→「Add a provider」→「Add a custom provider」接入 Router One：「Base URL」填 https://api.router.one/v1，填入 Router One Key 和精确的目录模型 ID（例如 anthropic/claude-sonnet-5），并为 Quick Chat 开启「Enable CORS」。之后，Quick Chat、Quick Ask、Copilot Commands 和 opencode Agent Chat 发出的模型请求由 Router One 处理；笔记、上下文、Agent 工具、权限与 Miyo 搜索仍由 Copilot 负责。本指南基于 2026-09-22 发布的 Copilot 4.0.10，以及它下载的 opencode 1.18.31；Claude 与 Codex 后端不使用 BYOK Key。

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

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

| Copilot 功能 | 是否使用 Router One provider | 请求从哪里发出 |
| --- | --- | --- |
| Quick Chat（桌面与移动端） | 是，选中 Router One 模型时 | Obsidian 本身：POST /v1/chat/completions |
| Quick Ask | 是，它使用 Quick Chat 模型 | Obsidian 本身：POST /v1/chat/completions |
| Copilot Commands 与 Trigger quick command | 是，所沿用或指定的模型是 Router One 模型时 | Obsidian 本身：POST /v1/chat/completions |
| Agent Chat + opencode（仅桌面端） | 是，前提是已安装 opencode 并为它启用该模型 | 本机 opencode 进程：POST /v1/chat/completions |
| Agent Chat + Claude 或 Codex | 否，它们从不使用 BYOK Key | 由 Claude Code 或 Codex CLI 按自身登录与配置发出，不使用这把 BYOK Key |
| Copilot 托管模型、托管的 Copilot Plus 工具 | 否，需要 Copilot 许可证，运行在 Brevilabs 服务上 | 不经过 Router One |
| Miyo 语义搜索、Relevant Notes | 否，Miyo 维护自己的索引 | 不经过 Router One |

## 把 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」：

`copilot-byok-custom-provider`

```text
# 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；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 「Test」显示「Verified」，但 Quick Chat 发不出消息，该改什么？

「Test」和状态标记只证明 GET /v1/models 通过 Obsidian 的 requestUrl 接受了 Key。「Enable CORS」关闭时，Quick Chat 用浏览器的原生 fetch 发送聊天请求，这类请求可能被 CORS 预检拦下（原因见「为什么 Quick Chat 需要开启 Enable CORS」）。所以先在 BYOK 中对 Router One provider 点「More actions」→「Edit key」，确认「Enable CORS」已开启并保存；之后回复会整段出现，不再流式输出。这也是 Copilot 文档针对这种情况给出的处理方法。如果 Quick Chat 随后返回了带消息的 HTTP 状态码，说明传输本身没有问题：检查精确的目录模型 ID、带 /v1 的 Base URL，以及是否误勾选了发现列表里的图片生成 ID。provider 显示「Verified」也不代表每个模型都能回答。

### 我在 Copilot 3 里把 Router One 配成了 3rd party (openai-format) 模型，需要重新配置吗？

通常不用。Copilot 4 已经没有 Model 标签页。首次加载时，它会执行一次性迁移，把每个已启用、填写了 base URL 的 3rd party (openai-format) 模型，连同 Key 和 CORS 选择，复制到名为 OpenAI Format 的 BYOK provider 中（base URL、Key 或 CORS 设置不同时分成多个 provider），并对 Quick Chat 和 opencode 启用。已停用的模型和 embedding 模型不会迁移，旧设置保持原样。打开 BYOK，确认该 provider 的「Base URL」是 https://api.router.one/v1、「Enable CORS」已开启、模型都是精确的目录 ID，然后可以改名，并删除已不在 /models 中的 ID。如果显示「No key」，编辑它并重新粘贴 Key。

### 为什么换到手机或另一台电脑后，Router One 的 Key 不见了？

Copilot 把 BYOK Key 存在每台设备自己的 Obsidian Keychain 中，而不是 vault 的 data.json，所以同步 vault 不会带上 Key。在那台设备上打开 Settings → Copilot → BYOK，通过「More actions」→「Edit key」重新输入 Key；如果列表里没有该 provider，就在那里重新添加。Keychain 需要 Obsidian 1.11.4 或更新版本，版本过旧时 Advanced → API Key Storage 会显示「Unavailable」。在 iOS 和 Android 上可以使用 Quick Chat、Quick Ask 和 Copilot Commands（Agent Chat 仅限桌面端），它们的模型列表位于 Basic → Quick Chat models；这些请求直接从设备本身发出。

### 同一个模型在 Quick Chat 里正常，在 opencode 的 Agent Chat 里却返回 400，为什么？

两者是不同的客户端。Quick Chat 只发送 model、messages 和 stream；本地运行 1.18.31 的结果显示，opencode 还会加上 tools、tool_choice、stream_options.include_usage 和 max_tokens 32000，对 ID 中含 gpt-5 的模型（如 openai/gpt-5.5）再加 reasoning_effort: medium。先看错误点名的是哪个参数或功能。如果是 max_tokens，在 Basic → Agents → opencode →「Environment variables」中添加 OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX，设一个更小的值，然后重新加载对话；opencode 文档把这个实验性变量说明为最大输出 tokens。Router One 的每分钟 token 限额在请求开始时会把 max_tokens 计入估算，Agent Chat 连续请求返回 429 TOKEN_QUOTA_EXCEEDED 时，调小这个值也有帮助。如果是工具相关错误，换用 /models 详情页列出工具调用的模型。错误提示 must be called via，说明该 ID 不是聊天模型（例如发现列表里的图片生成 ID）：目录中的聊天模型都可以走 /v1/chat/completions，而这是 opencode 通用 provider 唯一使用的路径。

### Copilot for Obsidian 能通过网关用哪些模型？

选用当前目录中同时支持 Copilot for Obsidian 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只说明它从自身配置或 GET /v1/models 读到了这个 ID，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Copilot for Obsidian 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Cline 接入：https://router.one/zh/integrations/cline
- Aider 接入：https://router.one/zh/integrations/aider
- opencode 接入：Agent Chat 背后的 Agent：https://router.one/zh/integrations/opencode
- LLM 流式输出：SSE 与 usage：https://router.one/zh/llm-streaming
- 连接与 /v1 路径排查：https://router.one/zh/api-connection-troubleshooting
- Copilot for Obsidian 官方文档：模型来源与 BYOK：https://docs.obsidiancopilot.com/llm-providers/
- Copilot for Obsidian 官方文档：BYOK 设置参考：https://docs.obsidiancopilot.com/settings/#byok
- Copilot for Obsidian 官方文档：故障排查：https://docs.obsidiancopilot.com/troubleshooting-and-faq/
- Copilot 4.0.10 发布说明：https://github.com/logancyang/obsidian-copilot/releases/tag/4.0.10
- Copilot 4.0.10 源码：聊天模型客户端：https://github.com/logancyang/obsidian-copilot/blob/4.0.10/src/LLMProviders/chatModelManager.ts
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/obsidian-copilot
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md