OpenCode 本地模型配置指南
一、概述
本文档记录如何将本地 Ollama 模型配置到 OpenCode AI 助手，使其能够调用本地部署的 AI 模型进行对话。
1.1 预期目标
- OpenCode 可以使用本地 Ollama 模型进行对话
- 支持流式输出
- 支持思考过程显示（适用于支持该特性的模型）
1.2 环境信息
| 项目 | 说明 |
|---|---|
| 操作系统 | Linux (OpenEuler/CentOS) |
| Node.js | v22.16.0 |
| OpenCode 版本 | 1.2.16 |
| Ollama 版本 | 最新版 |
| 本地模型 | qwen3.5:2b |
二、配置步骤
2.1 前提条件
- Ollama 服务已安装并运行
- 本地模型已下载
- OpenCode 已安装
2.2 检查 Ollama 服务状态
# 检查 Ollama 服务是否运行
systemctl status ollama
# 查看已安装的模型
curl -s http://localhost:11434/api/tags
2.3 配置 OpenCode 认证
OpenCode 通过 ~/.local/share/opencode/auth.json 文件管理模型服务认证。
方法一：使用 opencode auth 命令
# 添加 Ollama 认证
opencode auth add ollama --api-key sk-local
方法二：手动创建认证文件
创建 ~/.local/share/opencode/auth.json：
{
"ollama": {
"type": "api",
"key": "sk-local"
}
}
2.4 验证模型可用性
# 查看 OpenCode 可用的模型列表
opencode models
输出应包含：
ollama/qwen3.5:2b
三、使用方法
3.1 指定模型运行
# 使用 -m 参数指定模型
opencode -m ollama/qwen3.5:2b "你好，请介绍一下自己"
3.2 在会话中切换模型
# 启动交互式会话并指定模型
opencode -m ollama/qwen3.5:2b
3.3 查看模型列表
# 查看所有可用模型（包括云端模型）
opencode models
四、配置参数说明
4.1 模型格式
OpenCode 使用 provider/model 格式指定模型：
| 格式 | 示例 | 说明 |
|---|---|---|
ollama/model-name |
ollama/qwen3.5:2b |
本地 Ollama 模型 |
openai/model-name |
openai/gpt-4o |
OpenAI 云端模型 |
anthropic/model-name |
anthropic/claude-3-5-sonnet |
Anthropic 云端模型 |
4.2 模型命名注意事项
- Ollama 模型名称中的冒号
:需要保留 - 例如：
qwen3.5:2b而不是qwen3.5-2b
五、验证与测试
5.1 测试模型响应
# 简单对话测试
opencode -m ollama/qwen3.5:2b "你好"
5.2 预期响应时间
| 模型大小 | CPU 推理预计时间 |
|---|---|
| 270M (gemma3:270m) | ~5-10 秒 |
| 1.5B (qwen2.5:1.5b) | ~3-5 分钟 |
| 2B (qwen3.5:2b) | ~1-3 分钟 |
注意：CPU 推理速度较慢，建议添加 GPU 以提升性能。
5.3 检查模型是否正常工作
观察模型回复内容是否正常，例如：
正常回复示例：
"你好！我是通义千问 Qwen3.5，由阿里巴巴集团开发的大型语言模型。我可以帮助你..."
异常情况： - 回复内容为 "Thinking Process: ..." 开头（可能是 thinking 内容泄露） - 请求超时无响应 - 返回错误信息
六、常见问题
Q1: 模型列表中看不到 ollama 模型
检查步骤：
1. 确认 Ollama 服务正在运行：systemctl status ollama
2. 确认 auth.json 配置正确
3. 重启 OpenCode 服务
Q2: 模型响应很慢
原因： CPU 推理速度有限
解决方案： - 使用更小的模型（如 qwen3:0.5b） - 添加 GPU 显卡 - 使用云端 API（如硅基流动）
Q3: 模型回复内容异常
可能原因： - 模型配置不正确 - Prompt 设置问题 - 模型本身质量问题
排查方法：
# 直接测试 Ollama API
curl -s http://localhost:11434/api/generate \
-d '{"model": "qwen3.5:2b", "prompt": "你好", "stream": false}'
Q4: 如何切换到其他模型
# 指定不同的模型
opencode -m ollama/qwen2.5-coder:1.5b "你的问题"
七、相关配置路径
| 文件 | 路径 | 说明 |
|---|---|---|
| OpenCode 认证 | /root/.config/opencode/opencode.json | 模型服务认证配置 |
| Ollama 配置 | /etc/systemd/system/ollama.service |
Ollama 服务配置 |
| 模型文件 | ~/.ollama/models/ |
本地模型存储目录 |
八、总结
将本地 Ollama 模型配置到 OpenCode 的核心步骤：
- ✅ 确保 Ollama 服务正常运行
- ✅ 下载所需的 AI 模型
- ✅ 配置 OpenCode 认证（auth.json）
- ✅ 使用
-m ollama/model-name参数调用模型
文档创建日期：2026-03-04 最后更新：2026-03-04