OpenCode 自定义 provider：SDK 协议、模型键与最小运行

先选 SDK，再填地址

OpenCode 支持自定义 provider，但协议由使用的 SDK 决定。官方要求 Chat Completions 使用 @ai-sdk/openai-compatible，Responses 使用 @ai-sdk/openai。 即使地址相同，选错 SDK 仍可能发出服务端不认识的请求。

本文采用 Responses 示例。接入前取得真实服务的协议、模型 ID、认证要求以及流式和工具调用说明；模型列表里能看到一个名字，并不证明该模型已经可以完成 Agent 任务。

provider 和模型都要有独立键

项目 opencode.json 可定义 provider，用户级配置也可放在 ~/.config/opencode/opencode.json；不同来源会合并，而不是简单整份覆盖。 给示例使用唯一 ID，避免影响已在用的提供商。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "80321-example": {
      "npm": "@ai-sdk/openai",
      "name": "80321-example",
      "options": {
        "baseURL": "https://80321.cn/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": { "name": "YOUR_MODEL_ID" }
      }
    }
  },
  "model": "80321-example/YOUR_MODEL_ID"
}

地址只是占位示例，不存在本文可调用的真实接口。baseURL 注意大小写；模型选择使用 provider/model，不是只填显示名称。 环境变量未设置时，{env:...} 会替换成空字符串，可能造成看似有配置、实际上没凭证的问题。

connect 只保存凭证，不定义模型

官方 /connect 的 Other 选项可以为自定义 provider 保存 Key，但仍须另行定义 opencode.json。保存凭证时输入的 ID 必须与配置中的 provider 键一致。 如果使用上面的环境变量路线，则先确认启动进程能读到变量，不必为了同一个示例重复保存多套 Key。

Key 仅写作 YOUR_API_KEY。不要放进跟踪中的项目文件，也不要把诊断日志当作秘密管理工具。配置合并后仍需检查有效值，尤其是已有用户配置可能提供的模型与权限默认项。

如果选择 /connect 路线，可按官方指引用 opencode auth list 检查保存的 provider 身份；它不会自动替你注册模型。 只记录 provider ID 和凭证是否存在，不把认证文件作为排错附件。一个 ID 拼写错误，不需要删除其他已保存连接。

列出模型后再做单次请求

官方 opencode models 能按 provider 过滤，run 提供非交互执行。 下面是正式配置确认后的未执行验证形式，不附加业务文件。

export OPENAI_API_KEY="YOUR_API_KEY"
opencode models 80321-example
opencode run --model 80321-example/YOUR_MODEL_ID   "只返回 OK，不读写文件、不执行命令"

第一条说明配置中的模型是否被识别，第二条才进入模型请求。若条目缺失，查 provider 键和 JSON；认证错误查变量或保存凭证的 ID；响应格式错误回到 SDK 与协议。

别用上下文数字伪造兼容性

官方支持配置 limit.context 和 limit.output，它们用于让客户端理解上下文范围。 没有服务规格时不要从其他模型复制巨大数值，也不要随意补 reasoning、工具或图片能力。短提示词不替代实际权限约束，首次保留工具审批。本页只核对官方配置方式，未安装客户端或完成真实接口联通。