Obsidian Copilot 插件接入 QCode 图文教程(Windows 11 一步一图)
跟着 17 步、17 张截图,在 Windows 11 上装好 Obsidian 1.15.1 和 Copilot 4.1.0,用 BYOK 填 QCode 地址和密钥,在 Quick Chat 里用 gpt-6.2-sol 与 claude-opus-5-5 对话。
需要 API Key? 前往注册 →端点与 Base URL →
照着下面 17 步做完,你会在 Windows 11 上给 Obsidian 装好 Copilot 插件,并让它通过 QCode 用上 gpt-6.2-sol 与 claude-opus-5-5:在笔记里点开右侧 Quick Chat,几秒就能拿到中文的解释、总结和改写。
一句话答案:在 Obsidian 设置的「第三方插件 → Copilot → BYOK」里点「+ Add a provider」,选「Add a custom provider」,把 Base URL 填成 https://api.qcode.cc/openai/v1、粘贴 cr_ 密钥、打开 Enable CORS,Test 出现 Verified 后勾选 gpt-6.2-sol 保存。
| 项 | 填写 |
|---|---|
| 接入地址(GPT、国产) | https://api.qcode.cc/openai/v1 |
| 接入地址(Claude) | https://api.qcode.cc/api |
| 默认模型(GPT) | gpt-6.2-sol |
| 默认模型(Claude) | claude-opus-5-5 |
| 密钥格式 | cr_xxxxxxxx |
核对于 2026-11-22 · Obsidian 1.15.1 + Copilot 4.1.0 · Windows 11
下载与安装¶
Obsidian 的 Windows 安装包只有一个 .exe 文件,从官网下载即可;Copilot 插件不在这个安装包里,它要装完 Obsidian 之后在 Obsidian 内部的插件市场装。
先选你所在的地区:
- 打开 obsidian.md/download,点「Download for Windows」,得到
Obsidian-1.15.1.exe。 - Obsidian 的安装包实际托管在 GitHub,直连慢或断流时,改用命令行安装同样版本:
winget install Obsidian.Obsidian。 - 安装包按当前用户安装,通常不会弹「用户账户控制」;装完在开始菜单里就能找到 Obsidian。
- 打开 obsidian.md/download 下载 Windows 版,或直接去 GitHub Releases 拿最新一版的
Obsidian-1.15.1.exe。 - 只下
.exe;列表里的.dmg是 macOS、.apk是安卓,装了也用不了。 - 想省事也可以在「Windows 终端」里运行
winget install Obsidian.Obsidian。
- 官网和 GitHub 一般都能直连:打开 obsidian.md/download 点 Windows 按钮最省事。
- 若页面版本号和你要的不一致,到 GitHub Releases 找
v1.15.1那一版下载同名.exe。 - 安装时若弹出「Windows 已保护你的电脑」,点「更多信息」→「仍要运行」。
- 优先用官网 obsidian.md/download;打不开时改用
winget install Obsidian.Obsidian。 - 也可以从 GitHub Releases 下载,文件名格式固定是
Obsidian-<版本>.exe。 - 装完先打开一次,确认能进到「新建仓库」那一屏,再往下做。
跟着截图做:Windows 一步一图¶
下面 17 步,每步只做一件事。截图是中文界面的 Windows 11,图上的橙色编号和正文里的 ①②③ 一一对应。
打开 Obsidian 官方下载页¶
在浏览器里打开 obsidian.md/download。页面会自动识别你的系统,① 处的紫色按钮「Download for Windows」就是 Windows 版安装包。

做对了你会看到:浏览器开始下载一个文件,文件名是 Obsidian-1.15.1.exe,不是 .dmg 或 .apk。
卡住了?点了按钮没反应,或下载停在 0%
安装包托管在 GitHub,网络不通时容易卡住。可以换到「下载与安装」里的其他地区写法,或直接在「Windows 终端」里运行 winget install Obsidian.Obsidian 装同一版本。
首次启动,点「创建」新建仓库¶
双击刚下好的安装包,按提示装完(安装程序只有一个按钮,装完会自动打开),然后从开始菜单打开 Obsidian。第一次启动会自动显示简体中文,首页是三行选项,点 ① 处「新建仓库」右侧的紫色「创建」。

做对了你会看到:出现「创建本地仓库」表单,左上角有「返回」,右上角写着「版本 1.15.1」。
填仓库名称和存放位置¶
「仓库名称」里填一个好记的名字,比如 QCodeDemo(①);点 ② 的「浏览」挑一个文件夹当仓库位置(截图里的用户名已打码);最后点 ③ 的「创建」。

做对了你会看到:Obsidian 主窗口打开,标题栏显示 QCodeDemo - Obsidian,中间是一篇叫「欢迎」的笔记。
卡住了?提示这个位置已经有仓库
说明你挑的文件夹里已经有一个 Obsidian 仓库了。换一个空文件夹,或者在「仓库位置」里新建一个子文件夹再点「创建」。
打开设置里的「第三方插件」¶
在 Obsidian 窗口里按 Ctrl + , 打开设置。左侧列表点 ① 的「第三方插件」,右侧这时还在受限状态,点 ② 的「退出受限模式」。

做对了你会看到:受限模式的提示消失,页面上出现「浏览」按钮和已安装插件列表。
卡住了?左侧找不到「第三方插件」
说明 Obsidian 版本太旧。回到「下载与安装」装上 1.15.1,或者在「Windows 终端」里运行 winget upgrade Obsidian.Obsidian,装完重开设置。
搜索 Copilot 并安装¶
点「浏览」进入社区插件市场。在搜索框输入 Copilot(①),在结果里选中 ② 作者是 Logan Yang 的 Copilot,右侧详情页显示版本 4.1.0,点 ③ 的「安装」。

做对了你会看到:按钮开始转圈,几十秒后同一个位置变成「启用」。
点「启用」打开插件¶
装完后按钮自动变成「启用」,点 ① 的「启用」。如果弹出「信任作者并启用插件」,点信任那一项就好。

做对了你会看到:返回设置的「第三方插件」列表,Copilot 出现在已安装列表里,状态是已启用。
卡住了?提示需要信任作者
这是 Obsidian 对社区插件的常规确认。看一遍作者名(Logan Yang)和仓库地址,点「信任作者并启用」即可,之后不会再问。
打开 Copilot 的 BYOK 页¶
按 Ctrl + , 回到设置,左侧「第三方插件」分组下面点 ① 的「Copilot」,切到 ② 的「BYOK」标签页,再点 ③ 的「+ Add a provider」。

做对了你会看到:弹出「Add a provider」窗口,里面列着一排服务商名字。
选择「Add a custom provider」¶
弹窗里按类别列出常见服务商。接 QCode 的 GPT 和国产模型走 OpenAI 兼容协议,点最下面 ① 的「+ Add a custom provider」;想同时用上 Claude,就点 ② 的「Add Anthropic provider」。

做对了你会看到:弹出「Configure Custom OpenAI-compatible」表单,从上到下是 Display name、API key、Base URL、Enable CORS、Models。
填 QCode 的地址和密钥¶
Display name 填 QCode;API key 粘贴 cr_ 开头的那一整串;Base URL 填 ① 处的 https://api.qcode.cc/openai/v1,只填到 /v1 为止,末尾不要加斜杠;再把 ② 的「Enable CORS」开关打开;最后点 ③ 的「Test」。

做对了你会看到:「Test」右边出现绿色的「Verified」,下面 Models 区域开始列出模型名。
卡住了?Test 显示 Verified,但发消息报 Failed to fetch
这是「Enable CORS」没开。Obsidian 的聊天面板走浏览器接口,不打开这个开关能测试通过、却发不出消息。回到本步把 ② 的开关打开,再点一次「Test」。
勾选模型并保存¶
① 处密钥旁边的绿色「Verified」说明地址和密钥都对;在模型列表里勾选 ② 的 gpt-6.2-sol,再点 ③ 的「Save」。

做对了你会看到:弹窗关闭,BYOK 列表里多出一行 QCode,右边是绿色的「Verified」。
再加一个 Claude 接入点(可选)¶
① 处是 Test 通过后会出现的绿色「Verified」。测试之前,先点「+ Add a provider」→「Add Anthropic provider」,Display name 填 QCode Claude,粘贴同一把 cr_ 密钥,Base URL 填 ② 处的 https://api.qcode.cc/api,并打开「Enable CORS」,然后点「Test」等它变绿,再在 Model ID 里加上 claude-opus-5-5,最后点 ③ 的「Save」。

做对了你会看到:弹窗关闭后回到 BYOK 列表,这次不是空列表,而是两行服务商。
卡住了?只想用 GPT,这一步能不能跳过
可以。只用 gpt-6.2-sol 的话,本步整步跳过,后面的步骤照做,只是把涉及 Claude 的地方换成 GPT 即可。
确认两个接入点都已通过¶
回到「BYOK」列表核对两行:① 的 QCode(OpenAI 兼容)和 ② 的 QCode Claude(Anthropic),右边都应该是绿色的「Verified」。

做对了你会看到:两行都是绿色的「Verified」,没有任何红色提示或「Invalid key」。
在 Quick Chat 里启用模型¶
切回 ① 的「Quick Chat」标签(就在 Basic → Agents 这一排里)。确认 ② 的 Default model 是 gpt-6.2-sol;③ 的位置是模型开关列表,QCode 的 gpt-6.2-sol 和 QCode Claude 的 Claude Opus 5.5 都要拨开。

做对了你会看到:两个开关都是紫色打开状态,Default model 一行显示 gpt-6.2-sol。
卡住了?模型列表里只有 GPT,没有 Claude
先确认上一步的 QCode Claude 是绿色的「Verified」。再回到本页把 Claude Opus 5.5 的开关拨开;如果还看不到,点设置顶部的「重新加载插件」再进来一次。
用命令面板打开 Quick Chat¶
关掉设置回到笔记窗口,按 Ctrl + P 打开命令面板,输入 Quick Chat,选中 ① 的「Copilot: Open Copilot Quick Chat window」并回车。

做对了你会看到:窗口右侧打开 Copilot 面板,底部有输入框和模型名,中间提示可以按 @ 添加上下文。
卡住了?点「Open Copilot Chat」却让你下载别的东西
那是 Copilot V4 的 agent 模式,要另外装运行环境,和本篇的 BYOK 不是一条路。请认准命令名里带「Quick Chat window」的那一条。
让它总结当前笔记¶
在右侧输入框里输入「用三句话总结当前笔记」并回车。面板会自动把当前这篇「欢迎」笔记一起带上,几秒后 ① 处出现中文总结,② 处显示这次用的是 gpt-6.2-sol。

做对了你会看到:回复是通顺的中文,内容确实在讲那篇「欢迎」笔记,底部模型名是 gpt-6.2-sol。
换成 Claude 再问一句¶
① 处是换模型之后 Claude 的回复。先在 ② 的模型下拉里把 gpt-6.2-sol 换成「Claude Opus 5.5」,再输入「你好,用一句话介绍你自己」并回车,几秒后回复就出现在 ① 处。

做对了你会看到:回答是中文,底部模型名变成「Claude Opus 5.5」,中间还会出现一行「Thought for a while」。
到 probe.qcode.cc 核对请求¶
打开 probe.qcode.cc,粘贴同一把 cr_ 密钥,点「查询」,列表最上面那条就是刚才那次对话:① 框住的那一行时间对得上,状态是 200。

做对了你会看到:状态列是 200,时间和你刚才发消息的时刻一致,说明请求确实走了 QCode。
验证成功¶
下面四件事都对上,就说明 Obsidian 里的 Copilot 已经完整接通 QCode:
- 设置 →「第三方插件」→「Copilot」→「BYOK」里,
QCode与QCode Claude都显示绿色「Verified」; - 「Basic」→ Agents →「Quick Chat」里
gpt-6.2-sol是 Default model,Claude Opus 5.5的开关也开着; - 命令面板运行「Copilot: Open Copilot Quick Chat window」,发一句「用三句话总结当前笔记」,几秒内收到中文回复;
- 在 probe.qcode.cc 输入同一把密钥,能查到刚才那次请求,状态是
200。
全部完成¶
你现在可以在 Obsidian 里选中一段没读懂的笔记,用右侧的 Quick Chat 让 gpt-6.2-sol 或 claude-opus-5-5 帮你解释、总结和改写。接下来可以:
- 接入点与 API 格式
- 国产模型接入
- 计费说明
- 接下来:在定价页比较各个方案
- 回到控制台查看用量和余额
常见报错¶
| 报错原文 | 原因 | 怎么办 |
|---|---|---|
Connection error. more message: Failed to fetch |
能点 Test 通过,但聊天面板发不出消息,是「Enable CORS」没打开 | 在 BYOK 里点开 QCode 那一条,把「Enable CORS」开关打开,再点一次「Test」,然后重开 Quick Chat |
{"error":{"message":"Invalid URL (POST /v1/chat/completions/chat/completions)","type":"invalid_request_error"}} |
Base URL 里把 /chat/completions 也填进去了,客户端又自动拼了一次 |
Base URL 只填到 https://api.qcode.cc/openai/v1,末尾别加斜杠,也别带 /chat/completions,然后重填并点「Test」 |
401 invalid_api_key |
密钥不完整、前后带空格,或用的是别的厂商的 key | 回控制台重新复制 cr_ 开头那一整串,粘进 API key 一栏,前后不留空格,再点「Test」 |
Missing API key |
API key 一栏还空着,或粘贴后没保存就切换了标签页 | 把密钥粘进 API key,确认框里出现 cr_ 开头的内容,再依次点「Test」和「Save」 |
常见问题¶
密钥到期后怎么办?¶
分两种情况:个人套餐的密钥到期后不能续,只能重新开通、换一把新密钥;按量包的密钥到期后再买一个包,同一把密钥会自动恢复。
换到新密钥后,回到 BYOK 里点开 QCode(以及 QCode Claude),重新粘贴密钥,点「Test」通过后点「Save」。
Quick Chat 里看不到刚添加的模型?¶
BYOK 只是把服务商接进来,模型还要单独打开:到「Basic」→ Agents →「Quick Chat」,把想要的模型开关拨开,并在 Default model 里选中它。设置页没刷新的话,点一下顶部的「重新加载插件」再回来。
「Enable CORS」一定要开吗?¶
要开。不开的时候 Test 一样显示「Verified」,但 Quick Chat 发消息会失败。GPT 接入点和 Claude 接入点都要打开这个开关。
同一把密钥能同时填给两个接入点吗?¶
可以。同一把 cr_ 密钥在 Anthropic 端点(https://api.qcode.cc/api)和 OpenAI 兼容端点(https://api.qcode.cc/openai/v1)通用,用量都记在同一个账号下。
需要 Copilot 的许可证或账号登录吗?¶
不需要。本篇走的是 BYOK:用你自己的密钥直连 QCode,不用登录任何模型厂商的账号,也不用绑定 Copilot 的付费账号。
其他接入点¶
三个接入域能力相同,只是网络路由不同,同一把密钥通用。大陆网络连 api.qcode.cc 慢时,把地址换成亚洲节点再点一次「Test」。
| 节点 | Anthropic(Claude) | OpenAI 兼容(GPT / 国产) |
|---|---|---|
| 全球 | https://api.qcode.cc/api |
https://api.qcode.cc/openai/v1 |
| 亚洲(大陆首选) | https://asia.qcode.cc/api |
https://asia.qcode.cc/openai/v1 |
| 北美 / 欧洲 | https://us.qcode.cc/api |
https://us.qcode.cc/openai/v1 |
可用模型¶
| 模型 | 在 Copilot 里填的 Model ID | 说明 |
|---|---|---|
| Claude Opus 5.5 | claude-opus-5-5 |
Anthropic 接入点的默认推荐 |
| Claude Haiku 5.5 | claude-haiku-5-5 |
轻量备选,回复更快 |
| GPT 6.2 Sol | gpt-6.2-sol |
OpenAI 兼容接入点的默认推荐 |
| GPT 6.2 Astra | gpt-6.2-astra |
更高阶的备选 |
| GLM 5.3 | glm-5.3 |
国产主力,走 OpenAI 兼容接入点 |
Claude 系的模型只能填在 QCode Claude 这个 Anthropic 接入点里,GPT 和国产模型填在 QCode 这个 OpenAI 兼容接入点里。填错接入点,Test 会失败。完整模型清单见国产模型接入。
接入速览¶
| 项目 | 说明 |
|---|---|
| 插件 | Copilot for Obsidian 4.1.0(作者 Logan Yang,社区插件市场安装) |
| 协议与 Base URL | Anthropic:https://api.qcode.cc/api · OpenAI 兼容:https://api.qcode.cc/openai/v1 |
| 密钥 | 同一个 QCode 账号的 cr_ 密钥,两个接入点都能用 |
| 必开开关 | 「Enable CORS」(两个接入点都要打开) |
| 聊天入口 | 命令面板的「Copilot: Open Copilot Quick Chat window」 |
| 官方文档 | Obsidian 下载页 · Copilot 插件仓库 |
和 Copilot Chat 有什么区别¶
Copilot V4 有两条互不相通的路:
- Quick Chat(本篇):在右侧栏里对当前笔记提问,模型来自你在 BYOK 里接入的服务商,填个地址和密钥就能用。
- Copilot Chat(agent 模式):会调用 OpenCode、Claude Code、Codex 这类运行环境,需要单独安装或登录对应账号,配置重得多。
只是想让 AI 读笔记、答问题、改文字,用 Quick Chat 就够了;需要 AI 自己动手改多个文件、跑命令时,再去了解 agent 模式。
相关文档¶
- 接入点与 API 格式 — 各协议对应的地址与模型家族
- 国产模型接入 — OpenAI 兼容接入点可用的国产模型 ID
- 计费说明 — 用量怎么计算
- 故障排查 — 常见的连接与鉴权问题
开始使用 QCode
一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models