在 OpenCode 中接入本地模型：Ollama 部署与配置完全指南（TaoToken 统一 Key 通道版）

1. 为什么要在 OpenCode 里接本地模型OpenCode 是一个终端里的 AI 编码 Agent能读文件、改代码、跑命令支持 75 种以上模型提供商。它的默认玩法是接云端 API但很多人装完之后卡在第一步模型怎么配、Key 往哪放、本地模型能不能用。如果你手头有 GPU 或者只是想先跑通链路Ollama 是最省事的本地推理方案——它把开源模型打包成标准的 OpenAI 兼容接口OpenCode 只要把 baseURL 指过去就能用。这套组合适合三类人一是处理敏感代码、不想把内容传到云端的开发者二是网络环境受限、云 API 不稳定时想留个兜底通道的人三是想先零成本试玩 OpenCode、确认工作流顺手再决定要不要上云的人。本地模型跑起来之后OpenCode 就是一个完全离线的编码 Agent代码和对话记录全在本地。不过本地模型有个现实问题小模型在复杂任务上容易掉链子长上下文和工具调用能力也参差不齐。所以更稳的做法是双通道——日常轻量任务走 Ollama 本地遇到需要强推理或者长上下文的活儿切到 TaoToken 统一 Key 通道调云端模型。TaoToken 把多家模型的 Key 收敛成一个OpenCode 侧不用为每个厂商单独配环境变量切换成本很低。下面从 Ollama 部署开始一步步把两条通道都跑通。2. Ollama 部署把本地模型服务拉起来2.1 安装与版本确认各系统安装命令不一样挑你对应的那条# macOS brew install ollama # Linux curl -fsSL https://ollama.com/install.sh | sh # Windows官网下载安装包或用 WSL2 跑 Linux 那套装完先确认版本Ollama 0.15 以上才支持ollama launch这类快捷命令ollama --version2.2 拉取模型并留意上下文长度OpenCode 对上下文有硬性要求至少 64k。拉模型时留意模型卡上的上下文窗口参数太小的话 OpenCode 会直接不认。# 7B 级别8GB 显存差不多够用 ollama pull qwen2.5-coder:7b # 通用对话 ollama pull llama3.2 # 代码专用 ollama pull codellama:7b下载完确认列表ollama list2.3 启动服务并验证端口Ollama 安装后通常默认在后台跑监听http://localhost:11434。不放心就手动启一下ollama serve另开一个终端验证服务活着curl http://localhost:11434/api/tags能返回 JSON 模型列表就说明服务正常。这个 11434 端口后面配置 OpenCode 要用到记牢。3. TaoToken 统一 Key 通道一个 Key 管住云端模型本地模型负责离线兜底云端模型负责硬任务但云端如果每个厂商都配一套 Key环境变量会乱成一团。TaoToken 的思路是把多家模型的调用收敛到一个统一 Key 通道OpenCode 侧只需要认一个 baseURL 和一个 Key。先去控制台拿 Key# 控制台入口带来源标记 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole拿到 Key 之后API 端点用这个注意 API 地址不加 UTM 参数https://taotoken.net/api在 OpenCode 的配置里TaoToken 作为一个 OpenAI 兼容的 provider 接入baseURL填https://taotoken.net/api/v1apiKey填你拿到的统一 Key。这样你就能在同一个 OpenCode 会话里一边用ollama/qwen2.5-coder跑本地一边用taotoken/claude-sonnet之类的云端模型处理复杂重构。如果你主要做长期编码或者 Agent 类任务可以看下 Coding Plan额度模型更适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-planKey 的管理和轮换在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys4. OpenCode 配置双通道 config 骨架4.1 安装 OpenCode前提是 Node.js 18 及以上。三种装法挑一个# npm 全局安装推荐 npm install -g opencode-ai # 一键脚本 curl -fsSL https://opencode.ai/install | bash # HomebrewmacOS/Linux brew install sst/tap/opencode验证opencode --version4.2 配置文件位置OpenCode 的配置有两个位置项目级是项目根目录下的opencode.json全局级是~/.config/opencode/opencode.json。推荐用全局配置省得每个项目都配一遍。下面这份骨架同时挂了 Ollama 本地和 TaoToken 云端两条通道。{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama Local, options: { baseURL: http://localhost:11434/v1 }, models: { qwen2.5-coder:7b: { name: qwen2.5-coder:7b }, llama3.2: { name: llama3.2 } } }, taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api/v1, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-5: { name: claude-sonnet-4-5 }, gpt-4o: { name: gpt-4o } } } } }几个关键点baseURL末尾的/v1不能少Ollama 和 TaoToken 都是 OpenAI 兼容端点少了/v1会 404。apiKey用{env:TAOTOKEN_API_KEY}从环境变量读别把 Key 硬编码进配置文件。4.3 设置环境变量# Linux/macOS写进 ~/.bashrc 或 ~/.zshrc export TAOTOKEN_API_KEY你的统一Key # Windows PowerShell $env:TAOTOKEN_API_KEY你的统一Key4.4 上下文长度调优Ollama 模型元数据里标的上下文窗口可能很大但实际运行时num_ctx可能小得多。如果用的是自动发现插件可以显式指定{ plugin: [ [ opencode-local-ollama, { context: 65536, output: 4096 } ] ] }5. 验证请求curl 打通本地与云端配置写完别急着开 OpenCode先用 curl 把两条链路各自验一遍出问题好定位。5.1 验证 Ollama 本地模型curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-coder:7b, messages: [ {role: user, content: 用一句话说明什么是递归} ] }返回里有choices[0].message.content就说明本地推理链路通了。如果返回model not found回去ollama list确认模型名拼写一致。5.2 验证 TaoToken 云端通道curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-5, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }能正常返回内容说明统一 Key 通道也通了。两条都通之后启动 OpenCodeopencode进去输入/models应该能看到ollama/qwen2.5-coder:7b和taotoken/claude-sonnet-4-5都在列表里。选中一个就能开始干活。想单独测某个模型的对话效果也可以直接走模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chat6. 常见报错排查6.1 OpenCode 启动后看不到 Ollama 模型先确认服务在跑curl http://localhost:11434/api/tags。能返回模型列表说明服务正常。然后检查baseURL是否包含/v1这是最高频的坑。最后确认配置文件路径对不对全局配置在~/.config/opencode/opencode.json。6.2 模型跑起来很慢或者直接 OOM本地模型吃硬件。7B 模型至少需要 8GB 显存量化版本如 Q4可以降低门槛。另外检查上下文长度是不是设太大了num_ctx拉到 128k 会直接把显存吃满。显存不够时优先降上下文其次换更小的量化模型。6.3 云端通道返回 401 或 403大概率是 Key 没读到。确认环境变量名和配置里{env:TAOTOKEN_API_KEY}一致且当前 shell 确实 export 了。用echo $TAOTOKEN_API_KEY检查一下。如果 Key 本身有问题去 API Keys 页面重新生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys6.4 Windows 上各种路径和权限报错官方推荐用 WSL2。Windows 原生终端对路径和权限的处理有兼容性问题WSL 里跑省心很多。如果坚持原生注意配置文件路径要用 Windows 格式环境变量在系统设置里配。6.5 权限控制别图省事本地模型响应快你可能迭代着迭代着就忘了自己给过什么权限。OpenCode 的工具能读文件、写文件、执行 Shell 命令建议在配置里把高风险操作设成需要人工确认别全自动。接入文档里有更细的 provider 配置说明和参数对照遇到配置项拿不准可以翻一下https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用 Claude Code 或者 Anthropic 风格的调用TaoToken 也提供了对应的接入方式配置逻辑和上面一致只是 provider 字段不同https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude-code-anthropic整套流程捋下来就是Ollama 拉模型跑在 11434OpenCode 配好opencode.json指向本地/v1端点TaoToken 作为第二个 provider 挂同一个配置文件里curl 各验一遍再启动。本地负责离线兜底云端负责硬任务一个 Key 管住云端切换只改模型名。