3步把Cotabby接入Ollama:本地OpenAI兼容AI端点配置完整指南
3步把Cotabby接入Ollama:本地OpenAI兼容AI端点配置完整指南
Cotabby 是一款开源的 macOS 本地 AI 自动补全工具,能让几乎任何输入框都能获得 AI 灰色建议文字。除了内置的 Apple Intelligence 与开源模型引擎外,它还提供 Local Endpoint(OpenAI 兼容端点) 模式——只需 3 步,即可把 Cotabby 接入 Ollama,让你的 Mac 上自建的 AI 模型为全局文字补全提供支持,全程数据不出本机。
为什么选择 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 逐词接受:
第 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 设置
- 打开 Cotabby 设置窗口,进入 Engine 面板
- 顶部的 Engine 下拉框选择 Local Endpoint
- 面板会展开 "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 的预热机制会在焦点场景自动触发,第二次起速度正常
延伸阅读
- 引擎与端点的整体设计:ARCHITECTURE.md
- 隐私与引擎说明:FAQ.md
- 补全请求管线:OpenAICompatibleSuggestionEngine.swift
按 Tab 开始享受 Ollama 驱动的全局 AI 补全吧——从安装到出建议,整个过程不到 3 分钟。

