OpenCode模型配置完全指南：models-api.json深度解析与多模型切换实战

最近群里好几个朋友都在折腾 OpenCode上来第一句基本都问同一个问题模型到底怎么配尤其是刚装好的 OpenCode打开终端跑opencode默认模型要么连不上要么根本不在列表里体验极不友好。其实 OpenCode 的模型接入并不复杂核心就一个文件models-api.json。把这玩意儿吃透了本地跑 deepseek-r1:7b、接云端 DeepSeek API、甚至同时挂几个 provider 来回切都是顺手的事。这篇文章我就从 models-api.json 入手把 OpenCode 的模型配置讲透顺带把 Agent、Skill、CC Switch 联动这些经常一起出现的东西串起来说清楚。适合刚开始接触 OpenCode、或者已经跑通但想深入理解配置机制的人。1. 先弄明白OpenCode 和 models-api.json 到底解决什么问题1.1 OpenCode 是什么为什么大家都在配模型OpenCode 是一个终端里运行的 AI 编程助手开源、本地优先、Agent 架构。它跟 Claude Code 这类商业工具有点像但最大的区别是配置高度开放模型层完全可换。你用 Anthropic 的模型也行用本地 Ollama 跑的 deepseek-r1:7b 也行甚至自己写一个兼容 OpenAI 协议的内部网关也行。所以“模型配置”就成了 OpenCode 用户绕不开的第一个关卡。为什么模型配置这么重要因为 OpenCode 的整个执行逻辑是模型驱动的它读取用户指令由模型决定调用哪些工具、读哪些文件、执行哪些命令。模型选得好不好直接决定任务成功率。我实测下来同一个任务在 deepseek-r1:7b 和云端大模型上的表现差异非常大。本地小模型更适合做代码补全、简单重构和格式调整复杂架构调整还是得交给云端强推理模型。所以配置本身不是一次性的而是需要经常切换的。很多新手就是卡在这一步不知道模型接入文件长什么样也不知道怎么加一个本地模型结果 OpenCode 装上之后根本用不起来。1.2 models-api.json 在整套配置里的位置OpenCode 的配置目录一般在~/.config/opencode/Linux/macOS或%USERPROFILE%\.config\opencode\Windows。里面会有opencode.json、models-api.json、agents/目录、skills/目录等等。第一次打开 OpenCode它可能会自动生成基础配置但模型接入不会自动帮你写好这也是很多新手上来一脸懵的原因。这几个文件的分工大致是这样opencode.json主配置管行为、权限、工具开关、默认模型选择。models-api.json模型接入清单管 provider 和 model 的定义是这篇文章的主角。agents/自定义 Agent 定义比如“代码审查 Agent”“重构 Agent”。skills/技能包一些可复用的操作流程和提示词。为什么要拆成独立文件因为模型接入是变化最频繁的部分。今天加一个模型、明天换一个 baseURL如果全部堆在主配置里很容易改崩。拆开后主配置只负责引用 models-api.json 里注册的模型 ID模型层可以独立迭代。你可以把 models-api.json 理解成“通讯录”记录着所有能用的模型服务地址和名字opencode.json 则是“日程表”决定今天用通讯录里的哪个人干活。两者配合OpenCode 的灵活度才真正体现出来。2. models-api.json 配置深度拆解字段、结构与原理2.1 provider 是入口为什么要有这一层抽象models-api.json 最核心的概念就是 provider。所谓 provider就是模型服务的提供方。它可以是云厂商比如 DeepSeek、OpenAI、Anthropic也可以是本地推理引擎比如 Ollama、LM Studio甚至是一个自建的网关。OpenCode 通过 provider 这一层抽象把“模型服务的接入方式”和“具体模型”解耦了。这个设计很有用。你不需要为每个模型单独写一套连接逻辑只需要声明“这个 provider 走什么协议、baseURL 指向哪、API Key 怎么获取”然后在 provider 下面挂一堆模型 ID 就行。这样做的好处是切换模型时不需要改连接参数只需要改模型 ID或者直接改全局默认模型。provider 抽象对普通用户的意义在于你不需要懂内部实现只要按照固定格式填好地址和密钥OpenCode 就能自动识别并加载。2.2 model 条目如何描述一个可用模型在 provider 内部每个模型都有一个 ID 和一组描述属性。模型 ID 通常是你在该 provider 下的唯一标识比如deepseek-r1:7b、gpt-4o、claude-sonnet-4-20250514。OpenCode 在运行时通过这个 ID 去请求对应的模型服务。如果 ID 写错大概率会报 404 或者模型不存在这个坑后面会细说。模型条目里还常见这些字段字段作用示例name模型在界面里显示的名称方便识别DeepSeek R1 7Blimit上下文窗口限制超出会截断或报错{context: 32768}reasoning是否开启推理模式影响部分模型的输出格式truetemperature采样温度越高越随机越低越确定0.2maxTokens单次生成的最大 token 数8192cost计费信息用于统计成本{input: 1, output: 2}options透传给 provider 的额外参数{baseURL: ...}不是说每个字段都必须填。很多字段有默认值比如 temperature 大多数模型默认 0.7 左右maxTokens 有模型默认上限。但上下文窗口 limit 我建议一定要填尤其是本地模型。如果你不填OpenCode 会按一个默认值去算一旦你的对话历史超过了模型实际支持的上下文就会出现生成中断、报 400 错误甚至看起来像是“模型卡住了”。我习惯在配置本地模型时先把模型实际的上下文长度查清楚再填进去。2.3 本地模型配置以 Ollama deepseek-r1:7b 为例本地模型是很多人用 OpenCode 的初衷因为数据不出机器、不花钱、断网也能用。目前最常见的本地推理方案就是 Ollama。Ollama 本身是一个极简的模型运行工具装好后一条命令就能拉起模型并提供 HTTP API。先确保 Ollama 里已经有模型执行ollama pull deepseek-r1:7b ollama listollama list输出的名字就是你后面要填的模型 ID。接下来在 models-api.json 里这样写{ provider: { ollama: { npm: ai-sdk/ollama, name: Ollama, options: { baseURL: http://localhost:11434/api }, models: { deepseek-r1:7b: { name: DeepSeek R1 7B, limit: { context: 32768 }, reasoning: true, temperature: 0.6 } } } }, model: deepseek-r1:7b }关键点有两个。第一个是npm字段它指定 OpenCode 用什么 SDK 去和这个 provider 通信。Ollama 用的是ai-sdk/ollama接 OpenAI 兼容服务用ai-sdk/openai-compatible。如果你接的是 Anthropic 官方可以省略 npm 字段或者用ai-sdk/anthropic。第二个是baseURLOllama 的地址一定是http://localhost:11434/api注意末尾的/api不能丢。如果 Ollama 部署在远程服务器上就把localhost换成对应的 IP 或域名。填完之后OpenCode 里应该就能看到 DeepSeek R1 7B 这个模型了。不过本地模型有个现实问题7B 模型在复杂代码任务上能力有限上下文一大生成速度也会明显下降。我的经验是本地模型适合做“高频低难度”的任务比如补注释、写单测、改格式复杂任务还是交给云端模型。2.4 云端模型配置DeepSeek API、OpenAI 兼容服务怎么接云端模型的配置思路和本地类似只是多了 API Key 和网络地址。以 DeepSeek 官方 API 为例它的接口是 OpenAI 兼容格式所以 provider 类型可以走ai-sdk/openai-compatible具体写法{ provider: { deepseek: { npm: ai-sdk/openai-compatible, name: DeepSeek, options: { baseURL: https://api.deepseek.com/v1 }, models: { deepseek-chat: { name: DeepSeek V3, limit: { context: 65536 } }, deepseek-reasoner: { name: DeepSeek R1, reasoning: true, limit: { context: 65536 } } } } } }API Key 不建议直接写在 models-api.json 里因为配置文件可能会被同步到 git 仓库存在泄露风险。更安全的做法是设置环境变量比如在终端里执行export DEEPSEEK_API_KEYsk-xxxxxxxx然后在 models-api.json 的 provider 里通过环境变量引用 Key{ provider: { deepseek: { npm: ai-sdk/openai-compatible, name: DeepSeek, options: { baseURL: https://api.deepseek.com/v1, apiKey: {env:DEEPSEEK_API_KEY} } } } }如果你用的是 OpenAI、Anthropic 等官方模型也是同理只是 baseURL 和 API Key 对应各自的官方地址。这里我想强调一个细节OpenAI 兼容接口并不是所有字段都能透传比如有些推理模型特有的参数直接用通用兼容协议可能不生效。遇到这种情况优先看 provider 有没有专门的 npm SDK有就用专门的。3. 实操从零安装到多模型自由切换3.1 安装 OpenCode各平台都别踩坑模型配置写得再好OpenCode 没装好也是白搭。OpenCode 官方提供了一键安装脚本macOS 和 Linux 上执行curl -fsSL https://opencode.ai/install | bashWindows 用户常用的是通过包管理器安装比如winget install opencode或者用 scoopscoop install opencode新版 OpenCode 还在某些平台上提供了桌面版OpenCode Desktop如果你更喜欢图形界面管理配置可以去官方仓库的 Release 页面找对应安装包。移动端和 Web 端也有但主力开发场景还是终端。装好之后在终端执行opencode --version能输出版本号就说明基础安装没问题。如果你看到类似command not found多半是 PATH 没配置好检查一下安装目录是否在环境变量里。这里有个小提醒如果之前装过旧版本升级后最好确认一下配置目录里的文件有没有被迁移。OpenCode 的配置格式在版本迭代中会调整旧文件不兼容的情况并不罕见最典型的症状就是“明明配了模型但软件里看不到”。3.2 编写你的第一个 models-api.json为了让你能直接“抄作业”我写一个包含本地模型和云端模型的完整示例。假设你本地跑着 Ollama 的 deepseek-r1:7b同时有 DeepSeek 官方 API 和 OpenAI 的 API Key那么 models-api.json 可以这么组织{ provider: { ollama: { npm: ai-sdk/ollama, name: Ollama (Local), options: { baseURL: http://localhost:11434/api }, models: { deepseek-r1:7b: { name: DeepSeek R1 7B, limit: { context: 32768 }, reasoning: true }, qwen2.5-coder:7b: { name: Qwen 2.5 Coder 7B, limit: { context: 32768 } } } }, deepseek: { npm: ai-sdk/openai-compatible, name: DeepSeek Cloud, options: { baseURL: https://api.deepseek.com/v1, apiKey: {env:DEEPSEEK_API_KEY} }, models: { deepseek-chat: { name: DeepSeek V3, limit: { context: 65536 } }, deepseek-reasoner: { name: DeepSeek R1 (Cloud), reasoning: true, limit: { context: 65536 } } } }, openai: { npm: ai-sdk/openai, name: OpenAI, options: { apiKey: {env:OPENAI_API_KEY} }, models: { gpt-4o: { name: GPT-4o, limit: { context: 128000 } } } } }, model: deepseek-r1:7b }注意看model字段它指定了默认使用哪个模型值就是某个 provider 下的模型 ID。比如deepseek-r1:7b会让 OpenCode 默认启动本地模型。如果你有多个同名模型OpenCode 的解析规则通常是优先匹配 provider 下的模型 ID所以只要 ID 全局唯一就不会冲突。写完配置后重启 OpenCode执行/models命令应该能看到刚才配置的五个模型。如果看不到优先检查 JSON 格式有没有问题尤其注意别多写逗号、括号嵌套是否闭合。JSON 格式错误是初学者最常犯的问题没有之一。3.3 模型切换的几种方式日常够用就行配置好多个模型之后切换就非常随意了。OpenCode 提供了一条交互命令/models在会话中直接输入就会弹出模型列表让你选择选完立即生效不需要重启。这是最直观的方式适合临时切换。如果你的需求是“某个项目固定用某个模型”那就在项目根目录放一个项目级别的 opencode.json把默认模型写进去{ model: deepseek-reasoner }项目配置的优先级高于全局配置这样你在 A 项目里用云端推理模型在 B 项目里用本地快速模型互不干扰。还有一种方式是环境变量OpenCode 也支持通过环境变量覆盖默认模型适合在 CI/CD 或脚本里动态指定但日常开发用得较少。我习惯的做法是全局 models-api.json 里把常用模型都注册好全局默认模型设成本地模型省 token具体到某个代码库再在项目配置里覆盖成更强的云端模型。这套组合用下来既省钱又灵活。3.4 CC Switch 联动模型映射配置实战CC Switch 是社区里很流行的模型配置管理工具早期主要用来在 Claude Code、Codex 等工具之间切换模型。现在大家也把它和 OpenCode 配合用因为它提供了一个可视化界面可以批量维护多个工具的模型映射不用每次都去手改 JSON。CC Switch 的配置项里有一个“模型映射”功能它做的事情本质上是把不同工具要用的模型名映射到你实际想要调用的 provider 模型上。举个例子你想让 OpenCode 在调用sonnet这个别名时实际走的是本地 Ollama 的 deepseek-r1:7b那就在 CC Switch 里建一条映射把sonnet指向ollama/deepseek-r1:7b。这种映射在团队协作里很省事。因为每个人的 models-api.json 可能不一样但大家的工作流都引用同一个抽象模型名底层换成什么都行。CC Switch 会帮你生成或修正对应的 models-api.json 片段你只需要把这个片段贴回配置文件。我自己用的时候发现CC Switch 生成的配置里 API Key 可能会直接写入文件这没问题但记得调整文件权限或者改用环境变量引用别把密钥带到代码仓库里。4. 常见问题与排查技巧实录4.1 the agent execution provider did not respond in time这个报错出现的频率相当高大意是“Agent 执行提供方没有及时响应”。很多人一看到带 agent 的报错就懵了其实这里说的 provider 就是模型服务方报错指的就是模型服务超时或无法连接。排查顺序我一般这么走先确认模型服务本身是通的。Ollama 就直接在终端执行curl http://localhost:11434/api/tags能返回 JSON 就说明服务活着云端 API 可以执行一个简单的 curl 请求测试鉴权是否正常。确认模型 ID 是否存在且写对了。Ollama 的模型名是大小写敏感的deepseek-r1:7b和DeepSeek-R1:7b是两码事。确认网络链路。如果是本地模型看 Ollama 是否绑定在 127.0.0.1 上如果是云端模型排查代理、防火墙、网络延迟。确认上下文长度配置是否超过模型实际上限。超过之后模型服务可能在生成前就拒绝请求表现为“不响应”。这个报错还有一个容易被忽略的原因本地模型在慢速 CPU 或小内存机器上加载就要半分钟OpenCode 的请求等待时间有限直接判定超时。解决办法是换量化更低的模型文件或者给 OpenCode 所在环境的超时时间调大一点。如果条件允许给本地模型加一个 GPU 会立竿见影。4.2 模型列表为空或模型加载失败配置写好了但/models里看不到任何模型大概率是 provider 没有正确识别。先检查 models-api.json 里每个 provider 有没有填npm字段以及对应的 SDK 是否已经安装。OpenCode 在首次加载 provider 时会尝试自动安装 npm 依赖如果网络环境不好安装失败provider 自然就加载不出来。还有一种情况是 provider 里没写models字段或者 models 对象是空的。OpenCode 不会因为你注册了一个 provider 就默认帮你填模型模型必须一个个列出。我见过有人只写了 provider 没写 models折腾半天以为 OpenCode 坏了其实只是配置不完整。另一个隐蔽的坑是 JSON 注释。Opencode 的配置解析在某些版本里支持注释但 models-api.json 如果被当作严格 JSON 解析加了注释就会报错。如果你是从网上复制模板留意那些//或#开头的行最好去掉再写。4.3 配置修改后不生效OpenCode 在启动时会读取配置文件运行时有些地方会缓存配置。修改了 models-api.json 但看不到变化不要急着删重装先退出 OpenCode 再重新启动。如果还是不生效检查你改的文件路径对不对。注意区分全局配置目录和项目配置目录全局配置在~/.config/opencode/项目配置在项目根目录下两者有优先级关系。我踩过一次坑我以为自己改的是全局 models-api.json结果终端工作目录切到项目里后项目里也有一份 models-api.json优先级更高的项目配置覆盖了全局配置导致我改了半天全局文件实际用的还是项目里的旧配置。所以排查时先确认“当前正在被读取的是哪份文件”。OpenCode 提供了一个查看配置信息和日志的命令具体是opencode debug或/debug输出里会显示加载了哪些配置非常方便。4.4 本地模型性能与显存问题如果你在 OpenCode 里用 deepseek-r1:7b 感觉很慢甚至报显存不足这个不一定是配置的问题而是模型本身的硬件需求问题。7B 模型虽然不大但完整精度推理也要不少显存。以 deepseek-r1:7b 为例不同量化版本的显存需求大致如下模型版本显存需求估算建议场景Q4_K_M 量化约 5~6 GB大多数消费级显卡可跑Q8_0 量化约 8 GB显存充裕时用精度更高原版 FP16约 14 GB不适合日常小显存机器如果显存不够最直接的解决办法是换量化版本比如用deepseek-r1:7b:q4_K_M这个 tag 重新拉取模型。注意模型 ID 要和实际拉取的 tag 保持一致否则 OpenCode 请求的模型在 Ollama 里不存在还是会报错。除了显存上下文长度也很影响性能。给模型配置 32K 上下文不代表它就能流畅跑完 32K 的代码库分析实际体验上本地 7B 模型超过 8K~16K 后生成速度会明显下降。我建议本地模型配置context时保守一点或者在使用中勤用/compact压缩对话历史避免上下文爆掉。4.5 鉴权与安全注意事项模型配置过程中最容易被忽视的就是安全问题。API Key 如果直接写入 models-api.json又恰好被提交到 git 仓库那基本等于裸奔。我的经验是养成一上来就建.gitignore的习惯把包含密钥的配置文件排除掉。models-api.json 里如果有敏感字段最好是引用环境变量而不是硬编码。使用本地模型在隐私上天然有优势数据不出本机适合处理敏感代码。但也要注意本地模型能力有限如果把公司核心业务代码喂给一个完全没有防护的本地模型输出结果被谁看到、会不会被日志记录同样是问题。OpenCode 的权限系统可以限制代理执行的操作集合建议按需开启不要一把梭给全部权限。模型配置只是第一步安全合规的 Agent 使用习惯才是长期稳定用的基础。5. 再往深一层Agent、Skill 与模型配置的关系5.1 Agent、Skill、Harness 到底什么关系聊到模型配置很多热词榜单里会出现 agent、skill、harness它们和模型配置有什么关系我用最直白的话解释模型是“大脑”Agent 是“做决策的人”Skill 是“这个人掌握的技能包”Harness 是“让一切跑起来的运行框架”。OpenCode 本身就是一套 Harness它提供了循环执行、工具调用、上下文管理等能力。Agent 则是 OpenCode 里的一个角色它会被分配不同的系统提示词和工具集用来完成特定任务。Skill 是更细粒度的能力单元比如“如何格式化代码”“如何写 Git 提交信息”可以被 Agent 动态调用。模型配置为所有这些能力提供底层智力支撑。你在 models-api.json 里注册的每个模型本质上都是候选的“大脑”。OpenCode 允许不同 Agent 绑定不同模型比如主 Agent 用云端强推理模型做架构分析子 Agent 用本地快速模型做文件整理。这个思路非常实用能显著降低成本和延迟。5.2 自定义 Agent给模型配一个专属角色agents/ 目录下的文件就是用来定义自定义 Agent 的。一个典型的 agent 配置是 JSON 或 Markdown 格式里面包含提示词、绑定的模型、启用的工具等。假设我要定义一个“代码审查 Agent”配置可以长这样{ agent: { reviewer: { description: Code reviewer, system: You are a senior code reviewer. Focus on bugs, security issues, and readability., model: gpt-4o, tools: { read: true, grep: true, bash: false } } } }注意model字段它指定的模型必须是 models-api.json 里已经注册过的。如果你在这个 Agent 里写了一个不存在的模型 IDAgent 调用时就会报错。自定义 Agent 的价值在于你不需要每次都手动切换模型和调整提示词一个指令就能调出最合适的配置组合。5.3 Skill 配置与模型上下文配合Skill 的配置通常是一组 Markdown 文件里面写清楚触发条件和执行步骤类似“提示词模板 工具调用规范”。比如你可以给 OpenCode 加一个“智能提交”技能让它在执行 git commit 前先总结改动、生成提交信息再执行提交命令。这个技能由模型根据当前代码 diff 来生成内容模型能力越强技能执行效果越好。这揭示了一个关键点Skill 和模型是相辅相成的。Skill 负责结构化流程模型负责具体判断。如果你是第一次接触 OpenCode建议先从官方 Skill 仓库拉几个常用技能试用再用自己的项目场景来改造。Skill 配置不复杂难点在于如何设计好的提示词结构和工具调用边界这是需要反复调试的。5.4 从配置入手看懂 OpenCode 架构如果你对 Agent 开发感兴趣想深入理解 OpenCode我建议从配置文件入手去读源码。models-api.json 是入口它会告诉你看哪部分代码provider 和模型注册的逻辑、工具调用的封装、agent 的执行循环。顺着一条链路读下去你会发现 OpenCode 的架构并不神秘底层是 AI SDK 的 provider 抽象中间是 agent 循环与工具系统上层是终端交互界面。这种“从配置反推源码”的学习方式比直接啃源码要高效得多。因为你在配置文件里看到的每个字段都能在源码里找到对应的数据结构和处理逻辑。当你把一个真实报错逐步追踪到代码里的具体判断分支时你对这个项目的理解就不再是浮于表面的“会用”而是真正的“懂它怎么运作”。6. 我的实操体会与一些小建议模型配置这件事说到底是“工具服务于人”而不是“人服务于工具”。我见过很多人花大量时间去折腾各种模型参数结果任务产出并没有提升反而陷入了无休止的调参循环。就我的经验来说models-api.json 里最重要的字段不是 temperature也不是 context而是模型的正确注册和合理的默认模型选择。先把能用、稳定、成本可接受的模型跑通再谈优化。最后分享一个小技巧定期备份你的配置目录。尤其是 models-api.json 和自定义 Agent 配置这些都是你花时间调出来的产物。遇到 OpenCode 版本升级导致配置失效时有一份备份能让你快速恢复工作环境而不是从零开始。OpenCode 还在快速迭代配置文件的结构可能继续变化但底层思路不会变把模型接入独立管理、把 Agent 和 Skill 作为灵活的组合单元、把选择权交还给用户。顺着这个思路去用你会越来越顺手。