---
title: "配置模型供应商"
description: "理解 OpenCode provider、凭据、模型选择、本地模型和自定义 endpoint 的边界。"
verifiedAt: "2026-05-09"
---

OpenCode 可以接很多 LLM provider。官方 providers 页说明，OpenCode 使用 AI SDK 和 Models.dev，支持 75+ LLM providers，也支持本地模型。

> [!NOTE]
> **这一篇用 8 分钟换什么**：你会知道 provider、credential、model 和 baseURL 分别解决什么问题，第一次该怎么接入，以及 provider 出错时先排哪一层。

## 先给结论：第一次只接一个 provider

新手不需要先把每个 provider 的配置都学一遍。先让一条 provider 链路跑通，再比较价格、速度、模型质量和企业边界。

```mermaid
flowchart LR
  Connect["/connect 保存凭据"] --> Models["/models 确认模型"]
  Models --> Read["只读项目理解"]
  Read --> Edit["低风险单文件修改"]
  Edit --> Default["稳定后再写默认 model"]
  Default --> More["再扩展备用 provider / 本地模型 / 企业网关"]

  style Connect fill:#dbeafe,stroke:#3b82f6
  style Read fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style More fill:#fef3c7,stroke:#f59e0b
```

同时配置五六个 provider，会让问题变成“到底是哪家模型、网络、凭据、baseURL 或权限出了错”。

## provider 解决什么问题

Provider 是模型供应商入口。OpenAI、Anthropic、OpenRouter、Bedrock、Ollama、本地 OpenAI-compatible 服务，都属于 provider 层。

四个概念要分清：

| 概念 | 负责什么 |
| --- | --- |
| provider | 模型从哪里来 |
| credential | 怎么认证 |
| model | 具体用哪一个模型能力 |
| baseURL | 请求打到哪里 |

`/connect` 更适合管理凭据；`opencode.json` 更适合管理项目级偏好，例如默认模型、自定义 provider baseURL、provider options 或模型 alias。

> [!IMPORTANT]
> 不要把 API key 写进 `opencode.json`。配置文件会进仓库、会被复制、会被发给别人；凭据应该留在本机 auth store、环境变量或 secret manager。

## 怎么判断该选哪个 provider

按场景选择：

- 学习和日常开发：选 OpenCode Zen 或你已有账号的主流 provider。
- 国内网络、统一账单、多模型聚合：考虑 OpenRouter、302.AI、Vercel AI Gateway、Cloudflare AI Gateway 或团队内部 gateway。
- 企业云权限、VPC（Virtual Private Cloud，虚拟私有云——把云上资源放进只对你公司开放的隔离网络里）、合规：考虑 Bedrock、Azure、Vertex 等企业 provider。
- 隐私或离线实验：考虑 Ollama（命令行起本地模型最简单的工具）、LM Studio（桌面 GUI 跑本地模型）、llama.cpp（C++ 写的高性能本地推理引擎，前面两个底层都用它）、Atomic Chat 等本地模型入口。

本地模型的 tool calling 能力、上下文能力和速度要单独验证。能聊天不等于能稳定做 coding agent。

## `/connect` 和配置文件怎么分工

`/connect` 适合第一次上手：

```text
/connect
```

连接后用 `/models` 看可用模型。也可以用 CLI 管理：

```bash
opencode auth login
opencode auth list
```

项目配置适合写非敏感策略：

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

如果团队确实需要同一默认模型，再把它写进项目配置。个人偏好先放全局。

## baseURL 什么时候需要改

多数人不需要改 baseURL。只有这些情况才需要：

- 你走代理服务或企业网关。
- 你用 OpenAI-compatible 的本地模型服务。
- 你在 Azure、Bedrock、VPC endpoint 等环境里使用自定义 endpoint。
- 你需要把请求统一送到内部 AI gateway。

baseURL 改错时，常见表现是模型列表为空、认证失败、请求 404、工具调用异常。排查时先回到官方默认 provider，确认 OpenCode 本身没问题，再改自定义 endpoint。

## 新手常见坑

- 只看 provider 数量：provider 多不代表体验好。
- 把 key 写进项目配置：一旦提交就是泄露。
- 选了模型但没申请权限：企业 provider 经常需要先部署或授权模型。
- baseURL 写错：OpenCode 能启动，但模型请求失败。
- 本地模型能聊天但不能稳定调用工具。
- 同时配置多个聚合平台：错误来源变多，排查会变慢。
- 忽略供应商政策：某些订阅或第三方插件用法可能不被 provider 支持。

## 怎么验收

你至少要能确认：

- 当前默认 provider 和默认 model 是什么。
- key 没有出现在 `opencode.json`、git diff、日志和截图里。
- `/models` 能看到可用模型。
- 模型完成过一次读代码、一次改文件、一次工具调用。
- provider 出错时能区分凭据、模型权限、baseURL、网络和模型能力问题。

## 接下来去哪

<Cards>
  <Card title="选择模型" description="provider 连上后，再确认模型 ID、默认模型、variant 和加载优先级。" href="/docs/opencode/official/03-models/models" />
  <Card title="OpenCode Zen" description="如果第一次不知道选什么，可以先看官方精选模型入口的边界。" href="/docs/opencode/official/08-platform/zen" />
  <Card title="模型策略" description="按任务风险、成本和速度分层，而不是每天追最新模型。" href="/docs/opencode/understanding/06-model-provider-strategy" />
  <Card title="排查故障" description="provider、模型、认证、网络和缓存问题按层级定位。" href="/docs/opencode/official/08-platform/troubleshooting" />
</Cards>

## 官方资料

- Providers：[https://opencode.ai/docs/providers](https://opencode.ai/docs/providers)
- Models：[https://opencode.ai/docs/models](https://opencode.ai/docs/models)
- Config：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
