多模型配置

连接多个提供商后，可以按任务需要手动切换模型，并为常用模型保存配置。

文档核验：2026-10-06，依据当前官方文档。本文未执行账号认证、模型 API 调用或本地模型运行测试；示例模型不是“最新模型”推荐，可用性以账号权限及本机列表为准。

# 连接并查看模型#

在 OpenCode 的交互界面中执行 /connect，分别连接所需提供商，再用 /models 打开模型选择器：

text
/connect

text
/models

在系统终端中，可以列出模型或按提供商筛选：

bash
opencode models
opencode models anthropic

输出的完整 ID 采用 provider_id/model_id 格式。需要更新模型目录缓存时，可执行 opencode models --refresh。模型目录和实际调用权限是两回事；认证、地区和服务端权限仍会影响调用结果。

# 设置默认模型和轻量模型#

编辑全局 ~/.config/opencode/opencode.json，或项目根目录的 opencode.json。也支持 JSONC 格式及 .jsonc 扩展名：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "model": "anthropic/claude-sonnet-4-5",
4  "small_model": "anthropic/claude-haiku-4-5"
5}

model 用于默认模型；small_model 用于标题生成等轻量任务，不是主模型请求失败时的备用模型。请用 opencode models 输出中你能使用的 ID 替换示例。项目配置与全局配置合并，同名键由项目配置覆盖，详见首次配置与配置文档。

# 配置多个提供商#

常见提供商可以直接通过 /connect 认证。若需在文件中引用环境变量，使用 provider.<提供商 ID>.options.apiKey：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "provider": {
4    "openai": {
5      "options": {
6        "apiKey": "{env:OPENAI_API_KEY}"
7      }
8    },
9    "anthropic": {
10      "options": {
11        "apiKey": "{env:ANTHROPIC_API_KEY}"
12      }
13    }
14  }
15}

启动前应确保对应变量已设置；不要把真实密钥提交到项目中。自定义端点字段是 options.baseURL，密钥字段是 options.apiKey，注意大小写。内置提供商不需要按旧教程填写 models = [...] 数组。

Azure 等提供商还有各自的认证和部署要求，应按官方提供商文档↗配置，不能直接复用旧版 TOML 示例。

# 临时切换模型#

在 TUI 中使用 /models 选择模型；启动时也可通过 --model（简写 -m）指定：

bash
opencode --model anthropic/claude-sonnet-4-5

命令行参数优先于配置中的 model。没有显式指定时，OpenCode 再按配置、上次使用记录及内部顺序选择模型。不要使用旧教程中的 /model list 或 ollama:模型名 格式。

# 接入本地或 OpenAI 兼容服务#

以下是 Ollama 本地接口的配置结构。先启动本地服务并准备一个支持所需工具调用的模型，将 your-local-model 替换成服务中实际存在的模型 ID：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "provider": {
4    "ollama": {
5      "npm": "@ai-sdk/openai-compatible",
6      "name": "Ollama 本地服务",
7      "options": {
8        "baseURL": "http://localhost:11434/v1"
9      },
10      "models": {
11        "your-local-model": {
12          "name": "我的本地模型"
13        }
14      }
15    }
16  }
17}

这里的 models 是以模型 ID 为键的对象。配置后在 /models 中选择对应模型；完整 ID 为 ollama/your-local-model。接入其他 OpenAI 兼容服务时，需换用自己的提供商 ID、端点和模型 ID，并按服务要求在 options.apiKey 引用密钥。本地模型的工具调用与上下文能力取决于模型及服务设置，不能仅凭“本地”就保证完整离线可用。

# 用量与成本#

在终端中查看 OpenCode 记录的 Token 用量与费用统计：

bash
opencode stats

费用以提供商账单为准，预算和限额应在相应服务的控制台确认。可以先手动选择成本较低且适合任务的模型，需要时再切换。

旧教程的 aliases、auto_model、fallback、budget、cost_optimization 不是本次核验的官方配置 Schema↗中的顶层字段；不要复制这些设置来实现自动选模、失败回退或强制预算。插件若提供类似能力，应单独遵循该插件的文档。

# 排查模型不可用#

用 /connect 检查所选提供商的认证方式，确认账号具备目标模型的调用权限。
用 opencode models <提供商 ID> 核对名称；自定义提供商则检查 provider 键与 models 键是否匹配。
检查 enabled_providers 和 disabled_providers 是否限制了目标提供商。
检查项目配置是否覆盖了全局配置，以及密钥环境变量是否传给了启动进程。
自定义服务还需核对 baseURL、网络连通性与服务端错误。列出模型成功不能替代实际请求验证。