最近我把手头这个模拟项目X的AI编码流水线整体切到了OpenCode上，模型从默认的闭源服务换成了Qwen系列。折腾一圈下来，关于OpenCode如何配置Qwen模型这件事，我觉得很值得单独写一篇。尤其Agent这类终端工具，模型配置不像在网页里选个下拉框那么简单，它要同时处理Provider、BaseURL、模型标识、密钥这几层关系，弄不清楚很容易卡在第一步。这篇就是我从零配到顺手跑完整流程的记录，覆盖本地部署和云端接入两条路径，也把一些隐藏的坑一并交代清楚，正在折腾OpenCode的朋友可以直接对照操作。
先说结论：OpenCode的模型配置，本质上就是告诉Agent“去哪里调哪个模型，用什么凭证”。理解这一点，后面不管换成什么模型，思路都是通用的。本文会以Qwen为主角，从配置前的准备讲起，一步步走到实际运行，最后给出问题排查清单，新手照着敲基本都能跑通。
1. Agent场景下的模型配置思路
1.1 为什么OpenCode需要单独配置模型
OpenCode是跑在终端里的开源编码Agent，它的使用方式和IDE里的AI插件是两码事。你在命令行里输入opencode，它会基于你对代码库的描述，自己规划任务、读写文件、执行命令，甚至连续多步骤修改一个项目。这意味着模型不只是“聊天背景”，而是真正负责理解、决策、输出代码的执行大脑。模型能力不足，所有Agent能力都会塌方。它对配置的要求自然也更高：不能像网页端那样在右上角选个模型名就完事，必须明确告诉OpenCode往哪个端点发请求、发到什么模型方法上、鉴权用什么身份。所以配置Qwen模型这个动作，核心不是“填几个字段”，而是理解Agent和模型服务之间的整个请求链路。一旦这个链路的概念建立起来，OpenCode配Qwen、配其他开源模型、甚至配多个模型来回切，都只是改几行配置的事。
1.2 Qwen在Agent任务里到底强在哪
Qwen系列模型的几个特点跟Agent工具非常搭。第一是开源可私有化，代码不离开内网，这对很多团队的代码保密要求很重要。第二是它有专门的代码能力版本，在代码生成、代码补全、Bug修复这类任务上表现稳定，而Agent场景恰好最需要这种“稳”。第三是它对中文指令理解得比较自然，你写中文注释、让它生成中文文档时，输出不会像某些模型那样别扭。第四是覆盖面广，从几个B的小参数版本到几百B的大参数版本都有，意味着笔记本能跑、服务器能跑、云端也能调。综合下来，在开源模型里，Qwen系列是少有的“通用对话和编码Agent两头都能占”的选择。当你在OpenCode里把模型从闭源服务切换成Qwen后，我实测最直观的感受是：响应速度可控、工具调用成功率高、长任务的稳定性也过得去。
1.3 模型配置的四个动作
配置Qwen模型，说穿了就是四步：定来源、定协议、写配置、验连通。定来源是决定用本地推理服务还是云端API，这决定了你后面所有参数的去向。定协议是决定模型服务端对外的接口格式，目前主流模型服务基本都支持OpenAI风格的兼容接口，所以协议选型一般不用纠结。写配置就是在OpenCode的配置文件里声明provider和model，把端点地址、API Key、模型名称挂上。验连通则是启动OpenCode之后发一条消息测试，确认Agent真的在跟Qwen对话。这四个动作看起来简单，但每个环节都有各自的坑。比如模型名称不匹配、baseURL少了/v1、密钥没被正确读取，这些都是配置阶段最常见的问题。把这个流程记牢，后面遇到报错你就知道该去查哪一段，而不是在配置文件里瞎改。
2. 动手配置前的三个准备
2.1 确认OpenCode版本与配置文件位置
动手之前先确认你本地的OpenCode版本，别拿着一套旧版字段硬套新版。在终端执行opencode --version，版本号不同，配置文件的字段名和结构可能会有差异，但整体思路是一致的。OpenCode读取配置的路径有两条：项目级配置在项目根目录的opencode.json，没有就自己新建一个；全局配置通常在用户目录下的opencode.json。优先级上，项目级配置会覆盖或合并全局配置。我的习惯是全局只放公共provider定义，项目级放常用的默认模型和项目相关设置，这样不同项目切起来不混乱。你可以通过OpenCode会话里的/config命令直接查看当前生效的配置，这是个非常方便的入口。第一次接触的人容易犯的错，是全局改了一个配置，进项目却发现不生效，多半就是项目级配置覆盖了全局配置，排查顺序可以从这里开始。
2.2 本地推理还是云端API：两条路怎么选
我在配置前纠结最多的其实就是这个选择。本地推理服务的优势是数据不出内网、不按token计费、断网也能用，代价是你的硬件要扛得住模型推理。云端API的优势是能直接用更大参数的模型、上下文窗口更大、响应延迟通常更稳定，代价是代码会离开本机、按token计费。我用一个简单标准来判断：如果你手头有32G以上内存或者独立显卡，日常任务在32B以下，本地是很舒服的选择；如果你要处理整个仓库级别的重构，或者需要128K上下文，那云端大模型更合适。这里还有一个中间选项：本地小模型负责日常快速任务，云端大模型负责重活，两个模型在OpenCode里同时注册，用的时候手动切。这样一个配置就能覆盖绝大多数场景，也是我目前最推荐的做法。
2.3 挑哪个Qwen模型版本
Qwen系列的命名和版本迭代比较快，配置之前一定要弄清楚当前有哪些可用的模型标签。如果走本地线路，比较适合Agent的是带coder标识的代码专用版本，比如7B、14B、32B这几个尺寸；普通通用版本也可以做Agent，不过在纯代码任务上感受不如专职版本直接。如果走云端线路，一般能看到qwen-plus、qwen-max这类命名，不同服务商对模型暴露的名字不完全一样，以你申请到的控制台里显示的为准。选型时不能只看数字越大越好，要看你的硬件和预算。以本地量化版为例，7B级别大概需要6到8G内存，14B级别建议16G以上，32B级别最好有32G以上，不然推理速度会慢到影响体验。我的建议是新手先用14B起步，在成本和效果之间平衡比较舒服；跑通了想追更强推理再往上走。
3. 本地Qwen模型接入OpenCode全流程
3.1 先把Qwen模型跑成本地推理服务
本地接入的前提是先把Qwen模型跑起来，并对外暴露一个OpenCode能访问的接口。这一步我用的是常见的开源本地推理服务Ollama，界面简单，命令也直观。安装完成后做三件事：拉取模型、确认服务状态、确认接口可访问。拉取命令很直接，比如拿14B的代码模型：ollama pull qwen2.5-coder:14b。拉取需要一点时间，模型文件不小。拉完用ollama list确认模型已经在本地。然后确认服务是否在默认端口监听，默认地址是localhost:11434，Ollama从这里提供一套OpenAI兼容的/v1接口，OpenCode靠这个接口就能低门槛接通。用curl http://localhost:11434/v1/models看一下，能把模型列表打印出来就说明服务正常，这一步走通了，后面OpenCode的配置基本上就是水到渠成。
3.2 在opencode.json中注册本地provider
本地服务跑起来之后，就在OpenCode配置文件中注册一个provider，把模型挂上去。直接在项目根目录打开opencode.json，写上这样的结构：
{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "options": { "baseURL": "http://localhost:11434", "apiKey": "ollama" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen Coder 14B (本地)" } } } }, "model": "ollama/qwen2.5-coder:14b" }这段配置里，provider的key是自定义引用名，options里的baseURL指向本地服务，apiKey这里填什么都行，因为本地服务不做鉴权。models里面声明模型标识，name只是用来显示的好看名称。model字段是默认模型的完整引用，格式是provider名/模型标识。不同版本可能有细微差别，比如有人会把baseURL写到http://localhost:11434/v1，两种写法在多数版本都能正常工作，关键是保持与你的本地服务实际暴露的路径一致。
3.3 启动OpenCode并确认模型生效
配置文件写完保存，在项目根目录重新运行opencode，进入交互式会话。第一件事用/models命令确认模型列表里出现了刚才注册的模型。如果没出现，大概率是配置文件没被读进来，或者provider定义有问题。出现之后，输入/models并选中Qwen Coder 14B，然后发一句最简单的“你好”测试。能收到正常回复，说明链路已经通了。再进阶一点，让它读取当前目录下的某个文件并总结一下，这一步能确认Agent的文件访问能力和工具调用链路也正常。我当初第一次跑通时，就是让它改一个文件里的小Bug，它自动读文件、修改、再执行测试，整个流程一气呵成，那一刻才真正体会到Agent模式下模型配置完整体验是什么样的。如果这一步卡住，排查优先级是：服务是否存活、模型标签是否一致、配置里的引用名是否匹配。
3.4 让本地模型在Agent任务中更听话的参数调整
模型能用了，但Agent任务里本地模型往往还需要调几个参数才顺手。最重要的一个是temperature，控制输出随机性，Agent场景建议调低一点，比如0.2到0.5，避免它每次生成的内容差异太大，影响工具调用稳定性。第二个是上下文窗口，很多本地模型默认值偏小，Agent要读多个文件才能干活，建议至少设到16K，内存富裕可以上32K。第三个是超时时间，本地推理速度比云端慢，给OpenCode的请求超时设得长一点，比如600秒，免得它误判模型无响应。这些参数可以写在模型定义下的options里。要注意的是，盲目开大上下文会让推理显著变慢，内存不足还可能直接卡死，所以参数要根据机器实际情况一边压测一边调，不要一上来就全拉满。
"models": { "qwen2.5-coder:14b": { "name": "Qwen Coder 14B (本地)", "options": { "temperature": 0.3, "num_ctx": 32768 } } }4. 云端Qwen API接入OpenCode全流程
4.1 获取API密钥与兼容端点
本地方案够用，但遇到大项目和复杂任务，我都会切到云端Qwen大模型。云端的接入方式跟本地思路一样，区别只是端点地址和鉴权方式。你需要从模型服务商那里拿到两样东西：一个是API Key，通常是一串以sk开头的密钥；另一个是兼容端点地址，现在主流服务商都会提供一个OpenAI兼容的baseURL，形如https://your-endpoint.example.com/v1。申请的时候注意确认你选的服务商是否支持Qwen模型，以及模型在接口里的具体标识名称。很多人卡在这一步，就是因为接口地址或模型名与控制台里看到的不完全一致。端点地址一定是以/v1结尾的完整地址，少了这个尾巴，OpenCode会怀疑你在跟不兼容的服务说话。拿到的密钥不要硬编码在配置文件里，更不要提交到git，用环境变量去传递是最稳的做法。
4.2 在配置文件中注册云端provider
拿到端点地址后，回到opencode.json注册一个云端provider。OpenCode内置了OpenAI兼容的provider，把它指到Qwen的端点就能用：
{ "provider": { "openai": { "options": { "baseURL": "https://your-endpoint.example.com/v1", "apiKey": "{env:QWEN_API_KEY}" }, "models": { "qwen-plus": { "name": "Qwen Plus (Cloud)" } } } }, "model": "openai/qwen-plus" }这段配置的核心就是把云端Qwen的端点挂到内置provider上，然后声明它提供qwen-plus这个模型。apiKey这一行使用了环境变量引用，你需要在启动OpenCode之前，在终端里先export QWEN_API_KEY=你的密钥。如果你的OpenCode版本在处理OpenAI兼容provider时比较严格，启动时校验模型名报错，可以换一个自定义provider名，并通过兼容SDK适配器来对接，原理一样，只是多了个适配层。
4.3 密钥管理与多环境切换的实用做法
云端配置最容易翻车的地方就是密钥管理。我习惯的做法是，在用户目录放一个.env文件，存储实际密钥，然后在shell配置里加载它。不同项目共用同一个密钥时，全局读一遍就行。OpenCode的配置里统一用{env:QWEN_API_KEY}这种写法，这样即使配置文件跟着项目提交到git仓库，别人也看不到真实密钥，只会看到一个环境变量名。团队成员拿到项目后，只需要自己配置这个环境变量，就能无缝运行。多环境切换也是靠环境变量：本地开发用本地密钥，CI或服务器上用另一个密钥，同一个配置在不同环境也能跑通。这种设计不是炫技，而是避免“配置泄密”和“换环境就要改配置”两个经典问题。
4.4 云端大模型的体验差异化配置
云端模型的能力上限比本地高不少，所以在配置上可以更大胆。上下文窗口如果服务商支持，可以直接开到128K，这样OpenCode能把更多文件内容和历史操作放进记忆里，处理跨多个文件的改动时不容易“丢上下文”。给模型的option里还可以开启更长的maxTokens，确保长代码生成不被截断。成本控制是云端配置绕不开的话题，大模型的token费用不便宜，日常任务建议默认用性价比更高的qwen-plus，只有复杂重构或疑难Bug排查时切到最大的qwen-max。我在实际使用中，是把两个模型都注册好，平时默认qwen-plus，遇到重活手动切qwen-max，这样功能和预算能同时兼顾。
5. 高频问题与排查记录
5.1 本地服务连不上：先查端口和baseURL
无论是在本地还是云端，最容易遇到的问题就是“连不上”。本地服务的报错，第一步先确认本地推理进程还活着，用curl http://localhost:11434/v1/models看接口是否返回模型列表。如果接口正常，那问题多半出在OpenCode的baseURL上，比如漏了/v1，或者端口号写错。如果接口本身超时，就去查防火墙和端口占用，默认端口被别的进程占了也是常有的事。我踩过的坑是，系统代理开着导致localhost请求被代理转发，最后关掉代理才恢复。遇到连不上，按这个顺序排查基本能定位到具体环节，千万别一上来就改配置，容易越改越乱。
5.2 模型名称对不上：404和model not found的真相
配置完成但请求报404或者model not found，基本可以断定是模型标识和服务端实际提供的名字不一致。本地的情况，你配置里的模型名必须和ollama list输出的一模一样，包括版本号冒号后面的部分，比如14b后面有没有量化和参数后缀，一个字符都不能差。云端的情况，模型名要以服务商控制台接口文档里写明的为准，不要凭记忆写qwen-plus杠max之类的变体。在OpenCode里，模型引用是provider/模型标识的格式，如果标识里本身带斜杠，配置里要特别小心，避免把引用路径弄混。排查时可以先在本地用curl直接调服务端的模型列表，把服务端真正支持的名字和配置里的逐字对照一遍，通常一眼就能看出问题。
5.3 响应慢或者输出被截断：上下文和maxTokens在捣鬼
Qwen模型接入后，你可能会遇到两个体验问题：一是响应特别慢，二是生成到一半被掐断。前者在本地场景十有八九是上下文窗口开得太大或者模型参数太大，内存带宽跟不上，可以降低上下文到16K试一下，或者换小一号的模型。云端场景下响应慢则要查网络和服务商限流，别忽略公司网络的代理设置，代理会让延迟飙升。后者多半是maxTokens不够长，Agent生成完整代码文件时，默认输出长度限制不够用，把它调大一些就能缓解。上下文和maxTokens是两码事，上下文管的是“Agent能看到的输入有多大”，maxTokens管的是“它能一口气输出多长”，调的时候别搞混。
5.4 Agent工具调用不稳定：先降温度再升模型
配置好了模型也能对话，但Agent在调用工具时经常出错，这个问题的根源多半不是OpenCode，而是模型本身的稳定性。Qwen本地小模型在简单对话里表现挺好，一进入工具调用，每一步都要判断调用哪个工具、传什么参数，模型一旦“犹豫”就容易输出错误格式。我的处理流程是先把temperature降到0.3以下，减少随机性；再检查提示词里有没有要求它“先确认再执行”；如果还是不稳定，就果断换更大的模型。这个场景里，模型参数量级带来的稳定性差异，远比你调几个参数来得明显，所以不用在小模型上死磕，该升级就升级。
5.5 配置改了没生效：文件路径和重启顺序
很多“疑难杂症”其实只是配置文件没被正确加载。OpenCode的配置优先级里，项目级配置会覆盖全局配置，如果你项目根目录有一个旧的opencode.json，那你在全局配置文件里改的东西大概率不会生效。检查的办法是看当前生效配置，OpenCode的/config命令会直接展示实际使用的配置内容。另外，配置文件改完一定要重启OpenCode再测试，交互式会话里通常不会热加载文件改动。最后一个小细节，JSON格式的配置最容易错的是末尾多了一个逗号或者注释残留，JSON不允许写注释，有注释也会导致整个文件解析失败。我经常看到有人把JavaScript风格的注释写进JSON，结果配置被完全无视，这类小错排查起来还真得花点时间。
6. 一些实在的使用心得
到这里，OpenCode配置Qwen模型的两条路都走通了。我现在的默认组合是：日常重构和写单元测试用本地14B量化版，复杂跨模块改造和疑难Bug分析用云端大模型，两个模型同时注册，在会话里随时切换。这套组合我在模拟项目X里跑了好几个迭代，稳定性和响应速度都符合预期。配置本身不难，难的是理解Agent的请求链路：配置文件负责路由，模型服务负责执行，两端名字对不上，一切白搭。所以排查问题的时候，我的建议永远是先确认“请求到底发出去了没有、发到了哪里、对方收到了什么”，而不是反复修改配置碰运气。
最后再分享一个小技巧：把本地和云端两个模型都注册好之后，可以在OpenCode里用/models快捷切换命令，根据不同任务随手换模型。切换多了你会发现，真正舒服的用法不是只盯一个模型，而是让每个模型去干它最擅长的活。本地模型省成本、响应快，适合日常小步快跑；云端模型能力强、上下文大，适合接大活。只要链路通了，这套搭配就能一直用下去。
