返回博客
OpenCodeOpenAI 兼容 API第三方 API多模型AI 编程API Key
更新于

OpenCode 接入第三方 API：自定义 Provider、多模型与常见报错

用 OpenCode 的 /connect、opencode.json 和 OpenAI 兼容 Provider 接入第三方 API，配置多个模型、默认模型、密钥和排错方法。

查看接入文档
OpenCode 接入第三方 API：自定义 Provider、多模型与常见报错

连接第三方 API，需要先在 OpenCode CLI/TUI 中用 /connect → Other 保存 Provider ID 和 API Key，再在 opencode.json 中配置相同的 Provider ID、Base URL 和模型。只保存 Key，模型不会自动出现在 /models 中。

下面以 nbility 为 Provider ID、https://api.nbility.ai/v1 为 Base URL。用模型广场中的实际 ID 替换 YOUR_MODEL_ID。配置后在 /models 选择 nbility/YOUR_MODEL_ID，先让它只读一个小文件。本站的短版配置见 OpenCode 接入文档；本文继续解释多模型和报错。

配置方式核对于 2026-10-14 的官方 Providers 文档。如果界面提示 Custom providers are unavailable on this server，先看下文的版本限制说明。

第一步：用 /connect 保存 API Key

在 OpenCode TUI 中输入：

/connect

如果列表中没有目标服务，滚动到 Other，然后：

  1. 输入唯一 Provider ID：nbility；
  2. 输入 API Key；
  3. 完成凭据保存。

此步骤只保存凭据，不会自动创建 Provider 配置。OpenCode 官方界面也会提示你继续配置 opencode.json。

你可以检查凭据是否存在：

opencode auth list

不要把真实 Key 写进项目配置、终端截图、Issue 或聊天记录。若不想使用 /connect 的凭据存储，可以在配置中引用环境变量：

export NBILITY_API_KEY="YOUR_API_KEY"

然后使用 OpenCode 的变量语法：

"apiKey": "{env:NBILITY_API_KEY}"

第二步：创建自定义 OpenAI 兼容 Provider

在项目根目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nbility": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Nbility",
      "options": {
        "baseURL": "https://api.nbility.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Primary Coding Model"
        }
      }
    }
  }
}

各字段的含义：

  • nbility：自定义 Provider ID，必须与 /connect 输入的一致；
  • npm：OpenCode 调用该协议使用的 AI SDK 包；
  • name：模型选择器里显示的名称；
  • options.baseURL：API 根地址，不是完整 Endpoint；
  • models：OpenCode 可以选择的模型映射；
  • YOUR_MODEL_ID：第三方服务真实识别的模型 ID。

使用 Nbility 时，Base URL 是：

https://api.nbility.ai/v1

不要写成：

https://api.nbility.ai/v1/chat/completions

适配器会根据协议拼接 Endpoint。把完整 Endpoint 当作 Base URL，容易产生重复路径和 404。

如果你还不熟悉这些字段，可先阅读什么是 OpenAI 兼容 API。

配置前先理解四个对象

OpenCode 的凭据、Provider、Base URL 与模型之间的关系

对象作用常见位置
Provider ID连接凭据与配置的唯一标识/connect 与 provider 键
Credential调用服务的 API KeyOpenCode 凭据存储或环境变量
Base URL第三方 API 根地址options.baseURL
Model ID网关实际识别的模型provider.<id>.models

OpenCode 用 /connect 保存的凭据位于：

~/.local/share/opencode/auth.json

这个文件包含秘密，不应提交到 Git。opencode.json 则负责描述 Provider 和模型。Provider ID 必须在两处完全一致，否则 OpenCode 无法把凭据与配置关联起来。

例如，本文统一使用：

Provider ID: nbility

Chat Completions 和 Responses API 如何选择？

这是 OpenCode 自定义 Provider 最容易配置错的地方。

OpenCode 官方文档明确区分：

/v1/chat/completions → @ai-sdk/openai-compatible
/v1/responses        → @ai-sdk/openai

如果服务或模型使用 Chat Completions，配置：

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

如果使用 Responses API，则配置：

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

不要只因为服务“兼容 OpenAI”就默认使用同一个包。协议不匹配时，可能出现请求字段错误、404、空内容、工具调用失败或流式解析异常。

混合场景下，OpenCode 支持在模型级别覆盖 provider.npm。实际配置前，应先确认第三方服务为每个模型提供的是哪个 Endpoint。

一次配置多个模型

OpenCode 在多个代码模型之间选择与切换

在同一个 Provider 下，可以定义多个模型：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nbility": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Nbility",
      "options": {
        "baseURL": "https://api.nbility.ai/v1"
      },
      "models": {
        "YOUR_FAST_MODEL_ID": {
          "name": "Fast Coding"
        },
        "YOUR_PRIMARY_MODEL_ID": {
          "name": "Primary Coding"
        },
        "YOUR_REASONING_MODEL_ID": {
          "name": "Deep Reasoning"
        }
      }
    }
  }
}

然后在 TUI 输入：

/models

OpenCode 使用完整格式标识模型：

provider_id/model_id

例如：

nbility/YOUR_PRIMARY_MODEL_ID

模型 ID 必须与第三方 API 实际返回的一致。可先查询：

curl https://api.nbility.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

不要把展示名称当成模型 ID。Primary Coding 可以随意命名，但 YOUR_PRIMARY_MODEL_ID 必须是网关认识的值。

设置默认模型和轻量模型

若希望项目启动后默认使用某个模型，可在顶层设置 model：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "nbility/YOUR_PRIMARY_MODEL_ID",
  "small_model": "nbility/YOUR_FAST_MODEL_ID",
  "provider": {
    "nbility": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Nbility",
      "options": {
        "baseURL": "https://api.nbility.ai/v1"
      },
      "models": {
        "YOUR_PRIMARY_MODEL_ID": {
          "name": "Primary Coding"
        },
        "YOUR_FAST_MODEL_ID": {
          "name": "Fast Coding"
        }
      }
    }
  }
}

一个实用的分层策略是：

  • 轻量模型：标题、摘要、简单检索与小修改；
  • 主力模型：日常代码生成、排错和测试；
  • 强推理模型：架构设计、跨文件重构和复杂故障。

但模型能否胜任 OpenCode，不只取决于代码能力，还取决于 Tool Calling、长上下文与结构化输出。普通对话表现好，不代表 Agent 工具链一定稳定。

全局配置还是项目配置？

OpenCode 支持 JSON 和 JSONC，并会合并多个配置源。常用位置是：

全局：~/.config/opencode/opencode.json
项目：项目根目录/opencode.json

全局配置适合个人通用的 Provider、模型和权限；项目配置适合仓库专属模型或策略。官方文档说明，项目配置会覆盖全局配置中的冲突键，但不冲突的设置会被保留。

项目配置可以提交到 Git，但前提是里面没有真实凭据。推荐：

"apiKey": "{env:NBILITY_API_KEY}"

而不是：

"apiKey": "sk-real-secret"

如果项目不需要显式 apiKey，优先通过 /connect 保存凭据，让公开配置只包含 Provider 结构。

如何验证配置真的可用？

不要直接让 Agent 执行大规模重构。按层验证：

1. 验证服务本身

curl https://api.nbility.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

再发送最小聊天请求，确认 Base URL、Key、模型与 Endpoint 可用。

2. 验证 OpenCode 凭据

opencode auth list

确认列表中存在 nbility。

3. 验证模型发现

启动 OpenCode，输入：

/models

检查自定义 Provider 与模型是否出现。

4. 验证基础对话

先要求模型只解释一段小代码，不调用工具。

5. 验证 Agent 能力

依次测试：

读取文件
→ 搜索项目
→ 修改一个小文件
→ 运行测试
→ 多文件任务

每一步都成功后，再把它用于真实仓库。

常见错误排查

OpenCode 第三方 Provider 的认证、地址、模型与工具调用排错面板

“This only stores a credential. Configure the provider in opencode.json to use it.”

这是下一步配置提示。/connect 只存 Key；还需要上面的 provider.nbility、options.baseURL 和至少一个 models 条目。确认文件位于当前项目或运行 OpenCode 的机器上的全局配置目录，然后重新打开 /models。重复粘贴 Key 不能替代 Provider 配置。

“Custom providers are unavailable on this server”

在核对到的官方 V2 界面源码中，自定义 Provider 保存函数会直接抛出此错误；注释说明要等 V2 提供配置和任意凭据接口后再恢复。该版本尚未尝试保存或验证你的第三方 Key，因此这个提示本身不能证明 Nbility 的 Key 或 Base URL 有误。

先记录 opencode --version 和界面连接的服务端版本。需要自定义 Provider 时，使用官方文档支持的 CLI/TUI 配置路径，并把配置写到实际运行 OpenCode 的机器上；连接远程服务时，只改浏览器所在电脑的文件不会生效。受管理的远程服务则需由其管理员提供受支持的配置入口。这个源码结论只对应上述版本，不能保证任意版本升级后都会恢复界面保存功能。

/models 看不到自定义 Provider

检查：

  • /connect 的 Provider ID 是否与配置键完全一致；
  • opencode.json 是否位于当前项目或正确的全局目录；
  • JSON / JSONC 是否可解析；
  • models 是否至少定义了一个模型；
  • OpenCode 是否从预期项目根目录启动。

401 或凭据无效

运行：

opencode auth list

确认凭据已保存。若使用环境变量，确认 OpenCode 进程能读取该变量。不要把属于另一个域名的 Key 发给当前 Base URL。

404 Not Found

重点检查：

  • Base URL 是否包含且只包含一次 /v1；
  • 是否误填完整 /chat/completions；
  • npm 包是否与 Chat Completions / Responses 匹配；
  • 网关实际收到的最终 URL。

Model Not Found

模型配置键必须匹配服务端真实 ID。先查询 /v1/models，再检查 Token 是否有访问权限。完整选择值应是 provider_id/model_id。

聊天成功但工具调用失败

这通常不是 Key 问题。检查模型是否支持 Tool Calling、兼容层是否正确转换工具定义和结果、流式事件是否完整，以及模型上下文和输出上限是否足够。

OpenCode 官方也提醒，应选择既擅长代码生成、又擅长工具调用的模型。

更多状态码可参考 AI API 401、404、429 与 5xx 排错指南。

可选：限制模型列表

当 Provider 暴露大量模型时，可使用 whitelist 只保留团队允许的模型：

{
  "provider": {
    "nbility": {
      "whitelist": [
        "YOUR_FAST_MODEL_ID",
        "YOUR_PRIMARY_MODEL_ID"
      ]
    }
  }
}

或者用 blacklist 隐藏不需要的模型。官方规则是先用 whitelist 缩小范围，再用 blacklist 排除其中的条目。

这对团队环境很有用：减少误选昂贵模型，也能避免成员调用尚未验证工具能力的模型。

上线前检查清单

[ ] `/connect` 与配置使用相同 Provider ID
[ ] Base URL 是 API 根地址，不是完整 Endpoint
[ ] Chat Completions / Responses 选择了正确 npm 适配器
[ ] 所有模型 ID 来自当前服务的模型列表
[ ] API Key 不在 Git、截图和日志中
[ ] `/models` 能看到自定义模型
[ ] 普通聊天、流式输出和 Tool Calling 均已测试
[ ] 默认模型与 small_model 的成本和能力符合任务
[ ] 团队配置使用 whitelist / blacklist 控制范围
[ ] 401、404、429 与 5xx 有明确处理方式

FAQ

OpenCode 可以同时连接多个 Provider 吗？

可以。每个 Provider 使用独立 ID、凭据和模型集合，模型以 provider_id/model_id 区分。你可以通过 /models 在它们之间切换。

API Key 应写在 opencode.json 吗？

不建议写真实值。优先使用 /connect，或用 {env:NBILITY_API_KEY} 引用环境变量。项目配置进入 Git 前必须确认不含秘密。

为什么需要同时执行 /connect 和编辑配置？

/connect 负责凭据，opencode.json 负责 Provider 协议、Base URL 和模型。自定义 Provider 需要两者共同工作。

@ai-sdk/openai-compatible 与 @ai-sdk/openai 有什么区别？

按 OpenCode 当前文档，前者用于 /v1/chat/completions 兼容服务，后者用于 /v1/responses。应按服务实际协议选择，而不是按品牌名猜测。

总结

OpenCode 接入第三方 API 的可靠流程是：用 /connect 保存凭据，在 opencode.json 中用同一个 Provider ID 定义 npm、baseURL 和 models，再通过 /models 选择模型。

使用 Nbility 时，可将 OpenAI 兼容 Base URL 配置为 https://api.nbility.ai/v1。先通过模型列表确认真实模型 ID，再分别验证普通聊天、流式输出与工具调用。这样既能在一个 OpenCode 工作流中使用多个模型，也能把认证、协议和模型问题分层排查。

参考资料

相关文章

用 Nbility 跑通你的 Agent 工作流

获取 API Key，统一接入 OpenAI 兼容模型和开发工具。

获取 API Key