最近我把手头这个模拟项目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:11434Ollama从这里提供一套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快捷切换命令根据不同任务随手换模型。切换多了你会发现真正舒服的用法不是只盯一个模型而是让每个模型去干它最擅长的活。本地模型省成本、响应快适合日常小步快跑云端模型能力强、上下文大适合接大活。只要链路通了这套搭配就能一直用下去。
最近我把手头这个模拟项目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:11434Ollama从这里提供一套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快捷切换命令根据不同任务随手换模型。切换多了你会发现真正舒服的用法不是只盯一个模型而是让每个模型去干它最擅长的活。本地模型省成本、响应快适合日常小步快跑云端模型能力强、上下文大适合接大活。只要链路通了这套搭配就能一直用下去。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
