OpenCode是GitHub热门开源AI编程终端工具，支持75种以上大模型服务商，但大量开发者使用云端API时存在代码数据上传、网络受限、调用成本高等痛点。借助Ollama本地模型运行框架，可实现完全离线、零API密钥、数据不出本机的AI编码环境，适配涉密代码、内网开发场景。整套部署流程仅需15分钟，支持Qwen、Llama、CodeLlama等各类开源编码模型，本文分系统安装、模型拉取、OpenCode三种接入方式、进阶调优、排错全流程完整讲解。
一、Ollama本地模型部署前置与分系统安装
Ollama将各类开源模型封装为标准OpenAI兼容HTTP接口，本机运行推理，所有对话、文件读写数据仅保存在本地磁盘，无外网传输风险。
阿里云部署AI Agent：OpenClaw/Hermes Agent全网最简单，只需两步，详情👉访问阿里云OpenClaw/Hermes一键部署专题页面了解。
Token Plan Token最便宜/支持多模型切换：👉访问订阅阿里云百炼Token Plan AI大模型服务 。支持多模型切换，用于多模态模型灵活调用，实现多模型、多工具、多场景下的额度共享与统一管理，兼顾灵活性、稳定性与安全性，大幅降低企业使用大模型的门槛与成本。
系统安装命令
1 macOS（Homebrew）
brew install ollama
2 Linux通用一键脚本
curl -fsSL https://ollama.com/install.sh | sh
3 Windows
下载官方安装包双击安装，推荐搭配WSL2 Linux子系统，规避终端路径、权限兼容报错。
安装验证
终端执行ollama --version，输出版本号即安装成功。安装完成后Ollama后台常驻进程，默认监听http://localhost:11434。
拉取适配编码模型
OpenCode对上下文窗口硬性要求最低64k，挑选模型时必须满足长上下文规格：
1 通义千问编码：ollama pull qwen3.5（128k上下文，通用编码首选）
2 Llama3.2通用：ollama pull llama3.2
3 专用代码模型：ollama pull codellama:7b-code
查看本地已下载模型清单：ollama list
手动启动/校验服务
后台常驻失效时手动启动服务：ollama serve
健康检测接口，确认网关正常：
curl http://localhost:11434/api/tags
返回本地模型JSON列表代表服务正常。默认端口11434，若被占用可启动时指定偏移端口ollama --port 11534。
二、OpenCode安装三种方式（依赖Node.js 18+）
方式1 npm全局安装（推荐）
npm install -g opencode-ai
校验：opencode --version
方式2 一键安装脚本
curl -fsSL https://opencode.ai/install | bash
方式3 macOS Homebrew
brew install sst/tap/opencode
三、OpenCode对接Ollama三种配置方案
方案一：手动编辑配置文件（可控，适合长期使用）
OpenCode分两级配置：全局用户配置、项目独立配置，优先修改全局文件，所有项目共用本地模型。
1 创建全局配置目录
mkdir -p ~/.config/opencode
2 编辑~/.config/opencode/opencode.json完整内容
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "本地Ollama模型",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3.5": {
"name": "qwen3.5"},
"codellama:7b": {
"name": "codellama:7b"}
}
}
}
baseURL末尾必须携带/v1，是OpenAI兼容接口标准路径。保存后重启OpenCode，输入/models可读取本地模型列表。
方案二：自动发现插件（无需手动写模型清单）
安装Ollama自动识别插件，无需在配置内逐条罗列模型，启动后自动扫描本地拉取的全部模型：
npm install -g opencode-local-ollama
修改配置文件增加plugin字段：
"plugin": ["opencode-local-ollama"]
重启OpenCode，执行/models自动展示全部本地推理模型。插件支持通过环境变量OLLAMA_HOST修改远程服务器地址。
方案三：ollama launch一键极简（快速测试）
Ollama 0.15及以上版本内置集成命令，无需手动维护json配置，交互式选择模型直接拉起OpenCode：
ollama launch opencode
终端交互式选择本地模型，自动生成临时配置并启动编程终端，适合临时测试场景；缺点不会持久保存自定义参数，长期项目推荐方案一。
四、进阶配置调优
1 远程GPU服务器Ollama接入
模型部署在远端GPU主机时修改baseURL为服务器内网地址：
"options": {
"baseURL": "http://192.168.5.6:11434/v1"
}
安全规范：禁止公网直接暴露11434端口，通过SSH隧道或内网防火墙隔离访问。
2 上下文长度关键优化
Ollama模型默认num_ctx数值偏小，无法满足OpenCode 64k硬性需求，两种调整手段：
1 插件参数指定（使用opencode-local-ollama插件时）
"plugin": [
["opencode-local-ollama", {
"context": 65536, "output": 4096}]
]
2 自定义Modelfile固定上下文
新建modelfile文件写入：
FROM qwen3.5
PARAMETER num_ctx 65536
执行创建定制模型：ollama create qwen3.5-64k -f ./modelfile，配置内引用新模型名称。
上下文不足会出现代码截断、工具调用失效、推理逻辑错乱等问题。
3 本地权限安全管控
OpenCode具备本地文件读写、Shell执行能力，离线环境无云端鉴权，建议开启人工确认策略：
进入Open后执行/config修改permission为plan模式，所有文件修改、命令执行先输出完整方案人工审核再执行，规避模型生成高危脚本误运行。
五、常见报错排查
1 OpenCode执行/models看不到Ollama模型
- 校验ollama服务
curl http://localhost:11434/api/tags能否返回模型； - baseURL末尾缺失
/v1是高频错误，补齐路径； - 端口冲突，重新指定ollama启动端口并同步修改配置地址。
2 代码生成截断、工具调用失效
上下文窗口不足，按上文方式将num_ctx设置65536。
3 Windows终端各类异常
优先切换WSL2子系统部署，原生Windows存在路径、权限、换行符兼容问题。
4 ollama launch覆盖原有opencode.json
一键启动命令会生成临时配置，长期项目建议手动维护全局配置文件，避免自定义参数丢失。
5 推理速度缓慢
优先选用4bit/8bit量化版本模型；硬件最低8GB显存运行7B参数，16GB显存体验流畅；关闭后台占用GPU程序。
六、离线本地方案核心优势
1 数据安全：全部代码、对话、文件读取记录仅保存在本机，涉密项目、企业内网完全不触碰公网；
2 零调用成本：无云端Token计费，不限使用时长；
3 网络无依赖，断网环境持续编码；
4 模型自由切换，支持通义、Llama、CodeLlama等各类开源编码大模型；
5 可自定义上下文、推理参数，完全自主调控AI输出风格。
七、完整落地操作流程总结
1 对应系统安装Ollama，验证版本正常；
2 拉取64k及以上长上下文编码模型；
3 安装Node.js环境，全局部署OpenCode；
4 选择三种配置方案之一对接本地Ollama网关；
5 调整上下文至65536，配置权限人工审核模式；
6 启动OpenCode输入/models验证本地模型加载；
7 测试代码生成、文件读写、脚本执行等基础功能。
整套离线本地AI编程方案摆脱云端API密钥、网络、数据泄露三大痛点，开发、运维、安全涉密场景均可稳定落地，硬件达标后15分钟即可完成全链路部署。
