配置模型供应商

📖 本篇术语速查表

英文 / 缩写	中文	一句话解释
Providers	供应商	提供模型的服务方。
接入	connect	配 key 接通供应商。
切换	switch	在供应商间切换。

不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你给 OpenCode 接入并管理模型供应商。

你是 OpenCode 供应商接入顾问。

【角色】
OpenCode 供应商接入顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。

【输入】
- 想接哪些供应商：___
- 已有的 key：___
- 是否需本地 / 私有：___
- 切换需求：___
- 经验水平：___

【工作流程】
1. 说明供应商接入方式
2. 给配 key 步骤
3. 说明怎么切换
4. 处理常见接入问题
5. 给验证

【输出规范】
▌一、接入方式
▌二、配 key
▌三、切换
▌四、常见问题 + 验证

【硬约束】
- key 走环境变量不打日志
- 按需接入不堆账号
- 接通后实测验证
- 不要替我臆测情况或编造不存在的功能，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述

OpenCode 可以接很多 LLM provider。官方 providers 页说明，OpenCode 使用 AI SDK 和 Models.dev，支持 75+ LLM providers，也支持本地模型。

这一篇用 8 分钟换什么：你会知道 provider、credential、model 和 baseURL 分别解决什么问题，第一次该怎么接入，以及 provider 出错时先排哪一层。

先给结论：第一次只接一个 provider

新手不需要先把每个 provider 的配置都学一遍。先让一条 provider 链路跑通，再比较价格、速度、模型质量和企业边界。

flowchart LR
  Connect["/connect 保存凭据"] --> Models["/models 确认模型"]
  Models --> Read["只读项目理解"]
  Read --> Edit["低风险单文件修改"]
  Edit --> Default["稳定后再写默认 model"]
  Default --> More["再扩展备用 provider / 本地模型 / 企业网关"]

  style Connect fill:#dbeafe,stroke:#3b82f6
  style Read fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style More fill:#fef3c7,stroke:#f59e0b

同时配置五六个 provider，会让问题变成“到底是哪家模型、网络、凭据、baseURL 或权限出了错”。

provider 解决什么问题

Provider 是模型供应商入口。OpenAI、Anthropic、OpenRouter、Bedrock、Ollama、本地 OpenAI-compatible 服务，都属于 provider 层。

四个概念要分清：

概念	负责什么
provider	模型从哪里来
credential	怎么认证
model	具体用哪一个模型能力
baseURL	请求打到哪里

/connect 更适合管理凭据；opencode.json 更适合管理项目级偏好，例如默认模型、自定义 provider baseURL、provider options 或模型 alias。

不要把 API key 写进 opencode.json。配置文件会进仓库、会被复制、会被发给别人；凭据应该留在本机 auth store、环境变量或 secret manager。

怎么判断该选哪个 provider

按场景选择：

学习和日常开发：选 OpenCode Zen 或你已有账号的主流 provider。
国内网络、统一账单、多模型聚合：考虑 OpenRouter、302.AI、Vercel AI Gateway、Cloudflare AI Gateway 或团队内部 gateway。
企业云权限、VPC（Virtual Private Cloud，虚拟私有云——把云上资源放进只对你公司开放的隔离网络里）、合规：考虑 Bedrock、Azure、Vertex 等企业 provider。
隐私或离线实验：考虑 Ollama（命令行起本地模型最简单的工具）、LM Studio（桌面 GUI 跑本地模型）、llama.cpp（C++ 写的高性能本地推理引擎，前面两个底层都用它）、Atomic Chat 等本地模型入口。

本地模型的 tool calling 能力、上下文能力和速度要单独验证。能聊天不等于能稳定做 coding agent。

`/connect` 和配置文件怎么分工

/connect 适合第一次上手：

/connect

连接后用 /models 看可用模型。也可以用 CLI 管理：

opencode auth login
opencode auth list

项目配置适合写非敏感策略：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider_id/model_id"
}

如果团队确实需要同一默认模型，再把它写进项目配置。个人偏好先放全局。

baseURL 什么时候需要改

多数人不需要改 baseURL。只有这些情况才需要：

你走代理服务或企业网关。
你用 OpenAI-compatible 的本地模型服务。
你在 Azure、Bedrock、VPC endpoint 等环境里使用自定义 endpoint。
你需要把请求统一送到内部 AI gateway。

baseURL 改错时，常见表现是模型列表为空、认证失败、请求 404、工具调用异常。排查时先回到官方默认 provider，确认 OpenCode 本身没问题，再改自定义 endpoint。

新手常见坑

只看 provider 数量：provider 多不代表体验好。
把 key 写进项目配置：一旦提交就是泄露。
选了模型但没申请权限：企业 provider 经常需要先部署或授权模型。
baseURL 写错：OpenCode 能启动，但模型请求失败。
本地模型能聊天但不能稳定调用工具。
同时配置多个聚合平台：错误来源变多，排查会变慢。
忽略供应商政策：某些订阅或第三方插件用法可能不被 provider 支持。

怎么验收

你至少要能确认：

当前默认 provider 和默认 model 是什么。
key 没有出现在 opencode.json、git diff、日志和截图里。
/models 能看到可用模型。
模型完成过一次读代码、一次改文件、一次工具调用。
provider 出错时能区分凭据、模型权限、baseURL、网络和模型能力问题。

接下来去哪

选择模型

provider 连上后，再确认模型 ID、默认模型、variant 和加载优先级。

OpenCode Zen

如果第一次不知道选什么，可以先看官方精选模型入口的边界。

模型策略

按任务风险、成本和速度分层，而不是每天追最新模型。

排查故障

provider、模型、认证、网络和缓存问题按层级定位。

官方资料

Providers：https://opencode.ai/docs/providers
Models：https://opencode.ai/docs/models
Config：https://opencode.ai/docs/config

配置模型供应商

选择模型

OpenCode Zen

模型策略

排查故障

本页目录