1. 为什么要在 OpenCode 里折腾第三方 API 供应商OpenCode 这个工具最近在开发者圈子里讨论度很高它本质上是一个终端里的 AI 编程助手能读代码、改代码、跑命令交互方式跟 Claude Code、Cursor 那类工具是一个路数。但很多人装完之后卡在第一步默认的免费额度有限制控制台会甩出一句error from provider (console): opencodes free tier can only be used from within opencode意思是你想白嫖可以但只能在它自己的壳里用想接自己的模型或者第三方供应商就得手动配置。这就是这篇东西要解决的问题。我把它定位成一份保姆级配置手册面向三类人一是刚装好 OpenCode、想接自己 API Key 的新手二是手里有多个模型供应商、想统一管理的中级用户三是想搞清楚 OpenCode 配置逻辑、方便后续做自动化或者团队分发的老手。核心关键词就三个OpenCode、第三方 API 供应商、配置。先说清楚一个前提OpenCode 的配置体系是围绕供应商provider这个概念搭的。它内置了一批常见供应商比如 Anthropic、OpenAI 这些但内置不等于免费也不等于你能直接用。真正要干活你得告诉它三件事——用哪个供应商、用哪个模型、用什么凭证。这三件事配好了OpenCode 才能把请求发出去把结果拿回来。我见过太多人一上来就去改代码、翻源码其实没必要。OpenCode 的配置入口设计得还算克制主要就两个地方一个是配置文件一个是环境变量。配置文件管结构环境变量管密钥。把这两个东西理顺第三方供应商接入就是十分钟的事。下面我按实际操作的顺序从整体设计思路讲到具体落地再到踩坑排查一层层拆开。2. 配置体系的整体设计与思路拆解2.1 OpenCode 的供应商抽象层是怎么设计的要配第三方 API先得理解 OpenCode 为什么要把供应商单独抽一层出来。这跟很多工具直接写死 API 地址不一样OpenCode 走的是适配器模式每个供应商对应一个适配器适配器负责把 OpenCode 内部的统一请求格式翻译成各家 API 能听懂的格式再把返回结果翻译回来。这么设计的好处很直接。第一换供应商不用改业务逻辑你从 A 家换到 B 家只要换配置代码一行不动。第二支持多供应商并存你可以同时配好几个按任务类型切换比如写代码用一个、写文档用另一个。第三密钥和结构分离配置文件里不写明文密钥密钥走环境变量这样配置文件可以进版本库、可以团队共享不怕泄露。我个人的判断是这套设计对个人用户来说稍微有点重但对需要长期维护、多人协作的场景非常友好。你如果只是自己用理解到供应商适配器凭证模型列表这个层面就够了。2.2 为什么优先选配置文件而不是命令行参数OpenCode 支持命令行临时指定供应商比如opencode --provider xxx但我不推荐日常这么用。原因有三个不可复用每次都要敲一长串容易漏参数尤其是模型名和 base URL 这种容易记错的。不利于版本管理配置文件可以提交到 Git命令行参数不行团队里每个人的习惯不一样统一配置能省很多沟通成本。调试困难出问题的时候配置文件是静态的一眼能看出配了什么命令行参数是动态的得回忆当时敲了什么。所以我的建议是把稳定配置写进配置文件把密钥写进环境变量命令行只用来做临时覆盖。这个原则贯穿整篇教程。2.3 第三方供应商接入的三种典型场景实际用下来第三方 API 供应商的接入大致分三类配置方式略有差异场景典型特征配置重点兼容 OpenAI 协议大多数国产模型、自建服务改 base URL模型名对齐兼容 Anthropic 协议Claude 系及部分兼容服务注意 header 和版本字段完全自定义协议企业内部网关、私有部署需要写适配器或走代理层绝大多数人遇到的是第一类。兼容 OpenAI 协议意味着请求体结构、鉴权方式、返回格式都跟 OpenAI 一致你只要把baseURL指向供应商给的地址把apiKey换成自己的模型名填对基本就能跑。这也是为什么我建议新手从这类供应商入手成功率最高。3. 核心细节解析与实操要点3.1 配置文件的位置与结构OpenCode 的配置文件通常放在用户目录下的配置文件夹里具体路径跟操作系统有关。Linux 和 macOS 一般在~/.config/opencode/下面Windows 在%APPDATA%\opencode\下面。文件名常见的是config.json或者opencode.json具体以你安装的版本为准装完之后可以先跑一次opencode --help或者翻一下安装目录确认它读的是哪个文件。配置文件的结构是 JSON顶层一般有provider字段下面挂各个供应商的配置。一个典型的骨架长这样{ provider: { my-provider: { type: openai-compatible, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_PROVIDER_KEY} }, models: { my-model: { name: 实际模型名 } } } } }这里有几个细节值得说。type字段决定用哪个适配器兼容 OpenAI 的填openai-compatible。baseURL一定要带对版本路径很多供应商是/v1结尾漏了会 404。apiKey里写{env:XXX}是 OpenCode 的变量插值语法意思是运行时从环境变量XXX读取这样配置文件里就没有明文密钥。注意不同版本的 OpenCode 字段名可能有细微差异比如有的版本用npm字段指定适配器包有的用type。配置前最好对照你那个版本的官方示例别照搬网上的老配置。3.2 环境变量的设置与隔离密钥走环境变量是这套体系的安全底线。设置方式分临时和永久两种。临时的话在当前终端里export MY_PROVIDER_KEYsk-xxxx关掉终端就没了适合测试。永久的话写进 shell 的配置文件比如~/.bashrc、~/.zshrc或者 Windows 的系统环境变量里。我强烈建议按供应商分别命名环境变量比如PROVIDER_A_KEY、PROVIDER_B_KEY不要所有供应商共用一个API_KEY。原因很简单一旦你要换供应商或者临时禁用某一个共用变量会让你分不清哪个 Key 对应哪个服务排查起来很痛苦。而且多个供应商并存的时候共用变量根本没法区分。还有一个容易忽略的点环境变量的作用域。如果你在 IDE 里用 OpenCode 插件IDE 启动时继承的环境变量可能跟你终端里不一样。这时候要么在 IDE 的配置里单独指定要么把变量写到系统级别。我踩过这个坑终端里跑得好好的一到 IDE 里就报鉴权失败查了半天才发现是环境变量没继承过去。3.3 模型名的对齐问题模型名这块是最容易出错的地方。OpenCode 配置里的模型名跟你实际调用的模型名可能不是一回事。配置里的 key 是你自己起的别名name字段才是真正发给供应商的模型标识。举个例子供应商文档里写的模型是deepseek-chat你配置里可以写成models: { fast: { name: deepseek-chat } }这样你在 OpenCode 里选fast就行实际发出去的是deepseek-chat。这么做的好处是换供应商的时候只改 name不用改你日常用的别名。我习惯按用途起别名比如fast、smart、cheap这样切换模型的时候心智负担小。要特别小心的是模型名的大小写和连字符。有些供应商对模型名大小写敏感GPT-4和gpt-4可能一个能用一个报错。配置完先用一个最简单的请求测一下别等到正式用的时候才发现。4. 实操过程与核心环节实现4.1 从零开始一次完整的第三方供应商接入我拿一个兼容 OpenAI 协议的供应商做例子把完整流程走一遍。假设供应商给的 base URL 是https://api.example.com/v1模型是example-large密钥是sk-abc123。第一步设置环境变量。在终端里执行export EXAMPLE_API_KEYsk-abc123验证一下有没有生效echo $EXAMPLE_API_KEY能打印出密钥就说明设置成功。这一步别跳过很多人配置失败就是因为环境变量根本没设上。第二步编辑配置文件。找到 OpenCode 的配置文件加入供应商配置{ provider: { example: { type: openai-compatible, options: { baseURL: https://api.example.com/v1, apiKey: {env:EXAMPLE_API_KEY} }, models: { large: { name: example-large } } } } }第三步验证配置。跑一个最简单的命令比如让 OpenCode 解释一段代码或者直接问它一个问题。如果返回正常说明配置成功。如果报错看错误信息里的关键词401是鉴权问题404是地址问题400多半是模型名或者请求格式问题。第四步固化配置。测试通过之后把环境变量写进 shell 配置文件把配置文件提交到你的 dotfiles 仓库记得确认里面没有明文密钥。4.2 多供应商并存的配置策略手里有好几个供应商的时候配置文件的组织方式很关键。我的做法是按供应商分组按用途起别名。比如{ provider: { provider-a: { type: openai-compatible, options: { baseURL: https://api.a.com/v1, apiKey: {env:PROVIDER_A_KEY} }, models: { fast: { name: a-fast-model }, smart: { name: a-smart-model } } }, provider-b: { type: openai-compatible, options: { baseURL: https://api.b.com/v1, apiKey: {env:PROVIDER_B_KEY} }, models: { fast: { name: b-fast-model }, smart: { name: b-smart-model } } } } }这样两个供应商都有fast和smart两个别名切换的时候只要指定供应商和别名就行。实际用的时候我会根据任务类型选写代码用 A 家的 smart写文档用 B 家的 fast成本和质量都能兼顾。提示多供应商配置的时候注意别让别名冲突。如果两个供应商都叫fast切换的时候要同时指定供应商名否则 OpenCode 可能不知道你指的是哪个。4.3 参数调优超时、重试与并发配置能跑通只是第一步实际用起来还得调几个参数。最常调的是超时时间和重试次数。第三方供应商的网络质量参差不齐默认超时可能太短请求还没返回就断了。超时一般在options里配options: { baseURL: https://api.example.com/v1, apiKey: {env:EXAMPLE_API_KEY}, timeout: 60000 }timeout单位是毫秒60000 就是 60 秒。我一般设 60 到 120 秒太短容易误判失败太长卡着难受。重试次数看供应商的稳定性稳定的设 1 到 2 次不稳定的设 3 次但要注意重试会消耗额度别设太多。并发这块OpenCode 本身对并发有控制但如果你同时跑多个任务供应商那边可能有速率限制。遇到429错误就是被限流了这时候要么降低并发要么换供应商要么等一会儿再试。4.4 验证配置是否生效的三种方法配置完怎么确认真的生效了我常用三种方法看日志OpenCode 一般有日志输出能看到实际请求发到了哪个地址、用了哪个模型。日志里如果出现你配的 base URL说明配置被读到了。发测试请求让 OpenCode 做一个最简单的任务比如用一句话解释什么是递归看返回是否正常。对比响应同一个问题分别用不同供应商问一遍看回答风格和速度有没有差异能间接验证是不是真的走了你配的供应商。这三种方法我一般组合用日志确认配置读取测试请求确认连通对比响应确认路由正确。5. 常见问题与排查技巧实录5.1 报错信息速查表配置过程中遇到的报错八成集中在下面这几类。我整理成表方便对照排查报错关键词可能原因排查方向401 Unauthorized密钥错误或未读取到检查环境变量是否生效密钥是否过期403 Forbidden密钥权限不足确认密钥是否有该模型的调用权限404 Not Foundbase URL 错误检查是否漏了/v1或路径拼错400 Bad Request模型名或请求格式错误核对模型名大小写检查请求体结构429 Too Many Requests触发速率限制降低并发或等待后重试free tier can only be used from within opencode用了免费额度但不在官方壳里换成第三方供应商配置别用免费额度timeout网络慢或超时设置太短加大 timeout检查网络连通性这张表我建议存下来遇到报错先对号入座能省很多时间。5.2 密钥读取失败的排查思路密钥读取失败是最常见的问题表现是明明设了环境变量OpenCode 还是报鉴权错误。排查顺序我一般是这样的确认变量名一致配置文件里写的是{env:EXAMPLE_API_KEY}环境变量就得叫EXAMPLE_API_KEY大小写、下划线都不能错。确认作用域在跑 OpenCode 的那个终端里echo一下变量能打印出来才算设上。如果是 IDE 里跑确认 IDE 继承了环境变量。确认没有多余字符复制密钥的时候容易带上空格或者换行用echo $VAR | wc -c看长度对不对。确认配置文件被读取有的版本会读多个位置的配置文件确认你改的是它实际读的那个。我踩过最坑的一次是配置文件里写的是{env:EXAMPLE_API_KEY}但环境变量设成了EXAMPLE_KEY少了个API查了半小时才发现。所以变量名一定要仔细核对。5.3 模型切换后行为异常的排查有时候配置都对了但切换模型之后行为不对劲比如回答质量突然变差、或者干脆不返回。这种情况我一般从三个方向查模型名是否真的存在有些供应商的模型名跟文档不一致或者有版本后缀比如model-v2和model是两个不同的东西。上下文长度是否超限不同模型的上下文窗口不一样长对话切到小窗口模型会截断或者报错。供应商是否支持该功能有些模型不支持函数调用或者流式输出OpenCode 如果默认开了这些功能就会出问题。排查的时候先用一个短问题测排除上下文长度的影响再关掉流式输出测排除功能兼容问题。逐步缩小范围比盲目改配置高效得多。5.4 几个我踩过的坑和独家技巧说几个文档里不会写、但实际很实用的经验。第一个坑配置文件里的注释。JSON 标准不支持注释但有些 OpenCode 版本用的是 JSONC带注释的 JSON。如果你在标准 JSON 里加了注释解析会失败报错信息还不明显。我的做法是不确定的时候就不写注释把说明写在单独的 README 里。第二个坑base URL 的尾斜杠。https://api.example.com/v1和https://api.example.com/v1/在某些供应商那里行为不一样前者正常后者可能 404。配置的时候统一不带尾斜杠能避免大部分问题。第三个技巧用 curl 先验证供应商。配置 OpenCode 之前先用 curl 直接调一下供应商的接口确认密钥和地址没问题。这样能把供应商问题和OpenCode 配置问题分开排查效率翻倍。命令大概是这样curl https://api.example.com/v1/chat/completions \ -H Authorization: Bearer $EXAMPLE_API_KEY \ -H Content-Type: application/json \ -d {model:example-large,messages:[{role:user,content:hi}]}能返回正常结果说明供应商侧没问题问题就在 OpenCode 配置上。第四个技巧配置备份。改配置之前先备份一份改坏了能快速回滚。我习惯用 Git 管理配置文件每次改动都有记录出问题能 diff 出改了什么。第五个技巧关注版本更新。OpenCode 迭代比较快配置字段偶尔会变。升级版本之后先跑一次验证确认配置还兼容。遇到字段废弃的及时改别等到报错了才处理。6. 配置之外的延伸思考6.1 数据安全与密钥管理第三方 API 供应商接入之后你的代码和对话内容会发到供应商的服务器上。这一点必须心里有数。我的做法是敏感项目不接第三方或者接之前先脱敏。密钥管理上除了环境变量还可以考虑用系统的密钥管理工具比如 macOS 的 Keychain、Linux 的 secret-tool把密钥存进去环境变量里只放一个读取命令。团队协作的时候配置文件可以共享但密钥绝对不能进版本库。用.gitignore把包含密钥的文件排除掉或者用模板文件加本地覆盖的方式模板进库实际配置不进库。6.2 成本控制与用量监控第三方供应商大多是按量计费的用起来爽账单也可能吓人。我一般会做两件事一是给每个供应商设预算上限很多供应商后台支持设置月度限额超了就停二是定期看用量报表发现异常增长及时查原因。OpenCode 本身不一定有用量统计但供应商后台一般都有养成定期看的习惯。6.3 后续可以怎么扩展配置跑通之后还能做不少延伸。比如把配置模板化写一个脚本输入供应商信息就自动生成配置比如做多供应商的自动切换主供应商挂了自动切备用比如把配置和团队的工作流结合不同项目用不同的供应商配置。这些都属于锦上添花先把基础配置跑稳再考虑这些。我个人在实际操作中的体会是OpenCode 的第三方供应商配置难点不在配置本身而在排查。配置就那么几个字段但出错的时候原因可能有很多层。把排查思路理顺比记住配置语法更重要。上面那张报错速查表和 curl 验证法是我用得最多的两个工具基本能覆盖八成的问题。剩下的两成多半是版本差异或者供应商侧的临时问题遇到的时候别慌一步步缩小范围就行。 OpenCode 接入第三方 API 供应商：保姆级配置与排查指南
1. 为什么要在 OpenCode 里折腾第三方 API 供应商OpenCode 这个工具最近在开发者圈子里讨论度很高它本质上是一个终端里的 AI 编程助手能读代码、改代码、跑命令交互方式跟 Claude Code、Cursor 那类工具是一个路数。但很多人装完之后卡在第一步默认的免费额度有限制控制台会甩出一句error from provider (console): opencodes free tier can only be used from within opencode意思是你想白嫖可以但只能在它自己的壳里用想接自己的模型或者第三方供应商就得手动配置。这就是这篇东西要解决的问题。我把它定位成一份保姆级配置手册面向三类人一是刚装好 OpenCode、想接自己 API Key 的新手二是手里有多个模型供应商、想统一管理的中级用户三是想搞清楚 OpenCode 配置逻辑、方便后续做自动化或者团队分发的老手。核心关键词就三个OpenCode、第三方 API 供应商、配置。先说清楚一个前提OpenCode 的配置体系是围绕供应商provider这个概念搭的。它内置了一批常见供应商比如 Anthropic、OpenAI 这些但内置不等于免费也不等于你能直接用。真正要干活你得告诉它三件事——用哪个供应商、用哪个模型、用什么凭证。这三件事配好了OpenCode 才能把请求发出去把结果拿回来。我见过太多人一上来就去改代码、翻源码其实没必要。OpenCode 的配置入口设计得还算克制主要就两个地方一个是配置文件一个是环境变量。配置文件管结构环境变量管密钥。把这两个东西理顺第三方供应商接入就是十分钟的事。下面我按实际操作的顺序从整体设计思路讲到具体落地再到踩坑排查一层层拆开。2. 配置体系的整体设计与思路拆解2.1 OpenCode 的供应商抽象层是怎么设计的要配第三方 API先得理解 OpenCode 为什么要把供应商单独抽一层出来。这跟很多工具直接写死 API 地址不一样OpenCode 走的是适配器模式每个供应商对应一个适配器适配器负责把 OpenCode 内部的统一请求格式翻译成各家 API 能听懂的格式再把返回结果翻译回来。这么设计的好处很直接。第一换供应商不用改业务逻辑你从 A 家换到 B 家只要换配置代码一行不动。第二支持多供应商并存你可以同时配好几个按任务类型切换比如写代码用一个、写文档用另一个。第三密钥和结构分离配置文件里不写明文密钥密钥走环境变量这样配置文件可以进版本库、可以团队共享不怕泄露。我个人的判断是这套设计对个人用户来说稍微有点重但对需要长期维护、多人协作的场景非常友好。你如果只是自己用理解到供应商适配器凭证模型列表这个层面就够了。2.2 为什么优先选配置文件而不是命令行参数OpenCode 支持命令行临时指定供应商比如opencode --provider xxx但我不推荐日常这么用。原因有三个不可复用每次都要敲一长串容易漏参数尤其是模型名和 base URL 这种容易记错的。不利于版本管理配置文件可以提交到 Git命令行参数不行团队里每个人的习惯不一样统一配置能省很多沟通成本。调试困难出问题的时候配置文件是静态的一眼能看出配了什么命令行参数是动态的得回忆当时敲了什么。所以我的建议是把稳定配置写进配置文件把密钥写进环境变量命令行只用来做临时覆盖。这个原则贯穿整篇教程。2.3 第三方供应商接入的三种典型场景实际用下来第三方 API 供应商的接入大致分三类配置方式略有差异场景典型特征配置重点兼容 OpenAI 协议大多数国产模型、自建服务改 base URL模型名对齐兼容 Anthropic 协议Claude 系及部分兼容服务注意 header 和版本字段完全自定义协议企业内部网关、私有部署需要写适配器或走代理层绝大多数人遇到的是第一类。兼容 OpenAI 协议意味着请求体结构、鉴权方式、返回格式都跟 OpenAI 一致你只要把baseURL指向供应商给的地址把apiKey换成自己的模型名填对基本就能跑。这也是为什么我建议新手从这类供应商入手成功率最高。3. 核心细节解析与实操要点3.1 配置文件的位置与结构OpenCode 的配置文件通常放在用户目录下的配置文件夹里具体路径跟操作系统有关。Linux 和 macOS 一般在~/.config/opencode/下面Windows 在%APPDATA%\opencode\下面。文件名常见的是config.json或者opencode.json具体以你安装的版本为准装完之后可以先跑一次opencode --help或者翻一下安装目录确认它读的是哪个文件。配置文件的结构是 JSON顶层一般有provider字段下面挂各个供应商的配置。一个典型的骨架长这样{ provider: { my-provider: { type: openai-compatible, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_PROVIDER_KEY} }, models: { my-model: { name: 实际模型名 } } } } }这里有几个细节值得说。type字段决定用哪个适配器兼容 OpenAI 的填openai-compatible。baseURL一定要带对版本路径很多供应商是/v1结尾漏了会 404。apiKey里写{env:XXX}是 OpenCode 的变量插值语法意思是运行时从环境变量XXX读取这样配置文件里就没有明文密钥。注意不同版本的 OpenCode 字段名可能有细微差异比如有的版本用npm字段指定适配器包有的用type。配置前最好对照你那个版本的官方示例别照搬网上的老配置。3.2 环境变量的设置与隔离密钥走环境变量是这套体系的安全底线。设置方式分临时和永久两种。临时的话在当前终端里export MY_PROVIDER_KEYsk-xxxx关掉终端就没了适合测试。永久的话写进 shell 的配置文件比如~/.bashrc、~/.zshrc或者 Windows 的系统环境变量里。我强烈建议按供应商分别命名环境变量比如PROVIDER_A_KEY、PROVIDER_B_KEY不要所有供应商共用一个API_KEY。原因很简单一旦你要换供应商或者临时禁用某一个共用变量会让你分不清哪个 Key 对应哪个服务排查起来很痛苦。而且多个供应商并存的时候共用变量根本没法区分。还有一个容易忽略的点环境变量的作用域。如果你在 IDE 里用 OpenCode 插件IDE 启动时继承的环境变量可能跟你终端里不一样。这时候要么在 IDE 的配置里单独指定要么把变量写到系统级别。我踩过这个坑终端里跑得好好的一到 IDE 里就报鉴权失败查了半天才发现是环境变量没继承过去。3.3 模型名的对齐问题模型名这块是最容易出错的地方。OpenCode 配置里的模型名跟你实际调用的模型名可能不是一回事。配置里的 key 是你自己起的别名name字段才是真正发给供应商的模型标识。举个例子供应商文档里写的模型是deepseek-chat你配置里可以写成models: { fast: { name: deepseek-chat } }这样你在 OpenCode 里选fast就行实际发出去的是deepseek-chat。这么做的好处是换供应商的时候只改 name不用改你日常用的别名。我习惯按用途起别名比如fast、smart、cheap这样切换模型的时候心智负担小。要特别小心的是模型名的大小写和连字符。有些供应商对模型名大小写敏感GPT-4和gpt-4可能一个能用一个报错。配置完先用一个最简单的请求测一下别等到正式用的时候才发现。4. 实操过程与核心环节实现4.1 从零开始一次完整的第三方供应商接入我拿一个兼容 OpenAI 协议的供应商做例子把完整流程走一遍。假设供应商给的 base URL 是https://api.example.com/v1模型是example-large密钥是sk-abc123。第一步设置环境变量。在终端里执行export EXAMPLE_API_KEYsk-abc123验证一下有没有生效echo $EXAMPLE_API_KEY能打印出密钥就说明设置成功。这一步别跳过很多人配置失败就是因为环境变量根本没设上。第二步编辑配置文件。找到 OpenCode 的配置文件加入供应商配置{ provider: { example: { type: openai-compatible, options: { baseURL: https://api.example.com/v1, apiKey: {env:EXAMPLE_API_KEY} }, models: { large: { name: example-large } } } } }第三步验证配置。跑一个最简单的命令比如让 OpenCode 解释一段代码或者直接问它一个问题。如果返回正常说明配置成功。如果报错看错误信息里的关键词401是鉴权问题404是地址问题400多半是模型名或者请求格式问题。第四步固化配置。测试通过之后把环境变量写进 shell 配置文件把配置文件提交到你的 dotfiles 仓库记得确认里面没有明文密钥。4.2 多供应商并存的配置策略手里有好几个供应商的时候配置文件的组织方式很关键。我的做法是按供应商分组按用途起别名。比如{ provider: { provider-a: { type: openai-compatible, options: { baseURL: https://api.a.com/v1, apiKey: {env:PROVIDER_A_KEY} }, models: { fast: { name: a-fast-model }, smart: { name: a-smart-model } } }, provider-b: { type: openai-compatible, options: { baseURL: https://api.b.com/v1, apiKey: {env:PROVIDER_B_KEY} }, models: { fast: { name: b-fast-model }, smart: { name: b-smart-model } } } } }这样两个供应商都有fast和smart两个别名切换的时候只要指定供应商和别名就行。实际用的时候我会根据任务类型选写代码用 A 家的 smart写文档用 B 家的 fast成本和质量都能兼顾。提示多供应商配置的时候注意别让别名冲突。如果两个供应商都叫fast切换的时候要同时指定供应商名否则 OpenCode 可能不知道你指的是哪个。4.3 参数调优超时、重试与并发配置能跑通只是第一步实际用起来还得调几个参数。最常调的是超时时间和重试次数。第三方供应商的网络质量参差不齐默认超时可能太短请求还没返回就断了。超时一般在options里配options: { baseURL: https://api.example.com/v1, apiKey: {env:EXAMPLE_API_KEY}, timeout: 60000 }timeout单位是毫秒60000 就是 60 秒。我一般设 60 到 120 秒太短容易误判失败太长卡着难受。重试次数看供应商的稳定性稳定的设 1 到 2 次不稳定的设 3 次但要注意重试会消耗额度别设太多。并发这块OpenCode 本身对并发有控制但如果你同时跑多个任务供应商那边可能有速率限制。遇到429错误就是被限流了这时候要么降低并发要么换供应商要么等一会儿再试。4.4 验证配置是否生效的三种方法配置完怎么确认真的生效了我常用三种方法看日志OpenCode 一般有日志输出能看到实际请求发到了哪个地址、用了哪个模型。日志里如果出现你配的 base URL说明配置被读到了。发测试请求让 OpenCode 做一个最简单的任务比如用一句话解释什么是递归看返回是否正常。对比响应同一个问题分别用不同供应商问一遍看回答风格和速度有没有差异能间接验证是不是真的走了你配的供应商。这三种方法我一般组合用日志确认配置读取测试请求确认连通对比响应确认路由正确。5. 常见问题与排查技巧实录5.1 报错信息速查表配置过程中遇到的报错八成集中在下面这几类。我整理成表方便对照排查报错关键词可能原因排查方向401 Unauthorized密钥错误或未读取到检查环境变量是否生效密钥是否过期403 Forbidden密钥权限不足确认密钥是否有该模型的调用权限404 Not Foundbase URL 错误检查是否漏了/v1或路径拼错400 Bad Request模型名或请求格式错误核对模型名大小写检查请求体结构429 Too Many Requests触发速率限制降低并发或等待后重试free tier can only be used from within opencode用了免费额度但不在官方壳里换成第三方供应商配置别用免费额度timeout网络慢或超时设置太短加大 timeout检查网络连通性这张表我建议存下来遇到报错先对号入座能省很多时间。5.2 密钥读取失败的排查思路密钥读取失败是最常见的问题表现是明明设了环境变量OpenCode 还是报鉴权错误。排查顺序我一般是这样的确认变量名一致配置文件里写的是{env:EXAMPLE_API_KEY}环境变量就得叫EXAMPLE_API_KEY大小写、下划线都不能错。确认作用域在跑 OpenCode 的那个终端里echo一下变量能打印出来才算设上。如果是 IDE 里跑确认 IDE 继承了环境变量。确认没有多余字符复制密钥的时候容易带上空格或者换行用echo $VAR | wc -c看长度对不对。确认配置文件被读取有的版本会读多个位置的配置文件确认你改的是它实际读的那个。我踩过最坑的一次是配置文件里写的是{env:EXAMPLE_API_KEY}但环境变量设成了EXAMPLE_KEY少了个API查了半小时才发现。所以变量名一定要仔细核对。5.3 模型切换后行为异常的排查有时候配置都对了但切换模型之后行为不对劲比如回答质量突然变差、或者干脆不返回。这种情况我一般从三个方向查模型名是否真的存在有些供应商的模型名跟文档不一致或者有版本后缀比如model-v2和model是两个不同的东西。上下文长度是否超限不同模型的上下文窗口不一样长对话切到小窗口模型会截断或者报错。供应商是否支持该功能有些模型不支持函数调用或者流式输出OpenCode 如果默认开了这些功能就会出问题。排查的时候先用一个短问题测排除上下文长度的影响再关掉流式输出测排除功能兼容问题。逐步缩小范围比盲目改配置高效得多。5.4 几个我踩过的坑和独家技巧说几个文档里不会写、但实际很实用的经验。第一个坑配置文件里的注释。JSON 标准不支持注释但有些 OpenCode 版本用的是 JSONC带注释的 JSON。如果你在标准 JSON 里加了注释解析会失败报错信息还不明显。我的做法是不确定的时候就不写注释把说明写在单独的 README 里。第二个坑base URL 的尾斜杠。https://api.example.com/v1和https://api.example.com/v1/在某些供应商那里行为不一样前者正常后者可能 404。配置的时候统一不带尾斜杠能避免大部分问题。第三个技巧用 curl 先验证供应商。配置 OpenCode 之前先用 curl 直接调一下供应商的接口确认密钥和地址没问题。这样能把供应商问题和OpenCode 配置问题分开排查效率翻倍。命令大概是这样curl https://api.example.com/v1/chat/completions \ -H Authorization: Bearer $EXAMPLE_API_KEY \ -H Content-Type: application/json \ -d {model:example-large,messages:[{role:user,content:hi}]}能返回正常结果说明供应商侧没问题问题就在 OpenCode 配置上。第四个技巧配置备份。改配置之前先备份一份改坏了能快速回滚。我习惯用 Git 管理配置文件每次改动都有记录出问题能 diff 出改了什么。第五个技巧关注版本更新。OpenCode 迭代比较快配置字段偶尔会变。升级版本之后先跑一次验证确认配置还兼容。遇到字段废弃的及时改别等到报错了才处理。6. 配置之外的延伸思考6.1 数据安全与密钥管理第三方 API 供应商接入之后你的代码和对话内容会发到供应商的服务器上。这一点必须心里有数。我的做法是敏感项目不接第三方或者接之前先脱敏。密钥管理上除了环境变量还可以考虑用系统的密钥管理工具比如 macOS 的 Keychain、Linux 的 secret-tool把密钥存进去环境变量里只放一个读取命令。团队协作的时候配置文件可以共享但密钥绝对不能进版本库。用.gitignore把包含密钥的文件排除掉或者用模板文件加本地覆盖的方式模板进库实际配置不进库。6.2 成本控制与用量监控第三方供应商大多是按量计费的用起来爽账单也可能吓人。我一般会做两件事一是给每个供应商设预算上限很多供应商后台支持设置月度限额超了就停二是定期看用量报表发现异常增长及时查原因。OpenCode 本身不一定有用量统计但供应商后台一般都有养成定期看的习惯。6.3 后续可以怎么扩展配置跑通之后还能做不少延伸。比如把配置模板化写一个脚本输入供应商信息就自动生成配置比如做多供应商的自动切换主供应商挂了自动切备用比如把配置和团队的工作流结合不同项目用不同的供应商配置。这些都属于锦上添花先把基础配置跑稳再考虑这些。我个人在实际操作中的体会是OpenCode 的第三方供应商配置难点不在配置本身而在排查。配置就那么几个字段但出错的时候原因可能有很多层。把排查思路理顺比记住配置语法更重要。上面那张报错速查表和 curl 验证法是我用得最多的两个工具基本能覆盖八成的问题。剩下的两成多半是版本差异或者供应商侧的临时问题遇到的时候别慌一步步缩小范围就行。