---
title: "选择模型"
description: "基于 OpenCode 官方 Models 文档，帮助新手理解 provider、model、variant 和默认模型的选择边界。"
verifiedAt: "2026-05-09"
---

OpenCode 通过 **AI SDK**（Vercel 维护的 JS/TS 模型调用库，把不同 provider 的 API 差异统一成一套接口）和 **Models.dev**（社区维护的 LLM 元数据目录，OpenCode 从这里拉模型 ID、参数、上下文长度、价格等公开信息）支持 75+ LLM provider，也支持本地模型。模型页真正要解决的不是“哪个模型最新”，而是怎么确认 provider 已连上、模型 ID 写对、默认模型合适、variant（变体——同一模型的不同推理强度配置，比如"高思考预算"和"快速"两套）没有滥用。

> [!NOTE]
> **这一篇用 10 分钟换什么**：你会知道 `/models` 用来确认什么、`provider_id/model_id` 怎么写、官方推荐模型清单为什么不能死记、variant 怎么切，以及 OpenCode 启动时按什么优先级加载模型。

## 先给结论：先验证模型能完成 OpenCode 任务

一个模型适不适合 OpenCode，不只看聊天质量，还要看它能否稳定使用工具。

```mermaid
flowchart LR
    Connect["/connect 添加 provider 凭据"] --> Models["/models 查看可用模型"]
    Models --> Pick["选择 coding 主力模型"]
    Pick --> Read["只读解释项目结构"]
    Read --> Edit["低风险单文件修改"]
    Edit --> Verify["运行测试 / 检查 diff"]
    Verify --> Default["再设为默认模型"]

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

不要在还没跑通 provider 和工具调用之前，就把某个模型写成全局默认。

## 1. Provider 和 model 先分清

Provider 是模型从哪里来，例如 OpenAI、Anthropic、Google、OpenCode Zen、本地模型、企业网关或自定义 provider。

Model 是具体模型。OpenCode 里的完整模型 ID 通常是：

```text
provider_id/model_id
```

如果你用 OpenCode Zen，官方示例写法是：

```text
opencode/gpt-5.1-codex
```

如果使用自定义 provider，`provider_id` 来自配置里 `provider` 的 key，`model_id` 来自该 provider 下的 `models` key。

## 2. 用 `/models` 选择模型

配置好 provider 以后，在 TUI 输入：

```text
/models
```

这一步用于确认三件事：

- provider 凭据是否可用。
- 当前 provider 能看到哪些模型。
- 你准备写进配置的模型 ID 是否真实存在。

如果 `/models` 看不到模型，先排 `/connect`、API key、provider 权限和网络，不要直接改 model ID。

## 3. 官方推荐模型怎么读

官方 Models 页会列出若干适合 OpenCode 的模型，并明确说明清单不完整，也不一定永远最新。当前官方页列出的例子包括：

- GPT 5.2
- GPT 5.1 Codex
- Claude Opus 4.5
- Claude Sonnet 4.5
- Minimax M2.1
- Gemini 3 Pro

这类列表适合当起点，不适合当永久结论。OpenCode 需要的是“代码生成 + 工具调用”都稳定的模型。一个模型如果只会聊天，但不会稳定读文件、改文件、跑命令，就不适合作为主力 coding 模型。

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

## 4. 设置默认模型

默认模型写在 OpenCode config 的 `model` key：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider_id/model_id"
}
```

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

项目配置只在团队确实需要同一个默认模型时使用。个人偏好更适合放全局配置；临时实验用 `/models` 或命令行参数覆盖。

## 5. 配置模型 options

可以在 `provider.models` 下给模型设置全局 options，例如 reasoning、verbosity、thinking budget 等。具体字段取决于 provider 和模型，不是所有模型都支持同一组选项。

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "models": {
        "gpt-5": {
          "options": {
            "reasoningEffort": "high",
            "textVerbosity": "low"
          }
        }
      }
    }
  }
}
```

Agent 级配置可以覆盖这里的全局 options。只有当某类 agent 确实需要不同模型行为时，再把 options 下沉到 agent；不要为了“看起来高级”给每个模型都写一套 options。

## 6. Variant 怎么用

Variant 是同一模型的不同配置形态。官方文档列出的内置方向包括：

| Provider | 常见 variant |
| --- | --- |
| Anthropic | `high`、`max` |
| OpenAI | `none`、`minimal`、`low`、`medium`、`high`、`xhigh` |
| Google | `low`、`high` |

这个表不是完整清单。很多 provider 也有自己的默认 variant。

可以自定义或覆盖 variant，例如给同一模型准备高推理和快速两种模式：

```jsonc title="opencode.jsonc"
{
  "provider": {
    "openai": {
      "models": {
        "gpt-5": {
          "variants": {
            "thinking": {
              "reasoningEffort": "high",
              "textVerbosity": "low"
            },
            "fast": {
              "disabled": true
            }
          }
        }
      }
    }
  }
}
```

TUI 里可以通过 `variant_cycle` keybind 快速切换 variant。

> [!WARNING]
> 不要把所有任务都开最高 variant。高推理通常更慢、更贵，也不一定更适合小改动。

## 7. 模型加载优先级

OpenCode 启动时按这个顺序找模型：

| 优先级 | 来源 |
| --- | --- |
| 1 | 命令行 `--model` / `-m` |
| 2 | OpenCode config 里的 `model` |
| 3 | 上次使用的模型 |
| 4 | OpenCode 内部优先级选出的第一个模型 |

这能解释很多“我明明改了配置，为什么没生效”的问题。先看命令行参数和当前会话，再看 config。

## 8. 健康检查

模型配置健康，至少满足：

- `/models` 能列出可用模型。
- 你能说清 provider 和 model ID。
- 默认模型完成过只读项目理解、低风险修改和一次工具调用。
- 高风险任务会切高推理 variant，并人工确认。
- API key 没有出现在配置、diff、日志、截图或教程示例里。
- 模型异常时能区分凭据、权限、网络、baseURL、模型能力和工具调用问题。

## 接下来去哪

<Cards>
  <Card title="Provider 配置" description="先把 provider、credential、baseURL 和本地模型边界拆清楚。" href="/docs/opencode/official/03-models/providers" />
  <Card title="OpenCode Zen" description="第一次不知道怎么选模型时，先看 Zen 的模型 ID、计费和隐私边界。" href="/docs/opencode/official/08-platform/zen" />
  <Card title="模型策略" description="按任务风险、成本和速度分层，而不是每天追最新模型。" href="/docs/opencode/understanding/06-model-provider-strategy" />
  <Card title="Agents" description="当不同角色需要不同模型或权限时，再把模型策略下沉到 agent。" href="/docs/opencode/official/02-agents-skills/agents" />
</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 Config：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- Models.dev：[https://models.dev](https://models.dev)
