Joplin AI Chat 完整配置指南：连接云端与本地模型，让笔记具备智能能力

Joplin AI Chat 完整配置指南连接云端与本地模型让笔记具备智能能力【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 将 AI 能力统一收敛在「一处配置、处处复用」的模型之上你只需在设置中选定一个 Chat Provider内置的 AI chat panel 与各类插件即可共享同一个模型来完成笔记摘要、改写与问答。本文基于 Joplin 仓库的官方文档与底层源码packages/lib/services/ai/展开完整讲解从开启开关、选择提供商、本地/远程网络边界到 Token 用量统计与插件 API 调用的全部细节读完后你可以在桌面端独立完成一套可运行、可验证、可监控的 AI 笔记工作流。AI 功能总览为什么需要集中式配置Joplin 的 AI 能力设计有一个关键原则模型只配置一次全体使用者内置面板和插件共享。也就是说你不需要为每个插件单独填写 API Key插件在调用 AI 时也无法自行指定提供商或模型——它们只能使用你在 Settings → AI 中配置好的那一个模型。从源码结构看这一设计由packages/lib/services/ai/目录下的模块承载AiService.tsAI 服务的核心单例负责校验开关、根据设置构建 Provider、执行聊天请求并记录 Token 用量providers/三种 Provider 的具体实现Joplin Cloud、OpenAI-compatible、Anthropicclassification.ts判断某个 Base URL 属于「私网」还是「远程」是远程访问开关的判定依据JoplinAi.ts暴露给插件的joplin.ai.chat()等 API 入口。需要说明的是AI 功能仅限桌面端应用。在设置元数据 builtInMetadata.ts 中所有 AI 相关设置项的appTypes均限定为AppType.Desktop。开启 AI 功能四步完成首轮配置AI 默认是关闭的设置项ai.enabled的默认值为false且storage: SettingStorage.File即持久化在配置文件而非数据库。开启步骤如下打开配置界面进入AI分区勾选Enable AI features启用 AI 功能选择Chat provider聊天提供商并填写其对应的配置项点击Test AI configuration测试 AI 配置验证连通性。在底层勾选开关与选择提供商对应的是 AiService.applyFirstEnableDefault() 中的一段一次性逻辑如果你正通过 Joplin Cloud 同步且从未手动选择过提供商Joplin 会自动把提供商切到joplin-cloud实现零配置接入随后它会写死ai.chat.providerType.configured true从此同步目标的变化不再影响 AI 提供商的选择。相关行为在 AiService.test.ts 中有完整的用例覆盖只有「首次启用 正在使用 Joplin Cloud 同步」这一组合才会改写提供商其余情况非 Cloud 同步、或已手动选过都不会被覆盖。选择 Chat Provider三种接入方式对比Provider是什么配置方式Joplin Cloud AI由 Joplin Cloud 托管的聊天模型对受支持套餐的 Joplin Cloud 用户开放零配置——直接复用你的同步凭据。首次启用 AI 且正使用 Joplin Cloud 同步时会自动被选中OpenAI-compatible任何兼容 OpenAI API 的服务OpenAI 官方、Ollama、LM Studio、OpenRouter、vLLM 等填写 Base URL如https://api.openai.com/v1或 Ollama 的http://localhost:11434/v1、API Key 与模型名称Anthropic直连 Anthropic 的 Claude 系列模型填写 API Key 与模型 ID如claude-3-5-sonnet-latest你可以随时在 Settings → AI 中更换提供商。设置项的底层定义与存储方式在 builtInMetadata.ts 中三个提供商共用一组设置项字段含义如下ai.chat.providerType提供商类型枚举值为joplin-cloud/openai-compatible/anthropic默认openai-compatible。当你选择joplin-cloud却未同步 Joplin Cloud 时设置界面会直接显示警告文案「Joplin Cloud AI requires Joplin Cloud sync」ai.chat.baseUrlOpenAI-compatible 专属字段仅在providerType openai-compatible时显示。官方描述给出的示例正是https://api.openai.com/v1与 Ollama 的http://localhost:11434/v1ai.chat.apiKey标记为secure且存储于数据库SettingStorage.Database仅对 OpenAI-compatible 与 Anthropic 显示选择 Joplin Cloud AI 时无需填写因为复用同步凭据ai.chat.model模型标识符示例为gpt-4o-mini或claude-3-5-sonnet-latest。Provider 的构建与缓存从 AiService.ts 可以看到getProvider()会依据providerType、baseUrl、apiKey、model四个值的组合生成一个缓存键只要这四个值不变就会复用缓存的 Provider 实例一旦任何一个值发生变化Provider 会立即重建这正是「Token 计数器随配置切换自动重置」的实现基础。私网还是远程「Allow remote providers」开关的边界判定为防止笔记内容被意外发送到云服务Joplin 保留了一个独立于主开关的第二重开关Allow remote AI providers允许远程 AI 提供商默认关闭ai.allowRemote默认false。无需开启开关即可使用的「私网」提供商关闭该开关时只有下列地址的 OpenAI-compatible 服务可以使用你的笔记不会离开自己的网络localhost、127.0.0.1或::1私网 LAN 地址10.x.x.x、172.16.x.x–172.31.x.x、192.168.x.x、169.254.x.x以及 IPv6 唯一本地地址fc00::/7/ 链路本地地址fe80::/10以.localhost、.internal或.home.arpa结尾的主机名。这覆盖了 Ollama、LM Studio 以及任何部署在自身网络内的 OpenAI-compatible 服务。由于这类服务通常没有认证私网提供商不强制要求 API Key——只有当你的服务端确实需要时才填写否则留空即可。必须打开开关的「远程」提供商Joplin Cloud AI、Anthropic、OpenAI 以及任何公网端点都属于远程提供商必须打开该开关否则 AI 调用会直接失败并给出明确错误。源码级的分类逻辑与边界特例这一「私网/远程」判定并非简单的字符串匹配而是实现在 classification.ts 的deriveClassification()中并通过 AiService.chat() 在每次调用前强制检查若provider.classification remote而ai.allowRemote未开启则抛出错误码为aiRemoteNotAllowed的异常。分类的判定基准是「请求是否会离开本机」。源码中值得注意的几个实现细节回环地址的规范化new URL()会先把各种花式写法归一化再交给isLoopbackHost()判断。例如0177.0.0.1八进制、2130706433十进制整数形式、127.1都会在到达判断逻辑前被解析为127.0.0.1因此被归为本地.local后缀被一律视为远程这一点与原文档的警告一致。.local经由 mDNS/Bonjour 解析在你加入的任何网络包括公共 Wi-Fi上都可能指向不可信的机器因此不算安全假设文档明确建议改用机器的 LAN IP废弃的 site-local 地址fec0::/7也被归为远程。上述全部边界情况都能在 AiService.test.ts 的参数化测试用例中找到一一对应localhost:11434/v1、127.1等为local而10.0.0.5、192.168.1.50、ollama.internal、[fd12:3456::1]、ollama.local、[fec0::1]以及010.0.0.5前导零被解析为八进制实为公网8.0.0.5均为remote。Token 用量统计看清每一分钱多数聊天提供商按 Token 计费。为帮助你掌控用量Joplin 会为当前配置的提供商累计记录输入与输出 Token 数并显示在 Settings → AI 中旁边配有Reset token usage重置 Token 用量按钮。实现上这一机制由 AiService.recordTokens() 完成每次聊天完成后Provider 通过setUsageRecorder()注册的回调把inputTokens与outputTokens累加写入数据库设置项ai.usage.inputTokens与ai.usage.outputTokens定义见 builtInMetadata.ts。设置界面上的按钮描述会实时显示「%s input / %s output tokens used」用量为 0 时则提示「No AI usage recorded yet」builtInMetadata.ts。当你更换提供商或端点时计数器会自动重置避免把不同服务的用量混在一起统计——这正是上文提到的 Provider 重建机制缓存键变化的副作用。对于 Joplin Cloud AIProvider 还会从服务端响应中读取joplin元数据degraded、tokens_used、tokens_budget并回传到界面状态JoplinCloud.ts让你能看到服务端的降级状态与预算消耗情况。测试配置端到端验证连通性Test AI configuration按钮会向当前激活的 Provider 发送一条单消息对话内容为 Reply with the single word OK.并把回复内联显示在按钮下方。这是最快的端到端验证方式——配置界面本身不会预先校验提供商参数只有真正调用模型时才会暴露问题。如果测试失败错误信息会直接显示在按钮下方。常见错误及对策Joplin Cloud AI requires Joplin Cloud sync——你选择了 Joplin Cloud AI但当前并未使用 Joplin Cloud 同步。请恢复 Joplin Cloud 同步或改选其他提供商。对应源码错误码aiJoplinCloudSyncRequiredJoplinCloud.tsRemote AI providers are not allowed——请打开Allow remote AI providers开关No choices in response — check that the base URL includes /v1——常见于本地 Ollama / LM Studio 服务Base URL 需要带上/v1后缀。为什么「/v1 后缀」如此关键第三个错误在源码中有非常细致的处理。在 OpenAiCompatible.doChat() 中请求实际发送到${baseUrl}/chat/completionsOpenAiCompatible.ts。许多本地服务在收到错误路径时会返回 200 空响应而非 404导致响应体缺少choices数组。Joplin 检测到「2xx 但无choices」时会抛出错误码为aiProviderBadResponse的异常并明确提示 Base URL 必须以/v1结尾针对 OpenAI、Ollama、LM Studio。此外OpenAiCompatible.ts 内置了三类自动重试逻辑以兼容不同模型的接口差异新模型o1/o3/gpt-5 等拒绝max_tokens、要求max_completion_tokens时自动改用新参数名重试一次推理模型默认启用reasoning_effort而拒绝工具调用时自动以reasoning_effort: none重试老模型拒绝response_format: json_schema时去掉该字段重试。同时部分 Provider如旧版 Ollama不返回usage字段代码会安全地按 0 处理而不是抛错OpenAiCompatible.ts。使用 AI 的插件joplin.ai.chat()接口任何插件都可以通过joplin.ai.chat()向模型提问。插件不能选择提供商或模型——两者均来自你的设置。这意味着一个针对 OpenAI 编写的插件无需任何修改就能在 Ollama 或 Joplin Cloud AI 上运行。插件 API 源码 展示了这一接口的形态const reply await joplin.ai.chat([ { role: system, content: You are a concise assistant. }, { role: user, content: Summarise this note: ... }, ]); console.log(reply.text);从源码注释可以确认该接口的完整行为契约返回对象结构稳定包含text属性未来可安全扩展如 Token 用量、结束原因等字段当 AI 功能未启用时抛出异常AI features are disabled错误码aiDisabled当激活的 Provider 为远程而用户未允许远程访问时抛出异常Remote AI access is not allowed错误码aiRemoteNotAllowedProvider 配置缺失如缺少 API Key 或模型名或返回 HTTP 错误时同样抛异常插件应捕获并向用户提示前往设置页处理。隐私提示如果某个插件使用了 AI你会在插件的描述中看到相关说明。插件在构造提示词时可以读取你的笔记内容因此沿用同样的规则如果使用的是远程提供商这些笔记内容会随请求发送给该提供商。禁用 AI一键总开关在 Settings → AI 中取消勾选Enable AI features即可。主开关关闭时来自任何插件或内置功能的 AI 调用都会失败——无论提供商设置如何、远程开关是否开启。这一保证在 AiService.chat() 中位于最前面ai.enabled为假时直接抛出aiDisabled错误且该行为有测试用例锁定AiService.test.ts。完整调用链小结将以上内容串联起来一次 AI 请求在 Joplin 桌面端的完整路径是内置聊天面板或插件调用joplin.ai.chat()/AiService.chat()AiService校验ai.enabled未开启 →aiDisabled根据当前设置构建或复用缓存的Provider 实例校验 Provider 分类远程且未开ai.allowRemote→aiRemoteNotAllowedProvider 将消息转换为对应协议格式并发送OpenAI-compatible 走/chat/completionsJoplin Cloud 走同步服务端的api/ai/chat/completions解析响应含工具调用、自动重试、错误归一化记录 Token 用量到ai.usage.*结果回传调用方面板应用编辑、插件得到text文本。如果想进一步了解内置聊天面板如何对笔记提问、请求改写、选区工作流或语义搜索能力可继续阅读 AI chat panel 与 Semantic searchAI 相关的 MCPModel Context Protocol接入见 ai_mcp.md。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考