OpenCode Ollama 配置教程：接入本地模型前先做 7 个检查

快速结论：先用 launch 验证，再用配置沉淀

第一次测试时，官方的 `ollama launch opencode` 是更稳的入口。它减少了手写 provider 字段的错误，让你先确认机器性能、模型选择和终端工作流是否真的可用。

长期使用时，建议保留一份清晰的 `opencode.json` 示例或团队说明。配置文件能让 base URL、模型名、权限习惯和故障排查路径变得可审查，也方便比较不同机器为什么一个可用、另一个不可用。

因此不要把两种方式看成互斥。先用 launch 证明链路，再把值得保留的模型和参数写成可复现配置。

Ollama 接入方式选择表

选择方式要看任务，而不是看偏好。个人笔记本验证重视速度；团队交付重视可复现、可审查和可回滚。

本站已有 OpenCode 部署、OpenCode vs Claude Code 和 session storage 页面；本页只覆盖 OpenCode Ollama 接入，避免和已有页面抢同一个搜索意图。

连接 OpenCode 前先检查 Ollama

先单独测试 Ollama。安装后拉取一个适合编程的模型，并在终端里直接提问。如果模型在简单对话里都加载失败、速度过慢或内存不足，OpenCode 进入仓库后只会暴露更多问题。

第一次验证请选择小仓库。理想测试包含 Git 历史、README、一个文档改动或小 bug、一个无害命令。不要从生产迁移脚本、密钥文件或客户数据开始。

本地模型不是免费午餐。它减少云端费用和数据外发，但会消耗内存、显存和等待时间。小模型适合解释和轻量任务，大型编码任务可能仍需要更强模型。

可靠 OpenCode Ollama 工作流的 7 个检查点

这 7 步的目的不是证明本地模型永远更好，而是定位链路：Ollama 服务、模型加载、OpenCode provider、仓库上下文、编辑质量和命令审批。

1. 确认服务 先让 Ollama 本身能直接响应。
2. 拉取模型 选择适合编程且符合硬件预算的模型。
3. 选择方式 首次用 launch，复用时沉淀配置。
4. 确认模型可见 在 OpenCode 中确认 Ollama 模型能被选择。
5. 先做只读任务 让 OpenCode 总结一个小文件。
6. 再做低风险编辑 改文档或测试，并检查 Git diff。
7. 记录故障 保存模型名、端口、系统、shell 和修复步骤。

opencode.json 的 Ollama 配置形状

具体字段可能随版本变化，正式采用前应查看官方文档。稳定思路是：OpenCode 通过 OpenAI-compatible endpoint 把 Ollama 当作本地 provider，常见地址是 `http://localhost:11434/v1`。

不要把密钥写进配置。Ollama 本地端点通常不需要云 provider key，但同一个仓库可能还配置其他云模型，示例配置不要和真实 token 混在一起。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      }
    }
  }
}

排错：先定位是哪一层失败

如果 OpenCode 看不到模型，先确认 Ollama 能直接运行该模型，再检查本地服务、base URL 路径和模型名。一次改三个设置通常只会让故障更难复现。

如果模型能回答但改代码质量差，问题未必是安装。可以缩小任务范围、换更强模型，或把本地模型用于解释，把困难编辑交给云模型。

如果连接远程 Ollama，把它当成基础设施处理：检查网络、端口、防火墙、鉴权和是否暴露到可信网络之外。

什么时候不该把 Ollama 设为默认 provider

不要因为本地就默认更好。如果仓库很大、上下文不够、硬件过慢，本地模型可能不适合作为主力编辑模型。

团队没人维护时也不要强推本地方案。需要有人负责模型选择、硬件说明、更新节奏和排错路径，否则每个人都会形成不同配置。

更稳的做法通常是组合：困难编辑使用稳定云模型，低风险解释和隐私实验使用 Ollama，并写清楚何时使用哪一种。