跟着OpenCode学智能体设计和开发4：大模型提供商集成

提供商架构：多提供商支持模型

OpenCode 的提供商架构通过统一可扩展接口实现了多 AI 提供商的无缝集成，既抽象了不同提供商的底层复杂性，又保留了自定义配置和提供商专属优化的灵活性，核心支撑了超过 19 个内置提供商的快速接入与自定义提供商的扩展能力。

一、架构核心概述

提供商系统采用分层架构设计，将「配置管理、身份验证、模型发现、运行时执行」四大核心能力整合到内聚框架中，具备两大关键特性：

1. 内置丰富支持：直接捆绑 SDK 集成 19+ 主流 AI 提供商，消除常见用例的依赖管理成本
2. 无限扩展能力：通过插件系统支持自定义提供商加载，无需修改核心代码即可扩展新能力
3. 核心目标：让用户以一致的方式使用不同 AI 提供商的能力，同时最大化利用各提供商的专属优势

来源：provider.ts, models.ts

二、提供商状态管理与配置优先级

1. 集中式状态管理

提供商状态通过 Provider.state() 函数统一协调初始化，核心完成「提供商发现、配置解析、功能验证」三大流程，确保所有提供商的状态一致性。

2. 严格的配置优先级链

初始化过程中，配置会按照从低到高的优先级进行多源合并，既支持组织级基准配置，又允许开发者在项目/命令行级别灵活覆盖，优先级链如下（从低到高）：

1. Remote/well-known config：组织默认设置，优先级最低
2. Global user config：全局用户配置，适用于所有项目
3. Custom config path：通过 OPENCODE_CONFIG 标志指定的自定义配置文件
4. Project config：项目目录中的 opencode.json / opencode.jsonc，项目级专属配置
5. Inline config content：通过 OPENCODE_CONFIG_CONTENT 标志传入的内联配置，优先级最高

这种分层配置模式，兼顾了组织标准化与项目个性化的需求。

来源：provider.ts#L600-L700

三、内置提供商支持与自定义加载器

1. 19+ 内置提供商核心清单

OpenCode 直接捆绑主流 SDK，预集成了 19+ 提供商，每个提供商都具备专属优化功能，核心清单如下（关键提供商节选）：

提供商	依赖 SDK 包	核心特殊功能
Anthropic	@ai-sdk/anthropic	Beta 头部配置、缓存控制
OpenAI	@ai-sdk/openai	补全 URL 支持、Codex 兼容
Google Generative AI	@ai-sdk/google	项目/区域配置、多模态支持
Amazon Bedrock	@ai-sdk/amazon-bedrock	区域感知模型前缀、凭证链解析
Azure	@ai-sdk/azure	认知服务集成、企业级部署支持
GitHub Copilot	自定义 OpenAI 兼容	OAuth 流程、企业版/个人版分离

来源：provider.ts#L16-L40

2. 自定义提供商加载器（CUSTOM_LOADERS）

CUSTOM_LOADERS 对象专门处理超越标准 SDK 的提供商专属初始化逻辑，核心负责「身份验证、凭据解析、模型加载行为定制」，针对复杂提供商提供精细化支持，以下是典型场景：

（1）Amazon Bedrock 区域处理

实现了区域感知的模型前缀自动添加，支持跨区域推理，区域配置解析遵循三层优先级：

1. Provider config options（提供商配置，最高优先级）
2. AWS_REGION 环境变量
3. 默认 us-east-1（后备方案）

自动前缀示例：claude-sonnet-4-5 在不同区域会被转换为 us.claude-sonnet-4-5（美区）、eu.claude-sonnet-4-5（欧区）、jp.claude-sonnet-4-5（东京区）。

来源：provider.ts#L200-L300

（2）Google Vertex 集成

依赖环境变量完成项目与位置配置，缺少则自动禁用（autoload: false）：

• 项目标识：GOOGLE_CLOUD_PROJECT / GCP_PROJECT / GCLOUD_PROJECT
• 位置配置：GOOGLE_CLOUD_LOCATION / VERTEX_LOCATION

来源：provider.ts#L350-L380

（3）GitHub Copilot Enterprise 变体

自动创建 github-copilot-enterprise 提供商变体，继承标准 github-copilot 的模型，使用独立身份验证凭据，支持同时使用个人版与企业版账户。

来源：provider.ts#L620-L640

四、身份验证架构：类型安全与多流程支持

身份验证系统采用可区分联合架构，支持三种身份验证类型，实现跨提供商的类型安全凭据管理，兼顾灵活性与安全性。

1. 三大核心身份验证类型

验证类型	适用场景	核心特性
OAuth	企业级提供商、需要令牌刷新的场景	1. 存储访问令牌、刷新令牌、过期时间戳 2. 支持可选账户 ID 和企业 URL 3. 通过 ProviderAuth.authorize() / ProviderAuth.callback() 管理生命周期
API Key	大多数主流提供商（Anthropic/OpenAI 等）	1. 简单键值对存储，配置便捷 2. 支持通过环境变量或配置文件加载 3. 无需复杂令牌刷新流程
Well-known	组织级托管配置场景	1. 从提供商 .well-known/opencode 端点获取配置 2. 支持组织默认设置，简化团队部署 3. 无需手动配置单个用户凭据

来源：auth.ts#L1-L50、auth.ts#L8-L30

2. 插件扩展的身份验证流程

插件系统通过 auth 钩子扩展身份验证能力，允许自定义 OAuth 流程、凭据加载器，无需修改核心代码即可适配特殊提供商的身份验证需求。

来源：auth.ts#L1-L148

五、模型发现与元数据管理

OpenCode 与 models.dev API 深度集成，实现可用模型的自动发现与全面元数据管理，为智能模型选择、成本跟踪提供支撑。

1. 模型元数据结构

每个模型包含详细的元数据，覆盖身份、能力、定价、限制等全维度信息：

• Identity：id、名称、模型家族、发布日期
• Capabilities：附件支持、推理能力、温度调节、工具调用、交错响应
• Pricing：输入/输出成本、缓存读/写成本、扩展上下文定价
• Limits：上下文窗口大小、输出 Token 限制
• Modalities：文本、音频、图像、视频、PDF 的输入/输出支持
• Status：Alpha/Beta/Deprecated 状态标志
• Provider Configuration：API URL、请求头、模型变体

来源：models.ts#L21-L50

2. 缓存策略

models.dev 的响应结果缓存于本地 $OPENCODE_CACHE_DIR/models.json，兼顾启动速度与数据新鲜度：

1. 缓存刷新周期：每小时自动刷新一次，获取最新模型定义
2. 禁用方式：可通过 OPENCODE_DISABLE_MODELS_FETCH 标志禁用缓存
3. 核心优势：快速启动的同时，确保不遗漏模型更新、定价调整等关键信息

来源：models.ts#L85-L108

六、提供商配置：结构与过滤机制

1. 核心配置结构

提供商配置支持精细化定制，涵盖名称、环境变量、请求选项、模型黑白名单等，典型配置示例：

{
  "provider": {
    "anthropic": {
      "name": "Anthropic (Custom)",
      "env": ["ANTHROPIC_API_KEY"],
      "options": {
        "baseURL": "https://api.anthropic.com",
        "timeout": 60000,
        "headers": {
          "anthropic-beta": "custom-header"
        }
      },
      "api": "https://custom-proxy.com",
      "whitelist": ["claude-sonnet-4-5"],
      "blacklist": ["deprecated-model"],
      "models": {
        "claude-sonnet-4-5": {
          "cost": {
            "input": 0.003,
            "output": 0.015
          },
          "limit": {
            "context": 200000,
            "output": 8192
          }
        }
      }
    }
  },
  "enabled_providers": ["anthropic", "openai"],
  "disabled_providers": ["deprecated-provider"]
}

来源：config.ts#L1-L100

2. 三大提供商过滤机制

支持灵活的提供商与模型过滤，满足不同场景的权限控制与功能限制需求：

1. enabled_providers：白名单模式，仅加载配置中的提供商
2. disabled_providers：黑名单模式，排除指定提供商
3. Per-provider whitelist/blacklist：提供商内部模型过滤，仅启用/禁用特定模型

来源：provider.ts#L720-L850

七、运行时提供商管理

运行时层负责 SDK 实例化、模型加载、请求路由，通过缓存层优化重复访问，确保高效运行。

1. SDK 实例化与缓存（getSDK()）

getSDK() 函数统一管理提供商 SDK 生命周期，核心流程如下：

1. 缓存检查：根据「npm 包名称 + 选项哈希」检查 SDK 缓存是否存在实例
2. 凭据获取：从会话状态中提取该提供商的身份验证凭据
3. 选项合并：合并全局配置、项目配置、模型专属的请求头与选项
4. 实例化：加载捆绑提供商 SDK 或自动安装自定义提供商 SDK
5. 自定义配置：配置带超时处理的自定义 fetch 方法
6. 缓存存储：将实例存入缓存，供后续相同配置请求复用

核心优势：相同配置复用 SDK 实例，不同配置触发新实例，兼顾效率与灵活性。

来源：provider.ts#L900-L980、provider.ts#L930-L940

2. 自定义模型加载

针对不同提供商的模型特性，实现专属加载逻辑，确保功能兼容：

• OpenAI：补全 API 使用 sdk.responses()，聊天 API 使用 sdk.chat()
• GitHub Copilot：Codex 模型路由到 sdk.responses()，聊天模型路由到 sdk.chat()
• Amazon Bedrock：加载前自动添加区域模型前缀

来源：provider.ts#L90-L140

八、跨提供商转换层：规范化与优化

转换层的核心作用是抹平提供商差异，规范化消息与参数，同时保留提供商专属优化，确保一致的使用体验。

1. 消息规范化

处理不同提供商的消息结构差异，避免调用失败：

• 空内容过滤：Anthropic 拒绝空字符串消息，自动过滤
• 工具调用 ID 清理：Mistral 要求 9 位字母数字 ID，自动格式化
• 推理内容提取：分离部分提供商的推理文本与响应文本
• 消息序列修复：修正工具消息后的消息类型冲突（如部分提供商不支持工具消息后直接跟用户消息）

来源：transform.ts#L10-L100

2. 提供商专属缓存策略

自动为系统提示词和最近消息应用缓存，不同提供商使用专属缓存控制请求头：

const providerOptions = {
  anthropic: { cacheControl: { type: "ephemeral" } },
  openrouter: { cacheControl: { type: "ephemeral" } },
  bedrock: { cachePoint: { type: "ephemeral" } },
  openaiCompatible: { cache_control: { type: "ephemeral" } }
}

来源：transform.ts#L100-L130

九、插件扩展：自定义提供商接入

插件系统允许无需修改核心代码即可集成自定义提供商，核心扩展点包括「身份验证钩子、转换钩子、模型加载器」。

核心插件身份验证钩子示例

插件通过导出 auth 对象定义自定义提供商的身份验证流程：

{
  name: "custom-provider",
  auth: {
    provider: "custom-provider",
    methods: [
      { type: "oauth", label: "OAuth 2.0" },
      { type: "api", label: "API Key" }
    ],
    async authorize() { /* 自定义 OAuth 授权流程 */ },
    async callback(code) { /* 令牌交换逻辑 */ },
    async loader(getAuth, provider) { /* 凭据加载逻辑 */ }
  }
}

来源：provider/auth.ts#L20-L80、plugin/index.ts#L1-L118

十、模型选择逻辑与错误处理

1. 智能模型选择

系统基于配置优先级与模型功能实现自动模型选择，兼顾性能与成本：

• 默认模型优先级：倾向强大通用模型，排序如 gpt-5 > claude-sonnet-4 > big-pickle > gemini-3-pro
• 小模型选择：工具调用、快速分析等场景，优先轻量级模型（claude-haiku-4-5、gemini-3-flash、gpt-5-nano），兼顾速度与成本

来源：provider.ts#L1050-L1136

2. 全面错误处理

定义专属错误类型，方便问题排查与自动回退：

• ModelNotFoundError：请求模型不存在，附带模糊匹配建议
• InitError：SDK 初始化失败
• OAuth 相关错误：OAuthMissing、OauthCodeMissing、OauthCallbackFailed

来源：provider.ts#L1100-L1136

十一、使用示例：配置并使用 Anthropic 提供商

# 1. 登录 Anthropic 进行身份验证
opencode auth login anthropic

# 2. 编写项目级提供商配置
cat > opencode.json << EOF
{
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 120000,
        "headers": {
          "anthropic-beta": "max-tokens-3-5-sonnet-2024-07-15"
        }
      }
    }
  }
}
EOF

# 3. 使用配置的提供商执行任务
opencode "Explain this codebase"

总结

1. OpenCode 提供商架构的核心是「统一接口 + 分层扩展」，既抹平了提供商差异，又保留了专属优化空间。
2. 配置优先级链、SDK 缓存、消息规范化是保障系统高效运行与一致体验的关键。
3. 内置 19+ 提供商 + 插件扩展体系，满足从个人开发到企业级部署的多样化需求。
4. 与 models.dev 集成的模型发现与元数据管理，为智能模型选择与成本控制提供了支撑。

支持的 AI 提供商：Anthropic、OpenAI、Google 等

OpenCode 的多提供商架构以统一标准化接口为核心，实现了与 18+ 主流 AI 提供商的无缝集成，既动态管理配置、身份验证与模型选择，又提供丰富的定制选项满足高级用例，同时抹平了不同提供商的 API 差异，为用户提供一致且高效的使用体验。

一、提供商架构核心概述

1. 分层初始化模型

提供商系统基于多源配置合并的分层初始化模型运行，配置来源按优先级从低到高依次为：

1. 远程众所周知配置（.well-known/opencode）
2. 全局用户设置
3. 环境变量
4. 项目特定配置（opencode.json/opencode.jsonc）

这种分层设计既支持组织级集中化配置分发，又允许开发者在项目层面灵活覆盖，兼顾标准化与个性化需求。

2. 核心运行机制

每个提供商均通过 AI SDK 生态系统实例化，同时针对各提供商的独特性应用专属定制，核心解决三大问题：

• 独特 API 行为差异（如消息格式、接口类型）
• 多样化身份验证模式（如 API Key、OAuth、AWS 凭证链）
• 特定模型的功能要求（如区域前缀、Beta 功能头）

来源：provider/provider.ts

二、主流提供商支持与专属配置

OpenCode 内置 18+ 提供商，每个提供商均有对应的 SDK 依赖、身份验证方式和专属优化，以下是核心提供商的关键配置细节：

1. 核心提供商清单（关键节选）

提供商	SDK 包	身份验证方式	核心特殊功能
Anthropic	@ai-sdk/anthropic	API Key	Beta 功能头注入、交错推理支持
OpenAI	@ai-sdk/openai	API Key	动态切换 Responses/Chat API
Google Vertex	@ai-sdk/google-vertex	OAuth/服务账号	云项目集成、位置感知模型解析
Amazon Bedrock	@ai-sdk/amazon-bedrock	AWS 凭证链	跨区域推理、自动模型前缀添加
GitHub Copilot	自定义 OpenAI 兼容	OAuth	企业 URL 支持、代码/对话模型分流

2. 重点提供商专属配置

（1）Anthropic：Beta 功能头自动注入

需要 ANTHROPIC_API_KEY 环境变量或配置中的 API Key，系统自动注入高级功能 Beta 头，无需手动配置：

• claude-code-20250219：增强代码理解能力
• interleaved-thinking-2025-05-14：支持 CoT（思维链）推理可视化
• fine-grained-tool-streaming-2025-05-14：实现精确的工具调用流控制

来源：provider/provider.ts

（2）OpenAI：双 API 动态路由

根据模型需求自动选择对应的 API 模式，无需手动指定：

• Responses API（sdk.responses(modelID)）：适用于结构化输出、函数调用场景（如 Codex 模型）
• Chat API（sdk.chat(modelID)）：适用于标准对话场景（如 GPT-4、GPT-3.5-turbo）
• 额外支持：标准 OpenAI 端点与 Azure OpenAI 部署的配置兼容

来源：provider/provider.ts

（3）Amazon Bedrock：复杂凭证链与跨区域推理

这是配置最复杂的提供商，支持多层凭证优先级与跨区域模型适配：

• 身份验证优先级（从高到低）：
  1. 身份验证存储中显式提供的 API Key
  2. 环境变量中的 AWS 凭证（AWS_ACCESS_KEY_ID、AWS_BEARER_TOKEN_BEDROCK）
  3. 支持配置文件的 AWS 凭证提供商链

• 核心配置示例：

  {
    "provider": {
      "amazon-bedrock": {
        "options": {
          "region": "us-east-1",
          "profile": "default",
          "baseURL": "custom-endpoint"
        }
      }
    }
  }

• 跨区域推理：自动为模型添加区域前缀，适配不同区域的模型可用性：
  • 美区：us. 前缀（如 us.claude-sonnet-4-5）
  • 欧区：eu. 前缀（如 eu.claude-sonnet-4-5）
  • 亚太区：apac. / jp. 前缀（如 jp.claude-sonnet-4-5）

来源：provider/provider.ts

（4）GitHub Copilot & Enterprise：OAuth 认证与企业配置

• 身份验证：依赖插件系统实现 OAuth 流程，支持个人版与企业版双变体
• API 分流：代码模型（Codex）使用 Responses API，对话模型（GPT-5-mini）使用 Chat API

• 企业版额外配置（需指定企业 URL）：

  {
    "provider": {
      "github-copilot-enterprise": {
        "options": {
          "enterpriseUrl": "https://github.yourcompany.com"
        }
      }
    }
  }

来源：provider/provider.ts

三、三大身份验证方法：灵活适配不同场景

提供商系统通过 Auth 模块统一管理三种身份验证类型，实现跨提供商的类型安全凭据管理，覆盖从简单个人使用到复杂企业部署的所有场景。

1. API Key 身份验证：简单高效（适用于大多数提供商）

直接存储与加载 API Key，适用于支持简单令牌验证的提供商（Anthropic、OpenAI 等），核心结构：

{
  "type": "api",
  "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
}

• 配置方式：环境变量、项目配置文件、全局 auth.json 均可配置
• 核心优势：配置简单，无需复杂流程，快速上手

来源：auth/index.ts

2. OAuth 身份验证：复杂企业场景（适用于 Copilot、Google Vertex 等）

由插件驱动的完整 OAuth 流程，支持令牌刷新、账户关联，适用于复杂身份验证需求的提供商，核心结构：

{
  "type": "oauth",
  "access": "ya29.a0AfH6xxxxxxxxxxxxxxxx",
  "refresh": "1//0gxxxxxxxxxxxxxxxxxxxx",
  "expires": 1735689600,
  "accountId": "[email protected]"
}

• 生命周期管理：通过 ProviderAuth 模块协调授权 URL、回调处理、自动令牌刷新
• 核心优势：安全可靠，支持企业级账户管理，无需手动存储长期有效密钥

来源：auth/index.ts, provider/auth.ts

3. Well-Known 身份验证：组织级集中配置（适用于企业部署）

遵循 .well-known/opencode 规范，从远程企业服务器获取集中化配置，核心结构：

{
  "type": "wellknown",
  "key": "https://enterprise.internal",
  "token": "org-token-xxxxxxxx"
}

• 核心价值：实现跨组织的提供商配置统一分发，简化团队部署与权限管理
• 适用场景：大型企业、团队协作，需要标准化所有成员的提供商配置

来源：auth/index.ts

四、模型元数据与发现：动态缓存与全面信息

1. 模型元数据来源与缓存策略

• 数据来源：从 models.dev API 动态获取最新模型信息
• 缓存机制：获取后缓存到本地 ~/.cache/opencode/models.json，每 60 分钟自动刷新
• 手动操作：可通过 opencode models --refresh 手动刷新缓存，或直接删除缓存文件
• 禁用缓存：无需最新数据时，可通过配置禁用远程获取，仅使用本地缓存

2. 全面的模型元数据结构

每个模型的元数据覆盖功能、成本、限制、状态四大维度，为智能模型选择与成本跟踪提供支撑：

（1）模型功能（capabilities）

标记模型支持的核心能力与多模态输入输出：

{
  "capabilities": {
    "temperature": true,
    "reasoning": true,
    "attachment": true,
    "toolcall": true,
    "input": { "text": true, "image": false },
    "output": { "text": true, "audio": false },
    "interleaved": { "field": "reasoning_content" }
  }
}

（2）成本结构（cost）

详细定义每 100 万 Token 的输入/输出成本，包含缓存与扩展上下文定价：

{
  "cost": {
    "input": 0.003,
    "output": 0.015,
    "cache": { "read": 0.001, "write": 0.002 },
    "experimentalOver200K": { "input": 0.006, "output": 0.03 }
  }
}

（3）限制与状态（limit & status）

定义模型的上下文窗口、输出限制与生命周期状态：

{
  "limit": { "context": 200000, "output": 8192 },
  "status": "active",
  "release_date": "2024-05-14T00:00:00Z"
}

来源：provider/models.ts

五、提供商配置定制：覆盖与扩展

OpenCode 支持通过 opencode.json 对提供商进行深度定制，满足各种高级用例，核心定制方式包括三种：

1. 基本提供商覆盖：修改核心配置

自定义提供商名称、API 端点、超时时间等基础属性：

{
  "provider": {
    "anthropic": {
      "name": "Anthropic Custom",
      "options": {
        "apiKey": "{env:ANTHROPIC_KEY}",
        "baseURL": "https://custom.anthropic.com",
        "timeout": 600000
      }
    }
  }
}

2. 模型黑白名单：过滤可用模型

仅启用指定模型（白名单）或排除特定模型（黑名单）：

{
  "provider": {
    "openai": {
      "whitelist": ["gpt-4", "gpt-3.5-turbo"],
      "blacklist": ["gpt-4-32k"]
    }
  }
}

3. 自定义提供商集成：添加非内置提供商

通过 OpenAI 兼容接口，集成自定义提供商（如私有部署的 Llama 3）：

{
  "provider": {
    "custom-llama": {
      "api": "https://api.custom-llama.com/v1",
      "npm": "@ai-sdk/openai-compatible",
      "env": ["CUSTOM_LLAMA_KEY"],
      "models": {
        "llama-3-70b": {
          "id": "meta-llama/Meta-Llama-3-70B",
          "name": "Llama 3 70B",
          "cost": { "input": 0.7, "output": 0.7 },
          "limit": { "context": 8192, "output": 4096 },
          "capabilities": { "toolcall": true, "temperature": true }
        }
      }
    }
  }
}

来源：config/config.ts

六、提供商发现与过滤：自动识别与精准控制

1. 提供商发现来源（优先级顺序）

系统自动从多渠道发现可用提供商，无需手动注册：

1. 环境变量（扫描已知 API Key 模式）
2. API Key 存储（从 auth.json 加载已配置凭据）
3. 插件身份验证（从插件获取 OAuth 令牌）
4. 配置文件（opencode.json 中的显式定义）
5. 远程数据库（models.dev API 中的提供商清单）

2. 多层过滤机制

确保仅加载所需的提供商与模型，避免冗余：

1. 提供商级别：通过 disabled_providers / enabled_providers 配置数组，全局禁用/启用提供商
2. 模型级别：通过每个提供商的 whitelist / blacklist 数组，过滤内部模型
3. 状态过滤：Alpha 模型需要 OPENCODE_ENABLE_EXPERIMENTAL_MODELS 标志才能启用
4. 自动过滤：已弃用模型自动从可用列表中排除，无需手动配置

3. CLI 工具：查看可用模型

通过 opencode models 命令可快速查看提供商与模型信息，支持多种参数：

# 列出所有可用模型
opencode models

# 列出来自 Anthropic 的模型
opencode models anthropic

# 显示完整元数据（详细输出）
opencode models --verbose

# 刷新模型缓存
opencode models --refresh

来源：cli/cmd/models.ts

七、自定义提供商高级集成

对于需要特殊处理的提供商（非 OpenAI 兼容），可通过插件开发实现深度集成，核心步骤：

1. 实现 auth.loader 接口，自定义身份验证流程
2. 注册请求转换钩子，处理提供商专属的消息格式与参数
3. 配置模型加载逻辑，适配提供商的 API 接口
4. 注意事项：确保 API 支持流式响应与格式正确的工具输出，不支持则设置 includeUsage: false

来源：provider/provider.ts

总结

OpenCode 多提供商架构的核心优势在于「统一接口与个性化定制的平衡」：

1. 以分层配置、标准化接口抹平了不同提供商的差异，降低使用成本
2. 以专属定制、插件扩展保留了各提供商的独特优势，满足高级需求
3. 以动态发现、缓存机制、多层过滤确保了系统的高效性与灵活性
4. 覆盖从个人开发到企业部署的全场景，支持 18+ 内置提供商与无限自定义扩展

这种架构设计，既让普通用户能够快速上手不同 AI 提供商，又让高级用户能够实现精细化的定制与优化。

模型选择与配置

在 OpenCode 中配置和选择 AI 模型的核心是多层级配置系统，它通过合并多来源设置、灵活过滤规则和智能选择逻辑，让你能精准匹配不同任务的模型需求，同时兼顾成本、性能与功能的平衡。

一、核心配置架构：多层级设置合并

OpenCode 的模型配置遵循优先级递增的层级结构，系统会自动合并不同来源的配置，最终生成一份统一的可用模型列表。

1. 配置合并逻辑：低优先级配置会被高优先级配置覆盖，数组类型字段（如插件、指令）会进行拼接而非替换。

2. 配置来源优先级（从低到高）：

   | 配置位置 | 适用范围 | 优先级 |
   |—————|—————|————|
   | Remote .well-known/opencode | 组织默认值 | 最低 |
   | ~/.opencode/config.json | 全局用户配置 | 低 |
   | ~/.opencode/opencode.json | 全局用户配置 | 中 |
   | .opencode/config.json | 项目配置 | 高 |
   | .opencode/opencode.json | 项目配置 | 较高 |
   | OPENCODE_CONFIG 标志指定路径 | 自定义路径 | 最高 |
   | OPENCODE_CONFIG_CONTENT 标志内联内容 | 内联配置 | 最高 |

这种设计既支持团队级的标准化配置，又允许开发者在项目中灵活定制。
来源：provider.ts, config.ts

二、基础模型配置：默认与小模型

1. 全局默认模型

通过 model 字段设置所有交互的默认模型，适用于未指定 Agent 专属模型的场景。
配置格式：模型 ID 遵循 providerID/modelID 规范，系统通过 parseModel() 函数验证格式。

{
  "model": "anthropic/claude-sonnet-4-20250514"
}

2. 小模型配置（轻量级任务专用）

小模型用于处理会话标题生成、摘要生成等低复杂度任务，可独立配置以优化成本和延迟。

{
  "small_model": "anthropic/claude-haiku-4-20250514"
}

• 自动选择规则：若未配置 small_model，系统会从优先级列表自动选取，优先顺序包括 claude-haiku-4-5、gemini-3-flash、gpt-5-nano 等轻量模型。
• 核心优势：小模型的成本和延迟仅为大型模型的一小部分，完全能满足实用工具类任务的需求。

来源：provider.ts

三、提供商配置：身份验证与自定义集成

1. 内置提供商配置

针对每个内置提供商，可配置身份验证、端点、超时等专属选项，支持 models.dev 生态系统的所有提供商类型。
示例配置：

{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "your-api-key",
        "timeout": 300000,
        "headers": {
          "anthropic-version": "2023-06-01"
        }
      }
    },
    "amazon-bedrock": {
      "options": {
        "region": "us-west-2",
        "profile": "production"
      }
    }
  }
}

2. 提供商身份验证机制

系统支持多种身份验证方式，并按顺序自动发现凭据，无需手动指定：

验证方式	凭据来源	示例
环境变量	provider.env 数组定义的变量	ANTHROPIC_API_KEY
配置文件	provider.options.apiKey 字段	直接填写密钥字符串
加密存储	Auth.get() 方法	安全存储的凭据
插件加载器	自定义认证流程	特定提供商的 OAuth 令牌

系统会优先扫描 provider.env 数组中定义的环境变量，找到第一个有效值后停止扫描。
来源：provider.ts

3. 自定义提供商集成

对于未内置的提供商，可通过指定 NPM 包和模型元数据，实现无代码集成。
配置示例（以自定义模型为例）：

{
  "provider": {
    "custom-provider": {
      "name": "My Custom Provider",
      "api": "https://api.custom.com/v1",
      "npm": "@company/custom-ai-sdk",
      "env": ["CUSTOM_API_KEY"],
      "models": {
        "custom-model-v1": {
          "id": "custom-model-v1",
          "name": "Custom Model V1",
          "cost": { "input": 0.001, "output": 0.002 },
          "limit": { "context": 128000, "output": 4096 },
          "capabilities": {
            "toolcall": true,
            "temperature": true,
            "input": { "text": true },
            "output": { "text": true }
          }
        }
      }
    }
  }
}

• 核心机制：系统会动态安装指定的 NPM 包，并通过 create* 函数模式自动创建提供商实例。

来源：provider.ts

四、模型过滤与选择：精准控制可用范围

1. 模型黑白名单（提供商内过滤）

通过 whitelist/blacklist 控制单个提供商下的可用模型，实现精细化管理。

{
  "provider": {
    "anthropic": {
      "whitelist": ["claude-sonnet-4-20250514", "claude-haiku-4-20250514"]
    },
    "openai": {
      "blacklist": ["gpt-3.5-turbo", "gpt-4-turbo-preview"]
    }
  }
}

• 白名单模式：仅允许列表内的模型被使用，适合生产环境严格控风险。
• 黑名单模式：排除列表内的模型，适合临时禁用某些模型。
• 生效时机：过滤规则在提供商初始化时应用，被排除的模型不会进入 Agent 的可用模型池。

来源：provider.ts

2. 提供商全局启用/禁用

通过 enabled_providers/disabled_providers 配置，控制整个提供商的加载状态。

{
  "enabled_providers": ["anthropic", "openai"],
  "disabled_providers": ["google-vertex"]
}

• 白名单逻辑：设置 enabled_providers 后，仅列表内的提供商被加载。
• 黑名单逻辑：设置 disabled_providers 后，列表内的提供商被排除。

3. 基于状态的过滤（实验性/已弃用模型）

模型会根据 models.dev 数据库中的状态自动过滤，默认禁用高风险模型：

• 默认排除：Alpha 测试版、已弃用的模型。
• 启用方式：设置 Flag.OPENCODE_ENABLE_EXPERIMENTAL_MODELS 标志，即可解锁实验性模型。

{
  "provider": {
    "anthropic": {
      "models": {
        "claude-experimental": {
          "status": "alpha"
        }
      }
    }
  }
}

来源：provider.ts

五、模型变体：同一模型的多套参数配置

模型变体允许你为同一个底层模型配置多套不同的参数，适配不同任务场景，由 ProviderTransform.variants() 系统处理。
配置示例：

{
  "provider": {
    "anthropic": {
      "models": {
        "claude-sonnet-4-20250514": {
          "variants": {
            "fast": {
              "maxTokens": 4096,
              "temperature": 0.5
            },
            "detailed": {
              "maxTokens": 8192,
              "temperature": 0.3
            }
          }
        }
      }
    }
  }
}

• 典型用途：
  • fast 变体：低温度、小输出长度，适合快速迭代的代码生成。
  • detailed 变体：更低温度、大输出长度，适合深度分析和文档撰写。

来源：provider.ts

六、Agent 特定模型配置：任务专属优化

Agent 级别的模型配置优先级高于全局配置，可针对不同功能的 Agent 单独指定模型，匹配其任务特性。
配置示例：

{
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "description": "Code generation and implementation"
    },
    "plan": {
      "model": "anthropic/claude-opus-4-20250514",
      "description": "High-level planning and architecture"
    },
    "explore": {
      "model": "anthropic/claude-haiku-4-20250514",
      "description": "Fast codebase exploration"
    }
  }
}

• 合并规则：Agent 配置会与全局默认设置合并，只需覆盖 model 字段，其他 Agent 行为保持不变。

模型选择解析顺序（优先级从高到低）

当 Agent 发起请求时，系统会按以下顺序确定最终使用的模型：

1. Agent 特定配置的模型
2. 全局默认模型（model 字段）
3. 提供商的默认模型
4. 系统预定义的优先级模型列表

系统通过 defaultModel() 函数实现上述逻辑，确保模型选择的合理性。
来源：provider.ts, agent.ts

七、模型元数据：功能、成本与限制

每个模型的元数据都存储在 models.dev 数据库中，包含功能、成本、限制等关键信息，是智能模型选择的依据。

核心元数据字段说明

字段分类	具体字段	描述	示例
功能（capabilities）	toolcall	是否支持函数调用	true
	temperature	是否支持温度参数调节	true
	reasoning	是否具备思维链推理能力	false
	modalities.input	支持的输入类型	["text", "image"]
成本（cost）	input	每 100 万输入 Token 的成本	0.003
	output	每 100 万输出 Token 的成本	0.015
限制（limit）	context	最大上下文窗口 Token 数	200000
	output	最大输出 Token 数	8192
状态（status）	status	模型生命周期状态	alpha/active/deprecated

来源：provider.ts

八、动态模型数据库：缓存与刷新

OpenCode 维护一个动态的模型数据库，确保模型信息的时效性和访问速度：

1. 数据来源：从 https://models.dev/api.json 接口获取。
2. 缓存机制：
   • 缓存位置：~/.cache/opencode/models.json
   • 刷新间隔：每 60 分钟自动刷新一次
3. 禁用远程获取：设置 OPENCODE_DISABLE_MODELS_FETCH 标志，可仅使用本地缓存。

系统通过 ModelsDev.get() 函数管理缓存的读取与更新。
来源：models.ts

九、成本优化与最佳实践

1. 成本优化配置技巧

• 区分任务配置模型：轻量任务用小模型，核心任务用大模型，示例如下：

  {
    "model": "anthropic/claude-sonnet-4-20250514",
    "small_model": "anthropic/claude-haiku-4-20250514",
    "agent": {
      "title": { "model": "anthropic/claude-haiku-4-20250514" },
      "build": { "model": "anthropic/claude-sonnet-4-20250514" }
    }
  }

• 利用模型变体：为同一模型配置不同参数，避免为不同任务启用多个模型。

2. 通用最佳实践

1. 从全局默认开始：先配置一个通用的全局默认模型，再针对特殊 Agent 进行覆盖。
2. 生产环境用白名单：通过 whitelist 限制可用模型，防止误用昂贵或实验性模型。
3. 按功能选模型：优先匹配任务所需功能（如工具调用、多模态），而非盲目选择“最先进”的模型。
4. 配置提供商冗余：同时启用多个功能类似的提供商，确保服务可用性，支持故障切换。
5. 监控 Token 成本：利用系统的成本跟踪功能，优化模型选择以匹配预算。

自定义提供商集成与身份验证

扩展 OpenCode 提供商系统的核心是利用分层架构、自定义加载器和插件化认证，既支持简单的自定义提供商配置，又能满足复杂 OAuth 流程等高级用例，同时遵循系统的配置优先级和状态管理逻辑。

一、提供商架构核心与三种认证模式

1. 架构分层概述

OpenCode 提供商系统采用三层集成模式，覆盖从简单到复杂的所有扩展场景：

1. 内置 SDK：面向主流提供商，直接捆绑成熟 SDK 无需额外开发
2. 自定义加载器：面向具有特殊行为（如区域感知、双 API 切换）的提供商，提供初始化逻辑扩展
3. 插件化认证：面向复杂 OAuth 流程，支持自定义 UI 交互和外部依赖，实现全生命周期认证管理

来源：provider.ts, plugin/index.ts, config.ts

2. 三种核心认证模式（适配不同场景）

（1）API Key 认证：简单高效（静态令牌场景）

这是最基础的认证方式，将 API 密钥存储在安全 JSON 文件中，适用于支持静态令牌的提供商，操作简单且无需复杂流程。

// 配置 API Key 认证
await Auth.set("my-provider", {
  type: "api",
  key: "sk-proj-abc123..."
})

• 存储位置：受限权限的安全 JSON 文件，避免明文暴露在项目配置中
• 适用场景：个人开发、无需令牌刷新的小型提供商
• 核心优势：配置简单，无需额外依赖，快速集成

来源：auth.ts, provider/auth.ts

（2）OAuth 2.0 流程：复杂企业场景（支持令牌生命周期管理）

支持授权码流程和基于 PKCE 的流程，处理从授权 URL 生成到令牌自动刷新的完整生命周期，适用于企业级提供商（如 GitHub Copilot、Google Vertex）。

• 核心能力：
  1. 生成个性化授权 URL，引导用户完成认证
  2. 处理回调请求，提取授权码并交换访问令牌
  3. 存储访问令牌、刷新令牌和过期时间戳
  4. 令牌过期前自动刷新，维持认证有效性
• 适用场景：需要用户身份关联、支持令牌刷新的大型提供商/企业内部服务

来源：provider/auth.ts, auth.ts

（3）Well-Known 配置：企业集中化部署（远程配置分发）

遵循 .well-known/opencode 规范，从远程企业端点获取集中化配置，适用于多团队、多部署实例的企业场景。

{
  "type": "wellknown",
  "key": "https://enterprise.internal",
  "token": "service-account-token"
}

• 核心价值：
  1. 集中管理提供商配置，无需逐个实例修改
  2. 统一分发凭据和端点设置，简化团队部署
  3. 支持企业级权限管控，批量更新配置
• 适用场景：大型企业、多项目部署、需要标准化配置的团队

来源：auth.ts, config.ts

二、自定义提供商配置：无代码基础集成

1. 核心配置架构（opencode.json 中实现）

通过 provider 节点配置自定义提供商，支持端点覆盖、模型黑白名单、元数据定义等全量自定义，配置示例如下：

{
  "provider": {
    "custom-provider": {
      "name": "Custom AI Provider",
      "env": ["CUSTOM_API_KEY"], // 扫描的环境变量列表
      "options": {
        "apiKey": "sk-...",
        "baseURL": "https://api.custom.com/v1",
        "timeout": 300000,
        "setCacheKey": false
      },
      "whitelist": ["model-id-1", "model-id-2"], // 模型白名单
      "blacklist": ["deprecated-model"], // 模型黑名单
      "models": {
        "custom-model-v1": {
          "id": "custom-model-v1",
          "name": "Custom Model V1",
          "cost": { // 成本配置（每100万Token）
            "input": 0.001,
            "output": 0.002,
            "cache": { "read": 0.0001, "write": 0.0001 }
          },
          "limit": { // 限制配置
            "context": 128000, // 最大上下文窗口
            "output": 4096 // 最大输出Token数
          },
          "capabilities": { // 功能支持配置
            "temperature": true,
            "reasoning": false,
            "toolcall": true,
            "attachment": true,
            "input": { "text": true, "image": true },
            "output": { "text": true }
          }
        }
      }
    }
  }
}

• 关键说明：模型的 cost、limit、capabilities 是必填元数据，用于系统的智能选择和成本跟踪。

来源：config.ts, provider.ts

2. 严格的配置优先级层次（从低到高）

配置系统支持分层覆盖，低优先级配置会被高优先级配置覆盖，数组字段（如插件、指令）会拼接而非替换。

优先级	配置来源	描述
1（最低）	Remote Well-Known	企业级默认配置，统一分发
2	Global Config	全局用户配置（~/.opencode/config.json）
3	Custom Config Path	自定义路径配置（OPENCODE_CONFIG 标志指定）
4	Project Config	项目级配置（项目目录 opencode.json）
5（最高）	Inline Config	内联配置（OPENCODE_CONFIG_CONTENT 环境变量）

• 核心优势：兼顾企业标准化和项目个性化，既可以统一分发基础配置，又能在项目中灵活调整。

来源：config.ts

三、自定义加载器实现：高级初始化逻辑扩展

对于需要特殊行为的提供商（如区域感知、双 API 切换），可通过自定义加载器扩展初始化逻辑，自定义加载器是系统的核心扩展点。

1. 核心接口定义

自定义加载器包含两个核心接口，分别负责模型加载和提供商整体初始化：

// 自定义模型加载接口（处理单个模型的加载逻辑）
type CustomModelLoader = (
  sdk: any,
  modelID: string,
  options?: Record<string, any>
) => Promise<any>

// 自定义提供商加载器接口（处理整体初始化逻辑）
type CustomLoader = (
  provider: Info
) => Promise<{
  autoload: boolean // 是否自动加载该提供商
  getModel?: CustomModelLoader // 可选：覆盖默认模型加载逻辑
  options?: Record<string, any> // 可选：提供商额外配置选项
}>

来源：provider.ts

2. 基础自定义加载器实现

自定义加载器在 CUSTOM_LOADERS 对象中注册，处理提供商专属需求（如自定义请求头、模型 ID 转换、凭据校验），示例如下：

const CUSTOM_LOADERS: Record<string, CustomLoader> = {
  "my-custom-provider": async (provider) => {
    // 1. 校验凭据是否存在（扫描配置的环境变量）
    const env = Env.all()
    const hasKey = provider.env.some((item) => env[item])
    
    // 2. 根据认证状态过滤模型（无凭据时移除付费模型）
    if (!hasKey) {
      for (const [key, value] of Object.entries(provider.models)) {
        if (value.cost.input > 0) {
          delete provider.models[key]
        }
      }
    }
    
    // 3. 返回加载配置
    return {
      autoload: Object.keys(provider.models).length > 0, // 有可用模型则自动加载
      options: { // 自定义请求头等配置
        headers: {
          "X-Custom-Header": "custom-value",
          "User-Agent": "opencode-integration"
        }
      },
      // 4. 覆盖默认模型加载逻辑（转换模型ID格式）
      async getModel(sdk: any, modelID: string, options?: Record<string, any>) {
        const transformedID = modelID.replace("-", "_") // 模型ID格式转换
        return sdk.languageModel(transformedID)
      }
    }
  }
}

来源：provider.ts

3. 高级自定义加载器模式

（1）区域感知模型加载（适配多区域部署）

针对需要区域前缀的提供商（如 Amazon Bedrock），动态根据部署区域添加模型 ID 前缀，示例如下：

"region-aware-provider": async (input) => {
  const config = await Config.get()
  // 从配置中获取区域，默认 us-east-1
  const region = config.provider?.["region-aware-provider"]?.options?.region || "us-east-1"
  
  return {
    autoload: true,
    options: { region },
    async getModel(sdk: any, modelID: string, options?: Record<string, any>) {
      const providerRegion = options?.region || region
      const regionPrefix = providerRegion.split("-")[0]
      
      // 为 Claude 模型添加区域前缀
      if (modelID.includes("claude") && regionPrefix === "us") {
        modelID = `${regionPrefix}.${modelID}`
      }
      
      return sdk.languageModel(modelID)
    }
  }
}

（2）双 API 动态切换（Response API / Chat API）

针对支持多种接口的提供商，根据模型特征动态选择合适的 API（如代码模型用 Response API，对话模型用 Chat API）：

"dual-api-provider": async () => {
  return {
    autoload: false,
    async getModel(sdk: any, modelID: string, _options?: Record<string, any>) {
      // 代码模型（含 codex）使用 Response API
      if (modelID.includes("codex")) {
        return sdk.responses(modelID)
      }
      // 其他模型使用 Chat API
      return sdk.chat(modelID)
    },
    options: {}
  }
}

来源：provider.ts

四、基于插件的认证：复杂 OAuth 流程实现

对于需要外部依赖或自定义 UI 交互的复杂认证流程，通过插件系统实现，插件提供完整的 auth 钩子，管理 OAuth 全生命周期。

1. 核心插件结构

插件导出一个函数，返回包含 auth 钩子的对象，专门处理特定提供商的认证逻辑：

import type { Plugin } from "@opencode-ai/plugin"

export default function MyPlugin(input: Plugin.PluginInput): Plugin.Hooks {
  return {
    async auth(providerID) {
      // 仅处理目标提供商
      if (providerID !== "my-provider") return undefined
      
      return {
        provider: "my-provider",
        methods: [
          {
            type: "oauth",
            label: "Sign in with MyProvider",
            // 初始化 OAuth 授权流程
            async authorize(): Promise<Plugin.AuthOuathResult> {
              return {
                url: "https://auth.myprovider.com/authorize", // 授权 URL
                method: "code", // 授权模式（授权码）
                instructions: "Complete authorization in your browser",
                // 处理回调，交换令牌
                callback: async (code?: string) => {
                  const response = await fetch("https://auth.myprovider.com/token", {
                    method: "POST",
                    body: JSON.stringify({ code, client_id: "your-client-id" })
                  })
                  const tokens = await response.json()
                  
                  return {
                    type: "success",
                    access: tokens.access_token,
                    refresh: tokens.refresh_token,
                    expires: Date.now() + (tokens.expires_in * 1000)
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

2. 插件安装与加载

插件可通过 NPM 包或本地文件加载，在 opencode.json 中配置即可：

{
  "plugin": [
    "@scope/[email protected]", // NPM 包插件
    "file:///path/to/local/plugin.js" // 本地文件插件
  ]
}

• 系统会自动处理插件去重和加载顺序，数组字段拼接确保多个插件的 auth 钩子都能生效。

来源：plugin/index.ts, config.ts

五、高级配置：模型变体与超时处理

1. 模型变体配置（同一模型多套参数）

为同一基础模型定义多个变体，适配不同任务场景（如快速迭代、深度分析），配置示例：

{
  "provider": {
    "custom-provider": {
      "models": {
        "base-model": {
          "variants": {
            "fast": { // 快速变体：低成本、小窗口
              "cost": { "input": 0.001, "output": 0.001 },
              "limit": { "context": 64000, "output": 2048 },
              "options": { "max_tokens": 2048 }
            },
            "default": { // 默认变体：平衡成本与性能
              "cost": { "input": 0.002, "output": 0.004 },
              "limit": { "context": 128000, "output": 4096 }
            }
          }
        }
      }
    }
  }
}

2. 自定义超时与 Fetch 实现

为每个提供商配置专属超时时间，支持自定义 Fetch 逻辑（如重试、中断控制）：

{
  "provider": {
    "slow-provider": {
      "options": {
        "timeout": 600000, // 10分钟超时
        "fetch": async (input, init) => {
          const controller = new AbortController()
          // 自定义超时中断
          setTimeout(() => controller.abort(), 600000)
          return fetch(input, { ...init, signal: controller.signal })
        }
      }
    }
  }
}

来源：config.ts, provider.ts

六、测试与故障排除

1. 推荐测试策略

开发自定义提供商或认证流程时，需覆盖以下核心场景：

1. 单元测试：验证自定义加载器的自动加载逻辑、模型 ID 转换是否正确
2. 集成测试：模拟 OAuth 授权服务器，测试完整的令牌交换流程
3. 配置测试：验证配置优先级、数组拼接是否符合预期
4. SDK 测试：测试动态 NPM 包安装、SDK 实例化是否成功
5. 错误测试：验证缺失凭据、无效配置时的错误提示是否清晰

来源：provider/auth.ts

2. 常见问题排查

（1）提供商未加载

核心排查点：

• 提供商未被列入 disabled_providers 列表
• 配置中的提供商 ID 与自定义加载器注册的 ID 完全匹配
• 凭据可用（环境变量、API Key 或 OAuth 令牌已配置）
• 自定义加载器返回 autoload: true
• 模型元数据（cost、limit、capabilities）完整有效

（2）OAuth 回调失败

常见错误及解决方案：

• OauthMissing：回调前未启动授权流程，需先调用 authorize()
• OauthCodeMissing：授权码流程未传递 code，需确认回调 URL 正确返回 code
• OauthCallbackFailed：令牌交换失败，需检查 client_id、client_secret 配置，验证授权服务器响应

（3）模型未找到错误

核心排查点：

• 模型 ID 无拼写错误（系统会提供模糊匹配建议）
• 模型已列入提供商的 whitelist（未被 blacklist 排除）
• 模型元数据已正确定义在 provider.models 中

来源：provider.ts, provider/auth.ts

总结

1. 扩展 OpenCode 提供商的核心是分层配置 + 自定义加载器 + 插件化认证，兼顾简单性与灵活性。
2. 三种认证模式分别适配静态令牌、企业级 OAuth、集中化部署场景，覆盖全量使用需求。
3. 自定义加载器是处理特殊逻辑的关键，支持区域感知、双 API 切换等高级功能。
4. 插件系统实现复杂 OAuth 流程，无需修改核心代码即可扩展认证能力。
5. 配置优先级、模型变体、超时处理等高级功能，确保自定义提供商的稳定性与可用性。