客户端配置
OpenCode
在 OpenCode 配置自定义 provider。
OpenCode provider
在 opencode.json 中声明自定义 provider。以下配置使用 OpenAI-compatible SDK，适合兼容 Chat Completions 的基础接入；需要 Responses 特性时，应按当前 OpenCode 版本支持的 provider 包单独验证。
开始前准备
- 通过 cURL 确认
<API_KEY>和<MODEL>。 - 找到用户级或项目级
opencode.json，并备份现有内容。 - 确认项目不会把包含明文 Key 的配置提交到 Git。
添加 provider
将 custom provider 合并进已有 provider 对象。示例是合法 JSON，不要添加注释或尾随逗号。
json
{
"$schema": "https://opencode.ai/config.json",
"model": "custom/<MODEL>",
"provider": {
"custom": {
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "https://suoxie.codes/v1",
"apiKey": "<API_KEY>"
},
"models": { "<MODEL>": {} }
}
}
}custom/<MODEL> 中斜杠前的 custom 必须与 provider 键一致。baseURL 已含 /v1。
更安全的做法是使用当前 OpenCode 版本支持的环境变量或文件引用语法保存 Key；引用方式应以该版本官方配置说明为准。不要把占位符误当成真实 Key。
验证
- 运行 OpenCode 的配置检查或直接启动，确认没有 JSON/schema 错误。
- 明确选择
custom/<MODEL>。 - 在空目录发送一条短消息。
- 成功后再启用项目上下文和工具。
成功标志： provider 加载成功、模型可选、短消息正常返回。
常见问题
| 现象 | 先检查什么 |
|---|---|
| JSON 解析失败 | 注释、尾随逗号、括号和引号 |
| Unknown provider | custom 名称是否在 model 与 provider 中一致 |
| 401 | apiKey 引用是否实际解析出完整 Key |
| 404 | baseURL 是否重复 /v1，provider 包使用的端点是否匹配 |
| 模型不可用 | <MODEL> 是否来自当前 Key 的实时列表 |
安全与回退
优先使用用户级密钥存储，不要将完整 Key 直接放进项目级配置。回退时恢复备份或移除 custom provider；不要删除其他 provider 与规则。
下一步
使用 Key 用量确认 OpenCode 实际调用的端点与模型。若需要工具调用，先阅读 Responses API，并在小任务上逐项验证。