OpenCode 本地模型（Local Models）接入实战指南：用 Ollama 离线运行你的 AI 编程助手

引言

在 AI 编程助手的日常使用中，绝大多数人都会选择调用云端 API——无论是 Anthropic 的 Claude 还是 OpenAI 的 GPT 系列。云端模型确实强大，但随之而来的问题也不少：敏感代码上传到第三方服务器、网络不稳定导致响应中断、按 token 计费在长时间会话中成本飙升、还有那些需要完全隔离的开发环境根本不允许外网访问。

有没有一种方案，让 AI 编程助手完全跑在你的笔记本上？答案是肯定的。OpenCode 基于 AI SDK 和 Models.dev，官方支持 75+ 云端模型提供商，同时也完整支持本地模型（Local Models）。通过 Ollama、llama.cpp、LM Studio 等本地推理引擎，你可以在完全离线的环境下，让 OpenCode 调用本地开源模型完成代码补全、Bug 修复和重构。

本文将以 Ollama 为主线，手把手带你完成从安装、拉取模型到接入 OpenCode 的全流程，并对比 llama.cpp 与 LM Studio 等替代方案，最后分享本地模型的调优技巧和适用场景。

一、准备工作：安装 Ollama

Ollama 是目前最流行的本地大模型运行工具，支持 macOS、Linux 和 Windows，一行命令即可安装。

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

# Windows 用户直接下载安装包
# https://ollama.com/download

安装完成后，启动 Ollama 服务并验证是否正常运行：

ollama serve

打开另一个终端，确认服务已经监听在默认端口 11434：

curl http://localhost:11434/v1/models

如果返回包含模型列表的 JSON，说明 Ollama 服务已就绪。注意 OpenCode 通过 http://localhost:11434/v1 这个 OpenAI 兼容端点来访问 Ollama。

二、拉取一个编程专用模型

Ollama 官方仓库中有大量开源模型，但并非所有模型都适合编程和工具调用（Tool Calling）。建议优先选择专门针对代码训练的模型，例如 qwen3-coder、deepseek-coder 或 llama3.1 等。这里以 Qwen3-Coder 为例：

# 拉取模型
ollama pull qwen3-coder

# 查看本地已安装的模型
ollama list

# 快速测试模型能否正常对话
ollama run qwen3-coder "用 Python 写一个二分查找函数"

模型大小与参数量有关，例如 30B 参数模型通常需要 16GB 以上显存。如果硬件配置有限，可以选择更小的量化版本，比如 qwen3-coder:a3b（约 30 亿激活参数），普通 8GB 显存的笔记本也能流畅运行。

三、将 Ollama 接入 OpenCode

Ollama 提供了自动配置能力，只要本地 Ollama 服务在运行，OpenCode 通常会自动识别。如果自动配置没有生效，也可以通过 opencode.json 手动指定。

在项目根目录创建或编辑 opencode.json：

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

配置解读如下：

• ollama：自定义提供商 ID，可以随意命名，它会成为模型全名的前缀（provider_id/model_id）；
• npm：指定驱动包，这里使用 @ai-sdk/openai-compatible，所有兼容 OpenAI 协议的本地服务都能用；
• options.baseURL：本地推理服务的地址，Ollama 默认是 http://localhost:11434/v1；
• models：本地模型的映射表，key 必须与 ollama list 中显示的模型名一致。

配置完成后，在 OpenCode TUI 中执行 /models 命令，即可看到本地模型出现在列表中：

/models

选择 ollama/qwen3-coder，就能开始使用了。

四、把本地模型设为默认

如果希望每次启动 OpenCode 都自动使用本地模型，可以在配置中设置 model 键，格式为 provider_id/model_id：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen3-coder"
}

OpenCode 在启动时加载模型的优先级如下：

命令行参数 --model 或 -m（格式同为 provider_id/model_id）；

配置文件中的 model 键；

上次会话使用的模型；

内部优先级排序后的第一个模型。

# 也可以不修改配置，直接用命令行指定
opencode -m ollama/qwen3-coder

五、其他本地推理引擎

除了 Ollama，OpenCode 同样支持 llama.cpp 和 LM Studio 等方案，配置方式大同小异，核心都是指向各自的 OpenAI 兼容端点。

llama.cpp

llama.cpp 的 llama-server 默认监听 8080 端口：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama.cpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "qwen3-coder:a3b": {
          "name": "Qwen3-Coder: a3b (local)",
          "limit": {
            "context": 128000,
            "output": 65536
          }
        }
      }
    }
  }
}

这里额外使用了 limit 字段来声明模型的上下文长度与最大输出，防止 AI SDK 按照默认值裁剪上下文。

LM Studio

LM Studio 默认端口是 1234：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b (local)"
        }
      }
    }
  }
}

对比三种方案：Ollama 安装最简单、生态最完整，适合大多数用户；llama.cpp 性能优化极致、可控性最强，适合对底层有要求的进阶玩家；LM Studio 提供了图形化界面，下载模型和管理更方便，适合不习惯命令行的用户。

六、性能调优与常见问题

1. 工具调用失败怎么办？

这是本地模型最常见的坑。Agent 模式下 OpenCode 需要模型返回结构化的工具调用结果，而本地小模型往往默认上下文窗口太小，导致工具调用经常出错。官方文档给出的建议是增大 num_ctx：

# 将上下文窗口提高到 32K
ollama run qwen3-coder --num-ctx 32768

同时建议优先选择工具调用能力强的模型，如 Qwen-Coder 和 DeepSeek-Coder 系列，并尽量给模型留出充足的思考上下文。

2. 推理速度慢

本地模型的生成速度受显存带宽和模型大小的直接影响。如果速度无法忍受，可以：

• 换用更小的量化版本（如 q4_k_m 量化）；
• 使用 OLLAMA_NUM_PARALLEL 提升并发；
• 在 GPU 驱动支持时开启 OLLAMA_GPU_LAYERS 让更多层跑在显卡上。

3. 上下文不够用

大项目的代码量远超本地模型 16K/32K 的上下文。建议将大任务拆解为小任务，或使用 OpenCode 的 /agents 功能让子代理处理文件，再把结果汇总。

七、本地模型的适用场景

结合实践经验，本地模型最值得应用的场景包括：

• 敏感环境：涉及金融、政企、医疗等不能外发代码的场景，本地推理杜绝数据泄露；
• 离线开发：出差、机房、内网等没有稳定外网的环境；
• 高频低成本操作：格式化、批量重构、简单 CRUD 生成等简单任务用本地模型，复杂任务再切云端，成本最优；
• 私有化部署：企业内部统一搭建本地推理服务，为整个团队提供统一的 AI 能力。

总结

OpenCode 的本地模型支持让"离线 AI 编程"成为现实。通过 Ollama、llama.cpp 或 LM Studio，你可以用完全免费的开源模型构建一套不依赖外网的编程助手，兼顾代码安全与成本控制。接入过程并不复杂：安装推理引擎、拉取模型、在 opencode.json 中配置一个指向本地端点的 provider，再通过 /models 或 model 键完成模型选择。

当然也要清醒认识到，本地开源模型在复杂代码理解和多文件 Agent 任务上，与顶级云端模型仍有明显差距。最理性的做法是本地与云端混用：简单任务交给本地模型，复杂任务交给云端模型，用 OpenCode 一把梭搞定。毕竟，OpenCode 支持 75+ 提供商，模型切换不过是一个 /models 命令的事。