OpenCode 本地 AI 模型配置指南

主要配置项说明：

• data.directory：指定数据存储目录，默认是.opencode
• providers.local：启用本地模型支持
• agents：配置不同 AI 代理使用的模型及参数
  • model：模型标识符，本地模型以local.为前缀
  • maxTokens：模型生成的最大 token 数量
  • reasoningEffort：推理强度（low/medium/high）

自托管模型配置步骤

设置本地模型环境变量

配置本地模型需要设置 LOCAL_ENDPOINT 环境变量，指向本地模型服务的 API 端点：

# 临时设置（当前终端会话有效）
export LOCAL_ENDPOINT=http://localhost:1235/v1

# 永久设置（Linux/macOS）
echo 'export LOCAL_ENDPOINT=http://localhost:1235/v1' >> ~/.bashrc
source ~/.bashrc

配置文件修改

编辑全局配置文件：

nano ~/.opencode.json

添加或修改以下内容以配置本地模型：

{
  "providers": { "local": { "disabled": false } },
  "agents": {
    "coder": { "model": "local.granite-3.3-2b-instruct@q8_0", "maxTokens": 5000, "reasoningEffort": "high" }
  }
}

常用本地模型配置示例

OpenCode 支持多种本地模型，以下是一些常用模型的配置示例：

Granite 3.3 2B Instruct

{
  "model": "local.granite-3.3-2b-instruct@q8_0",
  "maxTokens": 4096,
  "reasoningEffort": "medium"
}

Llama 3.1 8B Instruct

{
  "model": "local.llama-3.1-8b-instruct",
  "maxTokens": 8192,
  "reasoningEffort": "high"
}

Mistral 7B Instruct

{
  "model": "local.mistral-7b-instruct-v0.2",
  "maxTokens": 4096,
  "reasoningEffort": "medium"
}

本地模型服务部署

推荐模型部署工具

部署本地模型需要使用适当的服务软件，以下是几种常用工具：

1. Ollama：简单易用的本地 LLM 管理工具，支持多种模型格式
2. LM Studio：提供图形界面的模型管理和部署工具
3. vLLM：高性能 LLM 服务库，支持 PagedAttention 技术
4. Text Generation Web UI：功能丰富的 Web 界面模型部署工具

以 Ollama 为例，部署本地模型的步骤：

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取并运行模型
ollama run granite3:2b

# 后台运行模型服务
ollama serve &

Ollama 默认会在 http://localhost:11434 提供 API 服务，我们需要将其与 OpenCode 连接：

export LOCAL_ENDPOINT=http://localhost:11434/v1

模型性能优化建议

为了获得更好的本地模型运行性能，可以考虑以下优化措施：

1. 模型量化：使用量化版本的模型（如 4-bit、8-bit 量化）减少内存占用
2. 硬件加速：
   • NVIDIA GPU：确保安装 CUDA 工具包
   • AMD GPU：使用 ROCm 框架
   • Apple Silicon：利用 Metal 加速
3. 内存管理：关闭不必要的应用程序，为模型运行释放内存
4. 模型选择：根据硬件条件选择合适大小的模型（如 2B、7B、13B 参数模型）

验证与测试

验证配置是否生效

使用以下命令检查 OpenCode 配置是否正确加载本地模型：

opencode -p "你正在使用什么 AI 模型？"

如果配置正确，模型应该会返回类似以下的响应：

我正在使用本地部署的 granite-3.3-2b-instruct 模型为您提供服务。

运行测试任务

测试本地模型的代码生成能力：

opencode -p "用 Go 语言写一个函数，计算斐波那契数列的第 n 项"

测试文件编辑能力（需要在交互模式下）：

opencode

在交互界面中输入："帮我修改当前目录下的 main.go 文件，添加错误处理"

常见问题解决

模型加载失败

问题表现：OpenCode 启动时报错，无法连接到本地模型服务。

解决方法：

1. 检查防火墙设置，确保端口未被阻止
2. 确认模型服务地址配置正确：

echo $LOCAL_ENDPOINT

3. 检查本地模型服务是否正在运行：

curl $LOCAL_ENDPOINT/health

性能不佳

问题表现：模型响应缓慢，生成文本卡顿。

解决方法：

1. 使用更小的模型或量化版本
2. 增加系统可用内存，关闭其他占用资源的应用
3. 降低模型推理强度：

"reasoningEffort": "low"

配置不生效

问题表现：修改配置后没有效果。

解决方法：

1. 检查配置文件路径是否正确
2. 重启 OpenCode 使配置生效
3. 验证 JSON 格式是否正确：

jq . ~/.opencode.json

高级配置与定制

多模型协作配置

OpenCode 支持为不同任务配置不同模型，实现多模型协作：

{
  "agents": {
    "coder": { "model": "local.llama-3.1-8b-instruct", "maxTokens": 4000 },
    "summarizer": { "model": "local.granite-3.3-2b-instruct", "maxTokens": 1000 },
    "title": { "model": "local.mistral-7b-instruct", "maxTokens": 80 }
  }
}

自定义模型集成

对于不在 OpenCode 默认支持列表中的模型，可以通过 MCP（Model Context Protocol）进行集成。配置 MCP 服务器：

{
  "mcpServers": {
    "custom-model": {
      "type": "stdio",
      "command": "/path/to/custom-model-server",
      "args": ["--port", "1236"]
    }
  }
}

总结与展望

通过本文介绍的步骤，你已经成功搭建了 OpenCode 自托管模型环境，实现了本地 AI 开发能力。这一配置不仅保护了数据隐私，还消除了 API 调用限制和相关费用，为长期开发提供了稳定高效的 AI 支持。

OpenCode 项目仍在持续发展中，未来将支持更多的自托管模型和高级功能。建议定期查看项目更新，保持系统最新状态。