进阶 opencode.ai 2026-11-11 16:13:22 · 18 阅读

第8章 OpenCode 模型管理与配置指南

模型 使用 /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提供商特定的请求体字段。
OpenCode 首先应用提供商值,其次应用模型值,最后应用所选变体。 嵌套的 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 令牌输出限制。
  • 未指定的输入限制。
OpenCode 识别 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。
自动缓存而不带标记的提供商(如 Gemini)会忽略它。更长的寿命通常写入成本更高:Anthropic 对一小时缓存写入收取 2 倍输入价格,对五分钟写入收取 1.25 倍。 预热可以使用寿命以 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 Chattrue 或 false。当设置了 reasoningField 或模型是 DeepSeek 时默认为 true,否则为 false。
maxTokensField承载输出令牌限制的 body 字段。OpenAI Chatmax_completion_tokens 或 max_tokens。未设置时检测需要它的提供商(如 DeepSeek、Moonshot、Together AI、Z.AI 和 Cerebras)的 max_tokens,否则为 max_completion_tokens。
requireFinishReason将没有 finish_reason 而结束的流视为不完整响应错误。false 接受其为已完成。OpenAI Chattrue 或 false。默认为 true。
requireAssistantAfterTool在工具结果和下一条用户消息之间插入助手消息,用于拒绝该顺序的端点。OpenAI Chattrue 或 false。Mistral 家族模型 ID 默认为 true,否则为 false。
supportsPromptCacheKey端点是否接受 prompt_cache_key body 字段。OpenAI Chat、OpenAI Responses、Mistraltrue 或 false。OpenAI Chat 仅在 true 时发送键,某些提供商包默认设置。其他 API 除非 false 否则发送。
streamUsage在流中通过 stream_options.include_usage 请求令牌使用量。OpenAI Chattrue 或 false。默认为 true。
cacheFormat端点接受的提示缓存标记语法。覆盖提供商的自动断点放置。alibaba 跳过工具定义。所有带提示缓存标记的 API,包括 OpenAI Chat、Anthropic Messages 和 Bedrock Converseanthropic 或 alibaba。未设置时使用提供商默认值。参见“提示缓存”。
supportsThinkingBlockBinding请求 API 丢弃先前上下文发生变化的思考块,而不是拒绝请求。Anthropic Messages、Bedrock Conversetrue 或 false。未设置时检测 Claude 5.1 及更高版本。
supportsEffortUpdates将推理力度更改作为按消息更新发送,这保留提示缓存。否则力度更改针对整个请求。Anthropic Messages、OpenAI Responsestrue 或 false。未设置时检测 Claude Opus 5、Claude 5.1 及更高版本,以及 GPT-6 及更高版本。
mediaInput决策请求中图片和其他媒体的位置。System Oneassets(从状态引用的图片)、state(内联在状态中)或 root(顶层图片、音频和视频列表)。未设置时使用提供商默认值。
OpenCode 自动从 Ollama、LM Studio 和 vLLM 的默认本地地址发现模型。你也可以手动配置任何 OpenAI 兼容服务器。 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 区分大小写。
使用目录 ID 而非提供商显示名称。Root、agent 和命令模型字段接受上述字符串形式或扩展对象: JSONC { "model": { "providerID": "openrouter", "model": "anthropic/claude-sonnet-5.5", }, } 扩展形式对生成或程序化配置很有用。 配置模型时请记住这些规则: JSONC { "model": "openai/gpt-6.1-sol" }
  • 选择器对象使用 model;提供商目录条目使用 modelID 作为发送给提供商的 ID。
  • 虽然根选择形状接受变体,但 V2 目录默认值不保留它。改为为会话、运行、Agent 或命令选择变体。
  • 模型选项是提供商特定的。另一个提供商包可能忽略或拒绝它们。
  • 目录数据、凭据和配置是位置范围的。在一个项目中可用的模型可能在另一个项目中不可用。
  • 配置文件通常自动重新加载。正在进行中的模型请求保留其开始时的设置。

评论 (0)