进阶 opencode.ai 2026-11-11 16:13:22 · 18 阅读
第8章 OpenCode 模型管理与配置指南
模型
使用
OpenCode 首先应用提供商值,其次应用模型值,最后应用所选变体。
嵌套的
自动缓存而不带标记的提供商(如 Gemini)会忽略它。更长的寿命通常写入成本更高:Anthropic 对一小时缓存写入收取 2 倍输入价格,对五分钟写入收取 1.25 倍。
预热可以使用寿命以
OpenCode 自动从 Ollama、LM Studio 和 vLLM 的默认本地地址发现模型。你也可以手动配置任何 OpenAI 兼容服务器。
使用目录 ID 而非提供商显示名称。Root、agent 和命令模型字段接受上述字符串形式或扩展对象:
/models 选择当前会话的模型:
/models
OpenCode 会列出来自 models.dev、提供商集成以及你的配置中的模型。选择器仅显示当前项目中可用的、已启用的模型。在“提供商”中连接提供商。
从 /models 列表中选择一个条目,而不是猜测其提供商或模型 ID。该选择仅应用于当前会话,不会更改你的配置。
anthropic/claude-sonnet-5-5
可用性因项目而异:
- 模型必须处于启用状态。
- 其提供商必须在当前项目中可用。
- 来自其他项目的凭据和配置不会自动携带。
--model 为单次命令行运行选择模型,而不更改已配置的默认值:
Terminal
opencode run --model anthropic/claude-sonnet-5-5 "Refactor parseToken"
Agent 和命令也可以自行选择模型。参见“Agents 和 Commands”。
在 opencode.json 或 opencode.jsonc 中设置 model 来选择新工作的默认值:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-5-5",
}
当配置的模型已启用且其提供商可用时,它将作为目录默认值。否则,OpenCode 会回退到最新可用的支持模型。
会话中已选定的模型优先于配置的默认值。切换会话模型不会重写配置文件。根部的模型目前仅保留默认提供商和模型,不保留变体。
参见“Config”了解配置位置及优先级。
在服务进程上设置 OPENCODE_DISABLE_FREE_MODELS=1(或 true)以隐藏免费的 OpenCode 模型:
Terminal
OPENCODE_DISABLE_FREE_MODELS=1 opencode serve
对于共享后台服务器:
Terminal
opencode service set env OPENCODE_DISABLE_FREE_MODELS 1
“免费”指的是 opencode 或 opencode-go 模型且没有输入价格。这些模型将从目录和默认值中消失;明确选择它们将导致“Model unavailable”错误。登出时,除非你连接 OpenCode Console 账号或设置 OPENCODE_API_KEY,否则 opencode 提供商不存在,这将恢复其付费模型。
变体是单个模型的命名选项,通常用于推理力度或令牌预算。为运行、会话、Agent 或命令选择变体时,在模型名称后添加 #variant:
Terminal
opencode run --model openai/gpt-6.1-sol#high "Review this migration plan"
变体名称来自所选模型当前的目录元数据。low、high 和 max 等名称并非对所有模型都可用,未知的变体将产生模型解析错误。
在模型的 variants 数组中定义新变体,或替换具有相同 ID 的目录变体:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"openai": {
"models": {
"gpt-6.1-sol": {
"settings": {
"reasoningEffort": "medium",
},
"variants": [
{
"id": "fast",
"settings": {
"reasoningEffort": "low",
},
},
{
"id": "deep",
"settings": {
"reasoningEffort": "high",
"reasoningSummary": "auto",
},
},
],
},
},
},
},
}
每个变体可以包含 settings、headers 和 body。其值在提供商和模型值之后应用。
要替换模型的推理变体,在 capabilities.reasoning 中描述其推理控件,使用 models.dev v2 格式。OpenCode 据此为模型包构建变体:
opencode.jsonc
{
"providers": {
"openai": {
"models": {
"gpt-6.1-sol": {
"capabilities": {
"reasoning": {
"supported": true,
"effort": ["low", "medium", "high"],
},
},
},
},
},
},
}
| 字段 | 用途 |
|---|---|
| supported | 模型是否进行推理。false 或没有控件的 true 不添加变体。 |
| toggle | 添加一个关闭推理的 none 变体。 |
| effort | 提供的力度级别。default 保留提供商默认值且不添加变体。 |
| budget | 可选的最小和最大思考令牌数。设置 effort 时被忽略。 |
variants 中列出的变体会叠加在由 capabilities.reasoning 构建的变体之上。
提供商和模型条目可以使用 settings、headers 和 body 自定义请求:
opencode.jsonc
{
"providers": {
"openai": {
"settings": {
"baseURL": "https://api.example.com/v1",
},
"headers": {
"X-Team": "platform",
},
"models": {
"gpt-6.1-sol": {
"settings": {
"reasoningEffort": "high",
},
"body": {
"store": false,
},
},
},
},
},
}
| 字段 | 用途 |
|---|---|
| settings | 提供商包选项,如 baseURL 或 reasoningEffort。 |
| headers | 额外的 HTTP 请求头。 |
| body | 提供商特定的请求体字段。 |
settings 和 body 对象会被合并。后续数组和标量值会替换先前的值。Header 名称不区分大小写。选项是提供商特定的,可能被另一个提供商包忽略或拒绝。
使用 modelID 为 API 模型提供友好的目录 ID:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"model": "openai/coding-default",
"providers": {
"openai": {
"models": {
"coding-default": {
"modelID": "gpt-6.1-sol",
"name": "Coding default",
"capabilities": {
"tools": true,
"freeform": ["text", "lark"],
"input": ["text", "image"],
"output": ["text"],
},
"limit": {
"context": 200000,
"output": 32000,
},
},
},
},
},
}
在这里,openai/coding-default 是可选择的引用,而 gpt-6.1-sol 被发送给提供商。对于不在目录中的模型,OpenCode 假设:
- JSON 工具支持、文本和图片输入、文本输出。除非
capabilities.freeform列出格式,否则没有自由格式工具输入。 - 200,000 令牌上下文限制和 32,000 令牌输出限制。
- 未指定的输入限制。
text、regex 和 lark。来自 models.dev 的其他格式名称会被忽略,而不会丢弃模型或其工具。如果前面的代理拒绝目录模型的自由格式工具,请为该模型设置 capabilities.freeform 为 []。
这些是回退假设,而非检测到的功能。已知时请设置准确的功能和限制值;显式值会替换回退值。添加 disabled: true 以从可用目录中隐藏模型:
opencode.jsonc
{
"providers": {
"openai": {
"models": {
"legacy-model": {
"disabled": true,
},
},
},
},
}
对于以自定义 assistant-message 字段流式传输推理的 OpenAI 兼容模型,设置 compatibility.reasoningField:
opencode.jsonc
{
"providers": {
"local": {
"models": {
"reasoner": {
"compatibility": {
"reasoningField": "reasoning_content",
},
},
},
},
},
}
OpenCode 识别 reasoning、reasoning_content 和 reasoning_text,并接受另一种提供商特定的字符串。它从该字段读取流式推理,并在将先前助手消息发回模型时恢复该字段。参见“Compatibility”了解相关的 requireReasoning 字段。
OpenCode 自动在已知需要缓存断点的路由上放置它们,例如 Anthropic。当 Claude 模型通过 OpenAI 兼容代理(如 LiteLLM)提供时,OpenCode 无法判断它们需要 Anthropic 风格的 cache_control 断点。在这些 Claude 模型上设置 compatibility.cacheFormat:
opencode.jsonc
{
"providers": {
"litellm": {
"package": "@opencode/ai/providers/openai-compatible",
"settings": { "baseURL": "https://litellm.example.com/v1" },
"models": {
"claude-sonnet-5-5": {
"compatibility": { "cacheFormat": "anthropic" },
},
"claude-opus-5-5": {
"compatibility": { "cacheFormat": "anthropic" },
},
// 同一代理上的其他模型自动缓存,无需设置。
"gpt-6.1-sol": {},
},
},
},
}
OpenCode 随后将 cache_control: { "type": "ephemeral" } 标记在最后一个工具定义、系统提示和最新消息上,这使用端点默认的五分钟缓存寿命。对于接受相同标记但在工具定义上忽略它们的 Alibaba Model Studio 模型,使用 "alibaba"。如果提供商提供的所有模型都接受相同格式,请改为在提供商上设置 compatibility.cacheFormat。参见“Compatibility”了解其他字段。
OpenCode 默认不发送缓存寿命,因此每个提供商使用其自己的默认值,例如 Anthropic 为五分钟。在提供商或模型上设置 settings.cache.ttl 以请求不同的寿命。模型设置覆盖提供商设置。
opencode.jsonc
{
"providers": {
"anthropic": {
"settings": { "cache": { "ttl": "1h" } },
"models": {
"claude-haiku-5-5": { "settings": { "cache": { "ttl": "5m" } } },
},
},
},
}
ttl 接受数字和单位:ms、s、m、h 或 d,例如 "5m"、"1h" 或 "24h"。OpenCode 按给定值发送,因此请使用提供商接受的值:
| API | 寿命所在处 |
|---|---|
| Anthropic Messages | 每个缓存标记上的 cache_control.ttl。Anthropic 接受 "5m" 和 "1h"。 |
| Bedrock Converse | 每个 cachePoint 上的 ttl。仅缓存五分钟较旧的 Claude 模型忽略 "1h"。 |
| OpenAI Chat 和 Responses | "24h" 去往 prompt_cache_retention;其他值去往 prompt_cache_options.ttl。 |
interval: "auto" 对其请求计时。
compatibility 描述模型所通过 API 的请求和响应怪癖,例如哪个字段承载推理或端点是否接受 prompt_cache_key。每个模型通过一个 API 提供服务,字段仅在该 API 读取时生效。其他字段被忽略。
opencode.jsonc
{
"providers": {
"local": {
"compatibility": { "streamUsage": false },
"models": {
"reasoner": {
"compatibility": { "reasoningField": "reasoning_content", "maxTokensField": "max_tokens" },
},
},
},
},
}
提供商 compatibility 适用于该提供商的所有模型。模型自身的 compatibility 逐字段覆盖它:OpenCode 从 models.dev 为该模型的 API 发布的值开始(reasoningField、maxTokensField 和 mediaInput),然后应用模型的配置。未设置的字段保留提供商包内置默认值或检测值。supportsThinkingBlockBinding 和 supportsEffortUpdates 仅限模型。
| 字段 | 作用 | 读取方 | 值和默认值 |
|---|---|---|---|
| reasoningField | 承载推理的助手消息字段。读取流式推理时首先检查,并在发回先前推理时使用。 | OpenAI Chat | 除 role、content、refusal 或 tool_calls 外的任何字段名。未设置时使用流中看到的字段,否则为 reasoning_content。 |
| requireReasoning | 在每个先前助手消息上发送推理字段,如果没有推理则发送空字符串。 | OpenAI Chat | true 或 false。当设置了 reasoningField 或模型是 DeepSeek 时默认为 true,否则为 false。 |
| maxTokensField | 承载输出令牌限制的 body 字段。 | OpenAI Chat | max_completion_tokens 或 max_tokens。未设置时检测需要它的提供商(如 DeepSeek、Moonshot、Together AI、Z.AI 和 Cerebras)的 max_tokens,否则为 max_completion_tokens。 |
| requireFinishReason | 将没有 finish_reason 而结束的流视为不完整响应错误。false 接受其为已完成。 | OpenAI Chat | true 或 false。默认为 true。 |
| requireAssistantAfterTool | 在工具结果和下一条用户消息之间插入助手消息,用于拒绝该顺序的端点。 | OpenAI Chat | true 或 false。Mistral 家族模型 ID 默认为 true,否则为 false。 |
| supportsPromptCacheKey | 端点是否接受 prompt_cache_key body 字段。 | OpenAI Chat、OpenAI Responses、Mistral | true 或 false。OpenAI Chat 仅在 true 时发送键,某些提供商包默认设置。其他 API 除非 false 否则发送。 |
| streamUsage | 在流中通过 stream_options.include_usage 请求令牌使用量。 | OpenAI Chat | true 或 false。默认为 true。 |
| cacheFormat | 端点接受的提示缓存标记语法。覆盖提供商的自动断点放置。alibaba 跳过工具定义。 | 所有带提示缓存标记的 API,包括 OpenAI Chat、Anthropic Messages 和 Bedrock Converse | anthropic 或 alibaba。未设置时使用提供商默认值。参见“提示缓存”。 |
| supportsThinkingBlockBinding | 请求 API 丢弃先前上下文发生变化的思考块,而不是拒绝请求。 | Anthropic Messages、Bedrock Converse | true 或 false。未设置时检测 Claude 5.1 及更高版本。 |
| supportsEffortUpdates | 将推理力度更改作为按消息更新发送,这保留提示缓存。否则力度更改针对整个请求。 | Anthropic Messages、OpenAI Responses | true 或 false。未设置时检测 Claude Opus 5、Claude 5.1 及更高版本,以及 GPT-6 及更高版本。 |
| mediaInput | 决策请求中图片和其他媒体的位置。 | System One | assets(从状态引用的图片)、state(内联在状态中)或 root(顶层图片、音频和视频列表)。未设置时使用提供商默认值。 |
ollama/gemma3:4b
lmstudio/google/gemma-4-26b-a4b
vllm/Qwen/Qwen3-Coder-30B-A3B-Instruct
当 Ollama 监听在 http://127.0.0.1:11434 时,使用 ollama 提供商 ID 选择发现的模型:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"model": "ollama/gemma3:4b",
}
OpenCode 在后台刷新清单,并从 Ollama 读取上下文、视觉和工具使用功能。仅嵌入模型被排除。
对于其他主机或端口,设置 Ollama 的 OpenAI 兼容 URL。发现仍使用同一路径前缀下的原生 Ollama API:
opencode.jsonc
{
"providers": {
"ollama": {
"settings": {
"baseURL": "http://127.0.0.1:5678/v1",
"apiKey": "{env:OLLAMA_API_KEY}",
},
},
},
}
如果端点不需要 bearer 身份验证,省略 apiKey。使用 "plugins": ["-opencode.provider.ollama"] 禁用发现。
对于在 http://127.0.0.1:1234 上未认证的 LM Studio 服务器,使用 lmstudio 提供商 ID 选择发现的模型:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"model": "lmstudio/google/gemma-4-26b-a4b",
}
OpenCode 在后台刷新清单,并从 LM Studio 读取上下文、视觉和工具使用功能。嵌入模型被排除。
对于其他主机或端口,设置 OpenAI 兼容 URL。模型仍自动发现:
opencode.jsonc
{
"providers": {
"lmstudio": {
"settings": {
"baseURL": "http://127.0.0.1:5678/v1",
"apiKey": "{env:LMSTUDIO_API_KEY}",
},
},
},
}
如果 LM Studio 身份验证被禁用,省略 apiKey。使用 "plugins": ["-opencode.provider.lmstudio"] 禁用发现。
对于在 http://127.0.0.1:8000 上监听的 vLLM,使用 vllm 提供商 ID 选择发现的模型:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"model": "vllm/Qwen/Qwen3-Coder-30B-A3B-Instruct",
}
OpenCode 检查 /health,在后台刷新 /v1/models,使用报告的 max_model_len 作为上下文限制,并仅包括由 vllm 拥有的模型卡片。
发现的模型宣告文本输入和输出,但不宣告视觉或工具。vLLM 通过 --enable-auto-tool-choice 和 --tool-call-parser 等服务器标志启用工具调用,发现不报告这些。
对于其他端点或已认证的服务器,设置其 OpenAI 兼容 URL:
opencode.jsonc
{
"providers": {
"vllm": {
"settings": {
"baseURL": "http://127.0.0.1:9000/v1",
"apiKey": "{env:VLLM_API_KEY}",
},
},
},
}
如果身份验证被禁用,省略 apiKey。使用 "plugins": ["-opencode.provider.vllm"] 禁用发现。支持路径前缀代理。例如,https://example.com/vllm/v1 检查 /vllm/health 并发现 /vllm/v1/models。
对于其他 OpenAI 兼容服务器,定义其提供商包、端点以及至少一个模型:
opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"model": "local/coder",
"providers": {
"local": {
"name": "Local server",
"package": "@opencode/ai/providers/openai-compatible",
"settings": {
"baseURL": "http://127.0.0.1:1234/v1",
},
"models": {
"coder": {
"modelID": "model-name-on-server",
"capabilities": {
"tools": true,
"input": ["text"],
"output": ["text"],
},
"limit": {
"context": 32768,
"output": 8192,
},
},
},
},
},
}
使用服务器的真实模型名称、限制、输入和输出类型以及工具支持。OpenCode 无法检测自定义模型回退值是否准确。如果端点需要密钥,在 settings 中添加 apiKey 并使用环境替换,如 "apiKey": "{env:LOCAL_API_KEY}";不要提交秘密。
模型选择器使用 provider/model 以及可选的 #variant:
openai/gpt-6.1-sol
openai/gpt-6.1-sol#high
openrouter/anthropic/claude-sonnet-5.5#high
| 部分 | 规则 |
|---|---|
| Provider | 在第一个 / 处结束;不能包含 / 或 #。 |
| Model | 可以包含额外的 / 字符;不能包含 #。 |
| Variant | 当存在时跟随 #。 |
| Casing | 提供商和模型 ID 区分大小写。 |
JSONC
{
"model": {
"providerID": "openrouter",
"model": "anthropic/claude-sonnet-5.5",
},
}
扩展形式对生成或程序化配置很有用。
配置模型时请记住这些规则:
JSONC
{
"model": "openai/gpt-6.1-sol"
}
- 选择器对象使用
model;提供商目录条目使用modelID作为发送给提供商的 ID。 - 虽然根选择形状接受变体,但 V2 目录默认值不保留它。改为为会话、运行、Agent 或命令选择变体。
- 模型选项是提供商特定的。另一个提供商包可能忽略或拒绝它们。
- 目录数据、凭据和配置是位置范围的。在一个项目中可用的模型可能在另一个项目中不可用。
- 配置文件通常自动重新加载。正在进行中的模型请求保留其开始时的设置。