06 · 模型与供应商策略

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

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

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

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。

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

2. 第一次只接一个 provider

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

/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，模型要在真实项目里验证。

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

4. 按任务风险分层

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

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

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

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

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

{
  "$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 通常是：

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。
• 你只是因为输出慢而临时焦虑。

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

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

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

9. Provider 出错先按层级排

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

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

10. 一个可执行起点

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

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

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

接下来去哪

官方资料

• OpenCode Models：https://opencode.ai/docs/models
• OpenCode Providers：https://opencode.ai/docs/providers
• OpenCode Zen：https://opencode.ai/docs/zen
• Models.dev：https://models.dev