快速解决OpenCode配置第三方API

前言

最近在 Mac 上配置 OpenCode 第三方 API 时踩了一个坑：

明明官方文档写着可以通过 /connect 添加自定义提供商，但实际操作时却发现 "Other" 并不是一个可直接选择的选项，导致整个流程卡住。

我折腾了一圈，最后在 GitHub Issues 里找到了可行方案，并成功完成配置。这里把完整排查和解决过程整理出来，方便遇到同样问题的朋友少走弯路。

环境说明

操作系统：macOS
使用方式：CLI
已安装：opencode

问题现象

我在 CLI 中安装好 opencode 后，按照提示：

按下 ctrl + p 打开 commands
输入 /connect
尝试连接 API 提供商

此时我发现一个问题：
列表中并没有第三方 API 供应商的直接选项。

于是我去查了 OpenCode 官方文档：

文档中提到，自定义提供商的方式是：

执行 /connect
向下滚动到 Other
输入 provider id
后续继续配置

文档示意如下：

bash 复制代码

$ /connect

┌  Add credential
│
◆  Select provider
│  ...
│  ● Other
└

接着输入 provider id：

bash 复制代码

$ /connect

┌  Add credential
│
◇  Enter provider id
│  myprovider
└

看起来似乎很简单，但实际操作并不是这样。

实际踩坑点

问题出在这一步：

文档里写的是"选择 Other"，但在实际 OpenCode 中，Other 其实是一个类别名，而不是一个可以直接选中的具体选项。

这就导致官方文档里的流程，在当前实际版本里并不能顺利走通。

排查过程

既然官方文档走不通，我继续去搜索相关问题，最后在 OpenCode 的 GitHub Issues 里找到了同样的报错和讨论：

根据该 Issue 中的方法，我最终成功完成了第三方 API 的配置。

最终解决方法

第一步：不要用 `/connect`，改用登录命令

在 CLI 中执行：

bash 复制代码

opencode auth login

通过这个命令进入认证流程后，弹出的选项中，"Other" 这次是可以真正被选择的。

第二步：选择 `Other`

在弹出的供应商列表中，选择：

text 复制代码

Other

第三步：输入供应商 ID

接下来会要求输入 Provider ID，也就是你给这个第三方 API 取的唯一标识名。

例如：

text 复制代码

myapi

注意几点：

建议自定义命名，方便后续识别
只能使用小写字母和数字
不要有空格或特殊字符

第四步：输入 API Key

输入你所使用的第三方平台提供的 API Key。

这一步完成后，认证信息就会被写入 OpenCode 的配置中。

第五步：手动编辑配置文件

打开配置文件：

bash 复制代码

~/.config/opencode/opencode.json

然后按你的第三方 API 平台信息，补充 provider 和 model 配置。

配置模板

下面是通用模板：

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "<your-provider-id>": {
      "npm": "@ai-sdk/openai",
      "name": "<Provider Display Name>",
      "options": {
        "baseURL": "<your-api-base-url>/v1",
        "setCacheKey": true
      },
      "models": {
        "<model-id>": {
          "name": "<Model Display Name>",
          "limit": {
            "context": 154840,
            "output": 16384
          }
        }
      }
    }
  },
  "model": "<your-provider-id>/<model-id>"
}

配置示例

比如我使用一个自定义 provider：myapi，模型为 gpt-4o，那么可以这样写：

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Custom API",
      "options": {
        "baseURL": "https://api.example.com/v1",
        "setCacheKey": true
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": {
            "context": 1048576,
            "output": 65535
          }
        }
      }
    }
  },
  "model": "myapi/gpt-4o"
}

注意事项

1. `npm` 包名要根据你的 API 类型调整

配置里的这一项：

json 复制代码

"npm": "@ai-sdk/openai"

不适合所有第三方供应商。

常见情况有：

如果你接的是 OpenAI 原生接口，不一定有问题
如果你接的是 Anthropic 相关接口，可能要改成：

json 复制代码

"npm": "@ai-sdk/anthropic"

但大多数第三方平台，实际上提供的是 OpenAI 兼容接口，此时应使用：

json 复制代码

"npm": "@ai-sdk/openai-compatible"

2. `model` 字段要和上面 provider、models 对应

例如你上面定义的是：

provider id：myapi
model id：gpt-4o

那么这里就必须写：

json 复制代码

"model": "myapi/gpt-4o"

否则 OpenCode 无法正确找到默认模型。

快速解决OpenCode配置第三方API