思源笔记(SiYuan)接入 QCode 图文教程(Windows 11 一步一图)
跟着 13 步、13 张截图,在 Windows 11 上装好思源笔记 v3.8.11,在内置「人工智能」里接入 QCode,配置 gpt-6.2-sol 并完成 AI 编写与智能体对话。
需要 API Key? 前往注册 →端点与 Base URL →
照着下面 13 步做,你会在 Windows 11 上装好思源笔记,并在内置的「人工智能」里接入 QCode,直接在笔记正文里用 AI 编写内容、在侧边栏和智能体多模型对话。
一句话答案:在思源笔记 v3.8.11 中点左上角主菜单 →「设置」→「人工智能」→「+ 添加提供商」→ 选「OpenAI」预设,把「API 基础地址」填为 https://api.qcode.cc/openai/v1、「API 类型」从默认的 Responses 改为 Chat Completions,粘贴 cr_ 开头的 QCode 密钥并配置 gpt-6.2-sol 即可使用内置「AI 编写」与「智能体」。
| 项 | 填写 |
|---|---|
| 配置入口 | 设置 → 人工智能 → API 提供商 → OpenAI |
| API 基础地址 | https://api.qcode.cc/openai/v1 |
| API 类型 | Chat Completions |
| API Key | cr_xxxxxxxx |
| 默认推荐模型 | gpt-6.2-sol |
核对于 2026-11-22 · SiYuan v3.8.11 · Windows 11
思源笔记(SiYuan)是一款本地优先的个人知识管理软件,支持块级引用、双链和大纲编辑。当前版本已原生内置「人工智能」与侧边栏「智能体」,本地使用无需安装第三方插件,也无需登录思源账号或 OpenAI 账号。
- 电脑是 Windows 10 / 11(64 位;ARM64 电脑需改选
win-arm64.exe安装包) - 已经注册 QCode.cc,并在控制台复制好
cr_开头的 API 密钥。还没有账号?先注册 QCode,在定价页选一个方案,再到控制台创建密钥。 - 电脑能正常访问
b3log.org(或github.com/ Microsoft Store)以及api.qcode.cc - 本地磁盘准备好一个普通文件夹作为工作空间(例如
C:\SiYuanWorkspace),不要选 OneDrive、iCloud 或坚果云等同步盘目录 - 本地笔记与内置 AI 无需登录思源账号,留出约 10 分钟按步骤操作即可
下载与安装¶
思源笔记在 Windows 上提供官方独立安装包与 Microsoft Store 两种安装方式。官方渠道如下:
- 官方下载页:b3log.org/siyuan/download.html(提供「x86_64 安装包」与「微软商店」两个直达入口)
- Microsoft Store:微软商店思源笔记页面(官方推荐桌面端使用,支持一键更新)
- GitHub Releases:siyuan-note/siyuan Releases(64 位电脑选
siyuan-3.8.11-win.exe,ARM64 电脑选siyuan-3.8.11-win-arm64.exe,文件名中的版本号会随更新变化;不要下载.apk、.dmg或linux安装包)
不同地区下载速度略有差异,先选你所在的地区:
- 优先打开官方下载页 b3log.org/siyuan/download.html,直接点击「x86_64 安装包」下载
siyuan-3.8.11-win.exe(约 230 MB,直连速度快)。 - 也可以在 Windows 自带的 Microsoft Store 搜索安装思源笔记,日后可直接一键升级。
- 安装包带有有效数字签名,默认「仅为我安装」,正常情况下无需管理员权限弹窗。
- 优先通过 Microsoft Store 安装,后续更新最省心。
- 如需离线安装程序,可从 GitHub Releases 或 官方下载页 下载
siyuan-3.8.11-win.exe(ARM64 电脑选siyuan-3.8.11-win-arm64.exe)。
跟着截图做:Windows 一步一图¶
下面 13 步每步只做一件事,截图里的橙色编号和正文里的 ①②③ 一一对应。
下载思源笔记安装包¶
用浏览器打开官方下载页 b3log.org/siyuan/download.html。点击页面正中 ① 指向的「x86_64 安装包(升级需要再次下载)」蓝色按钮,下载 Windows 64 位安装程序(如需自动更新,也可点右侧的「微软商店(支持一键升级)」)。

做对了你会看到:浏览器开始下载 siyuan-3.8.11-win.exe(约 230 MB),下载完成后可在「下载」文件夹里找到它。
运行安装向导并完成安装¶
双击刚下载好的 siyuan-3.8.11-win.exe 启动安装向导。先在许可证页点「我同意(I)」,接着在安装选项页保持默认的「仅为我安装」(不需要管理员权限)点「下一步(N) >」。进入「选定安装位置」页面后,确认 ① 处的目标文件夹路径无误,点击右下角 ② 指向的「安装(I)」;装完后保持勾选「运行 SiYuan(R)」点「完成(F)」。

做对了你会看到:安装进度条走完并出现「正在完成 SiYuan 安装向导」,点「完成(F)」后思源笔记自动启动。
卡住了?出现安全拦截提示或想修改安装位置
思源官方安装包带有有效数字签名,一般不会触发拦截。如果系统弹出「Windows 已保护你的电脑」,点击「更多信息」再点「仍要运行」即可。安装路径建议保持默认本地目录,不要装到 OneDrive 等同步盘里。
首次启动并选择本地工作空间¶
首次启动思源笔记会进入整页工作空间引导界面。点击 ① 指向的「工作空间」右侧「选择」按钮,在弹出的 Windows「选择文件夹」窗口里选一个纯本地目录(例如新建并选择 C:\SiYuanWorkspace),接着在同步盘安全提示弹窗里点「确定」即可初始化进入主界面。

做对了你会看到:初始化完成后进入思源主界面,左侧显示文档树,顶栏左上角显示刚刚选定的工作空间名称。首次进入时若弹出防火墙询问、右上角 Defender 排除提示或右下角「欢迎使用思源」浮窗,直接关闭或点「忽略」即可继续。
卡住了?为什么不能把工作空间放进 OneDrive 或坚果云?
思源笔记会在工作空间内高频读写本地数据库和索引,放在 OneDrive、iCloud、坚果云等第三方同步盘里容易引起文件锁冲突和数据损坏。请务必选择普通本地磁盘目录。如需切换界面语言,可在当前引导页的「外观语言」里修改,或稍后在「设置 → 外观 → 界面 → 语言」调整。
打开「设置」窗口¶
进入主界面后,点击顶栏左上角 ① 指向的主菜单(显示当前工作空间名称),在展开的下拉菜单里点击 ② 指向的「设置」(快捷键 Alt+P,也可以直接按键盘 Alt+P 打开)。思源笔记已原生内置 AI 配置,不需要去插件市场安装第三方 OpenAI 插件。

做对了你会看到:屏幕中央弹出「设置」窗口,左侧是一整列中文设置分类菜单。
点击「+ 添加提供商」¶
确认左侧已选中 ① 处的「人工智能」分类,然后点击右侧「API 提供商」区域右上角 ② 指向的「+ 添加提供商」按钮。

做对了你会看到:右侧切换为「API 提供商」预设卡片列表,上方标题为「官方服务商」。
选择「OpenAI」预设卡片¶
在「官方服务商」双栏卡片列表里,点击左上角 ① 指向的「OpenAI」卡片。注意选左侧标着 https://api.openai.com/v1 的「OpenAI」,不要误点右侧需要登录账号的「ChatGPT(ChatGPT 账户)」。

做对了你会看到:界面进入「添加提供商」详情表单,依次列出「自定义显示名称」「API 基础地址」「API 类型」「超时时间」和「API Key」。
填写 QCode 接口地址、API 类型与密钥¶
先把最上方的「自定义显示名称」从 OpenAI 改为 QCode(方便识别),再按图中编号依次填写三项关键参数:
- ①「API 基础地址」:清空默认内容,填入
https://api.qcode.cc/openai/v1(不要在末尾多写/chat/completions或斜杠); - ②「API 类型」:点开下拉框,务必把默认的
Responses改为Chat Completions; - ③「API Key」:粘贴你在 QCode 控制台复制的
cr_开头密钥(例如cr_xxxxxxxx,可点右侧小眼睛图标检查有没有多复制空格)。
「超时时间」保持默认 120 即可,不用改动。

做对了你会看到:「API 基础地址」显示 https://api.qcode.cc/openai/v1,「API 类型」显示 Chat Completions,「API Key」输入框里已填好掩码圆点。
刷新可用模型、测试连接并保存¶
不用离开当前窗口,向下滚动到「模型设置」区域:
- 点击 ① 指向的「刷新可用模型」,思源会从 QCode 拉取可用模型清单并自动添加一行模型配置;
- 在 ② 指向的「请输入或选择模型」输入框里填上推荐的
gpt-6.2-sol(如果想多配一个轻量国产模型,可以点旁边的「+ 添加模型」再新增一行填入deepseek-v4.1-flash); - 点模型行右侧的「测试连接」,看到右上角弹出「连接成功」提示后,点击右下角 ③ 指向的「确定」保存配置。

做对了你会看到:点击「测试连接」后右上角出现「连接成功」提示,点「确定」后返回「人工智能」设置页。
卡住了?点「刷新可用模型」失败或「测试连接」报错
按顺序核对三件事:1)「API 类型」是否已经改成 Chat Completions(默认 Responses 会失败);2)「API 基础地址」是否正好为 https://api.qcode.cc/openai/v1;3)密钥前后是否多了空格或引号。如果临时拉取模型列表失败,也可以直接点「+ 添加模型」手填 gpt-6.2-sol 再点「测试连接」。
确认提供商开关与默认模型¶
保存返回「人工智能」设置页后,核对三处状态:
- ① 处
QCode卡片右侧的「启用」开关已打开,卡片下方显示https://api.qcode.cc/openai/v1和已配置的模型数量; - ② 处「编辑器 → 默认模型」已选中
gpt-6.2-sol; - ③ 处「智能体 → 默认模型」也已选中
gpt-6.2-sol。
如果默认模型为空或你想换用其他已添加的模型,直接点下拉框切换即可。核对无误后按键盘 Esc 关闭设置窗口。

做对了你会看到:QCode 卡片开关亮起,「编辑器」和「智能体」两处的默认模型都显示 gpt-6.2-sol。
在编辑器里用「AI 编写」生成正文¶
回到任意一篇笔记,在空白行用键盘敲 / 呼出斜杠命令菜单,点选「AI 编写」。在弹出的提示框里输入你的需求(例如让它用两句话总结一段主题)并点「确定」。稍等几秒,笔记内联出现预览卡片:① 处标明当前由 gpt-6.2-sol 生成结果,点击右下角 ② 指向的「在原位置插入」就能把内容直接写入文档。

做对了你会看到:预览卡片里完整输出中文内容,点「在原位置插入」后内容立即写入当前段落。
卡住了?输入 / 没弹出菜单,或「AI 编写」不可用
斜杠菜单需要在英文输入法下用键盘直接敲击 / 触发,复制粘贴 / 不会弹出菜单。如果菜单里找不到「AI 编写」或提示未配置模型,回「设置 → 人工智能」确认 QCode 启用开关已打开且「编辑器 → 默认模型」不为空。
在右侧「智能体」里对话并切换模型¶
点击窗口最右侧停靠栏最上方 ① 指向的「智能体」图标,展开侧边栏对话面板。在底部输入框写一句测试消息并点发送(或按 Ctrl+Enter),稍等片刻就能看到 ② 处返回正常回复。如果前面添加了多个模型,点击输入框右下角 ③ 指向的模型名称按钮(如图从 gpt-6.2-sol 切到 deepseek-v4.1-flash),可以在不离开对话的情况下随时切换模型并继续提问(图中切换后发出测试指令立即收到 PONG)。

做对了你会看到:右侧「智能体」面板正常返回回复,且点击右下角模型按钮能够顺畅切换到其他已添加模型并继续收到回答。
在「设置 → 关于」查看版本号(可选)¶
如果后续排查问题或核对功能位置需要确认版本,打开左上角主菜单 →「设置」(或按 Alt+P),点左侧最底部的「关于」,就能在 ① 处看到当前的思源笔记版本号(图中为 当前版本 v3.8.11)。关闭并重新打开思源笔记后,刚才配好的 QCode 提供商与默认模型均会完整保留。

做对了你会看到:「关于」页面清晰显示当前版本号;重启思源后回到「设置 → 人工智能」,QCode 配置依然在列。
验证成功¶
四件事都确认正常,就说明思源笔记已经完整接通 QCode:
- 「设置 → 人工智能」里
QCode卡片开关已打开,显示https://api.qcode.cc/openai/v1和已添加的模型数量; - 「编辑器 → 默认模型」与「智能体 → 默认模型」均已选中
gpt-6.2-sol(或其他你需要的可用模型); - 在笔记正文敲
/→「AI 编写」能生成并插入内容,右侧「智能体」能正常回复且可切换模型; - 关闭并重启思源笔记后,
QCode提供商和默认模型配置依然保留。
全部完成¶
你已经在 Windows 11 上装好思源笔记并接通了 QCode。以后写笔记时随时可以敲 / 调用「AI 编写」,或在右侧「智能体」面板直接对话和切换模型。接下来可以:
常见报错¶
| 报错原文 | 原因 | 怎么办 |
|---|---|---|
Invalid API key |
密钥为空、被截断、前后带了空格或引号,或者填入了已失效的密钥 | 回到 QCode 控制台重新完整复制 cr_ 开头的密钥,清空「API Key」输入框后重新粘贴,再点「测试连接」验证 |
Invalid URL (POST /v1/chat/completions/chat/completions) |
把 /chat/completions 填进了「API 基础地址」,而思源会自动拼接聊天路径导致路径重复;或「API 类型」保留了默认的 Responses |
把「API 基础地址」改回 https://api.qcode.cc/openai/v1(不加 /chat/completions 或末尾斜杠),并将「API 类型」改为 Chat Completions |
请确认没有将工作空间设置在第三方同步盘路径下,否则会造成数据损坏……是否继续? |
首次选定工作空间目录时弹出的安全确认,防止误选 OneDrive、iCloud 或坚果云目录 | 确认所选目录为本地普通文件夹(如 C:\SiYuanWorkspace)后点击「确定」;若误选了同步盘,换回本地目录 |
Microsoft Defender 可能会误杀内核、误删数据和严重降低运行性能,建议将思源安装路径和工作空间路径添加到排除列表 |
首次进入主界面时右上角出现的系统提醒 | 点「忽略」即可继续配置 QCode,不影响接入;若日后出现内核被杀毒软件拦截,再按需将安装路径和工作空间加入排除列表 |
是否要允许公共网络和专用网络访问此应用? |
首次启动本地内核时触发的 Windows 安全中心防火墙提示 | 直接取消或关闭该窗口即可,不会影响本地内核运行与出站请求 QCode API |
常见问题¶
密钥到期后怎么办?¶
分两种情况:
- 个人套餐的密钥到期后不能续,只能重新开通、换一把新密钥;
- 按量包的密钥到期后再买一个包,同一把密钥会自动恢复。
如果更换了新密钥,打开「设置 → 人工智能」,点开 QCode 卡片把新的 cr_ 密钥填进「API Key」并点「确定」保存即可。
需要安装第三方 OpenAI 插件或登录思源账号吗?¶
都不需要。思源笔记 v3.8.11 已经原生内置「设置 → 人工智能 → API 提供商」与侧边栏「智能体」,本地工作空间和内置 AI 都可以免登录使用,不需要再去集市安装旧的 OpenAI 插件,也不需要 OpenAI 官方账号。
为什么必须把「API 类型」从 Responses 改成 Chat Completions?¶
思源笔记里「OpenAI」预设的默认「API 类型」是 Responses,但 QCode 的 OpenAI 兼容端点使用标准 Chat Completions 协议。如果不改,测试连接和对话请求都会失败;改为 Chat Completions 后即可正常拉取模型并对话。
如何在思源笔记里切换界面语言?¶
首次启动的工作空间引导页可以直接在「外观语言」里选择;进入主界面后,打开「设置 → 外观 → 界面 → 语言」即可随时在简体中文与其他语言之间切换。
可以同时在思源笔记里使用 Claude 模型吗?¶
可以,但不要把 Claude 模型填到 OpenAI 兼容端点里。QCode 的 OpenAI 兼容端点不接受 Claude 模型,需要单独添加一个提供商,将「API 类型」选为 Anthropic Messages、「API 基础地址」填为 https://api.qcode.cc/api,再填入同一把 cr_ 密钥与 claude-opus-5-5(详见下方进阶配置)。
接入速览¶
| 项目 | 说明 |
|---|---|
| 配置位置 | 顶栏左上角主菜单 →「设置」(Alt+P)→「人工智能」→「API 提供商」 |
| OpenAI 兼容端点(GPT / 国产) | https://api.qcode.cc/openai/v1(API 类型:Chat Completions) |
| Anthropic 端点(Claude) | https://api.qcode.cc/api(API 类型:Anthropic Messages) |
| API Key 格式 | cr_xxxxxxxx(同一把 QCode 密钥在双协议端点通用) |
| 默认模型设置位置 | 「设置 → 人工智能」下的「编辑器 → 默认模型」与「智能体 → 默认模型」 |
| 官方入口 | 官方下载页 · GitHub 仓库 |
进阶配置:使用 Claude 模型与其他接入点¶
单独配置 Claude(Anthropic 端点)¶
如果你希望在思源笔记里调用 Claude 系列模型,请回到「设置 → 人工智能 → API 提供商」再点一次「+ 添加提供商」,按下面参数填写:
| 字段 | 填写 |
|---|---|
| 自定义显示名称 | QCode Claude(可自定义) |
| API 基础地址 | https://api.qcode.cc/api |
| API 类型 | Anthropic Messages |
| API Key | cr_xxxxxxxx(同一把 QCode 密钥) |
| 推荐模型 | claude-opus-5-5(轻量备选 claude-haiku-5-5) |
其他接入点(可选)¶
如果遇到连接偏慢或超时,可以将「API 基础地址」中的域名切换为距离更近的接入点,三个接入点能力完全一致,同一把密钥通用:
| 节点 | OpenAI 兼容(GPT / 国产) | Anthropic(Claude) |
|---|---|---|
| 全球(默认) | https://api.qcode.cc/openai/v1 |
https://api.qcode.cc/api |
| 亚洲(中国大陆可选) | https://asia.qcode.cc/openai/v1 |
https://asia.qcode.cc/api |
| 北美 / 欧洲 | https://us.qcode.cc/openai/v1 |
https://us.qcode.cc/api |
推荐模型¶
| 模型名称 | 对应 API 类型与端点 | 适用场景 |
|---|---|---|
gpt-6.2-sol |
Chat Completions · https://api.qcode.cc/openai/v1 |
OpenAI 默认主力推荐,写作、总结与智能体对话均衡 |
gpt-6.2-astra |
Chat Completions · https://api.qcode.cc/openai/v1 |
OpenAI 最高阶备选,适合深度分析与复杂长文整理 |
claude-opus-5-5 |
Anthropic Messages · https://api.qcode.cc/api |
Anthropic / Claude 默认主力推荐,长文润色与结构化梳理 |
claude-haiku-5-5 |
Anthropic Messages · https://api.qcode.cc/api |
Anthropic / Claude 轻量备选,响应快 |
deepseek-v4.1-flash |
Chat Completions · https://api.qcode.cc/openai/v1 |
轻量国产备选,适合快速问答与日常笔记整理 |
更多国产模型 ID 可参考 国产模型接入;完整协议与路径对照见 接入点与 API 格式。
相关文档¶
- 接入点与 API 格式 — 双协议端点与路径真源对照
- 国产模型接入 — OpenAI 兼容端点可用的国产模型清单
- 计费说明 — 用量统计与计费规则
- 故障排查 — 常见连接与鉴权问题排查
- 思源笔记官方下载页
- 思源笔记 Microsoft Store 页面
开始使用 QCode
一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models
