介绍如何使用 OpenCode 搭建本地 AI 开发环境。通过配置自托管模型，用户可实现数据隐私保护、无 API 限制及离线使用。内容涵盖环境准备、配置文件详解、模型部署（如 Ollama）、性能优化及常见问题解决，帮助开发者在本地运行 Granite、Llama 等主流模型。
OpenCode 是一个基于 Go 语言开发的终端 AI 助手，支持多种 AI 模型提供商，包括 OpenAI、Anthropic Claude、Google Gemini 等。其核心优势在于能够集成自托管模型，允许用户在本地环境中运行 AI 模型，无需依赖外部 API 服务。
| 优势 | 详细说明 |
|---|---|
| 数据隐私保护 |
| 所有数据处理均在本地完成，避免敏感信息外泄 |
| 无 API 调用限制 | 不受第三方服务的请求频率、token 数量限制 |
| 降低成本 | 一次性硬件投入替代持续的 API 服务订阅费用 |
| 网络独立性 | 无需网络连接即可使用 AI 功能，适合离线开发 |
| 定制化能力 | 可根据需求调整模型参数，优化特定任务表现 |
OpenCode 的模块化架构设计使其能够灵活集成各种自托管模型。核心模块包括命令行界面、配置管理、数据库操作、LLM 集成和终端 UI 等。
在开始配置自托管模型前，请确保你的系统满足以下最低要求：
OpenCode 提供多种安装方式，推荐使用安装脚本或 Go 语言直接编译：
# 使用安装脚本（推荐）
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash
# 或使用 Go 语言编译安装
git clone https://github.com/opencode-ai/opencode
cd opencode
go build -o opencode
sudo mv opencode /usr/local/bin/
验证安装是否成功：
opencode --version
若安装成功，将显示当前 OpenCode 版本信息。
OpenCode 的配置系统采用 JSON 格式，支持全局配置和项目级配置。
OpenCode 会按以下顺序查找配置文件：
$HOME/.opencode.json 或 $XDG_CONFIG_HOME/opencode/.opencode.json.opencode.json以下是一个包含自托管模型配置的示例：
{
"data": {
"directory": ".opencode"
},
"providers": {
"local": {
"disabled": false
}
},
"agents": {
"coder": {
"model": "local.granite-3.3-2b-instruct@q8_0",
"maxTokens": 5000,
"reasoningEffort": "high"
},
"summarizer": {
"model": "local.llama-3.1-8b-instruct",
"maxTokens": 2000
}
},
"autoCompact": true
}
主要配置项说明：
data.directory：指定数据存储目录，默认是.opencodeproviders.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 支持多种本地模型，以下是一些常用模型的配置示例：
{
"model": "local.granite-3.3-2b-instruct@q8_0",
"maxTokens": 4096,
"reasoningEffort": "medium"
}
{
"model": "local.llama-3.1-8b-instruct",
"maxTokens": 8192,
"reasoningEffort": "high"
}
{
"model": "local.mistral-7b-instruct-v0.2",
"maxTokens": 4096,
"reasoningEffort": "medium"
}
部署本地模型需要使用适当的服务软件，以下是几种常用工具：
以 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
为了获得更好的本地模型运行性能，可以考虑以下优化措施：
使用以下命令检查 OpenCode 配置是否正确加载本地模型：
opencode -p "你正在使用什么 AI 模型？"
如果配置正确，模型应该会返回类似以下的响应：
我正在使用本地部署的 granite-3.3-2b-instruct 模型为您提供服务。
测试本地模型的代码生成能力：
opencode -p "用 Go 语言写一个函数，计算斐波那契数列的第 n 项"
测试文件编辑能力（需要在交互模式下）：
opencode
在交互界面中输入："帮我修改当前目录下的 main.go 文件，添加错误处理"
问题表现：OpenCode 启动时报错，无法连接到本地模型服务。
解决方法：
echo $LOCAL_ENDPOINT
curl $LOCAL_ENDPOINT/health
问题表现：模型响应缓慢，生成文本卡顿。
解决方法：
"reasoningEffort": "low"
问题表现：修改配置后没有效果。
解决方法：
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 项目仍在持续发展中，未来将支持更多的自托管模型和高级功能。建议定期查看项目更新，保持系统最新状态。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online