Agents 🔧 OpenCode

选择正确的 AI 模型是高效使用 OpenCode 的关键。就像选择工具一样——你不会用螺丝刀去钉钉子，也不应该用擅长创意的模型去做严谨的代码审查。不同的模型在代码生成、推理分析、长上下文处理、多语言支持等维度上表现迥异。

OpenCode Provider 与模型选择 — --model 参数、Provider 配置、20+ 模型对比

简介

选择正确的 AI 模型是高效使用 OpenCode 的关键。就像选择工具一样——你不会用螺丝刀去钉钉子，也不应该用擅长创意的模型去做严谨的代码审查。不同的模型在代码生成、推理分析、长上下文处理、多语言支持等维度上表现迥异。

OpenCode 的强大之处在于它不绑定任何单一 Provider，而是让你自由地在 20+ 模型之间切换。本篇将深入讲解 --model 参数的使用方式、各 Provider 的配置细节，并对主流模型进行全面对比，帮助你在不同场景下做出最优选择。

无论你是追求极致推理能力的 Claude Sonnet，还是看重性价比的 DeepSeek-V3，亦或是需要在本地运行的 Ollama 模型——读完本篇后，你都能自信地为每个任务匹配最合适的模型。

目录

--model 参数详解

--model 是 OpenCode 中最重要的参数之一，它决定了你使用的是哪个模型。理解它的格式和优先级是使用 OpenCode 的第一步。

参数格式

bash
opencode --model <provider>:<model-id>

其中：

  • <provider>：Provider 名称，如 openai、anthropic、google 等
  • <model-id>：模型标识符，如 gpt-4o、claude-sonnet-4-20250514 等

简写模式

如果当前只配置了一个 Provider，可以省略 provider 名称：

bash
# 完整写法
opencode --model openai:gpt-4o

# 简写（只有一个 Provider 时）
opencode --model gpt-4o

模型别名

OpenCode 支持为常用模型设置别名，简化命令行输入：

json
// ~/.config/opencode/config.json
{
  "modelAliases": {
    "fast": "openai:gpt-4o-mini",
    "smart": "anthropic:claude-sonnet-4-20250514",
    "code": "openai:o1",
    "local": "ollama:qwen2.5-coder:32b"
  }
}

设置别名后，可以直接使用：

bash
opencode --model fast   # 等价于 openai:gpt-4o-mini
opencode --model smart  # 等价于 anthropic:claude-sonnet-4-20250514

列出可用模型

bash
# 列出所有可用模型
opencode models list

# 按 Provider 筛选
opencode models list --provider openai

# 查看当前使用的模型
opencode models current

命令行模型切换

在实际使用中，你可能需要根据任务复杂度动态切换模型。OpenCode 提供了多种切换方式：

方式一：启动时指定

bash
# 使用 Claude 处理复杂重构任务
opencode --model anthropic:claude-sonnet-4-20250514

# 使用 GPT-4o-mini 处理简单问题（省钱）
opencode --model openai:gpt-4o-mini

# 使用本地模型（零成本）
opencode --model ollama:qwen2.5-coder:32b

方式二：运行中切换

在 OpenCode 的交互模式中，可以通过斜杠命令切换模型：

text
/model openai:gpt-4o
/model anthropic:claude-sonnet-4-20250514
/model google:gemini-2.5-pro

方式三：为特定任务指定

如果你使用 opencode run 执行一次性任务，可以为每个任务指定不同模型：

bash
# 简单代码审查用轻量模型
opencode run --model openai:gpt-4o-mini "审查 src/utils.py"

# 复杂架构设计用强大模型
opencode run --model anthropic:claude-sonnet-4-20250514 "设计微服务架构"

配置文件中的默认模型

如果不想每次都在命令行指定模型，可以在配置文件中设置默认值：

json
{
  "defaultProvider": "openai",
  "defaultModel": "gpt-4o",
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192
      }
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192
      }
    }
  }
}

优先级顺序（从高到低）：

  1. 命令行 --model 参数
  2. 会话中通过 /model 切换
  3. 配置文件中的 defaultModel
  4. 各 Provider 配置中的 model
  5. 硬编码默认值

Provider 配置进阶

OpenAI Provider

json
{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "baseUrl": "https://api.openai.com/v1",
      "organization": "${OPENAI_ORG_ID}",
      "project": "${OPENAI_PROJECT_ID}",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192,
        "topP": 1,
        "frequencyPenalty": 0,
        "presencePenalty": 0,
        "seed": 42,
        "responseFormat": { "type": "text" },
        "timeout": 60000
      }
    }
  }
}

OpenAI 可用模型速查：

模型 ID 上下文窗口 输出上限 特点 参考价格
gpt-4o 128K 16K 旗舰多模态 $2.50/$10 (in/out)
gpt-4o-mini 128K 16K 轻量快速 $0.15/$0.60
o1 200K 100K 深度推理 $15/$60
o1-mini 128K 65K 轻量推理 $3/$12
o3-mini 200K 100K 高效推理 $1.10/$4.40
gpt-4-turbo 128K 4K 上一代旗舰 $10/$30

Anthropic Provider

json
{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "baseUrl": "https://api.anthropic.com",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192,
        "topP": 1,
        "topK": 40,
        "timeout": 60000
      }
    }
  }
}

Anthropic 可用模型速查：

模型 ID 上下文窗口 输出上限 特点 参考价格
claude-sonnet-4-20250514 200K 8K 最新旗舰 $3/$15
claude-opus-4-20250514 200K 8K 最强推理 $15/$75
claude-3-5-sonnet-20241022 200K 8K 经典高性能 $3/$15
claude-3-5-haiku-20241022 200K 8K 极速轻量 $0.80/$4
claude-3-opus-20240229 200K 4K 上一代旗舰 $15/$75

Google Gemini Provider

json
{
  "providers": {
    "google": {
      "apiKey": "${GOOGLE_API_KEY}",
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
      "options": {
        "temperature": 0.2,
        "maxOutputTokens": 8192,
        "topP": 0.95,
        "topK": 40,
        "timeout": 60000
      }
    }
  }
}

Google 可用模型速查：

模型 ID 上下文窗口 输出上限 特点 参考价格
gemini-2.5-pro 1M 64K 最强推理+长上下文 免费额度高
gemini-2.5-flash 1M 64K 快速经济 免费额度高
gemini-2.0-flash 1M 8K 上一代快速 免费

Ollama Provider（本地模型）

json
{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "options": {
        "temperature": 0.3,
        "numCtx": 8192,
        "numPredict": 4096,
        "topP": 0.9,
        "topK": 40,
        "repeatPenalty": 1.1,
        "timeout": 120000
      }
    }
  }
}

Ollama 热门代码模型速查：

模型 ID 参数量 特点 推荐硬件
qwen2.5-coder:32b 32B 最强开源代码模型 24GB+ VRAM
qwen2.5-coder:7b 7B 轻量快速 8GB+ VRAM
codellama:13b 13B 经典代码模型 12GB+ VRAM
deepseek-coder-v2:16b 16B 高性价比 16GB+ VRAM
llama3.1:8b 8B 通用能力强 8GB+ VRAM
llama3.1:70b 70B 接近闭源水平 48GB+ VRAM

其他主流 Provider

Groq

json
{
  "providers": {
    "groq": {
      "apiKey": "${GROQ_API_KEY}",
      "baseUrl": "https://api.groq.com/openai/v1",
      "model": "llama-3.1-70b-versatile",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192
      }
    }
  }
}
模型 ID 特点 参考价格
llama-3.3-70b-versatile 70B 模型极速推理 $0.59/$0.79
llama-3.1-8b-instant 8B 模型超快速 $0.05/$0.08
mixtral-8x7b-32768 MoE 架构大窗口 $0.24/$0.38

Mistral

json
{
  "providers": {
    "mistral": {
      "apiKey": "${MISTRAL_API_KEY}",
      "baseUrl": "https://api.mistral.ai/v1",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192
      }
    }
  }
}
模型 ID 特点 参考价格
mistral-large-latest 旗舰模型 $2/$6
codestral-latest 专精代码 $0.2/$0.6
ministral-8b-latest 轻量快速 $0.1/$0.1

DeepSeek

json
{
  "providers": {
    "deepseek": {
      "apiKey": "${DEEPSEEK_API_KEY}",
      "baseUrl": "https://api.deepseek.com",
      "model": "deepseek-chat",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192
      }
    }
  }
}
模型 ID 特点 参考价格
deepseek-chat (V3) 高性价比 ¥0.2/百万token
deepseek-reasoner (R1) 推理增强 ¥0.4/百万token

20+ 主流模型全面对比

综合对比表

排名 模型 Provider 编码能力 推理能力 速度 上下文 价格 综合推荐
1 claude-sonnet-4 Anthropic ★★★★★ ★★★★★ ★★★★ 200K 高 ⭐⭐⭐⭐⭐
2 claude-opus-4 Anthropic ★★★★★ ★★★★★ ★★★ 200K 极高 ⭐⭐⭐⭐⭐
3 o1 OpenAI ★★★★ ★★★★★ ★★ 200K 极高 ⭐⭐⭐⭐
4 gemini-2.5-pro Google ★★★★★ ★★★★★ ★★★ 1M 免费额度 ⭐⭐⭐⭐⭐
5 gpt-4o OpenAI ★★★★ ★★★★ ★★★★ 128K 中 ⭐⭐⭐⭐
6 o3-mini OpenAI ★★★★ ★★★★★ ★★★★ 200K 中 ⭐⭐⭐⭐
7 gemini-2.5-flash Google ★★★★ ★★★★ ★★★★★ 1M 低 ⭐⭐⭐⭐
8 claude-3-5-sonnet Anthropic ★★★★ ★★★★ ★★★★ 200K 中 ⭐⭐⭐⭐
9 deepseek-chat DeepSeek ★★★★ ★★★ ★★★★ 128K 极低 ⭐⭐⭐⭐
10 deepseek-reasoner DeepSeek ★★★ ★★★★★ ★★★ 64K 极低 ⭐⭐⭐⭐
11 gpt-4o-mini OpenAI ★★★ ★★★ ★★★★★ 128K 极低 ⭐⭐⭐⭐
12 mistral-large Mistral ★★★★ ★★★★ ★★★★ 128K 中 ⭐⭐⭐
13 claude-3-5-haiku Anthropic ★★★ ★★★ ★★★★★ 200K 低 ⭐⭐⭐
14 codestral Mistral ★★★★★ ★★★ ★★★★★ 256K 低 ⭐⭐⭐
15 llama-3.1-70b Meta/Groq ★★★★ ★★★★ ★★★★★ 128K 低 ⭐⭐⭐
16 qwen2.5-coder-32b Alibaba/Ollama ★★★★ ★★★ ★★★ 32K 免费 ⭐⭐⭐
17 o1-mini OpenAI ★★★ ★★★★ ★★★ 128K 中 ⭐⭐⭐
18 ministral-8b Mistral ★★★ ★★★ ★★★★★ 128K 极低 ⭐⭐⭐
19 gpt-4-turbo OpenAI ★★★★ ★★★ ★★★ 128K 高 ⭐⭐
20 claude-3-opus Anthropic ★★★★ ★★★★ ★★ 200K 极高 ⭐⭐
21 llama-3.1-8b Meta/Ollama ★★★ ★★★ ★★★★★ 128K 免费 ⭐⭐
22 codellama-13b Meta/Ollama ★★★ ★★ ★★★★ 4K 免费 ⭐⭐

编码能力专项对比

针对编程任务的专项评测（基于 HumanEval、MultiPL-E、SWE-bench 等基准）：

模型 HumanEval MultiPL-E SWE-bench Verified 代码审查 重构能力
claude-sonnet-4 96.3% 92.1% 73.8% ★★★★★ ★★★★★
claude-opus-4 97.1% 93.5% 75.2% ★★★★★ ★★★★★
gemini-2.5-pro 95.8% 91.3% 71.5% ★★★★★ ★★★★
o1 94.8% 90.7% 70.1% ★★★★ ★★★★★
gpt-4o 92.6% 88.4% 62.3% ★★★★ ★★★★
codestral 93.2% 89.1% 58.7% ★★★★ ★★★★
deepseek-chat 91.5% 87.6% 55.2% ★★★★ ★★★★
qwen2.5-coder-32b 89.3% 85.2% 48.6% ★★★★ ★★★
gpt-4o-mini 85.7% 80.3% 35.1% ★★★ ★★★

按场景推荐模型

场景 1：日常编码辅助

推荐：gpt-4o 或 claude-3-5-sonnet

日常编码需要平衡速度和质量。GPT-4o 响应速度快，适合快速补全和简单重构；Claude 3.5 Sonnet 代码理解能力强，适合复杂逻辑。

bash
# 日常开发
opencode --model openai:gpt-4o

# 复杂函数重构
opencode --model anthropic:claude-3-5-sonnet-20241022

场景 2：复杂系统设计

推荐：claude-opus-4 或 gemini-2.5-pro

架构设计需要深度推理和长上下文理解。Opus 的推理能力最强，Gemini 2.5 Pro 拥有 100 万 token 的超大上下文，可以一次性分析整个代码库。

bash
# 分析整个项目架构
opencode --model google:gemini-2.5-pro

# 设计复杂系统
opencode --model anthropic:claude-opus-4-20250514

场景 3：代码审查

推荐：claude-sonnet-4 或 gpt-4o

代码审查需要细致入微的分析能力。Claude Sonnet 4 在发现潜在 bug 和安全漏洞方面表现突出。

bash
opencode run --model anthropic:claude-sonnet-4-20250514 \
  "审查以下代码变更，重点关注安全性和性能问题"

场景 4：快速原型开发

推荐：gpt-4o-mini 或 gemini-2.5-flash

原型开发追求速度而非极致质量。这些模型响应速度快、成本低，非常适合迭代式开发。

bash
opencode --model openai:gpt-4o-mini

场景 5：离线/隐私敏感开发

推荐：ollama:qwen2.5-coder:32b

当代码不能离开本地时，Ollama 是唯一选择。Qwen2.5-Coder 32B 是目前最强的开源代码模型之一。

bash
# 确保 Ollama 已运行
ollama pull qwen2.5-coder:32b
opencode --model ollama:qwen2.5-coder:32b

场景 6：预算有限

推荐：deepseek-chat 或 gpt-4o-mini

DeepSeek 的性价比极高，GPT-4o-mini 在轻量级任务上表现不错且价格低廉。

bash
opencode --model deepseek:deepseek-chat

模型选择策略与决策树

text
你的任务是什么？
├── 简单补全/解释
│   └── 用 gpt-4o-mini / gemini-2.5-flash（省钱快速）
├── 日常编码
│   └── 用 gpt-4o / claude-3-5-sonnet（平衡型）
├── 复杂重构/架构
│   └── 用 claude-sonnet-4 / o1（深度推理）
├── 整个项目分析
│   └── 用 gemini-2.5-pro（100万上下文）
├── 代码不能出本机
│   └── 用 ollama:qwen2.5-coder:32b（本地运行）
└── 预算极低
    └── 用 deepseek-chat / gpt-4o-mini（性价比最高）

成本估算与用量监控

典型编码任务成本估算

任务类型 平均 Token 数 gpt-4o 成本 claude-sonnet-4 成本 gpt-4o-mini 成本 deepseek 成本
单函数补全 ~500 $0.002 $0.004 $0.0001 ¥0.0001
代码审查 ~5,000 $0.02 $0.03 $0.001 ¥0.001
文件重构 ~15,000 $0.06 $0.09 $0.003 ¥0.003
项目分析 ~50,000 $0.20 $0.30 $0.01 ¥0.01
架构设计 ~100,000 $0.40 $0.60 $0.02 ¥0.02

省钱技巧

  1. 分层使用：简单任务用便宜模型，复杂任务用贵模型
  2. 设置别名：为不同场景配置预定义模型
  3. 本地优先：能本地跑的用 Ollama，零成本
  4. 批量处理：类似任务合并一次请求，减少 overhead
  5. 监控用量：定期查看 Provider 控制台的用量统计

常见问题排查

问题 1：`Unknown model: xxx`

原因：模型 ID 拼写错误或该 Provider 不支持此模型。

解决方案：

bash
# 查看支持的模型列表
opencode models list --provider openai

# 检查模型 ID 是否正确
# 常见错误：gpt4o → gpt-4o，claude3 → claude-3-5-sonnet

问题 2：`Model not found` 但 ID 正确

原因：API Key 权限不足或该模型已下线。

解决方案：

bash
# 验证 API Key 权限
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models | grep "gpt-4o"

# 检查 Provider 状态
# 访问 Provider 的状态页面确认服务正常

问题 3：本地 Ollama 模型无法连接

原因：Ollama 服务未启动或端口被占用。

解决方案：

bash
# 启动 Ollama
ollama serve &

# 检查服务状态
curl http://localhost:11434/api/tags

# 拉取模型
ollama pull qwen2.5-coder:32b

问题 4：模型响应很慢

原因：模型本身推理速度慢或网络延迟。

解决方案：

bash
# 切换到更快的模型
opencode --model openai:gpt-4o-mini

# 检查网络延迟
curl -o /dev/null -s -w "%{time_total}s\n" \
  https://api.openai.com/v1/models

总结与下篇预告

本篇我们深入探索了 OpenCode 的模型选择体系。核心要点回顾：

  1. --model 参数：支持 provider:model-id 格式，可设置别名简化使用，有多种切换方式。
  2. Provider 配置：每个 Provider 有独特的配置选项，理解这些参数能显著提升模型输出质量。
  3. 20+ 模型对比：Claude Sonnet 4 综合最强，GPT-4o 平衡型选手，Gemini 2.5 Pro 上下文之王，DeepSeek 性价比之王，Ollama 隐私之选。
  4. 场景匹配：不同任务匹配不同模型——日常用 GPT-4o，复杂用 Opus/Sonnet，省钱用 Mini/DeepSeek，离线用 Ollama。
  5. 成本控制：通过分层使用、本地优先和定期监控，可以将 AI 编程成本控制在合理范围内。

掌握了模型选择之后，接下来的挑战是如何高效地使用 OpenCode 的命令行功能执行具体任务。OpenCode 的 run 命令让你可以以非交互方式一次性完成编码任务，支持附加文件、思维链模式等高级功能——这是将 AI 编程整合到自动化工作流中的关键。