LowHow 文档中心

中文

English

中文

English

深色模式

OpenCode 连接本地大模型 ​

📚 分类: AI 开发工具配置 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode，一台可联网的电脑 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解“自托管模型”的概念和优势
  • [ ] 配置 OpenCode 连接本地运行的推理服务器（如 Ollama）
  • [ ] 在 .opencode.json 文件中为不同任务指定不同的本地模型
  • [ ] 掌握基本的性能调优和故障排除技巧

最终效果 ​

你将成功配置 OpenCode，让它不再依赖远程的 API（如 OpenAI），而是使用你本地电脑上运行的 AI 模型来执行代码编写、任务分析等操作。这意味着你的数据完全由你掌控，无需联网也能获得 AI 辅助。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
OpenCode最新稳定版opencode --version
网络可访问 localhost无需验证

1. 安装并运行一个本地推理服务器 ​

本教程以 Ollama 为例，因为它对新手最友好。你也可以选择 LM Studio、vLLM 等。

操作步骤：

  1. 访问 ollama.ai 并下载安装 Ollama。

  2. 打开终端，拉取一个模型。我们先用一个小模型测试：

    bash
    $ ollama pull qwen2.5-coder:7b-instruct-q4_K_M

    💡 提示：qwen2.5-coder:7b-instruct-q4_K_M 是一个针对代码场景优化的、经过量化（Q4）的 70亿参数模型，对内存要求不高。

  3. 启动 Ollama 服务（通常安装后会自动启动，如果没启动，在终端运行 ollama serve）。

✅ 验证：在浏览器中访问 http://localhost:11434，如果看到 Ollama 的响应页面（或没有任何错误），则说明服务已成功运行。

第 1 步：设置本地模型端点 ​

🎯 目标：告诉 OpenCode 你的本地模型服务在哪里。

📝 操作：

你需要设置一个名为 LOCAL_ENDPOINT 的环境变量。这个地址就是你的推理服务器提供的 API 地址。

bash
# 如果你使用 Ollama，端口通常是 11434
$ export LOCAL_ENDPOINT="http://localhost:11434/v1"

🤔 为什么要这样做？ OpenCode 通过这个环境变量来发现你的本地模型。它相当于一个“地址”，告诉 OpenCode：“嘿，我的 AI 模型在这里提供服务。”

✅ 验证：在终端输入以下命令，查看变量是否设置成功：

bash
$ echo $LOCAL_ENDPOINT
# 你应该看到输出：
http://localhost:11434/v1

⚠️ 注意：

  • 如果你使用 LM Studio，默认端口是 1234，请将命令中的 11434 改为 1234。
  • 如果你使用 vLLM，根据你启动服务时的 --port 参数来设置。

第 2 步：配置 OpenCode 的模型映射 ​

🎯 目标：在 OpenCode 的配置文件中，指定哪个“代理”（Agent）使用哪个本地模型。

📝 操作：

找到你的 OpenCode 配置文件 .opencode.json（通常在你的项目根目录或用户主目录下）。如果文件不存在，你需要创建一个。

将以下内容复制到你的 .opencode.json 文件中：

json
{
  "agents": {
    "coder": {
      // 将模型名称改为你下载的本地模型
      "model": "local.qwen2.5-coder:7b-instruct-q4_K_M",
      "maxTokens": 4096
    },
    "task": {
      // 分析任务也用同一个模型
      "model": "local.qwen2.5-coder:7b-instruct-q4_K_M",
      "maxTokens": 2048
    },
    "title": {
      // 为生成标题这类简单任务，使用一个更小的模型
      "model": "local.granite-3.3-2b-instruct@q8_0",
      "maxTokens": 80
    }
  }
}

💡 提示：

  • 模型名称格式为 local.<模型名称>，其中 <模型名称> 必须和你推理服务器中拉取的模型名称完全一致。
  • 要查看 Ollama 中已拉取的模型列表，可以在终端运行 ollama list。

✅ 验证： 确保你的 .opencode.json 文件格式正确（没有多余的逗号或引号）。JSON 格式错误是新手最容易犯的错误。

第 3 步：测试你的配置 ​

🎯 目标：运行一个简单的 OpenCode 命令，确认它能成功调用本地模型。

📝 操作：

打开一个新的终端窗口（确保 LOCAL_ENDPOINT 环境变量仍然有效），或在同一终端中，运行一个简单的 OpenCode 命令：

bash
# 让 OpenCode 解释一个命令
$ opencode --model local.qwen2.5-coder:7b-instruct-q4_K_M -- "在 Linux 中，如何查看当前目录下的所有文件？"

✅ 验证：

  • 如果配置成功，OpenCode 会连接到你本地的 Ollama 服务，并返回一个用中文写的、带代码示例的回答。
  • 你可能需要稍等片刻（取决于你的电脑配置和模型大小），等待模型加载。
  • 如果你看到 Connection refused 错误，请回到第 1 步检查 LOCAL_ENDPOINT 是否正确，并确认 Ollama 服务是否在运行。

进阶技巧（可选） ​

1. 为不同任务分配不同模型 ​

你可以为不同“代理”分配不同大小的模型，以平衡速度和性能。

  • coder 代理：处理最复杂的代码生成任务，使用大模型（如 llama3.3:70b）。
  • task 代理：分析任务，使用中等模型（如 qwen2.5-coder:7b）。
  • title 代理：生成标题，使用小模型（如 granite-3.3-2b），速度飞快。

2. 启用推理模式（如果模型支持） ​

某些模型（如 DeepSeek-R1）支持“推理”模式，可以花更多时间思考，得到更高质量的回答。

json
{
  "agents": {
    "coder": {
      "model": "local.deepseek-r1:70b",
      "maxTokens": 5000,
      // 启用高级推理
      "reasoningEffort": "high"
    }
  }
}

reasoningEffort 可选的值为 low、medium（默认）、high。

常见问题 (FAQ) ​

Q1: 报错 Connection refused 怎么办？A: 这通常意味着 OpenCode 找不到你的推理服务器。

  1. 确认服务器（如 Ollama）正在运行。
  2. 检查 LOCAL_ENDPOINT 环境变量是否设置正确，特别是端口号。
  3. 如果你在另一个终端设置了环境变量，新终端需要重新设置。

Q2: 报错 Model not found 怎么办？A: 这表示模型名称写错了。

  1. 运行 ollama list（或在你的推理服务器界面查看）获取准确的模型名称。
  2. 检查 .opencode.json 中 model 字段的 local. 后面的名称是否完全一致。

Q3: 模型响应非常慢怎么办？A: 模型越大，运行越慢。

  1. 使用量化版本（如 q4_K_M）的模型，可以大幅减少内存占用和加速推理。
  2. 为 title 等简单任务分配一个更小的模型（如 2B 或 7B 参数）。
  3. 确保你的电脑有足够的 RAM 或 VRAM（显存）。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 自托管概念：你可以运行自己的 AI 模型，完全掌控数据和隐私。
  2. 环境配置：通过设置 LOCAL_ENDPOINT 环境变量，将 OpenCode 连接到你的本地推理服务器。
  3. 模型映射：在 .opencode.json 配置文件中，为不同任务指定不同的本地模型。
  4. 故障排除：掌握了连接失败、模型未找到、运行缓慢等常见问题的解决方法。

© 2026 LowHow