7.2 Provider 注册与解析

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

OpenCode 的 Provider 系统不是简单的"配置一个 API Key 就能用"——它需要从多个来源收集信息（环境变量、配置文件、OAuth 认证、Plugin 钩子），经过多层合并和验证，最终构建一个完整的 Provider 注册表。本节将详细分析这个过程。

7.2.1 Provider.Info 数据模型

每个 Provider 的元信息定义如下：

export const Info = z.object({
  id: z.string(),                              // Provider 唯一标识
  name: z.string(),                            // 显示名称
  source: z.enum(["env", "config", "custom", "api"]),  // 注册来源
  env: z.string().array(),                     // 可用的环境变量名列表
  key: z.string().optional(),                  // API Key
  options: z.record(z.string(), z.any()),       // Provider 特定选项
  models: z.record(z.string(), Model),          // 该 Provider 下的所有模型
})

source 字段记录了 Provider 是如何被发现的：

Source	说明
"env"	通过环境变量中的 API Key 发现
"config"	通过 opencode.json 配置文件定义
"custom"	通过 Custom Loader 或 Plugin 自动发现
"api"	通过 opencode auth 命令存储的 API Key

7.2.2 Provider 状态初始化的完整流程

Provider 的初始化使用 Instance.state() 模式，完整流程如下图所示：

   ┌──────────────────────────────────┐
   │  1. 加载 models.dev 数据库       │
   │     (所有已知 Provider 和 Model)  │
   └──────────────┬───────────────────┘
                  │
   ┌──────────────▼───────────────────┐
   │  2. 合并用户 config 中的 provider │
   │     (扩展模型列表、覆盖选项)       │
   └──────────────┬───────────────────┘
                  │
   ┌──────────────▼───────────────────┐
   │  3. 从环境变量发现 API Key        │
   │     (ANTHROPIC_API_KEY 等)        │
   └──────────────┬───────────────────┘
                  │
   ┌──────────────▼───────────────────┐
   │  4. 从 Auth 存储发现 API Key      │
   │     (opencode auth 存储的凭据)     │
   └──────────────┬───────────────────┘
                  │
   ┌──────────────▼───────────────────┐
   │  5. Plugin Auth 加载              │
   │     (如 Copilot、Codex Auth)      │
   └──────────────┬───────────────────┘
                  │
   ┌──────────────▼───────────────────┐
   │  6. Custom Loader 执行            │
   │     (Provider 特定的初始化逻辑)    │
   └──────────────┬───────────────────┘
                  │
   ┌──────────────▼───────────────────┐
   │  7. 最终合并 config 选项           │
   └──────────────┬───────────────────┘
                  │
   ┌──────────────▼───────────────────┐
   │  8. 过滤：禁用列表、白名单、       │
   │     deprecated 模型、空 Provider   │
   └──────────────────────────────────┘

步骤 1：加载 models.dev 数据库

const modelsDev = await ModelsDev.get()
const database = mapValues(modelsDev, fromModelsDevProvider)

OpenCode 使用 models.dev 作为模型元数据的数据源。这是一个集中化的模型信息数据库，包含所有主流 LLM 的能力描述、价格信息、上下文窗口大小等。

ModelsDev.get() 的加载优先级是：

1. 本地缓存文件（~/.cache/opencode/models.json）

2. 构建时内嵌的快照（models-snapshot）

3. 从 https://models.dev/api.json 在线获取

步骤 3：环境变量发现

const env = Env.all()
for (const [providerID, provider] of Object.entries(database)) {
  if (disabled.has(providerID)) continue
  const apiKey = provider.env.map((item) => env[item]).find(Boolean)
  if (!apiKey) continue
  mergeProvider(providerID, { source: "env", key: apiKey })
}

每个 Provider 都有一组关联的环境变量名（如 Anthropic 对应 ANTHROPIC_API_KEY）。系统遍历所有已知 Provider，检查对应的环境变量是否存在。如果找到了 API Key，该 Provider 就被自动注册。

这种零配置的发现机制非常优雅——用户只需设置一个环境变量，就能自动启用对应的 Provider，无需在配置文件中显式声明。

步骤 6：Custom Loader

某些 Provider 需要特殊的初始化逻辑，这通过 CUSTOM_LOADERS 实现：

const CUSTOM_LOADERS: Record<string, CustomLoader> = {
  async anthropic() {
    return {
      autoload: false,
      options: {
        headers: {
          "anthropic-beta": "claude-code-20250219,interleaved-thinking-...",
        },
      },
    }
  },
  
  async "amazon-bedrock"() {
    // 复杂的 AWS 认证链：Profile → Access Key → Bearer Token → Web Identity
    const { fromNodeProviderChain } = await import(
      await BunProc.install("@aws-sdk/credential-providers")
    )
    return {
      autoload: true,
      options: providerOptions,
      async getModel(sdk, modelID) {
        // 跨区域推理前缀处理（us., eu., global., etc.）
      },
    }
  },
  
  async gitlab(input) {
    // GitLab OAuth + AI Gateway 配置
    return {
      autoload: !!apiKey,
      options: { instanceUrl, apiKey, aiGatewayHeaders, featureFlags },
      async getModel(sdk, modelID) {
        return sdk.agenticChat(modelID, { /* ... */ })
      },
    }
  },
  // ...
}

Custom Loader 的返回值包含三个关键字段：

• autoload：是否自动加载该 Provider（即使没有显式的 API Key）。例如 AWS Bedrock 如果检测到 IAM 配置就自动加载。

• options：Provider 特定的初始化选项。例如 Anthropic 需要特殊的 beta header。

• getModel：自定义的模型获取函数。不同 Provider 获取 LanguageModel 实例的方式不同。

步骤 8：过滤与清理

for (const [providerID, provider] of Object.entries(providers)) {
  // 检查是否被允许
  if (!isProviderAllowed(providerID)) { delete providers[providerID]; continue }
  
  for (const [modelID, model] of Object.entries(provider.models)) {
    // 移除 deprecated 模型
    if (model.status === "deprecated") delete provider.models[modelID]
    // 移除实验性模型（除非启用了实验标志）
    if (model.status === "alpha" && !Flag.OPENCODE_ENABLE_EXPERIMENTAL_MODELS)
      delete provider.models[modelID]
    // 应用黑名单/白名单
    if (configProvider?.blacklist?.includes(modelID) || 
        (configProvider?.whitelist && !configProvider.whitelist.includes(modelID)))
      delete provider.models[modelID]
  }
  
  // 移除没有任何模型的 Provider
  if (Object.keys(provider.models).length === 0) {
    delete providers[providerID]
  }
}

7.2.3 Provider.getLanguage()：从配置到 LanguageModel 实例

当 Agent 需要调用 LLM 时，系统通过以下链路获取可用的 LanguageModelV2 实例：

export async function getLanguage(model: Model): Promise<LanguageModelV2> {
  const s = await state()
  const key = `${model.providerID}/${model.id}`
  
  // 缓存检查
  if (s.models.has(key)) return s.models.get(key)!
  
  const provider = s.providers[model.providerID]
  const sdk = await getSDK(model)      // 获取 Provider SDK 实例
  
  // 使用 Custom Loader 的 getModel 或默认方式
  const language = s.modelLoaders[model.providerID]
    ? await s.modelLoaders[model.providerID](sdk, model.api.id, provider.options)
    : sdk.languageModel(model.api.id)
  
  s.models.set(key, language)     // 缓存结果
  return language
}

getSDK() 的实现中有一个精巧的缓存机制——使用 xxHash32 对 Provider 配置进行哈希，确保相同配置的 SDK 实例被复用：

const key = Bun.hash.xxHash32(JSON.stringify({ 
  providerID: model.providerID, 
  npm: model.api.npm, 
  options 
}))
const existing = s.sdk.get(key)
if (existing) return existing

7.2.4 自定义 Provider 注册

用户可以在 opencode.json 中注册自定义 Provider：

{
  "provider": {
    "my-llm": {
      "name": "My Custom LLM",
      "npm": "@ai-sdk/openai-compatible",
      "api": "https://my-llm-api.example.com/v1",
      "env": ["MY_LLM_API_KEY"],
      "models": {
        "my-model-v1": {
          "name": "My Model v1",
          "limit": { "context": 128000, "output": 4096 },
          "cost": { "input": 1.0, "output": 3.0 }
        }
      }
    }
  }
}

通过 @ai-sdk/openai-compatible 这个"万能适配器"，任何兼容 OpenAI API 格式的 LLM 服务（如 Ollama、LM Studio、vLLM 等）都可以无缝接入 OpenCode。

7.2.5 模型搜索与默认模型选择

OpenCode 提供了模糊搜索和智能默认选择：

// 模糊搜索：当用户输入的模型名有误时，提供建议
export async function getModel(providerID: string, modelID: string) {
  const provider = s.providers[providerID]
  if (!provider) {
    const matches = fuzzysort.go(providerID, availableProviders, { 
      limit: 3, threshold: -10000 
    })
    throw new ModelNotFoundError({ providerID, modelID, 
      suggestions: matches.map((m) => m.target) })
  }
  // ...类似地对 modelID 进行模糊匹配
}

// 默认模型选择
export async function defaultModel() {
  const cfg = await Config.get()
  if (cfg.model) return parseModel(cfg.model)
  
  // 自动选择第一个可用 Provider 的最高优先级模型
  const provider = await list()
    .then((val) => Object.values(val))
    .then((x) => x.find((p) => !cfg.provider || 
      Object.keys(cfg.provider).includes(p.id)))
  
  const [model] = sort(Object.values(provider.models))
  return { providerID: provider.id, modelID: model.id }
}

模型排序的优先级：

const priority = ["gpt-5", "claude-sonnet-4", "big-pickle", "gemini-3-pro"]

如果用户没有指定默认模型，系统会按照上述优先级自动选择当前可用的最佳模型。

---

下一节将分析模型元数据系统——OpenCode 如何管理每个模型的能力描述、价格信息和上下文窗口限制。