OpenCode 自定义 API 怎么接？模型不显示时这样查

OpenCode 接自定义 API，需要登记凭证、声明 provider 和模型，再用 provider_id/model_id 选择模型。 先运行 opencode --version，因为常规文档和 v2 文档的配置字段不同，不能混着抄。

本文于 2026 年 9 月 9 日核对常规 Providers 文档和 v2 文档。两套文档存在，不代表 v2 已是 npm 最新稳定版，也不代表所有安装都要升级。下方是带占位值的文档配置示例，不是付费调用实测。

还没决定在哪里开通 API？先看 OpenCode API 供应商与计费比较，再添加凭证。

先确认安装版本

opencode --version

出现未知配置字段时，先核对执行文件与文档版本。不要只改一个键名：包名和选项也属于对应版本的配置。常规文档采用 opencode.json，不要混用其他工具的配置格式。

登记凭证后，还要声明 provider

按常规文档，在 OpenCode 内运行 /connect，选择 Other，输入 provider ID，例如 myprovider，再按提示输入 Key。这个 ID 要和配置中的供应商键名一致。

/connect 保存的是凭证，不会替你补齐所有自定义模型配置。在项目目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My provider",
      "options": {
        "baseURL": "https://api.example.com/v1"
      },
      "models": {
        "your-model-id": { "name": "My coding model" }
      }
    }
  },
  "model": "myprovider/your-model-id"
}

将 https://api.example.com/v1 换成供应商文档中的真实 API 地址，将 your-model-id 换成可用型号。这里都是占位值，原样复制不能调用服务。不要把网站首页填成 API 地址。

示例读取 /connect 登记的凭证，不必把 Key 写进 JSON。供应商已内置时，其官方连接流程可能更简单。Ofox 的端点可在 SDK 文档核对，远程模型 ID 以目录为准；OpenCode 的配置格式仍按本教程对应版本填写。

运行包要匹配协议

常规文档中，@ai-sdk/openai-compatible 对应兼容 /v1/chat/completions 的服务；使用 /v1/responses 的供应商或模型，文档指定 @ai-sdk/openai。Key 的外观不能说明服务使用哪种协议。

端点、凭证和型号要一起核对。网关上不同模型不一定支持相同请求格式、工具调用和上下文限制，不能宣传改一个 model 就能让任意任务无缝切换。

选择刚声明的模型

配置完成后，在 OpenCode 内运行 /models。模型文档规定的选择形式是 provider_id/model_id，示例即 myprovider/your-model-id，两部分都要匹配配置键名。

界面显示的 name 是标签，改标签不会让远端多出一个型号。如果网关型号本身带供应商前缀和斜杠，应按该服务文档保留完整 ID。

模型没出现，按这张表查

常规流程可用 opencode auth list 查看凭证条目，不要打印 Key 内容。改了配置或密钥后，重启相关进程并检查模型列表。

缓存过旧可以作为排查方向，但不是通用答案。不能把某个历史版本的观察写成“第一次一定失败，跑两次一定好”。

使用 v2 时，整套迁移

按 v2 文档使用完整配置。除映射、包名和选项外，文档还用 modelID 指定发给供应商的远端 ID，不要未经核实把它塞进旧版配置。

先备份可用配置，再同时调整对应版本的字段，确认配置加载和模型选择，最后才发送真实任务。JSON 能读取，不等于凭证和远端工具调用已经通过。

其他终端工具可参考 Pi 自定义供应商配置。连接正常但被限流时，看 429 何时该重试。