最近在折腾终端里的 AI 编程 Agent 工具 OpenCode，有一件事绕不开：模型配置。OpenCode 这类工具默认的模型接入方式对国内开发者不算友好，网络、计费、可用性都有门槛。好在这类工具大多支持自定义模型接入，而这几年国产开源模型里最争气的就是 Qwen（通义千问）系列。把 Qwen 接进 OpenCode，既能绕开默认模型的种种限制，又能用上不错的代码能力，而且配置过程不复杂，关键点就几个：模型选型、API 接入方式、配置文件写法、还有一堆容易踩的坑。这篇文章我就把我实际配置 Qwen 模型的过程完整写下来，包括选型思路、配置步骤、报错排查和调参心得，给想折腾同样事情的朋友一份能直接照抄的参考。这次的项目背景很简单：本地安装好了 OpenCode，想让它用 Qwen 模型来干 Agent 活——读代码、改文件、执行命令、写 commit 这类任务。核心就三步：搞到可用的 Qwen API、把模型写进 OpenCode 配置、验证 Agent 能正常调用。下面从原理开始拆。1. 为什么绕开默认模型：OpenCode 的模型接入逻辑1.1 OpenCode 这类终端 Agent 工具，到底把模型"藏"在了哪先弄清楚 OpenCode 的运行逻辑。OpenCode 本质是一个跑在终端里的 AI 编程 Agent：它把 LLM 作为"大脑"，通过工具调用（Tool Calling）去操作文件系统、执行 Shell 命令、查找代码，最终完成你交给它的编程任务。所以它对模型的依赖比普通聊天工具更重，不光是生成文本，还要求模型能稳定输出结构化的工具调用指令。官方默认的模型配置往往指向国外模型服务，这也是很多人装完 OpenCode 后卡在第一步的原因。而 OpenCode 这类工具在设计时留了灵活的模型接入层：模型配置一般写在用户目录下的配置文件中，通过"服务提供商（Provider） + 模型名（Model） + 密钥（API Key）"三个要素定义一次调用。你只要换掉这三件套，就能让工具整体换脑。这也是为什么配置 Qwen 这件事听起来复杂、实际操作却很简单——你不需要改工具本体，只改配置。1.2 为什么国产模型 Qwen 成了"替代默认"的首选我见过不少人直接把默认模型 API 地址改成本地代理想继续用国外模型，结果折腾半天还是不稳。相比之下，Qwen 的优势很实在：国内访问延迟低、注册就能拿 API Key、文档全而且兼容 OpenAI 格式的接口调用方式。Qwen 系列有几个特点对 Agent 场景尤其重要：一是上下文窗口从 32K 到 128K 甚至更大，能容纳大型代码库片段；二是工具调用能力经过专门训练，输出结构化 JSON 的稳定度不错；三是模型参数规格覆盖从 0.5B 到 72B 的完整梯度，既能云端调大模型，也能本地跑小模型。特别是 qwen2.5-coder 系列，本来就是为代码任务优化的，做编程 Agent 的基座模型很合适。更关键的是，Qwen 的开源协议对商用相对友好，个人开发者、小型创业团队用起来没有太多心理负担。2. Qwen 模型选型：同一家模型，路子差很多开始配置之前，先选模型。Qwen 目前能玩的花样不少，但接入 OpenCode 的方式大类就两种：云端 API 和本地私有化部署。两条路的模型选择逻辑完全不同，别选错。2.1 云端 API 路线：用旗舰还是用轻量云端路线适合不想折腾显卡、追求省事和稳定的人。国内某云厂商的百炼平台提供了 Qwen 系列模型的托管 API，申请 API Key 之后就可以通过兼容 OpenAI 格式的接口调用。云端选型主要看任务类型：任务场景推荐模型原因日常代码生成、补全qwen2.5-coder-32b代码专项优化，4K 窗口内表现稳定Agent 多轮工具调用qwen2.5-72b-instruct综合推理能力强，复杂指令理解更准长上下文代码库分析qwen2.5-7b-instruct长文本处理中有性价比优势轻量快速任务qwen3 系列轻量版响应快、成本低，适合高频小任务我个人建议：如果跑 Agent 任务而不是简单聊天，优先上 32B 以上的模型。Agent 场景里模型要同时理解你的自然语言指令、当前文件内容、工具返回结果，推理负担比单轮问答大得多，7B 模型在云端跑起来虽然便宜，但复杂任务的成功率会明显下降。2.2 本地 Ollama 路线：适合什么场景，不适合什么场景本地路线通过 Ollama 这类工具在自家机器上跑 Qwen 开源权重。好处是隐私好、离线可用、没有 API 按量计费的心理压力。坏处是吃硬件——40 系显卡或者 Mac 大内存机型才能跑得动稍有规模的模型。本地选型基本跟着显存走：8GB 显存：跑 qwen2.5-coder-3b 或 7b 的量化版，写写常规函数、改改小文件够用。16GB 显存：跑 qwen2.5-coder-7b 全精度或 14b 量化版，已经能处理多数项目级任务。24GB 以上显存：可以考虑 qwen2.5-coder-32b 的量化版，体验接近云端中等配置。本地部署我只有在两种情况下推荐：一是你对数据隐私极度敏感，代码不能出机器；二是网络环境不稳定，云端调用老断，本地至少能保底。否则优先云端，因为 32B 以上模型在本地跑的成本——无论是硬件投入还是等待时间——都远高于按量付费的 API。2.3 选型对照表：按需求快速定位最终怎么选，我总结成一张表，直接对照抄：需求推荐方案理由不想折腾，快速上手云端 qwen2.5-coder-32b省心、稳定、效果好代码量大，上下文要求高云端 128K 上下文版本大仓库代码塞得下隐私优先，能接受硬件投入本地 14b 量化版数据不出本机，效果中上低成本试水，验证可行性云端 7b 或本地 3b先跑通链路再升级选定模型之后，配置的核心就变成把"用哪个模型"和"去哪调这个模型"这两件事告诉 OpenCode。接下来要准备的东西就是老三样：API Key、模型名、API 地址。3. 配置前必须备齐的三样东西配置之前，先别急着打开配置文件。有经验的朋友都知道，80% 的配置问题都出在准备工作上——密钥没拿对、模型名写错、地址拼错，任何一个错了都会让你在排查时怀疑人生。所以先把三样东西准备齐全。3.1 API Key 与密钥环境变量云端方案需要在对应平台的控制台创建 API Key。创建之后务必自己复制保存，很多平台只在创建时显示一次完整 Key，关掉页面就再也看不到了。拿到 Key 之后，强烈建议不要直接硬编码到 OpenCode 的配置文件里，而是设置成环境变量。原因有两个：一是配置文件可能会被你分享出去或者放进版本管理，硬编码 Key 等于裸奔；二是以后换模型、换平台时，只需要改环境变量，不用动配置主体。在终端里执行：export QWEN_API_KEY="sk-你的密钥"为了方便每次终端会话都能读到，建议把这一行加进 shell 的启动文件（比如.bashrc或.zshrc），然后执行source ~/.zshrc让它立即生效。3.2 模型名与上下文长度模型名是配置中最容易出错的一项。注意，API 调用时填的模型名不是我们说人话时的简称，而是要严格使用平台定义的模型标识符。常见格式类似：qwen2.5-coder-32b-instruct qwen2.5-72b-instruct qwen2.5-7b-instruct注意两点：第一，有些模型标识带日期版本后缀（比如-1219这类），平台升级后旧后缀可能失效，配置时要查一下当前文档确认；第二，上下文长度参数要单独确认，API 默认值可能只有 4K 或 8K，Agent 场景至少设置到 32K 才有实用意义，否则代码稍微一长就被截断，Agent 会开始"失忆"。3.3 平台 API 地址OpenAI 兼容接口通常需要一个 Base URL（或叫 baseURL）。Qwen 云端服务的接入地址是标准的 OpenAI 兼容格式，形如：https://你的服务商域名/v1如果你用本地 Ollama，地址一般是：http://localhost:11434/v1这个地址拼写有个坑：很多人在结尾漏掉/v1，或者多写一个规则不匹配的路径，导致请求 404。配置时先把地址在浏览器里试一遍能不能打开（会返回提示或 404 页面，能通就行），再填进配置。4. 手把手配置：编辑配置文件把 Qwen 接进来三样东西齐了，就进入正式配置阶段。整个流程分成三步：定位配置文件、写入 Qwen 配置、启动验证。4.1 找到并认识 OpenCode 的模型配置文件OpenCode 的配置文件惯例放在用户配置目录下，按平台区分。Linux/macOS 一般在~/.config/opencode/下，Windows 在用户目录的.opencode文件夹下。主配置文件通常是 JSON 格式。先确认文件存在：ls -la ~/.config/opencode/如果目录不存在，先启动一次 OpenCode 让它自动初始化，或者手动创建目录和文件。打开配置文件后，里面应该已经有工具默认生成的一些配置项。我们的工作就是在配置里增加或修改模型服务商的定义。4.2 写入 Qwen 的 Provider 和模型配置在配置文件的合适位置，新增 Qwen 的服务商配置。OpenCode 的服务商定义遵循 AI SDK 体系，核心字段是 provider 的 id、options（包括 apiKey 和 baseURL），以及要暴露的模型列表。我实际配置时的写法如下（JSON 格式）：{ "$schema": "https://opencode.ai/config.json", "model": "qwen/qwen2.5-coder-32b-instruct", "provider": { "qwen": { "npm": "@ai-sdk/qwen", "name": "Qwen", "options": { "baseURL": "https://你的服务商域名/v1", "apiKey": "env:QWEN_API_KEY" }, "models": { "qwen2.5-coder-32b-instruct": { "name": "Qwen 2.5 Coder 32B Instruct" }, "qwen2.5-72b-instruct": { "name": "Qwen 2.5 72B Instruct" } } } } }几个字段的作用和理由说明一下：model字段：指定默认模型，格式是"服务商名/模型标识"。这里我选的是qwen2.5-coder-32b-instruct，因为 Agent 核心任务是写代码。provider对象：定义了一个叫qwen的服务商。npm字段告诉 OpenCode 加载哪个官方模型接入包，@ai-sdk/qwen是 AI SDK 体系对 Qwen 的官方适配包，有它就不用自己拼 HTTP 请求。options.apiKey：填env:QWEN_API_KEY，意思是从环境变量读取密钥，而不是直接写死。models对象：把这个服务商下可用的模型列出来。这里我只列了两款，够用就行。以后模型更新了，往这里加条目即可。注意一个细节：每个平台要求的鉴权请求头格式可能不同。OpenCode 的 provider 适配包一般已经处理好了鉴权方式，所以配置里不用手动指定 header。但如果你用的是完全自定义的网关地址，可能需要在 options 里补充 headers 字段，这时就要去查目标平台 API 文档确认鉴权头。我在一次接入内部代理网关时就在这里卡过，后来发现是少了一个自定义请求头。4.3 启动验证：用一条指令确认连接成功保存配置文件后，启动 OpenCode，输入一条简单的指令验证模型连通性，比如：请用 Python 写一个快速排序函数，并添加注释如果模型正常响应，说明配置已经生效。注意观察响应速度：如果等了几秒钟才出第一个 token，可能是因为上下文窗口设置过大导致首 token 延迟，不用急着下结论，多测几条再判断。进一步验证 Agent 的工具调用能力，可以下一个更复杂的指令：读取当前目录下 README.md 内容，总结项目用途，并列出所有 Python 文件这条指令会触发模型调用文件读取工具。如果它能正确列出文件，说明 Qwen 的工具调用链路也通了。到这一步，配置就算完成，可以正常干活了。5. 连接失败排查链路：从 401 到 404配置完不一定一次就通。我帮好几个朋友排查过，问题高度集中。这里把最常见的几类报错和排查思路完整列出来，你可以直接按链路对照。5.1 401 认证失败：Key 没读到还是 Key 不对表现：调用时报类似401 Unauthorized或Authentication failed。排查链路：先确认环境变量确实存在：终端里执行echo $QWEN_API_KEY，能打印出值才说明设置了。确认 OpenCode 是否继承了这个环境变量。有些图形界面启动的终端不会自动加载 shell 启动文件，这时要在完整终端里启动 OpenCode，或者重启终端会话。检查 Key 是否复制完整。很多平台生成的 Key 带短横线或特定前缀，复制时漏字符是家常便饭。确认 Key 状态是否有效，去平台控制台看一眼有没有被停用或过期。我用一个简单命令直接测鉴权，比反复启动 OpenCode 高效：curl https://你的服务商域名/v1/models \ -H "Authorization: Bearer $QWEN_API_KEY"返回200且带模型列表，说明 Key 没问题，问题在 OpenCode 侧的环境继承；返回401，直接怀疑 Key 本身。5.2 404 模型不存在：标识符拼错的经典场景表现：报错信息带Model Not Found或404。这基本就是模型标识符拼错了。注意两点：一是大小写敏感，二是平台升级后模型名变更。排查方法是拿平台文档当前给出的模型标识符，逐一核对你的配置文件。有些平台在/v1/models接口会返回当前可用模型清单，用上面那个 curl 命令直接查看最准。比如最近我在接入某个平台新版本模型时，发现文档里写的是qwen3-32b，跟之前的命名规则完全不同，照抄老配置自然 404。5.3 429 限流与连接超时的处理方式429 表示请求太频繁触发限流。排查点是确认你用的账号套餐 QPS 上限，再把 OpenCode 的并发请求数调低。连接超时则要分头排查：先 ping 服务商域名看网络通不通，再确认 baseURL 是否填对，最后看本地是不是有代理工具干扰了终端流量。我遇到过一次玄学问题：配置完全正确，但就是超时，最后发现是系统代理服务吞掉了 API 请求。关闭代理后恢复正常。6. 从能用到好用：上下文窗口和工具调用的实测心得配置通了只是开始。想让它真正好用，还要处理几个影响体验的细节，这里分享一些实测心得。6.1 上下文窗口设置：不是越大越好Agent 任务中文档内容、工具返回结果都会进入上下文。窗口设置太小，长文件会被截断；设置太大，每次请求消耗的 token 和费用直线上升，而且首 token 延迟也会变高。我的实践经验是一个平衡区间：常规编码任务设 32K 足够，分析中型仓库时可以临时切到 128K 版本，但不要作为日常默认值。如果你发现 Agent 频繁忘记前几轮说过的话，先检查是不是窗口太小，而不是怀疑模型智力。6.2 温度参数：写代码别用高温度温度（temperature）控制生成随机性。代码任务需要确定性和准确性，温度高了容易生成"好看但跑不通"的代码。实测下来，代码生成和工具调用场景把温度设在 0.1 到 0.3 之间最顺手。OpenCode 的模型服务商配置里可以通过 options 传递自定义参数，不过多数情况下默认值已经偏保守，改不改看你个人习惯。6.3 Agent 工具调用表现：Qwen 的强项与边界实测 Qwen 在 OpenCode 里的工具调用表现总体值得肯定。文件读取、代码搜索、执行命令这类常见操作稳定度不错，依赖结构化输出的场景很少出现卡死。边界情况也有：复杂多步骤任务在上下文很长时，偶尔会出现工具参数格式偏差，比如少传一个必填字段。遇到这种情况，把任务拆细、每步只交代一个目标，成功率会明显上升。这是所有模型在 Agent 场景下的共性规律，Qwen 已经算处理得比较好的一档。7. 长期使用 Qwen 的几个额外建议最后聊几个配置之外、但迟早会用到的事情。API 费用预估口径别搞混。模型计费通常按 token 计，输入和输出价格不同。Agent 场景里输出 token 占比不高，大头反而是反复塞入的文件内容和工具返回结果，这些都属于输入 token。一晚上重度使用，输入 token 消耗量惊人。设置上下文窗口别贪大，够用就行，这是省钱的最实在手段。模型版本升级要主动跟进。Qwen 系列迭代快，新版本模型在代码能力和工具调用上常有明显提升。每两三个月去平台看一次模型列表，把新版本加到 OpenCode 配置里试用，对比好了再切换默认模型。这个习惯能让你持续吃到模型进步的红利。本地和云端可以混合用。一些简单的格式化、变量重命名任务，丢给本地小模型处理响应更快、成本为零；复杂架构分析、跨文件重构再走云端大模型。我现在的做法是在 OpenCode 配置文件里同时保留两个 provider，根据任务手动切换模型。混跑之后整体体验比单纯用云端或单纯用本地都要舒服。Qwen 进 OpenCode 这件事做到这个程度，基本就是把模型层完全拿捏在手了。以后再换别的模型、接别的平台，无非是照着 Provider 配置重新填一遍三件套的事。工具是死的，配置思路是通的，这比记住某一个具体配置片段更有用。
最近在折腾终端里的 AI 编程 Agent 工具 OpenCode，有一件事绕不开：模型配置。OpenCode 这类工具默认的模型接入方式对国内开发者不算友好，网络、计费、可用性都有门槛。好在这类工具大多支持自定义模型接入，而这几年国产开源模型里最争气的就是 Qwen（通义千问）系列。把 Qwen 接进 OpenCode，既能绕开默认模型的种种限制，又能用上不错的代码能力，而且配置过程不复杂，关键点就几个：模型选型、API 接入方式、配置文件写法、还有一堆容易踩的坑。这篇文章我就把我实际配置 Qwen 模型的过程完整写下来，包括选型思路、配置步骤、报错排查和调参心得，给想折腾同样事情的朋友一份能直接照抄的参考。这次的项目背景很简单：本地安装好了 OpenCode，想让它用 Qwen 模型来干 Agent 活——读代码、改文件、执行命令、写 commit 这类任务。核心就三步：搞到可用的 Qwen API、把模型写进 OpenCode 配置、验证 Agent 能正常调用。下面从原理开始拆。1. 为什么绕开默认模型：OpenCode 的模型接入逻辑1.1 OpenCode 这类终端 Agent 工具，到底把模型"藏"在了哪先弄清楚 OpenCode 的运行逻辑。OpenCode 本质是一个跑在终端里的 AI 编程 Agent：它把 LLM 作为"大脑"，通过工具调用（Tool Calling）去操作文件系统、执行 Shell 命令、查找代码，最终完成你交给它的编程任务。所以它对模型的依赖比普通聊天工具更重，不光是生成文本，还要求模型能稳定输出结构化的工具调用指令。官方默认的模型配置往往指向国外模型服务，这也是很多人装完 OpenCode 后卡在第一步的原因。而 OpenCode 这类工具在设计时留了灵活的模型接入层：模型配置一般写在用户目录下的配置文件中，通过"服务提供商（Provider） + 模型名（Model） + 密钥（API Key）"三个要素定义一次调用。你只要换掉这三件套，就能让工具整体换脑。这也是为什么配置 Qwen 这件事听起来复杂、实际操作却很简单——你不需要改工具本体，只改配置。1.2 为什么国产模型 Qwen 成了"替代默认"的首选我见过不少人直接把默认模型 API 地址改成本地代理想继续用国外模型，结果折腾半天还是不稳。相比之下，Qwen 的优势很实在：国内访问延迟低、注册就能拿 API Key、文档全而且兼容 OpenAI 格式的接口调用方式。Qwen 系列有几个特点对 Agent 场景尤其重要：一是上下文窗口从 32K 到 128K 甚至更大，能容纳大型代码库片段；二是工具调用能力经过专门训练，输出结构化 JSON 的稳定度不错；三是模型参数规格覆盖从 0.5B 到 72B 的完整梯度，既能云端调大模型，也能本地跑小模型。特别是 qwen2.5-coder 系列，本来就是为代码任务优化的，做编程 Agent 的基座模型很合适。更关键的是，Qwen 的开源协议对商用相对友好，个人开发者、小型创业团队用起来没有太多心理负担。2. Qwen 模型选型：同一家模型，路子差很多开始配置之前，先选模型。Qwen 目前能玩的花样不少，但接入 OpenCode 的方式大类就两种：云端 API 和本地私有化部署。两条路的模型选择逻辑完全不同，别选错。2.1 云端 API 路线：用旗舰还是用轻量云端路线适合不想折腾显卡、追求省事和稳定的人。国内某云厂商的百炼平台提供了 Qwen 系列模型的托管 API，申请 API Key 之后就可以通过兼容 OpenAI 格式的接口调用。云端选型主要看任务类型：任务场景推荐模型原因日常代码生成、补全qwen2.5-coder-32b代码专项优化，4K 窗口内表现稳定Agent 多轮工具调用qwen2.5-72b-instruct综合推理能力强，复杂指令理解更准长上下文代码库分析qwen2.5-7b-instruct长文本处理中有性价比优势轻量快速任务qwen3 系列轻量版响应快、成本低，适合高频小任务我个人建议：如果跑 Agent 任务而不是简单聊天，优先上 32B 以上的模型。Agent 场景里模型要同时理解你的自然语言指令、当前文件内容、工具返回结果，推理负担比单轮问答大得多，7B 模型在云端跑起来虽然便宜，但复杂任务的成功率会明显下降。2.2 本地 Ollama 路线：适合什么场景，不适合什么场景本地路线通过 Ollama 这类工具在自家机器上跑 Qwen 开源权重。好处是隐私好、离线可用、没有 API 按量计费的心理压力。坏处是吃硬件——40 系显卡或者 Mac 大内存机型才能跑得动稍有规模的模型。本地选型基本跟着显存走：8GB 显存：跑 qwen2.5-coder-3b 或 7b 的量化版，写写常规函数、改改小文件够用。16GB 显存：跑 qwen2.5-coder-7b 全精度或 14b 量化版，已经能处理多数项目级任务。24GB 以上显存：可以考虑 qwen2.5-coder-32b 的量化版，体验接近云端中等配置。本地部署我只有在两种情况下推荐：一是你对数据隐私极度敏感，代码不能出机器；二是网络环境不稳定，云端调用老断，本地至少能保底。否则优先云端，因为 32B 以上模型在本地跑的成本——无论是硬件投入还是等待时间——都远高于按量付费的 API。2.3 选型对照表：按需求快速定位最终怎么选，我总结成一张表，直接对照抄：需求推荐方案理由不想折腾，快速上手云端 qwen2.5-coder-32b省心、稳定、效果好代码量大，上下文要求高云端 128K 上下文版本大仓库代码塞得下隐私优先，能接受硬件投入本地 14b 量化版数据不出本机，效果中上低成本试水，验证可行性云端 7b 或本地 3b先跑通链路再升级选定模型之后，配置的核心就变成把"用哪个模型"和"去哪调这个模型"这两件事告诉 OpenCode。接下来要准备的东西就是老三样：API Key、模型名、API 地址。3. 配置前必须备齐的三样东西配置之前，先别急着打开配置文件。有经验的朋友都知道，80% 的配置问题都出在准备工作上——密钥没拿对、模型名写错、地址拼错，任何一个错了都会让你在排查时怀疑人生。所以先把三样东西准备齐全。3.1 API Key 与密钥环境变量云端方案需要在对应平台的控制台创建 API Key。创建之后务必自己复制保存，很多平台只在创建时显示一次完整 Key，关掉页面就再也看不到了。拿到 Key 之后，强烈建议不要直接硬编码到 OpenCode 的配置文件里，而是设置成环境变量。原因有两个：一是配置文件可能会被你分享出去或者放进版本管理，硬编码 Key 等于裸奔；二是以后换模型、换平台时，只需要改环境变量，不用动配置主体。在终端里执行：export QWEN_API_KEY="sk-你的密钥"为了方便每次终端会话都能读到，建议把这一行加进 shell 的启动文件（比如.bashrc或.zshrc），然后执行source ~/.zshrc让它立即生效。3.2 模型名与上下文长度模型名是配置中最容易出错的一项。注意，API 调用时填的模型名不是我们说人话时的简称，而是要严格使用平台定义的模型标识符。常见格式类似：qwen2.5-coder-32b-instruct qwen2.5-72b-instruct qwen2.5-7b-instruct注意两点：第一，有些模型标识带日期版本后缀（比如-1219这类），平台升级后旧后缀可能失效，配置时要查一下当前文档确认；第二，上下文长度参数要单独确认，API 默认值可能只有 4K 或 8K，Agent 场景至少设置到 32K 才有实用意义，否则代码稍微一长就被截断，Agent 会开始"失忆"。3.3 平台 API 地址OpenAI 兼容接口通常需要一个 Base URL（或叫 baseURL）。Qwen 云端服务的接入地址是标准的 OpenAI 兼容格式，形如：https://你的服务商域名/v1如果你用本地 Ollama，地址一般是：http://localhost:11434/v1这个地址拼写有个坑：很多人在结尾漏掉/v1，或者多写一个规则不匹配的路径，导致请求 404。配置时先把地址在浏览器里试一遍能不能打开（会返回提示或 404 页面，能通就行），再填进配置。4. 手把手配置：编辑配置文件把 Qwen 接进来三样东西齐了，就进入正式配置阶段。整个流程分成三步：定位配置文件、写入 Qwen 配置、启动验证。4.1 找到并认识 OpenCode 的模型配置文件OpenCode 的配置文件惯例放在用户配置目录下，按平台区分。Linux/macOS 一般在~/.config/opencode/下，Windows 在用户目录的.opencode文件夹下。主配置文件通常是 JSON 格式。先确认文件存在：ls -la ~/.config/opencode/如果目录不存在，先启动一次 OpenCode 让它自动初始化，或者手动创建目录和文件。打开配置文件后，里面应该已经有工具默认生成的一些配置项。我们的工作就是在配置里增加或修改模型服务商的定义。4.2 写入 Qwen 的 Provider 和模型配置在配置文件的合适位置，新增 Qwen 的服务商配置。OpenCode 的服务商定义遵循 AI SDK 体系，核心字段是 provider 的 id、options（包括 apiKey 和 baseURL），以及要暴露的模型列表。我实际配置时的写法如下（JSON 格式）：{ "$schema": "https://opencode.ai/config.json", "model": "qwen/qwen2.5-coder-32b-instruct", "provider": { "qwen": { "npm": "@ai-sdk/qwen", "name": "Qwen", "options": { "baseURL": "https://你的服务商域名/v1", "apiKey": "env:QWEN_API_KEY" }, "models": { "qwen2.5-coder-32b-instruct": { "name": "Qwen 2.5 Coder 32B Instruct" }, "qwen2.5-72b-instruct": { "name": "Qwen 2.5 72B Instruct" } } } } }几个字段的作用和理由说明一下：model字段：指定默认模型，格式是"服务商名/模型标识"。这里我选的是qwen2.5-coder-32b-instruct，因为 Agent 核心任务是写代码。provider对象：定义了一个叫qwen的服务商。npm字段告诉 OpenCode 加载哪个官方模型接入包，@ai-sdk/qwen是 AI SDK 体系对 Qwen 的官方适配包，有它就不用自己拼 HTTP 请求。options.apiKey：填env:QWEN_API_KEY，意思是从环境变量读取密钥，而不是直接写死。models对象：把这个服务商下可用的模型列出来。这里我只列了两款，够用就行。以后模型更新了，往这里加条目即可。注意一个细节：每个平台要求的鉴权请求头格式可能不同。OpenCode 的 provider 适配包一般已经处理好了鉴权方式，所以配置里不用手动指定 header。但如果你用的是完全自定义的网关地址，可能需要在 options 里补充 headers 字段，这时就要去查目标平台 API 文档确认鉴权头。我在一次接入内部代理网关时就在这里卡过，后来发现是少了一个自定义请求头。4.3 启动验证：用一条指令确认连接成功保存配置文件后，启动 OpenCode，输入一条简单的指令验证模型连通性，比如：请用 Python 写一个快速排序函数，并添加注释如果模型正常响应，说明配置已经生效。注意观察响应速度：如果等了几秒钟才出第一个 token，可能是因为上下文窗口设置过大导致首 token 延迟，不用急着下结论，多测几条再判断。进一步验证 Agent 的工具调用能力，可以下一个更复杂的指令：读取当前目录下 README.md 内容，总结项目用途，并列出所有 Python 文件这条指令会触发模型调用文件读取工具。如果它能正确列出文件，说明 Qwen 的工具调用链路也通了。到这一步，配置就算完成，可以正常干活了。5. 连接失败排查链路：从 401 到 404配置完不一定一次就通。我帮好几个朋友排查过，问题高度集中。这里把最常见的几类报错和排查思路完整列出来，你可以直接按链路对照。5.1 401 认证失败：Key 没读到还是 Key 不对表现：调用时报类似401 Unauthorized或Authentication failed。排查链路：先确认环境变量确实存在：终端里执行echo $QWEN_API_KEY，能打印出值才说明设置了。确认 OpenCode 是否继承了这个环境变量。有些图形界面启动的终端不会自动加载 shell 启动文件，这时要在完整终端里启动 OpenCode，或者重启终端会话。检查 Key 是否复制完整。很多平台生成的 Key 带短横线或特定前缀，复制时漏字符是家常便饭。确认 Key 状态是否有效，去平台控制台看一眼有没有被停用或过期。我用一个简单命令直接测鉴权，比反复启动 OpenCode 高效：curl https://你的服务商域名/v1/models \ -H "Authorization: Bearer $QWEN_API_KEY"返回200且带模型列表，说明 Key 没问题，问题在 OpenCode 侧的环境继承；返回401，直接怀疑 Key 本身。5.2 404 模型不存在：标识符拼错的经典场景表现：报错信息带Model Not Found或404。这基本就是模型标识符拼错了。注意两点：一是大小写敏感，二是平台升级后模型名变更。排查方法是拿平台文档当前给出的模型标识符，逐一核对你的配置文件。有些平台在/v1/models接口会返回当前可用模型清单，用上面那个 curl 命令直接查看最准。比如最近我在接入某个平台新版本模型时，发现文档里写的是qwen3-32b，跟之前的命名规则完全不同，照抄老配置自然 404。5.3 429 限流与连接超时的处理方式429 表示请求太频繁触发限流。排查点是确认你用的账号套餐 QPS 上限，再把 OpenCode 的并发请求数调低。连接超时则要分头排查：先 ping 服务商域名看网络通不通，再确认 baseURL 是否填对，最后看本地是不是有代理工具干扰了终端流量。我遇到过一次玄学问题：配置完全正确，但就是超时，最后发现是系统代理服务吞掉了 API 请求。关闭代理后恢复正常。6. 从能用到好用：上下文窗口和工具调用的实测心得配置通了只是开始。想让它真正好用，还要处理几个影响体验的细节，这里分享一些实测心得。6.1 上下文窗口设置：不是越大越好Agent 任务中文档内容、工具返回结果都会进入上下文。窗口设置太小，长文件会被截断；设置太大，每次请求消耗的 token 和费用直线上升，而且首 token 延迟也会变高。我的实践经验是一个平衡区间：常规编码任务设 32K 足够，分析中型仓库时可以临时切到 128K 版本，但不要作为日常默认值。如果你发现 Agent 频繁忘记前几轮说过的话，先检查是不是窗口太小，而不是怀疑模型智力。6.2 温度参数：写代码别用高温度温度（temperature）控制生成随机性。代码任务需要确定性和准确性，温度高了容易生成"好看但跑不通"的代码。实测下来，代码生成和工具调用场景把温度设在 0.1 到 0.3 之间最顺手。OpenCode 的模型服务商配置里可以通过 options 传递自定义参数，不过多数情况下默认值已经偏保守，改不改看你个人习惯。6.3 Agent 工具调用表现：Qwen 的强项与边界实测 Qwen 在 OpenCode 里的工具调用表现总体值得肯定。文件读取、代码搜索、执行命令这类常见操作稳定度不错，依赖结构化输出的场景很少出现卡死。边界情况也有：复杂多步骤任务在上下文很长时，偶尔会出现工具参数格式偏差，比如少传一个必填字段。遇到这种情况，把任务拆细、每步只交代一个目标，成功率会明显上升。这是所有模型在 Agent 场景下的共性规律，Qwen 已经算处理得比较好的一档。7. 长期使用 Qwen 的几个额外建议最后聊几个配置之外、但迟早会用到的事情。API 费用预估口径别搞混。模型计费通常按 token 计，输入和输出价格不同。Agent 场景里输出 token 占比不高，大头反而是反复塞入的文件内容和工具返回结果，这些都属于输入 token。一晚上重度使用，输入 token 消耗量惊人。设置上下文窗口别贪大，够用就行，这是省钱的最实在手段。模型版本升级要主动跟进。Qwen 系列迭代快，新版本模型在代码能力和工具调用上常有明显提升。每两三个月去平台看一次模型列表，把新版本加到 OpenCode 配置里试用，对比好了再切换默认模型。这个习惯能让你持续吃到模型进步的红利。本地和云端可以混合用。一些简单的格式化、变量重命名任务，丢给本地小模型处理响应更快、成本为零；复杂架构分析、跨文件重构再走云端大模型。我现在的做法是在 OpenCode 配置文件里同时保留两个 provider，根据任务手动切换模型。混跑之后整体体验比单纯用云端或单纯用本地都要舒服。Qwen 进 OpenCode 这件事做到这个程度，基本就是把模型层完全拿捏在手了。以后再换别的模型、接别的平台，无非是照着 Provider 配置重新填一遍三件套的事。工具是死的，配置思路是通的，这比记住某一个具体配置片段更有用。