找不到 OpenCode 提供商：修复模型 ID

对于 OpenCode 的 provider 或 model not found 错误，首先将所选模型与 OpenCode 实际加载的 provider 和模型 ID 进行匹配。该引用通常采用 providerId/modelId 的形式。正确的 API key 无法修复拼写错误的 ID、未声明的自定义模型，或运行进程从未读取的配置文件。

遵循错误本身，而不只是短语“provider problem”

你看到的情况	首先检查的分支
`ProviderModelNotFoundError`	Provider/model 身份、已加载目录和模型适配器
v2：模型不可用	未启用的 provider、缺失或禁用的模型、发现机制变化或别名
`ProviderInitError`	Provider 包和初始化配置
端点返回 HTTP 401 或 403	凭据、主机和账户权限
HTTP 429 或计费消息	响应 provider 的速率和支出限制

官方故障排除指南将 model-not-found 错误指向模型引用。在 provider 源代码中，查找会同时检查 provider 条目及其模型映射。同一个错误也可能包装适配器的缺失模型错误。在更改凭据或购买更多额度之前，请记录确切的错误消息。

1. 确认版本和所选模型

请从发生故障的项目中运行这些检查。如果桌面应用使用不同的服务器，请将其版本和配置与此终端安装进行比较：

检查相同的安装和项目

opencode --version
opencode models
opencode auth list

在列表中找到完整的模型引用，然后逐字符与您的选择进行比较。provider 前缀是身份的一部分。通过自定义网关提供的模型不会仅仅因为名称包含 Claude，就变成内置的 Anthropic provider。

不要将已保存的凭据解释为远程身份验证成功的证明。它只能证明本地存在凭据；发出请求时，端点仍必须接受该凭据。

2. 修复 provider/model 配对

此示例使用 v1 provider 格式，并展示三个相匹配的标识符。请在启动 OpenCode 的进程中设置所引用的环境变量，或使用文档所述的凭据流程。将相关字段合并到配置中，而不是覆盖无关设置：

v1 风格的 opencode.json——提供商和模型标识

{
  "$schema": "https://opencode.ai/config.json",
  "model": "kunavo/claude-sonnet-5",
  "provider": {
    "kunavo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kunavo",
      "options": {
        "baseURL": "https://api.kunavo.com/v1",
        "apiKey": "{env:KUNAVO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5"
        }
      }
    }
  }
}

这里，kunavo 是 provider key，claude-sonnet-5 是 model key。因此，所选项是 kunavo/claude-sonnet-5。选择 anthropic/claude-sonnet-5 会选择不同的 provider；选择 Kunavo/Claude Sonnet 5 会用显示名称替代查找 key。两者都不是上方显示的条目。

使用 /connect 和 Other 作为自定义 provider 时，请输入相同的 provider ID。凭据本身不会定义模型目录。还请检查适配器：此处显示的 v1 兼容适配器使用 Chat Completions；Responses 端点需要相应的适配器。

3. 分开保存 v1 和 v2 配置

v2 provider 文档使用 providers、package 和 settings，而不是 v1 的 provider、npm 和 options。请使用对应版本的设置方式，不要将前面的代码块原样复制到 v2 配置中。

在 v2 中，模型的映射 key 也可以与上游 modelID 不同。如果映射包含 coder 并发送上游模型 upstream/coder-v2，请为 provider company 选择 company/coder。将选择改为上游名称会绕过已配置的别名。

4. 检查哪个配置生效

OpenCode 会合并配置来源。项目文件可以覆盖全局模型；自定义路径、内联配置和托管设置也可能产生影响。请检查失败项目的文件、全局配置及任何已配置的覆盖项。检查 provider 允许列表或已禁用 provider 条目。

进行一次有针对性的更改，重启受影响的进程，然后再次列出模型。如果模型现在可用，但第一次请求返回 HTTP 错误，请根据这个新错误继续排查。诊断期间请保留原始文件和会话数据；删除整个数据目录可能会移除凭据和历史记录，却无法修复错误的模型引用。

用一个小请求收尾

选择解析成功后，在执行仓库任务前先尝试一个简短提示。确认预期的 provider 收到了请求，并记录了预期模型。如果仍然失败，请收集版本、脱敏后的配置、确切错误和相关日志摘录。分享前请检查日志中是否包含 key 和项目内容。

对于 Kunavo，请继续阅读 OpenCode 集成指南，并检查您的使用记录。当前 Claude Sonnet 5 费率为每百万 token 输入 $1.40、输出 $7.00。客户端选择了预期路由后，价格比较才有意义。

常见问题

OpenCode 中的 ProviderModelNotFoundError 是什么意思？

OpenCode 无法解析所选的提供商/模型组合，或其模型适配器无法解析该模型。请先检查已加载的提供商 ID、模型键和当前配置，再判断是否是余额或 API 密钥问题。诸如 401 的提供商 HTTP 响应属于不同的诊断分支。

为什么添加 API 密钥后没有添加自定义模型？

已保存的凭据和提供商/模型定义用途不同。在 v1 自定义提供商流程中，通过 /connect 输入的提供商 ID 必须与配置键一致，模型必须在该提供商的 models 映射中声明。

我应该在 opencode.json 中使用 provider 还是 providers？

请与已安装版本的文档保持一致。v1 文档使用带有 npm 和 options 的 provider。v2 文档使用带有 package 和 settings 的 providers。混用两种格式并不是可靠的迁移方式；请遵循匹配的架构和 provider 指南。

为什么模型在一个项目中可用，在另一个项目中却不可用？

项目设置可以覆盖全局设置，而环境、内联或托管配置也可能影响结果。请从失败项目的工作目录检查所选模型和 provider 设置。如果桌面客户端连接到不同的服务器，也请检查该服务器的配置。

官方文档和提供者源代码的检查日期：2026 年 9 月 17 日。该示例说明配置标识；它不是端到端任务基准测试。