连接 Ollama（本地模型）

Ollama 让你可以在自己电脑上运行本地模型：数据完全不出本机，适合处理敏感信息和高保密项目。不需要 API Key、可以离线。

学完你能做什么

不吹牛，只写「立刻能干」的事

在完全离线、数据不出本机的环境使用 OpenCode 处理敏感数据
安装并验证 Ollama 是否正常工作
根据你的硬件挑一个合适的本地模型并下载
在 OpenCode 里配置并使用 Ollama 本地模型，完成第一次对话

你现在的困境

如果你正在经历这些，这课就是给你的

桌面上有很多敏感文件（财务数据、客户信息、个人隐私等），不想上传给第三方大模型
正在开发高保密等级的项目，代码和文档绝对不能离开公司电脑
对数据隐私有严格要求，即使大模型承诺不保存，也不想让任何数据出本机
网络环境受限，需要离线使用 AI 助手
输入 /connect 想找本地 Ollama，却只看到 Ollama Cloud，不知道下一步怎么做

什么时候用这一招

本地模型的核心价值：隐私第一

当你需要：
- 处理敏感数据（财务报表、客户资料、个人隐私）
- 开发保密项目（商业机密、专利代码、安全系统）
- 保证数据不出本机（零信任原则、合规要求）
而且不想：
- 把桌面文件、Excel 内容上传给第三方
- 让项目代码离开你的电脑
- 依赖网络连接才能使用 AI

💡 本地模型 vs 云端模型

场景	本地模型（Ollama）	云端模型
处理敏感 Excel 数据	✅ 数据不出本机	❌ 需要上传
开发保密项目	✅ 代码在本地处理	❌ 需要上传
日常开发任务	⚠️ 能力较弱	✅ 能力强
完全离线使用	✅ 支持	❌ 需要联网

🎒 开始前的准备

确保你已经完成以下事项，否则请先停下

[ ] 完成了 1.2 安装，能运行 opencode --version
[ ] 你的硬盘至少有 10GB 可用空间（模型文件会很快变大）
[ ] 你大概知道自己机器的内存/显存规模（不知道也没关系，下面会按经验推荐）

核心思路

先讲「怎么想」，不讲命令

本地模型的核心优势：隐私和保密
- 所有数据都在本机处理，没有任何内容发送到第三方服务器
- 适合：财务数据、客户资料、个人隐私、商业机密、专利代码等
/connect 只用来保存 API key（所以你会看到 Ollama Cloud）；本地 Ollama 不需要 key，需要用 opencode.json 配置 provider 才能在 /models 里选到
本地跑模型主要看 内存/显存：模型越大越吃资源
新手不要一上来就追 70B：先用 7B/8B 把流程跑通，再升级
选模型时同时看：
- 参数规模（B）：越大一般越强
- 用途：写代码优先选 *-coder，通用对话选 llama/qwen/gemma

跟我做

一步一步来，假设你会犯错

第 1 步：安装 Ollama

为什么
你需要一个本地模型运行时，它会在本机启动服务，OpenCode 才能连上。

macOSLinuxWindows

bash

brew install ollama

bash

curl -fsSL https://ollama.com/install.sh | sh

powershell

# 从官网下载安装包
# https://ollama.com/download

验证安装：

bash

ollama --version

你应该看到：版本号输出（例如 ollama version x.y.z）。

第 2 步：选一个适合你硬件的模型并下载

为什么
模型选太大，常见结果就是：下载很久、跑起来很慢、甚至直接内存/显存不够。

先记住一个选型规则（经验值，对新手够用）：

3B~8B：入门/轻量，16GB 内存的电脑也能跑
14B：明显更强，通常需要 16GB 显存或 32GB 以上内存才更舒服
27B~32B：高质量本地助手，建议 24GB~32GB 显存或 48GB 以上内存
70B/72B：本地“天花板”级别，通常需要 48GB+ 显存（或多卡/CPU 混合 offload，速度会明显下降）

下载大小 ≠ 运行占用

Ollama 模型页面显示的 GB 是“下载文件大小”。运行时还会额外占用 KV cache（上下文越长越吃内存/显存）。

建议至少预留 1.2~1.5 倍“下载大小”的可用内存/显存作为余量。

热门模型推荐（按用途）：

通用对话（轻量）：llama3.2:3b（约 2.0GB 下载）
通用对话（更强）：llama3.1:8b（约 4.9GB 下载）
中文/通用能力：qwen2.5:7b（约 4.7GB 下载）、qwen2.5:14b（约 9.0GB 下载）
编程优先：qwen2.5-coder:7b（约 4.7GB 下载）、qwen2.5-coder:14b（约 9.0GB 下载）、qwen2.5-coder:32b（约 20GB 下载）
其他常用：gemma2:9b（约 5.4GB 下载）、mistral:7b（约 4.4GB 下载）

按硬件直接选（经验推荐）：

你的硬件	推荐参数规模	推荐模型（举例）
MacBook（Apple Silicon）16GB 统一内存（例如 M4 16GB）	3B~8B	`llama3.2:3b` / `llama3.1:8b` / `qwen2.5-coder:7b`
独显 16GB 显存（例如 16GB VRAM 的 NVIDIA/AMD）	7B~14B	`qwen2.5-coder:14b` / `qwen2.5:14b` / `gemma2:9b`
独显 24GB 显存	14B~32B	`qwen2.5-coder:32b` / `qwen2.5:32b` / `gemma2:27b`
独显 32GB 显存（以 RTX 5090 32GB 为例）	32B	`qwen2.5-coder:32b` / `qwen2.5:32b`
独显 48GB+ 显存	70B/72B	`llama3.1:70b` / `qwen2.5:72b`

关于“5090 能跑多少 B”

关键不是型号，而是你的 显存大小。

如果你的 5090 是 24GB~32GB 显存，一般更适合优先跑 32B 这一档；70B/72B 往往需要 48GB+ 显存，或者用 CPU 混合 offload（能跑但会慢）。

开始下载（任选其一，建议先跑通流程）：

bash

# 编程优先（推荐）
ollama pull qwen2.5-coder:7b

# 通用对话
ollama pull llama3.1:8b

# 更轻量
ollama pull llama3.2:3b

你应该看到：类似 pulling manifest ... success 的下载过程与成功提示。

第 3 步：启动 Ollama 服务

为什么
OpenCode 需要通过本地 HTTP 服务和 Ollama 通信。

在终端运行：

bash

ollama serve

你应该看到：出现 Listening on 127.0.0.1:11434（保持这个终端窗口开着）。

第 4 步：在 OpenCode 配置“本地 Ollama 提供商”（可复制）

为什么
你在 /connect 里只看到 Ollama Cloud 是正常的：/connect 只负责保存 API key（写到 ~/.local/share/opencode/auth.json）。

本地 Ollama 不需要 key，所以正确做法是：在 opencode.json 里配置一个 provider，把 Ollama 的 OpenAI 兼容地址填进去。

把配置写到哪里？（推荐二选一）

全局：~/.config/opencode/opencode.json（所有项目通用）
项目级：把 opencode.json 放到当前项目根目录（只对这个项目生效）

如果你不确定 OpenCode 到底在读哪个路径，可以运行：

bash

opencode debug paths

可直接复制的配置（本地 Ollama）：

json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:7b": { "name": "Qwen2.5 Coder 7B (local)" },
        "llama3.1:8b": { "name": "Llama 3.1 8B (local)" },
        "llama3.2:3b": { "name": "Llama 3.2 3B (local)" }
      }
    }
  }
}

两个容易忽略的点

models 里的 key（例如 qwen2.5-coder:7b）建议和你 ollama pull 的模型名一致。
这个配置只是在 OpenCode 里“声明可选模型列表”，并不会帮你下载模型；下载仍然要靠 ollama pull ...。

你应该看到：保存完配置后，重启 OpenCode，/models 里会出现 Ollama (local) 下的模型（下一步验证）。

第 5 步：重启 OpenCode，选择本地模型并发送第一句话

为什么
OpenCode 需要在启动时读取 opencode.json；你改完配置后通常要重启一次才能生效。

新开终端：

bash

opencode

输入：

/models

选择你刚刚下载并写进配置的模型，然后发送：

你好，请介绍一下你自己

你应该看到：模型开始输出回复（本地模型可能会比云端慢一点）。

为什么要用本地模型？

本地模型 vs 云端模型：选对场景很重要

本地模型的两大核心价值

1. 隐私保护：数据完全不出本机

使用本地模型时，你的所有数据（包括文件内容、代码、对话历史）都在你自己的电脑上处理，不会发送到任何第三方服务器。

典型使用场景：

处理敏感的 Excel 数据（财务报表、客户资料、工资单等）
分析桌面文件和文件夹（包含个人隐私或商业机密）
整理个人文档（身份证号、银行信息、健康记录等）

⚠️ 为什么这点很重要

即使大模型服务商承诺"不保存你的数据"，但数据确实传输到了他们的服务器。对于严格合规要求（如金融、医疗、政府）的场景，这可能违反规定。

2. 项目保密：代码绝不离开本机

开发高保密等级项目时，使用本地模型可以确保代码和文档永远在你的电脑上处理。

典型使用场景：

开发商业机密项目（未公开的产品、专利技术）
安全相关开发（安全工具、加密系统、防护系统）
客户委托项目（签署了保密协议，代码不能外传）
企业内部项目（源代码包含内部机密）

💡 什么时候必须用本地模型

如果任何一条符合，强烈建议使用本地模型：

✅ 项目有保密协议或合规要求
✅ 代码涉及专利技术或商业机密
✅ 数据涉及个人隐私（身份证、银行卡、医疗记录）
✅ 数据属于客户或合作伙伴（需要保密）
✅ 公司安全政策禁止数据上传外部服务

本地模型的局限性

本地模型虽然隐私好，但也有局限性：

方面	本地模型	云端模型
隐私安全	⭐⭐⭐⭐⭐ 数据不出本机	⭐⭐ 数据需要上传
模型能力	⭐⭐⭐ 相对较弱	⭐⭐⭐⭐⭐ 能力更强
响应速度	⭐⭐ 取决于硬件	⭐⭐⭐⭐⭐ 更快
使用成本	⭐⭐⭐⭐⭐ 免费（需要硬件）	⭐⭐ 需要付费
网络要求	⭐⭐⭐⭐⭐ 可离线	⭐ 需要联网

💡 推荐使用策略

对于大多数用户：

敏感数据、保密项目 → 本地模型
日常开发、非敏感任务 → 云端模型（能力更强）

混合使用策略：

先用本地模型处理敏感部分
再用云端模型处理非敏感部分（如果需要）

检查点 ✅

全部通过才能继续；任一项失败，回到对应步骤重来

[ ] ollama --version 能输出版本号
[ ] ollama serve 能监听在 127.0.0.1:11434
[ ] opencode.json 已配置 baseURL: http://localhost:11434/v1
[ ] OpenCode 里 /models 能看到 Ollama (local) 和你配置的模型
[ ] 发送一句话能收到回复

踩坑提醒

80% 的人会卡在这里

现象	原因	解决
`/connect` 里只有 Ollama Cloud	`/connect` 只用来保存 API key	按第 4 步配置 `opencode.json`，然后用 `/models` 选择本地模型
`/models` 里看不到 `Ollama (local)`	配置文件位置不对 / JSON 写错 / 没重启 OpenCode	运行 `opencode debug paths` 找到 config 目录；检查 JSON；重启 OpenCode
`connection refused`	Ollama 服务没启动	先运行 `ollama serve`，再回到 OpenCode `/models`
下载很慢	网络问题或镜像源慢	换个时间段重试；先下小模型（3B/7B）
一跑就卡死/报内存不足	模型太大	换小一档（例如 14B → 7B/8B；32B → 14B）
回复特别慢	在跑 CPU/资源不足/首次加载	先关掉占用大的应用；再试更小模型；首次加载慢是正常的
端口被占用	已有 `ollama serve` 在运行	不要重复启动；保留一个服务进程即可

Ollama 的注意事项

每次用 OpenCode 前，要先启动 ollama serve
本地模型能力不如 Claude、DeepSeek，复杂任务可能做不好
如果电脑发热、风扇狂转，是正常的

本课小结

你学会了：

理解本地模型的核心价值：隐私保护和项目保密
安装并验证 Ollama
根据硬件选择合适的本地模型并下载
用 opencode.json 配置并使用 Ollama 本地模型完成第一次对话

下一课预告

你已经跑通本地模型路线了。接下来进入第一阶段的最后一课：自动更新。

快速预览

OpenCode 默认会自动更新，通常不用管它。想知道更多？→ 1.5 自动更新

遇到问题？

本地模型加载慢？加入社群，和 500+ 同路人一起交流，实时答疑。

连接 Ollama（本地模型） ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

跟我做 ​

第 1 步：安装 Ollama ​

第 2 步：选一个适合你硬件的模型并下载 ​

第 3 步：启动 Ollama 服务 ​

第 4 步：在 OpenCode 配置“本地 Ollama 提供商”（可复制） ​

第 5 步：重启 OpenCode，选择本地模型并发送第一句话 ​

为什么要用本地模型？ ​

本地模型的两大核心价值 ​

本地模型的局限性 ​

检查点 ✅ ​

踩坑提醒 ​

本课小结 ​

下一课预告 ​

连接 Ollama（本地模型）

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

跟我做

第 1 步：安装 Ollama

第 2 步：选一个适合你硬件的模型并下载

第 3 步：启动 Ollama 服务

第 4 步：在 OpenCode 配置“本地 Ollama 提供商”（可复制）

第 5 步：重启 OpenCode，选择本地模型并发送第一句话

为什么要用本地模型？

本地模型的两大核心价值

本地模型的局限性

检查点 ✅

踩坑提醒

本课小结

下一课预告