3步把Cotabby接入Ollama:本地OpenAI兼容AI端点配置完整指南

原创2026-10-14 11:50:451,991 阅读

3步把Cotabby接入Ollama:本地OpenAI兼容AI端点配置完整指南

Cotabby 是一款开源的 macOS 本地 AI 自动补全工具,能让几乎任何输入框都能获得 AI 灰色建议文字。除了内置的 Apple Intelligence 与开源模型引擎外,它还提供 Local Endpoint(OpenAI 兼容端点) 模式——只需 3 步,即可把 Cotabby 接入 Ollama,让你的 Mac 上自建的 AI 模型为全局文字补全提供支持,全程数据不出本机。

Cotabby DMG 安装窗口背景图:将 Cotabby 拖入 Applications 目录

为什么选择 Ollama 作为 Cotabby 的 AI 引擎

Cotabby 内置三种补全引擎,在 Settings → Engine 中切换:

引擎 说明
Apple Intelligence 使用 macOS 26+ 系统内置模型,无需下载
Open Source 下载 GGUF 模型(如 tabby-2-nano),完全在本机 llama.cpp 运行时推理
Local Endpoint 连接你自己管理的 OpenAI 兼容服务:本地 Ollama、局域网主机或公网 HTTPS 服务

选择 Ollama 的理由:

  • 🚀 模型自由:ollama pull 一行命令即可拉取 Qwen、Llama 等数千种模型,无需在 Cotabby 里下载特定 GGUF 文件
  • 🔒 隐私可控:端点可以是 127.0.0.1 回环地址,Cotabby 会识别为 loopback 并免隐私警告
  • ⚡ 冷启动预热:Cotabby 会针对 Ollama 默认端点调用其 /api/generate 接口提前加载模型(见 OpenAICompatibleAPIClient.swift),第一次补全不卡顿

接入后的实际效果——在邮件等文本框中输入时,灰色建议实时出现,按 Tab 逐词接受:

Cotabby 在邮件应用中实时给出灰色文字补全建议的演示

第 1 步:安装并启动 Ollama

在终端安装 Ollama(官方安装包或 Homebrew 均可),然后拉取一个适合补全的小模型:

ollama pull qwen3:0.6b

启动后 Ollama 默认监听 127.0.0.1:11434。验证服务可用:

ollama list

提示:Cotabby 对端点 URL 有安全校验——公网地址必须使用 HTTPS,http 仅限本机或局域网(见 OpenAICompatibleEndpointModels.swift)。

第 2 步:在 Cotabby 中打开 Local Endpoint 设置

  1. 打开 Cotabby 设置窗口,进入 Engine 面板
  2. 顶部的 Engine 下拉框选择 Local Endpoint
  3. 面板会展开 "Connection" 区域,包含 Server URL、API Key 与连接状态

该面板的实现位于 EngineAndModelPaneView.swift,端点连接控件在 EngineAndModelPaneView+Endpoint.swift。

第 3 步:填写 Server URL 并选择模型

Server URL:保持默认即可。Cotabby 内置的 Ollama 默认地址是:

http://127.0.0.1:11434/v1

如果地址没有路径部分,Cotabby 会自动补上 /v1;误改后可点 Use Ollama Default 一键还原。

API Key:可选的 bearer token,通过系统 Keychain 安全存储;Ollama 本地服务不需要填写。

点击连接按钮后,Cotabby 会请求 GET /v1/models 拉取模型列表,状态行显示为 Connected · N models。

Model:从下拉菜单选择刚拉取的模型(如 qwen3:0.6b),也可以手动输入模型标识符。

API Format:

  • Chat Completions(推荐):走 /v1/chat/completions,适合绝大多数 Ollama 聊天模型
  • Text Completions:走 /v1/completions,用于以原始 prompt 续写方式工作的 base 模型

两种 API 路由定义见 OpenAICompatibleEndpointModels.swift。

完成配置后,回到任意应用开始打字,Ollama 模型驱动的建议就会出现在光标旁。按 Tab 逐词接受、按 ` 一次接受全部、按 Esc 或继续输入即可忽略。

隐私说明:你的文字会发到哪

Cotabby 按端点主机范围给出明确的隐私分级(见 hostScope 实现):

端点类型 示例地址 隐私提示
loopback(回环) 127.0.0.1、localhost、::1 无警告,数据不出本机
localNetwork(局域网) 192.168.x.x、10.x.x.x、.local 域名 提示文字会发送到局域网服务器
publicInternet(公网) 任何公网 HTTPS 服务 提示文字将离开你的设备

也就是说,接入本机 Ollama 时补全请求只发往你自己的 Mac,符合 Cotabby 无遥测、无崩溃上报的隐私承诺。

常见问题排查

  • 连接失败 / Not connected:确认 Ollama 已启动(ollama list 能列出模型)、端口未被占用;再点一次连接按钮
  • 状态行显示 HTTP 错误码:客户端会把服务端状态透传为 The endpoint returned HTTP xxx(见 客户端错误定义),常见原因是模型名拼错
  • 提示 "Public endpoints must use HTTPS":说明 URL 被判定为公网 http,请改为本机地址或 HTTPS 地址
  • 首次补全较慢:Ollama 冷启动需要把模型加载进内存,Cotabby 的预热机制会在焦点场景自动触发,第二次起速度正常

延伸阅读

按 Tab 开始享受 Ollama 驱动的全局 AI 补全吧——从安装到出建议,整个过程不到 3 分钟。

登录后查看全文
cotabby