1. OpenCode 配置第三方 API 时 provider 到底卡在哪OpenCode 是一个跑在终端里的 AI 编码 CLI能读项目文件、执行命令、按你的指令改代码。它默认对接的是官方渠道但很多本地开发者想把它接到第三方 API 上原因很直接统一管理 Key、按量计费、或者团队里已经在用某个兼容 OpenAI 协议的服务。问题就出在“接第三方”这一步——provider 配置环节。我见过太多人卡在同一处照着文档敲/connect翻到列表底部找Other结果发现它根本不是一个能直接选中的条目而是一个分类名。你按回车没反应或者选完让你输 provider id 之后流程就断了。这不是你操作错了是文档和当前 CLI 版本的行为对不上。OpenCode 的 provider 体系分两层一层是认证信息credential存在 auth 文件里另一层是 provider 定义baseURL、npm 适配包、模型列表写在opencode.json里。/connect只处理第一层而且对自定义 provider 的支持不完整所以你会觉得“明明填了却用不了”。这篇要解决的就是这个具体场景你在 macOS 或 Linux 终端里已经装好 opencode手里有一个第三方 API 的 Base URL 和 Key想把它配成默认 provider 并跑通一次请求。我会给出可复制的opencode.json片段、Base URL 该填在哪一行、以及一条验证连通性的命令和预期返回。适合已经会用命令行、但被 provider 配置绕进去的开发者。核心检索词就三个OpenCode、第三方 API、provider 配置文件。读完你能自己定位 401、模型找不到、baseURL 拼错这几类高频错误。先说清楚一个前提第三方 API 这里指的是兼容 OpenAI 或 Anthropic 接口协议的服务不是让你去搞什么网络层的东西。你只需要一个正常的 HTTPS 地址和 Key剩下的都是配置文件的事。TaoToken 就是这类兼容服务的一个例子它的 API 地址是https://taotoken.net/api后面我会用它做示例但你换成任何兼容服务步骤完全一样。2. TaoToken 前置准备Key、Base URL 和模型 ID 三件套在动配置文件之前你得先把三样东西拿到手缺一个后面都会报错。这三件套是Base URL、API Key、Model ID。很多人配置失败不是不会写 JSON而是这三样里有一个填错了位置或者格式。Base URL 是最容易出错的一个。OpenCode 的 provider 配置里baseURL字段需要指向服务的 API 根路径。以 TaoToken 为例它的 API 地址是https://taotoken.net/api但在 OpenCode 里通常要写成带/v1的形式也就是https://taotoken.net/api/v1。为什么因为 OpenCode 底层用的是 AI SDK 的 OpenAI 兼容适配器它会在这个 baseURL 后面拼/chat/completions。如果你只填到/api最终请求会打到https://taotoken.net/api/chat/completions少了/v1这一段服务端返回 404 或者路径不匹配。这个坑我踩过报错信息不会直接告诉你“少了个 v1”而是给你一个模糊的 not found。API Key 的获取入口在 TaoToken 的控制台里。你可以打开https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite登录后创建。创建时给它起个能认出来的名字比如opencode-local方便以后在列表里区分。Key 只在创建时完整显示一次复制下来先存到安全的地方别直接贴在聊天窗口或者提交到 git 里。Model ID 是你打算调用的具体模型标识。TaoToken 支持多种模型你需要在文档里确认你要用的那个模型的准确 ID 字符串。注意这个 ID 是服务端认的标识不是你随便起的显示名。比如你看到文档里写的是某个模型 ID那配置里models下面的键名就得用这个 ID而name字段才是给人看的显示名。这两个别搞混搞混的后果是 OpenCode 找不到模型报model not found。三件套齐了之后建议先在终端里用 curl 单独验证一次确认 Key 和 Base URL 本身是通的再去改 OpenCode 配置。这样能把“服务端问题”和“配置文件问题”分开排障效率高很多。验证命令长这样curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: ping}] }如果这条命令返回了正常的 JSON里面有choices字段说明三件套没问题可以进入下一步。如果返回 401那是 Key 的问题返回 404大概率是路径问题返回模型相关错误那是 Model ID 写错了。这一步花两分钟能省掉后面半小时的瞎猜。3. 可复制的 opencode.json provider 配置片段现在进入正题改配置文件。OpenCode 的全局配置在~/.config/opencode/opencode.json。如果这个文件不存在手动创建即可。注意路径是opencode目录下的opencode.json不是项目根目录那个。项目级的配置可以覆盖全局但 provider 这种认证相关的东西放全局更省事。先给一个完整的、可以直接抄的配置模板把里面的占位符换成你自己的值{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api/v1, setCacheKey: true }, models: { 你的模型ID: { name: 你的模型显示名, limit: { context: 128000, output: 16384 } } } } }, model: taotoken/你的模型ID }逐字段说清楚避免你抄错。provider下面的taotoken是你给这个 provider 起的 ID全小写、无空格、无特殊字符。这个 ID 会出现在最后的model字段里格式是providerID/modelID。npm字段指定用哪个适配包第三方兼容 OpenAI 协议的服务统一用ai-sdk/openai-compatible。如果你接的是 Anthropic 原生协议才改成ai-sdk/anthropic但大多数第三方平台都是 OpenAI 兼容所以这个值基本不用动。options.baseURL就是前面强调的填到/v1这一层。setCacheKey设为 true 可以让相同请求命中缓存省钱也提速建议保留。models下面的键名必须是服务端认的模型 IDname是显示名limit里的context和output按你所用模型的实际能力填填大了服务端会拒绝填小了浪费上下文。不确定的话先填一个保守值跑通再调。model字段是全局默认模型格式taotoken/你的模型ID必须和上面 provider ID、models 键名完全对应。这里错一个字符OpenCode 启动时就找不到模型。如果你之前用opencode auth login走过认证流程Key 已经存在 auth 文件里了那配置文件里不需要再写 Key。但如果你想让配置自包含也可以在options里加apiKey字段。不过更推荐用 auth 流程存 Key避免明文写在 JSON 里被误提交。auth 文件的位置在~/.local/share/opencode/auth.json这个文件权限建议设成 600。改完配置后别急着跑先用opencode启动一次看它有没有报配置解析错误。JSON 格式错一个逗号整个文件就废了。可以用python -m json.tool ~/.config/opencode/opencode.json快速校验格式返回格式化后的 JSON 就说明语法没问题。4. 验证请求一条命令确认 provider 连通性配置写好了怎么确认它真的通了最直接的办法是在 OpenCode 里发一条最简单的请求看它能不能返回内容。启动 opencode 后直接输入一句ping或者say hello回车。如果配置正确你会看到模型开始流式输出回复。如果卡住不动或者立刻报错那就是配置还有问题。但更可控的验证方式是在终端里用 OpenCode 的非交互模式跑一次。OpenCode 支持opencode run这种一次性执行命令适合脚本化验证opencode run 回复一个字好 --model taotoken/你的模型ID预期返回是模型输出的那个字比如好。如果这条命令成功说明 provider 配置、认证、模型 ID、baseURL 全部正确。如果失败它会打印错误信息你根据错误类型去第 5 节对照排查。还有一种情况你想确认 OpenCode 到底把请求发到了哪个地址。可以在启动时加调试环境变量让它打印底层 HTTP 请求。不同版本变量名可能不同常见的是DEBUG*或者OPENCODE_LOGdebug。加上之后你会看到类似POST https://taotoken.net/api/v1/chat/completions的日志。如果这里显示的 URL 和你预期的不一样比如少了/v1或者多了重复路径那就是baseURL拼错了回去改配置文件。验证通过后建议把这条opencode run命令存成一个 shell alias比如alias octestopencode run 回复一个字好 --model taotoken/你的模型ID。以后每次改完配置跑一下这个 alias两秒就知道有没有搞坏。这个习惯能帮你在频繁调整模型或 Key 的时候快速回归。另外提一句如果你在 OpenCode 里同时配了多个 providermodel字段决定默认用哪个。想临时切换可以在启动时用--model参数覆盖不用改配置文件。这个在对比不同模型效果时很好用。5. 常见报错对照401、local proxy failed、reading choices、OAuth配置过程中会遇到的错误其实就那么几类每一类都有明确的指向。下面按报错原文对照你看到哪条就查哪条。401 Unauthorized。这是认证失败Key 不对或者没带上。先确认 auth 文件里存的 Key 和你在控制台创建的一致。如果你是在options里直接写的apiKey检查有没有多余空格或者引号。还有一种可能是 Key 被禁用或额度耗尽去控制台看一眼状态。TaoToken 的 Key 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite可以重新生成一个替换测试。local proxy failed。这个报错通常出现在 OpenCode 尝试通过本地代理转发请求但失败的时候。它和你的 provider 配置关系不大更多是环境变量里有HTTP_PROXY或HTTPS_PROXY指向了一个不可用的地址。检查你的 shell 配置把无关的代理变量清掉再试。注意这里说的是本地环境变量清理不是让你去搞什么网络层的东西纯粹是排除干扰项。reading choices 相关错误。完整报错可能是Cannot read properties of undefined (reading choices)。这说明请求发出去了但返回的 JSON 结构里没有choices字段。原因通常是 baseURL 路径不对请求打到了错误的端点返回了一个 HTML 错误页或者别的 JSON 结构。回去检查baseURL是不是精确到/v1以及模型 ID 是否被服务端识别。用第 2 节的 curl 命令单独测一次能快速定位是服务端还是配置的问题。OAuth 相关报错。如果你之前用opencode auth login选过某个 OAuth 类型的 providerauth 文件里可能残留了旧的 token 结构和现在的 API Key 认证冲突。解决办法是删掉~/.local/share/opencode/auth.json里对应的条目或者干脆备份后清空这个文件重新走一次opencode auth login选Other输入 Key。清空 auth 文件不会影响opencode.json里的 provider 定义两者是分开的。model not found。这个最直接就是model字段里的 ID 和models下面的键名对不上或者服务端根本不认这个模型 ID。逐字符核对注意大小写。有些服务端的模型 ID 是区分大小写的。配置文件解析失败。OpenCode 启动时报 JSON parse error那就是opencode.json语法错了。用python -m json.tool校验它会告诉你第几行出错。常见的是尾随逗号、中文引号、注释没删干净。JSON 标准不支持注释别在里面写//。把这几类错误对照一遍基本能覆盖 90% 的配置问题。剩下的 10% 大概率是服务端临时故障隔几分钟重试或者换个模型 ID 试试。6. 配好之后把 OpenCode 用顺手的几个实际技巧配置跑通只是起点真正让 OpenCode 在本地开发里发挥作用还得知道怎么用它。这里说几个我实际用下来觉得有用的点。第一把常用模型配成多个 provider 条目用--model切换。比如你同时有快速模型和强推理模型在provider.taotoken.models下面都列出来日常用快的遇到复杂重构再切强的。不用改配置文件命令行参数覆盖就行。第二OpenCode 读项目文件的能力依赖当前工作目录。在项目根目录启动它它才能正确索引代码。如果你在子目录启动它可能看不到上层文件。养成cd到项目根再跑opencode的习惯。第三长会话注意上下文消耗。limit.context填的是模型上限但实际对话里每一轮都会累积 token。如果发现响应变慢或者报上下文超限用/clear或者重启会话。别让一个会话跑太久该开新的就开新的。第四Key 的轮换。如果你在团队里共用建议每人用自己的 Key方便在控制台看用量和排查。TaoToken 的控制台可以创建多个 Key按人或者按项目分。这样出问题的时候能快速定位是谁的请求异常。第五配置备份。~/.config/opencode/opencode.json改好之后复制一份到 dotfiles 仓库里。换机器或者重装系统时直接拉下来就能用省得重新配一遍。注意别把 Key 一起提交Key 走 auth 文件或者环境变量。最后如果你在配置过程中遇到本文没覆盖的报错可以去 TaoToken 的接入文档里对照接口说明地址是https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。文档里有完整的请求示例和参数说明配合本文的配置步骤基本能解决所有接入问题。配好之后OpenCode 就能稳定调用你指定的模型本地开发的效率提升是实打实的。