---
title: "06 · 模型与供应商策略"
description: "在 OpenCode 中按任务风险、成本、速度和数据边界选择 provider、model、variant 与默认模型。"
verifiedAt: "2026-05-09"
---

OpenCode 支持切换 provider 和 model，但“可切换”不是让你每天追最新模型。真正稳定的策略，是把任务风险、模型能力、调用成本、数据边界和团队默认值放在一起判断。

> [!NOTE]
> **这一篇用 12 分钟换什么**：你会知道 provider、model、credential 怎么分层，第一次只该接几个 provider，默认模型为什么不要选最贵的，什么时候用高推理 variant，以及团队长期使用时怎么降低排障成本。

## 先给结论：先有主力模型，再扩展备选

默认模型应该是稳定、成本可接受、能完成真实 coding agent 任务的主力模型。高风险任务再切高推理模型；轻量任务交给 `small_model` 或低成本模型；provider 数量先少后多，否则排障会变成猜供应商、猜网络、猜凭据、猜模型能力。

```mermaid
flowchart LR
  Task["任务类型"] --> Risk["判断风险"]
  Risk --> Provider["选择 provider"]
  Provider --> Model["选择 model"]
  Model --> Variant["需要时切 variant"]
  Variant --> Verify["只读 / 小改 / 测试验证"]
  Verify --> Default["稳定后再写默认配置"]

  style Risk fill:#fef3c7,stroke:#f59e0b
  style Verify fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Default fill:#dbeafe,stroke:#3b82f6
```

如果一个模型只能聊天，不能稳定读文件、改文件、调用 shell、处理长上下文和解释 diff，它就不适合作为 OpenCode 的主力 coding 模型。

## 1. 先分清三层

OpenCode 里最容易混的是 provider、model 和 credential。

| 层级 | 负责什么 | 常见入口 |
| --- | --- | --- |
| Provider | 模型从哪里来，例如 OpenAI、Anthropic、Zen、OpenRouter、本地模型或企业网关 | `/connect`、`provider` 配置 |
| Model | 具体用哪个模型，是否使用 variant | `/models`、`model`、`--model` |
| Credential | 怎么证明你有权限调用它 | `/connect`、环境变量、本机 auth store |

`/connect` 更适合保存本机凭据，项目级 `opencode.json` 更适合写默认模型、provider options 和团队偏好。真实 API key 不应该进仓库、截图、日志或教程示例。

> [!WARNING]
> 凭据泄露不是“以后再修”的问题。只要 key 出现在配置、diff、CI 日志、分享会话或教学截图里，就应该立即轮换。

## 2. 第一次只接一个 provider

新手最常见的错误，是同时接入多个 provider，然后不知道故障来自哪一层。第一次用 OpenCode，先跑通一条最短闭环：

```text
/connect
  ↓
选择 provider 并完成认证
  ↓
/models
  ↓
选择一个 coding 主力模型
  ↓
只读解释项目结构
  ↓
低风险单文件改动
```

provider 选择可以这样判断：

- 新手快速跑通：OpenCode Zen 或你已有账号的主流 provider。
- 统一账单 / 国内网络：聚合 provider 或团队内部 gateway。
- 企业权限 / 合规：Bedrock、Azure、Vertex 或内部 AI gateway。
- 隐私 / 离线实验：Ollama、LM Studio、llama.cpp 等本地入口。
- 团队统一体验：同一 provider + 项目级默认模型。

OpenCode Zen 是官方提供的可选 provider，用来降低模型组合试错成本。它不是使用 OpenCode 的前提；如果你已经有稳定 provider，可以继续用自己的 key。

## 3. 模型先过五项验证

不要只看模型排行榜。OpenCode 是工具驱动的 coding agent，模型要在真实项目里验证。

| 维度 | 要验证什么 |
| --- | --- |
| 代码能力 | 能不能读懂项目结构、写出可运行改动 |
| 工具调用 | 能不能稳定调用文件、shell、MCP、LSP 等工具 |
| 上下文能力 | 能不能处理多文件、多轮任务和长输出 |
| 延迟和限流 | 会不会频繁卡住、超时、被 rate limit |
| 成本 | 能不能支撑日常高频使用 |

官方 Models 页会给推荐模型，但这类列表会随时间变化。更稳的做法是保留自己的验证闭环：只读解释项目结构、定位一个小 bug、改一个低风险文件、运行测试或给出可验证结果，再 review diff。

> [!IMPORTANT]
> 模型名、价格、上下文、免费期和可用性变化很快。写配置前用 `/models` 和 Models.dev 复核，不要从旧教程复制模型 ID。

## 4. 按任务风险分层

不要用同一个模型处理所有任务。更合理的是按风险和成本分层：

| 层级 | 任务 | 模型策略 |
| --- | --- | --- |
| L1 低风险 | 文档整理、摘要、命名建议、简单解释 | 快速低成本模型 |
| L2 中风险 | 小 bug、局部重构、测试补充、配置调整 | 稳定 coding 主力模型 |
| L3 高风险 | 架构迁移、安全、数据、发布、跨模块改动 | 高推理模型 + 人工确认 |
| L4 批处理 | 批量分类、格式修正、生成报告 | 低成本模型 + command 模板 |

模型越强，不代表越适合所有任务。小 README 修改交给最高推理模型通常只是浪费；跨模块迁移交给便宜小模型，风险会转移到后续排错上。

## 5. 默认模型不要设成最贵模型

默认模型应该是你最常用、最稳定、成本可接受的 coding 主力。它不是账号里最贵的模型。

项目配置可以这样表达分工：

```jsonc title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  // provider-id/model-id 的实际值用 `/models` 命令列出，或参 https://opencode.ai/docs/models
  "model": "provider-id/main-coding-model",
  "small_model": "provider-id/lightweight-model"
}
```

`model` 是主力模型。`small_model` 用于标题生成等轻量任务；如果没有单独配置，OpenCode 会尝试使用 provider 里的便宜模型，否则回退到主模型。

个人偏好更适合放全局配置。只有当团队确实需要同一默认模型时，才把 `model` 写进项目级配置。

## 6. 模型 ID 和加载优先级

OpenCode 的模型 ID 通常是：

```text
provider_id/model_id
```

排错时先看两件事：provider 是否已经连接并有权限，model ID 是否存在且被当前 provider 支持。

OpenCode 启动时按这个顺序找模型：命令行 `--model` / `-m` 优先，其次是 OpenCode config 里的 `model`，再其次是上次使用的模型，最后才是 OpenCode 内部优先级选出的第一个模型。

这能解释一个常见困惑：你明明改了配置，但当前命令行参数或会话状态仍然覆盖了它。

## 7. Variant 和 agent 绑定只在必要时用

Variant 是同一模型的不同配置形态，例如更高 reasoning、更低 verbosity 或更大 thinking budget。

适合切 variant 的场景：

- 快速解释、小修小补：低 reasoning / fast。
- 复杂 review、迁移、架构判断：高 reasoning。
- 少数高价值任务：更高预算或最大 thinking。

Agent 也可以绑定模型。比如 `docs` 用低成本稳定模型，`review` 用推理强的模型，`security` 用高推理且权限收紧的模型。这个能力适合角色差异明确的团队，不适合为了“看起来专业”给每个 agent 都配不同模型。

## 8. 不要在长任务中途随便切模型

这些情况不建议中途切模型：

- 当前模型已经读了很多上下文。
- 任务依赖前面的工具输出和修复假设。
- 工作区已经产生未提交 diff。
- 你只是因为输出慢而临时焦虑。

确实要切时，先让当前模型写交接摘要：

```text
请输出一份交接摘要：
1. 当前任务目标。
2. 已阅读和修改的文件。
3. 已验证的事实。
4. 尚未完成的步骤。
5. 需要避免误改的边界。
```

新模型接手时，从摘要和当前 diff 开始，不要让它靠猜继续。

## 9. Provider 出错先按层级排

Provider 出问题时，不要一上来换模型。

| 现象 | 优先检查 |
| --- | --- |
| `/models` 看不到模型 | `/connect` 是否成功、key 是否有效、provider 是否可用 |
| 认证失败 | API key、企业权限、环境变量、auth store |
| 请求 404 | `baseURL`、provider ID、model ID |
| 频繁超时 | provider 网络、限流、`timeout` / `chunkTimeout` |
| 能聊天但不会改代码 | 工具调用能力、模型是否适合 coding agent |
| 本地模型失败 | OpenAI-compatible endpoint、上下文和 tool calling 支持 |

先回到官方默认 provider 或一个已知可用模型，确认 OpenCode 本身没问题，再排自定义 endpoint、代理、企业网关和本地模型。

## 10. 一个可执行起点

如果你不知道怎么开始，先用这套策略：

- 普通阅读和文档：快速低成本模型。
- 局部代码编辑：稳定 coding 主力模型。
- 跨模块 bug 和重构：高推理模型。
- 安全、发布、数据：高推理模型 + 人工确认。
- 批量重复任务：低成本模型 + command 模板。
- 标题和摘要：`small_model`。

这套策略的目标不是永远最省钱，也不是永远最强，而是让任务风险、模型能力和成本结构匹配。

## 接下来去哪

<Cards>
  <Card title="选择模型" description="确认 `/models`、`provider_id/model_id`、variant 和默认模型的官方配置边界。" href="/docs/opencode/official/03-models/models" />
  <Card title="配置模型供应商" description="理解 provider、credential、baseURL、本地模型和自定义 endpoint 的分工。" href="/docs/opencode/official/03-models/providers" />
  <Card title="OpenCode Zen" description="判断是否使用官方精选模型入口，以及如何核对价格、隐私和团队限额。" href="/docs/opencode/official/08-platform/zen" />
  <Card title="Agents、Skills、Plugins" description="当模型策略需要落到角色和权限时，继续看 agent 分工。" href="/docs/opencode/understanding/05-agents-skills-plugins" />
</Cards>

## 官方资料

- OpenCode Models：[https://opencode.ai/docs/models](https://opencode.ai/docs/models)
- OpenCode Providers：[https://opencode.ai/docs/providers](https://opencode.ai/docs/providers)
- OpenCode Zen：[https://opencode.ai/docs/zen](https://opencode.ai/docs/zen)
- Models.dev：[https://models.dev](https://models.dev)
