From 20161e1459318286de3e2233c23d4ff92a3a1155 Mon Sep 17 00:00:00 2001 From: Gr33nbl00d Date: Mon, 19 Oct 2026 20:05:04 +0200 Subject: [PATCH] feat(core): discover models for configured OpenAI-compatible providers Custom OpenAI-compatible providers such as LiteLLM need every model listed by hand. Read GET {baseURL}/models and add the missing chat models, keeping configured models untouched. Ollama, LM Studio, and vLLM keep their own discovery. Discovered models accept text and can call tools unless the endpoint reports modalities or supported parameters, so an image in the history cannot break every later request to a text-only model. Guarded by the openai_compatible_discovery feature flag. --- .../client/src/promise/generated/types.ts | 1 + packages/core/src/plugin/internal.ts | 3 + .../src/plugin/provider/openai-compatible.ts | 178 +++++++++ .../plugin/provider-openai-compatible.test.ts | 353 ++++++++++++++++++ packages/protocol/openapi.json | 3 + packages/schema/src/config/flag.ts | 2 + services/site/src/docs/content/config.mdx | 14 + services/site/src/docs/content/providers.mdx | 51 +++ 8 files changed, 605 insertions(+) create mode 100644 packages/core/src/plugin/provider/openai-compatible.ts create mode 100644 packages/core/test/plugin/provider-openai-compatible.test.ts diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index a6a62e36cc2a..e0c92a810763 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -2631,6 +2631,7 @@ export type ConfigEntry = console_watches?: boolean mcp_events?: boolean full_codemode?: boolean + openai_compatible_discovery?: boolean schedules?: boolean part_rows?: boolean image_generate?: boolean | { model?: string | { providerID: string; model: string; variant?: string } } diff --git a/packages/core/src/plugin/internal.ts b/packages/core/src/plugin/internal.ts index 988343b8189b..cdcca82abf5a 100644 --- a/packages/core/src/plugin/internal.ts +++ b/packages/core/src/plugin/internal.ts @@ -110,6 +110,7 @@ import { McpCodeModeDefaultsPlugin } from "./mcp-codemode-defaults.js" import { ProviderPlugins } from "./provider.js" import { DynamicProviderPlugin } from "./provider/dynamic.js" import { OpencodePlugin } from "./provider/opencode.js" +import { OpenAICompatiblePlugin } from "./provider/openai-compatible.js" import { WebSearchPlugins } from "./websearch/index.js" import { SkillPlugin } from "./skill.js" import { VcsHgPlugin } from "./vcs/hg.js" @@ -305,6 +306,8 @@ const post = [ ConfigProviderPlugin.Plugin, // Run the dynamic npm SDK loader after SDK, instance, and external plugins register their `sdk` hooks. DynamicProviderPlugin, + // Fills configured providers with discovered models, so it must see their config applied first. + OpenAICompatiblePlugin, ConfigWebSearchPlugin.Plugin, ConfigPolicyPlugin.Plugin, ] as const satisfies readonly InternalPlugin[] diff --git a/packages/core/src/plugin/provider/openai-compatible.ts b/packages/core/src/plugin/provider/openai-compatible.ts new file mode 100644 index 000000000000..addf77701cdc --- /dev/null +++ b/packages/core/src/plugin/provider/openai-compatible.ts @@ -0,0 +1,178 @@ +import { define } from "@opencode/plugin/effect/plugin" +import type { Document, Entry } from "@opencode/schema/config" +import { type Duration, Effect, Schedule, Schema, Semaphore, Stream } from "effect" +import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http" +import { Bus } from "../../bus.js" +import { Config } from "../../config.js" +import { Credential } from "../../credential.js" +import { Flag } from "../../flag.js" +import { Model } from "../../model.js" +import { Provider } from "../../provider.js" +import type { PluginInternal } from "../internal.js" +import { foldSettings } from "./configured.js" + +const Strings = Schema.NullOr(Schema.Array(Schema.String)).pipe(Schema.optional) + +const RemoteModel = Schema.Struct({ + id: Schema.String, + mode: Schema.NullOr(Schema.String).pipe(Schema.optional), + // Gateways report modalities at the top level or under `architecture`, as OpenRouter does. + input_modalities: Strings, + output_modalities: Strings, + architecture: Schema.NullOr(Schema.Struct({ input_modalities: Strings, output_modalities: Strings })).pipe( + Schema.optional, + ), + supported_parameters: Strings, +}) + +const Models = Schema.Struct({ data: Schema.Array(RemoteModel) }) + +// Gateways such as LiteLLM also list embedding, image, and audio models. +const chat = new Set(["chat", "responses"]) + +const packages = new Set(["@ai-sdk/openai-compatible", "@opencode/ai/providers/openai-compatible"]) + +// These providers have dedicated discovery plugins that own their whole model list. +const dedicated = new Set(["ollama", "lmstudio", "vllm"]) + +type Target = ReturnType[number] + +export function make(interval: Duration.Input = "5 minutes") { + return define({ + id: "opencode.provider.openai-compatible", + effect: Effect.fn(function* (ctx) { + const http = HttpClient.filterStatusOk(yield* HttpClient.HttpClient) + const bus = yield* Bus.Service + const config = yield* Config.Service + const flags = yield* Flag.Service + const loading = Semaphore.makeUnsafe(1) + const loaded = { + inventory: new Map< + Provider.ID, + { source: string; models: readonly { id: string; capabilities: Model.Capabilities }[] } + >(), + hash: "[]", + } + + yield* ctx.provider.transform((providers) => { + for (const [providerID, item] of loaded.inventory) { + const provider = providers.get(providerID) + if (!provider) continue + for (const model of item.models) { + // Configured models keep their own capabilities. + if (provider.models.has(Model.ID.make(model.id))) continue + providers.models.update(providerID, model.id, (draft) => { + draft.capabilities = { + tools: model.capabilities.tools, + input: [...model.capabilities.input], + output: [...model.capabilities.output], + } + }) + } + } + }) + + const inventory = Effect.fnUntraced(function* (target: Target) { + const connection = yield* ctx.integration.connection.active(target.providerID) + const credential = connection + ? yield* ctx.integration.connection.resolve(connection).pipe(Effect.orElseSucceed(() => undefined)) + : undefined + // Same precedence as requests: a stored key replaces the configured one. + const apiKey = credential?.type === "key" ? credential.key : target.apiKey + const source = JSON.stringify([target.baseURL, apiKey, target.headers]) + const previous = loaded.inventory.get(target.providerID) + const request = HttpClientRequest.get(`${target.baseURL}/models`).pipe( + HttpClientRequest.acceptJson, + HttpClientRequest.setHeaders(target.headers ?? {}), + ) + const models = yield* http.execute(apiKey ? request.pipe(HttpClientRequest.bearerToken(apiKey)) : request).pipe( + Effect.flatMap(HttpClientResponse.schemaBodyJson(Models)), + Effect.timeout("5 seconds"), + Effect.map((response) => + response.data + .filter((model) => model.id.length > 0 && (!model.mode || chat.has(model.mode))) + .map((model) => ({ id: model.id, capabilities: capabilities(model) })) + .toSorted((a, b) => a.id.localeCompare(b.id)), + ), + // Log the message only: the request in the cause carries configured headers, which may hold secrets. + Effect.tapError((error) => + Effect.logDebug("openai-compatible model discovery failed", { + providerID: target.providerID, + message: error.message, + }), + ), + // Keep the last successful inventory through transient outages while the endpoint and key are unchanged. + Effect.orElseSucceed(() => (previous?.source === source ? previous.models : undefined)), + ) + return models === undefined ? [] : [[target.providerID, { source, models }] as const] + }) + + const load = Effect.fn("OpenAICompatiblePlugin.load")(function* () { + const entries = yield* config.entries() + // Internal plugins are not re-run on config changes, so read the flag on every refresh; turning it off drops + // the discovered models. + const results = flags.resolve(entries).openai_compatible_discovery.enabled + ? yield* Effect.forEach(targets(entries), inventory, { concurrency: 4 }) + : [] + const next = new Map(results.flat()) + const hash = JSON.stringify([...next]) + if (hash === loaded.hash) return + loaded.inventory = next + loaded.hash = hash + yield* ctx.provider.reload() + }) + const refresh = () => loading.withPermit(load()) + + yield* ctx.event.subscribe().pipe( + Stream.filter((event) => event.type === "config.updated"), + Stream.runForEach(refresh), + Effect.forkScoped({ startImmediately: true }), + ) + yield* bus.subscribe(Credential.Event.Switched).pipe( + Stream.runForEach(refresh), + Effect.forkScoped({ startImmediately: true }), + ) + yield* refresh().pipe(Effect.ignore, Effect.repeat(Schedule.spaced(interval)), Effect.forkScoped) + }), + } satisfies PluginInternal.InternalPlugin) +} + +export const OpenAICompatiblePlugin = make() + +function targets(entries: readonly Entry[]) { + const documents = entries.filter((entry): entry is Document => entry.type === "document") + const ids = new Set(documents.flatMap((file) => Object.keys(file.info.providers ?? {}))) + return [...ids].flatMap((id) => { + if (dedicated.has(id)) return [] + const configured = documents.flatMap((file) => file.info.providers?.[id] ?? []) + const pkg = configured.findLast((item) => item.package !== undefined)?.package + // Migrated V1 configs store the package as `aisdk:@ai-sdk/openai-compatible`. + if (pkg === undefined || !packages.has(Provider.packageName(pkg))) return [] + const settings = foldSettings(entries, id, undefined) + const baseURL = typeof settings?.baseURL === "string" ? settings.baseURL.replace(/\/+$/, "") : "" + if (!URL.canParse(baseURL) || !["http:", "https:"].includes(new URL(baseURL).protocol)) return [] + return [ + { + providerID: Provider.ID.make(id), + baseURL, + apiKey: typeof settings?.apiKey === "string" && settings.apiKey !== "" ? settings.apiKey : undefined, + headers: configured.reduce( + (headers: Record | undefined, item) => Provider.mergeHeaders(headers, item.headers), + undefined, + ), + }, + ] + }) +} + +// Without metadata, assume text-only input: an image sent to a text-only model fails every later request in the +// session, while a missing image capability only blocks attachments. +function capabilities(model: typeof RemoteModel.Type): Model.Capabilities { + const input = model.input_modalities ?? model.architecture?.input_modalities ?? ["text"] + return { + tools: model.supported_parameters?.includes("tools") ?? true, + // OpenRouter calls PDF input `file`. + input: input.map((modality) => (modality === "file" ? "pdf" : modality)), + output: model.output_modalities ?? model.architecture?.output_modalities ?? ["text"], + } +} diff --git a/packages/core/test/plugin/provider-openai-compatible.test.ts b/packages/core/test/plugin/provider-openai-compatible.test.ts new file mode 100644 index 000000000000..a7f6a3028bdf --- /dev/null +++ b/packages/core/test/plugin/provider-openai-compatible.test.ts @@ -0,0 +1,353 @@ +import { Bus } from "@opencode/core/bus" +import { Config } from "@opencode/core/config" +import { ConfigNormalize } from "@opencode/core/config/normalize" +import { ConfigProviderPlugin } from "@opencode/core/config/plugin/provider" +import { Credential } from "@opencode/core/credential" +import { Integration } from "@opencode/core/integration" +import { Model } from "@opencode/core/model" +import { Plugin } from "@opencode/core/plugin" +import { PluginHost } from "@opencode/core/plugin/host" +import { make } from "@opencode/core/plugin/provider/openai-compatible" +import { Provider } from "@opencode/core/provider" +import { Document, Event, Info } from "@opencode/schema/config" +import { describe, expect } from "bun:test" +import { Effect, Layer, Schema } from "effect" +import { withEnv } from "../fixture/env" +import { testEffect } from "../lib/effect" +import { PluginTestLayer } from "./fixture" + +const it = testEffect(Layer.merge(PluginTestLayer, Config.testLayer())) +const decode = Schema.decodeUnknownSync(Info) + +// Registers the config plugin first, matching production order, so discovery sees configured providers. +const addPlugins = Effect.fn(function* () { + const plugin = yield* Plugin.Service + const config = yield* PluginHost.make(plugin, ConfigProviderPlugin.Plugin.id) + yield* ConfigProviderPlugin.Plugin.effect(config) + const discovery = make("1 hour") + const host = yield* PluginHost.make(plugin, discovery.id) + yield* discovery.effect(host) +}) + +// Bounded by elapsed time rather than attempts, so a slow plugin start on a busy machine still fits. +function eventually( + effect: Effect.Effect, + predicate: (value: A) => boolean, + deadline = Date.now() + 10_000, +): Effect.Effect { + return Effect.gen(function* () { + const value = yield* effect + if (predicate(value)) return value + if (Date.now() > deadline) return yield* Effect.fail(new Error("Timed out waiting for value")) + yield* Effect.promise(() => Bun.sleep(1)) + return yield* eventually(effect, predicate, deadline) + }) +} + +// Shaped like LiteLLM, which only sometimes reports a mode. +const litellm = [ + { id: "configured-model", object: "model" }, + { id: "discovered-model", object: "model", mode: "chat" }, + { id: "untyped-model", object: "model", mode: null }, + { id: "embedding-model", object: "model", mode: "embedding" }, +] + +function serve(data: readonly Record[] = litellm) { + const state = { failing: false } + const requests: Array<{ path: string; authorization: string | null; team: string | null }> = [] + const server = Bun.serve({ + port: 0, + fetch: (request) => { + requests.push({ + path: new URL(request.url).pathname, + authorization: request.headers.get("authorization"), + team: request.headers.get("x-team"), + }) + if (state.failing) return new Response(null, { status: 503 }) + return Response.json({ object: "list", data }) + }, + }) + return { state, requests, server } +} + +// Flags are off in the test channel, so discovery is switched on explicitly. +function configuration(providers: Record, enabled = true) { + return new Document({ + type: "document", + info: decode({ providers, experimental: { openai_compatible_discovery: enabled } }), + }) +} + +describe("OpenAICompatiblePlugin", () => { + it.live("adds discovered models to configured OpenAI-compatible providers without replacing configured ones", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + yield* config.setEntries([ + configuration({ + litellm: { + package: "@ai-sdk/openai-compatible", + settings: { baseURL: `${server.url.origin}/litellm/v1/`, apiKey: "secret" }, + headers: { "x-team": "core" }, + models: { "configured-model": { name: "Configured" } }, + }, + mistral: { package: "@ai-sdk/mistral", settings: { baseURL: `${server.url.origin}/mistral` } }, + ollama: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/ollama/v1` } }, + }), + ]) + yield* addPlugins() + + const discovered = yield* eventually( + models.get(providerID, Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(discovered).toMatchObject({ + modelID: "discovered-model", + name: "discovered-model", + capabilities: { tools: true, input: ["text"], output: ["text"] }, + }) + expect(yield* models.get(providerID, Model.ID.make("untyped-model"))).toBeDefined() + expect(yield* models.get(providerID, Model.ID.make("embedding-model"))).toBeUndefined() + expect(yield* models.get(providerID, Model.ID.make("configured-model"))).toMatchObject({ + name: "Configured", + capabilities: Model.Capabilities.default(), + }) + expect(requests).toEqual([{ path: "/litellm/v1/models", authorization: "Bearer secret", team: "core" }]) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("reads advertised modalities and tool support", () => + Effect.acquireUseRelease( + Effect.sync(() => + serve([ + { + id: "vision-model", + architecture: { input_modalities: ["text", "image", "file"], output_modalities: ["text"] }, + supported_parameters: ["tools", "temperature"], + }, + { id: "text-model", input_modalities: ["text"], supported_parameters: ["temperature"] }, + ]), + ), + ({ server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("gateway") + yield* config.setEntries([ + configuration({ + gateway: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/v1` } }, + }), + ]) + yield* addPlugins() + + const vision = yield* eventually( + models.get(providerID, Model.ID.make("vision-model")), + (model) => model !== undefined, + ) + expect(vision).toMatchObject({ capabilities: { tools: true, input: ["text", "image", "pdf"], output: ["text"] } }) + expect(yield* models.get(providerID, Model.ID.make("text-model"))).toMatchObject({ + capabilities: { tools: false, input: ["text"], output: ["text"] }, + }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("lets config disable a discovered model that reports no mode", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + yield* config.setEntries([ + configuration({ + litellm: { + package: "@ai-sdk/openai-compatible", + settings: { baseURL: `${server.url.origin}/v1` }, + models: { "untyped-model": { disabled: true } }, + }, + }), + ]) + yield* addPlugins() + + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model !== undefined) + expect(yield* models.get(providerID, Model.ID.make("untyped-model"))).toMatchObject({ enabled: false }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("discovers keyless providers and prefers a stored key over the configured one", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const credentials = yield* Credential.Service + const models = yield* Model.Service + yield* config.setEntries([ + configuration({ + local: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/local/v1` } }, + gateway: { + package: "@opencode/ai/providers/openai-compatible", + settings: { baseURL: `${server.url.origin}/gateway/v1`, apiKey: "configured" }, + }, + }), + ]) + yield* credentials.create({ + integrationID: Integration.ID.make("gateway"), + value: Credential.Key.make({ type: "key", key: "stored" }), + }) + yield* addPlugins() + + yield* eventually( + models.get(Provider.ID.make("gateway"), Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(yield* models.get(Provider.ID.make("local"), Model.ID.make("discovered-model"))).toBeDefined() + expect(requests).toContainEqual({ path: "/local/v1/models", authorization: null, team: null }) + expect(requests).toContainEqual({ path: "/gateway/v1/models", authorization: "Bearer stored", team: null }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("uses the key from the provider's configured environment variable", () => + withEnv({ DISCOVERY_ACME_KEY: "from-env" }, () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + yield* config.setEntries([ + configuration({ + acme: { + env: ["DISCOVERY_ACME_KEY"], + package: "@opencode/ai/providers/openai-compatible", + settings: { baseURL: `${server.url.origin}/v1` }, + }, + }), + ]) + yield* addPlugins() + + yield* eventually( + models.get(Provider.ID.make("acme"), Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(requests).toContainEqual({ path: "/v1/models", authorization: "Bearer from-env", team: null }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ), + ) + + it.live("discovers models for providers migrated from a V1 config", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const config = yield* Config.Test + const models = yield* Model.Service + const normalized = ConfigNormalize.normalize({ + provider: { + litellm: { + npm: "@ai-sdk/openai-compatible", + options: { baseURL: `${server.url.origin}/v1`, apiKey: "secret" }, + }, + }, + experimental: { openai_compatible_discovery: true }, + }) + if (normalized.type !== "normalized") return yield* Effect.fail(new Error("V1 config was rejected")) + const info = decode(normalized.encoded) + expect(info.providers?.litellm?.package).toBe("aisdk:@ai-sdk/openai-compatible") + yield* config.setEntries([new Document({ type: "document", info })]) + yield* addPlugins() + + yield* eventually( + models.get(Provider.ID.make("litellm"), Model.ID.make("discovered-model")), + (model) => model !== undefined, + ) + expect(requests).toContainEqual({ path: "/v1/models", authorization: "Bearer secret", team: null }) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("stops discovery and drops its models when the flag is turned off", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ requests, server }) => + Effect.gen(function* () { + const bus = yield* Bus.Service + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + const entries = (enabled: boolean) => [ + configuration( + { litellm: { package: "@ai-sdk/openai-compatible", settings: { baseURL: `${server.url.origin}/v1` } } }, + enabled, + ), + ] + yield* config.setEntries(entries(true)) + yield* addPlugins() + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model !== undefined) + + const before = requests.length + yield* config.setEntries(entries(false)) + yield* bus.publish(Event.Updated, {}) + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model === undefined) + expect(requests.length).toBe(before) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) + + it.live("keeps the last inventory through outages and drops it when the endpoint changes", () => + Effect.acquireUseRelease( + Effect.sync(serve), + ({ state, requests, server }) => + Effect.gen(function* () { + const bus = yield* Bus.Service + const config = yield* Config.Test + const models = yield* Model.Service + const providerID = Provider.ID.make("litellm") + const entries = (path: string) => [ + configuration({ + litellm: { + package: "@ai-sdk/openai-compatible", + settings: { baseURL: `${server.url.origin}${path}` }, + }, + }), + ] + yield* config.setEntries(entries("/first/v1")) + yield* addPlugins() + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model !== undefined) + + // Config events refresh one at a time, so the second failed request proves the first refresh finished. + state.failing = true + const before = requests.length + yield* bus.publish(Event.Updated, {}) + yield* bus.publish(Event.Updated, {}) + yield* eventually( + Effect.sync(() => requests.length), + (count) => count >= before + 2, + ) + expect(yield* models.get(providerID, Model.ID.make("discovered-model"))).toBeDefined() + + yield* config.setEntries(entries("/second/v1")) + yield* bus.publish(Event.Updated, {}) + yield* eventually(models.get(providerID, Model.ID.make("discovered-model")), (model) => model === undefined) + }), + ({ server }) => Effect.promise(() => server.stop(true)), + ), + ) +}) diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index 1e241a9bfa20..a7d51d523125 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -17349,6 +17349,9 @@ "full_codemode": { "type": "boolean" }, + "openai_compatible_discovery": { + "type": "boolean" + }, "schedules": { "type": "boolean" }, diff --git a/packages/schema/src/config/flag.ts b/packages/schema/src/config/flag.ts index 4a2064879c2d..b086019e597e 100644 --- a/packages/schema/src/config/flag.ts +++ b/packages/schema/src/config/flag.ts @@ -20,6 +20,8 @@ export const registry = { "Enable experimental MCP Events, a draft MCP extension: declare support to MCP servers and read the events of servers that offer them.", full_codemode: "Enable the full Code Mode work in progress. Off by default in every build, including local and dev; opt in with OPENCODE_FLAGS=full_codemode or experimental.full_codemode: true.", + openai_compatible_discovery: + "Add the models that OpenAI-compatible providers in config list at `GET {baseURL}/models`, so they do not have to be listed by hand.", } as const satisfies Record export type Key = keyof typeof registry diff --git a/services/site/src/docs/content/config.mdx b/services/site/src/docs/content/config.mdx index 3a6cf47e5475..b6de3191c620 100644 --- a/services/site/src/docs/content/config.mdx +++ b/services/site/src/docs/content/config.mdx @@ -644,6 +644,20 @@ Set `todo` to `true` to give agents a `todowrite` tool for tracking multi-step w `subagent_depth` sets how deeply subagents can start their own subagents. Defaults to `1`, so a subagent cannot start another subagent. +### OpenAI-compatible model discovery + +Set `openai_compatible_discovery` to `true` to add the models that OpenAI-compatible providers list at +`GET {baseURL}/models`, so they don't have to be listed under `models`. Defaults to `false`. See +[Discovered models](/providers#discovered-models) for how it works. + +```jsonc +{ + "experimental": { + "openai_compatible_discovery": true, + }, +} +``` + ### Image generation `image_generate` sets the default model for the [`experimental_image_generate`](/tools#image-generate) tool, as diff --git a/services/site/src/docs/content/providers.mdx b/services/site/src/docs/content/providers.mdx index 0d93bcb15b15..e0d96ebf06a7 100644 --- a/services/site/src/docs/content/providers.mdx +++ b/services/site/src/docs/content/providers.mdx @@ -96,6 +96,57 @@ The `providers` object is keyed by the provider ID used in model references, suc | `body` | JSON fields merged into request bodies. | | `models` | Models to add or override, keyed by the OpenCode model ID. | +### Discovered models + +With the [experimental](/config#experimental) `openai_compatible_discovery` flag, OpenCode reads `GET {baseURL}/models` +from OpenAI-compatible providers, so `models` can be omitted. This covers gateways such as LiteLLM: + +```jsonc title="opencode.jsonc" +{ + "experimental": { + "openai_compatible_discovery": true, + }, + "providers": { + "litellm": { + "name": "LiteLLM", + "package": "@opencode/ai/providers/openai-compatible", + "settings": { + "baseURL": "http://127.0.0.1:4000/v1", + }, + }, + }, +} +``` + +- Discovery authenticates with the saved key, an `env` variable, or `settings.apiKey`, and sends the provider `headers`. +- Discovery only adds missing models. Models listed under `models` keep their configuration. +- Models that report a non-chat `mode`, such as embedding models, are skipped. Entries without a `mode` are treated as + chat models; hide one by listing it under `models` with `"disabled": true`. +- The list refreshes every five minutes and after config or credential changes, and survives temporary outages. +- Ollama, LM Studio, and vLLM keep their own [discovery](/models#local). +- Turning the flag off removes the discovered models. + +#### Capabilities + +Discovered models accept text and can call tools. An endpoint can report more per model, at the top level or under +`architecture` as OpenRouter does: + +```json title="GET {baseURL}/models" +{ + "data": [ + { + "id": "qwen3-vl", + "input_modalities": ["text", "image"], + "supported_parameters": ["tools", "temperature"] + } + ] +} +``` + +- `input_modalities` and `output_modalities` replace the text-only default. `file` means PDF input. +- `supported_parameters` without `tools` turns tool calls off. +- Override any of these under `models`. + ## Endpoint Override `settings.baseURL` to send a catalog provider through a proxy or compatible endpoint. Its existing package,