叶云梦天

OpenCode 模型配置完全指南：从连接提供商到深调推理参数

引言

OpenCode 支持 75+ 个 LLM 提供商，从 OpenAI、Anthropic 到本地模型如 Ollama、LM Studio，选择空间极其丰富。但许多开发者将 API key 粘贴进去后就停滞在默认配置，错过了大量能显著提升编程体验的调优手段。

本文将系统性地讲解 OpenCode 的模型配置体系，涵盖提供商连接、默认模型设置、推理参数调优、模型黑白名单、变体管理以及小模型配置等核心话题，帮助你针对不同任务场景选择最合适的模型和参数组合。

1. 连接提供商

OpenCode 使用 /connect 命令来添加提供商的认证凭据。令牌统一存储在 ~/.local/share/opencode/auth.json 中。

1.1 基本流程

在 TUI 中输入 /connect，然后搜索目标提供商。以 DeepSeek 为例：

/connect
→ 搜索 "DeepSeek"
→ 输入 API key
→ /models 查看可用模型

1.2 利用已有订阅

OpenCode 一个被低估的功能是可以复用你已有的 AI 订阅，无需额外付费：

GitHub Copilot：通过 OAuth 登录，直接使用 Copilot 代理的模型
OpenAI ChatGPT Plus/Pro：同样通过 OAuth 认证即可
GitLab Duo：Premium/Ultimate 订阅用户可以直接使用

# 以 GitHub Copilot 为例
/connect
→ 搜索 "GitHub Copilot"
→ 浏览器打开 github.com/login/device
→ 输入设备码
→ 授权完成

这不仅省去了单独申请 API key 的麻烦，也让已付费的服务物尽其用。

1.3 本地模型

对于注重隐私或希望离线使用的场景，OpenCode 对接本地模型也非常便捷：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder (local)",
          "limit": {
            "context": 128000,
            "output": 65536
          }
        }
      }
    }
  }
}

支持 Ollama、llama.cpp、LM Studio、Atomic Chat 等主流本地推理工具。

2. 设置默认模型

每次启动 OpenCode 都手动选模型很烦人。通过配置 model 键可以固定默认模型：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.1-codex"
}

模型 ID 格式为 provider_id/model_id。对于自定义提供商，provider_id 就是 config 中 provider 下面的键名。

模型加载优先级

当 OpenCode 启动时，按以下顺序确定使用哪个模型：

--model 或 -m 命令行参数

opencode.json 中配置的 model 字段

上次使用的模型（会话记忆）

内部优先级列表的第一个模型

这意味着你可以用命令行参数临时覆盖默认配置：

# 本次使用 Claude，不改变配置文件
opencode -m anthropic/claude-sonnet-4-5-20250929

3. 模型参数精细调优

不同模型支持不同的运行时参数，OpenCode 允许在配置文件中精确控制。

3.1 OpenAI 推理模型

GPT-5 等推理模型支持控制推理深度：

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

reasoningEffort：推理深度，minimal / low / medium / high / xhigh
textVerbosity：回复长度，low / medium / high
reasoningSummary：推理摘要，auto 表示自动生成

3.2 Anthropic 思考预算

Claude 系列支持设置思考令牌预算：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "models": {
        "claude-sonnet-4-5-20250929": {
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        }
      }
    }
  }
}

budgetTokens：越大思考越深，但消耗也越大
type: "enabled"：开启思考模式

3.3 上下文和输出限制

自定义模型时可以指定上下文窗口和最大输出长度：

{
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "limit": {
            "context": 131072,
            "output": 32768
          }
        }
      }
    }
  }
}

不做限制的语境容易让计费失控。合理设置 output 上限既控制成本，也让模型更聚焦。

4. 模型黑白名单

当提供商提供几十甚至上百个模型时，/models 列表会变得冗长。通过黑白名单精简：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "whitelist": [
        "claude-opus-4-5-20251101",
        "claude-sonnet-4-5-20250929",
        "claude-haiku-4-5-20251001"
      ]
    },
    "openai": {
      "blacklist": [
        "gpt-4-turbo",
        "gpt-3.5-turbo"
      ]
    }
  }
}

whitelist：只保留列表中指定的模型
blacklist：从列表中移除指定模型
两者可以组合使用：whitelist 先收缩范围，blacklist 再从中排除

5. 模型变体（Variants）

5.1 内置变体

OpenCode 为多家提供商预设了变体。以 Anthropic 为例：

high：高思考预算（默认）
max：最大思考预算

OpenAI 的变体更丰富：

none —— 无推理
minimal —— 最小推理
low / medium / high / xhigh —— 梯度递增

5.2 自定义变体

你可以创建自己的变体来适配不同场景：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "models": {
        "gpt-5": {
          "variants": {
            "thinking": {
              "reasoningEffort": "high",
              "textVerbosity": "low"
            },
            "fast": {
              "reasoningEffort": "low",
              "textVerbosity": "low"
            },
            "balanced": {
              "reasoningEffort": "medium"
            }
          }
        }
      }
    }
  }
}

同一个模型按场景定义不同配置：快速浏览用 fast，深度分析用 thinking。

5.3 切换变体

通过 variant_cycle 快捷键（需在 keybinds 中配置）可以快速在不同变体间切换，不需要重新 /models 选模型。

6. 小模型配置

OpenCode 在执行某些轻量任务（如生成会话标题）时会使用一个小模型，默认使用 Zen 提供的 gpt-5-nano。你可以覆盖这个配置，特别是在使用自托管 GitLab 等需要锁定提供商的场景：

{
  "$schema": "https://opencode.ai/config.json",
  "small_model": "gitlab/duo-chat-haiku-4-5"
}

这确保即使是后台任务也使用你授权的模型，避免意外调用了外部服务。

7. 实战：构建多场景模型配置

下面是一个完整的实战配置，针对不同工作场景应用不同模型和参数：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.1-codex",
  "small_model": "anthropic/claude-haiku-4-5-20251001",
  "provider": {
    "opencode": {
      "models": {
        "gpt-5": {
          "variants": {
            "deep": {
              "reasoningEffort": "high",
              "textVerbosity": "low"
            },
            "quick": {
              "reasoningEffort": "low",
              "textVerbosity": "low"
            }
          }
        }
      }
    },
    "anthropic": {
      "whitelist": [
        "claude-opus-4-5-20251101",
        "claude-sonnet-4-5-20250929"
      ],
      "models": {
        "claude-opus-4-5-20251101": {
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 32000
            }
          }
        },
        "claude-sonnet-4-5-20250929": {
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          }
        }
      }
    }
  }
}

这个配置的思路是：

默认模型：使用 Zen 的 GPT-5.1 Codex，平衡性能与成本
小任务：Claude Haiku 快速且便宜
复杂重构：切换到 Claude Opus + 高思考预算
日常开发：Claude Sonnet + 中等思考预算
快速浏览：GPT-5 的 quick 变体

8. 针对 Agent 的模型覆盖

不同的 Agent 可以指定不同模型，这在 Plan/Build 模式下尤其有用：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "opencode/gpt-5.1-codex"
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "temperature": 0.1
    },
    "code-reviewer": {
      "description": "审查代码质量和安全性",
      "mode": "subagent",
      "model": "anthropic/claude-haiku-4-5-20251001",
      "temperature": 0.0,
      "permission": {
        "edit": "deny"
      }
    }
  }
}

Plan 模式用 Sonnet + 低温度保证分析严谨；Build 模式用能力最强的 Codex；审查 Agent 用快速的 Haiku 节省成本——每种 Agent 用最适配的模型。

9. 常见问题与技巧

模型不显示？

首先确认 /connect 已成功添加凭据。其次检查是否被 blacklist 过滤掉了。运行 opencode models 可以列出当前所有可用模型及其 ID。

工具调用不生效？

部分本地模型工具调用能力较弱。Ollama 用户建议将 num_ctx 调到 16k-32k。在配置中确保选择工具调用能力强的模型（如 Qwen-Coder、DeepSeek-Coder 系列）。

如何检查实际使用的 Token 消耗？

使用 Helicone 等 LLM 可观测平台集成，或者通过 /cost 命令查看会话的 token 消耗统计。

总结

OpenCode 的模型配置系统给予了开发者极大的灵活性——从选择哪个提供商、到设定推理深度、再到不同 Agent 用不同模型。关键是找到适合自己工作流的配置组合：

先连接：用 /connect 和 /models 建立基础

设默认：固定日常开发的主力模型

调参数：为推理模型开启思考模式和推理层级

建变体：同一个模型适配不同场景

配 Agent：Plan/Build/Review 各用其长

花半小时调好这些配置，之后的每一天都会享受到更精准、更高效、更经济的 AI 编程体验。

OpenCode 模型配置完全指南：从连接提供商到深调推理参数

OpenCode 模型配置完全指南：从连接提供商到深调推理参数

引言

1. 连接提供商

1.1 基本流程

1.2 利用已有订阅

1.3 本地模型

2. 设置默认模型

模型加载优先级

3. 模型参数精细调优

3.1 OpenAI 推理模型

3.2 Anthropic 思考预算

3.3 上下文和输出限制

4. 模型黑白名单

5. 模型变体（Variants）

5.1 内置变体

5.2 自定义变体

5.3 切换变体

6. 小模型配置

7. 实战：构建多场景模型配置

8. 针对 Agent 的模型覆盖

9. 常见问题与技巧

模型不显示？

工具调用不生效？

如何检查实际使用的 Token 消耗？

总结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客