docs: document model compatibility settings (#59509)

This commit is contained in:
Aiden Cline
2026-10-27 00:02:55 -05:00
committed by GitHub
Unverified
parent 08132f1891
commit da638b65f5
3 changed files with 55 additions and 9 deletions
+10 -5
View File
@@ -24,22 +24,27 @@ export type CacheFormat = typeof CacheFormat.Type
export interface Compatibility extends Schema.Schema.Type<typeof Compatibility> {}
export const Compatibility = Schema.Struct({
/** OpenAI Chat: assistant-message field that carries reasoning. Unset uses the streamed field, else `reasoning_content`. */
reasoningField: ReasoningField.pipe(optional),
/** Require every assistant message to include its reasoning field, even when empty. */
/** OpenAI Chat: send the reasoning field on every prior assistant message, even when empty. */
requireReasoning: Schema.Boolean.pipe(optional),
/** OpenAI Chat: body field for the output token limit. Unset detects it from the provider. */
maxTokensField: MaxTokensField.pipe(optional),
/** OpenAI Chat: fail a stream that ends without `finish_reason`. Defaults to true. */
requireFinishReason: Schema.Boolean.pipe(optional),
/** OpenAI Chat: insert an assistant message between a tool result and the next user message. */
requireAssistantAfterTool: Schema.Boolean.pipe(optional),
/** OpenAI Chat, OpenAI Responses and Mistral: whether the endpoint accepts `prompt_cache_key`. */
supportsPromptCacheKey: Schema.Boolean.pipe(optional),
/** Request usage in the stream with `stream_options.include_usage`. Defaults to true. */
/** OpenAI Chat: request usage in the stream with `stream_options.include_usage`. Defaults to true. */
streamUsage: Schema.Boolean.pipe(optional),
/** Prompt-cache marker syntax the endpoint accepts. Overrides the route default; both send `cache_control`, and `alibaba` skips tool definitions. */
cacheFormat: CacheFormat.pipe(optional),
/** Supports Anthropic's thinking-prefix mismatch controls. Overrides model-ID detection. */
/** Anthropic Messages and Bedrock Converse: supports Anthropic's thinking-prefix mismatch controls. Overrides model-ID detection. */
supportsThinkingBlockBinding: Schema.Boolean.pipe(optional),
/** Supports per-message effort updates. Overrides model-ID detection. */
/** Anthropic Messages and OpenAI Responses: supports per-message effort updates. Overrides model-ID detection. */
supportsEffortUpdates: Schema.Boolean.pipe(optional),
/** Where a System One decision host reads media. Unset keeps the route default. */
/** System One: where the decision host reads media. Unset keeps the route default. */
mediaInput: MediaInput.pipe(optional),
}).annotate({ identifier: "Model.Compatibility" })
+43 -2
View File
@@ -273,7 +273,7 @@ For an OpenAI-compatible model that streams reasoning in a custom assistant-mess
OpenCode recognizes `reasoning`, `reasoning_content`, and `reasoning_text`, and also accepts another provider-specific
string. It reads streamed reasoning from that field and restores the field when sending prior assistant messages back to
the model.
the model. See [Compatibility](#compatibility) for the related `requireReasoning` field.
## Prompt caching
@@ -305,7 +305,48 @@ Anthropic-style `cache_control` breakpoints. Set `compatibility.cacheFormat` on
OpenCode then marks the last tool definition, the system prompt, and the latest message with
`cache_control: { "type": "ephemeral" }`, which uses the endpoint's default five-minute cache lifetime. Use `"alibaba"`
for Alibaba Model Studio models, which accept the same markers but ignore them on tool definitions. Set
`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format.
`compatibility.cacheFormat` on the provider instead when every model it serves accepts the same format. See
[Compatibility](#compatibility) for the other fields.
## Compatibility
`compatibility` describes request and response quirks of the API a model is served through, such as which field carries
reasoning or whether the endpoint accepts `prompt_cache_key`. Each model is served through one API, and a field only
takes effect when that API reads it. Other fields are ignored.
```jsonc title="opencode.jsonc"
{
"providers": {
"local": {
"compatibility": { "streamUsage": false },
"models": {
"reasoner": {
"compatibility": { "reasoningField": "reasoning_content", "maxTokensField": "max_tokens" },
},
},
},
},
}
```
Provider `compatibility` applies to every model of that provider. A model's own `compatibility` overrides it field by
field: OpenCode starts from the values [models.dev](https://models.dev) publishes for the model's API (`reasoningField`,
`maxTokensField`, and `mediaInput`), then applies the model's configuration. Unset fields keep the provider package's
built-in default or detection. `supportsThinkingBlockBinding` and `supportsEffortUpdates` are model-only.
| Field | What it does | Read by | Values and default |
| --- | --- | --- | --- |
| `reasoningField` | Assistant-message field that carries reasoning. Checked first when reading streamed reasoning and used when sending prior reasoning back. | OpenAI Chat | Any field name except `role`, `content`, `refusal`, or `tool_calls`. Unset uses the field seen in the stream, else `reasoning_content`. |
| `requireReasoning` | Sends the reasoning field on every prior assistant message, as an empty string when there was no reasoning. | OpenAI Chat | `true` or `false`. Defaults to `true` when `reasoningField` is set or the model is DeepSeek, otherwise `false`. |
| `maxTokensField` | Body field that carries the output token limit. | OpenAI Chat | `max_completion_tokens` or `max_tokens`. Unset detects `max_tokens` for providers that need it, such as DeepSeek, Moonshot, Together AI, Z.AI, and Cerebras, otherwise `max_completion_tokens`. |
| `requireFinishReason` | Treats a stream that ends without `finish_reason` as an incomplete response error. `false` accepts it as finished. | OpenAI Chat | `true` or `false`. Defaults to `true`. |
| `requireAssistantAfterTool` | Inserts an assistant message between a tool result and the next user message, for endpoints that reject that order. | OpenAI Chat | `true` or `false`. Defaults to `true` for Mistral-family model IDs, otherwise `false`. |
| `supportsPromptCacheKey` | Whether the endpoint accepts the `prompt_cache_key` body field. | OpenAI Chat, OpenAI Responses, Mistral | `true` or `false`. OpenAI Chat only sends the key when `true`, which some provider packages set by default. Other APIs send it unless `false`. |
| `streamUsage` | Requests token usage in the stream with `stream_options.include_usage`. | OpenAI Chat | `true` or `false`. Defaults to `true`. |
| `cacheFormat` | Prompt-cache marker syntax the endpoint accepts. Overrides the provider's automatic breakpoint placement. `alibaba` skips tool definitions. | Every API with prompt-cache markers, including OpenAI Chat, Anthropic Messages, and Bedrock Converse | `anthropic` or `alibaba`. Unset uses the provider default. See [Prompt caching](#prompt-caching). |
| `supportsThinkingBlockBinding` | Asks the API to drop thinking blocks whose earlier context changed instead of rejecting the request. | Anthropic Messages, Bedrock Converse | `true` or `false`. Unset detects Claude 5.1 and later. |
| `supportsEffortUpdates` | Sends reasoning effort changes as per-message updates, which keep the prompt cache. Otherwise the effort changes for the whole request. | Anthropic Messages, OpenAI Responses | `true` or `false`. Unset detects Claude Opus 5, Claude 5.1 and later, and GPT-6 and later. |
| `mediaInput` | Where images and other media go in a decision request. | System One | `assets` (images referenced from the state), `state` (inline in the state), or `root` (top-level `images`, `audio`, and `videos` lists). Unset uses the provider default. |
## Local
+2 -2
View File
@@ -90,7 +90,7 @@ The `providers` object is keyed by the provider ID used in model references, suc
| `env` | Ordered environment variable names that can provide the credential. |
| `package` | Runtime provider package. |
| `canonical` | Built-in provider ID whose catalog defaults this provider inherits. |
| `compatibility` | Request and response compatibility overrides for every model of this provider. Model `compatibility` overrides individual fields. `supportsThinkingBlockBinding` and `supportsEffortUpdates` are model-only. |
| `compatibility` | API quirks shared by every model of this provider. See [Compatibility](/models#compatibility). |
| `settings` | Typed OpenCode controls and JSON options passed to the runtime package. |
| `headers` | String-valued HTTP headers added to requests. |
| `body` | JSON fields merged into request bodies. |
@@ -300,7 +300,7 @@ ID sent to the provider.
| `headers` | Additional string-valued request headers. |
| `body` | Additional JSON request body fields. |
| `capabilities` | Tool support, accepted input and output media types, temperature support, and reasoning controls. |
| `compatibility` | Request and response compatibility overrides. |
| `compatibility` | API quirks for this model, overriding the provider's. See [Compatibility](/models#compatibility). |
| `variants` | Named variants with their own `settings`, `headers`, and `body`. |
| `cost` | Input, output, and optional cache pricing per million tokens. |
| `limit` | Context, input, and output token limits. |