opencode-models-discovery

Discover models from OpenAI-compatible providers and add them to OpenCode automatically.

This plugin queries a provider's model endpoint, applies optional filters, and injects the discovered models into OpenCode. It supports OpenCode v2 as the primary integration and keeps a separate OpenCode v1 adapter for legacy configurations.

• Dynamic model discovery from /v1/models or a configured endpoint
• Provider-level enablement, endpoint overrides, timeouts, and model filters
• Optional human-friendly model names
• Optional metadata enrichment for limits, reasoning, tools, attachments, structured output, and modalities
• OpenCode v2 /connect credentials, host-managed storage, refresh commands, and model console
• OpenCode v1 XDG caching, helper commands, and compatibility with Mimocode
• Works with any provider that returns an OpenAI-compatible model-list response

OpenCode v2 uses plugins and providers. Discovery settings belong under providers.<id>.settings.modelsDiscovery and require enabled: true for that provider.

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "opencode-models-discovery@2.1.1"
  ],
  "providers": {
    "gateway": {
      "name": "My Gateway",
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "{env:GATEWAY_API_KEY}",
        "modelsDiscovery": {
          "enabled": true,
          "smartModelName": true,
          "models": {
            "includeBy": [{ "field": "id", "match": "^(gpt|gemini)" }]
          }
        }
      }
    }
  }
}

The plugin requests /v1/models by default. For a provider that exposes /models, set "endpoint": "/models". The endpoint is resolved from the provider URL's origin.

You can omit apiKey and manage credentials with OpenCode's native /connect command. Resolved credentials are used in memory and are not written to configuration, caches, or logs.

For the complete V2 configuration reference, see Configuration Guide.

• /models-discovery-refresh refreshes discovered models.
• /models-discovery-console browses providers, models, metadata, and caches.
• models_discovery_refresh and models_discovery_status are available as agent tools.
• Pass rawCache: true to models_discovery_status to inspect cached raw models and enrichment results.

V2 caching is disabled by default and uses OpenCode's host-provided storage when enabled. After rebuilding a local plugin, restart the background service with opencode service restart.

For OpenCode v1 (1.18.29+), use plugin, provider, and options:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-models-discovery@2.1.1"],
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1",
        "modelsDiscovery": {
          "enabled": true,
          "smartModelName": true
        }
      }
    }
  }
}

V1 discovery is configured per provider at provider.<id>.options.modelsDiscovery. V1 remains supported for compatibility, security fixes, and severe regressions; new discovery, TUI, RPC, cache, and override features target V2 first.

For V1 migration, helper commands, disk caching, filters, and legacy configuration details, see:

• Configuration Guide
• Migrating from V1 to V2
• Persisted Model Discovery Cache
• Upgrade Guide

Enrichment is opt-in. Without modelInfoFormat, the plugin does not contact external metadata sources and leaves unknown fields unset.

Supported formats include:

aiproxy, bifrost, litellm, lmstudio, llama-swap, models.dev, ollama, omniroute, openrouter, and vllm.

Example using models.dev:

{
  "modelsDiscovery": {
    "enabled": true,
    "modelInfoFormat": "models.dev"
  }
}

models.dev uses https://models.dev/models.json by default and supports a custom modelInfoEndpoint. Provider-specific formats read metadata from the provider's own response or endpoint. See Model Metadata Enrichment for format-specific paths and behavior.

All options are provider-scoped. The exact configuration path depends on the host:

Frequently used options:

See the full configuration reference for defaults, filter semantics, cache behavior, model assembly, and V1/V2 differences.

• Configuration Guide
• Provider Compatibility
• Connect and Auth
• Migrate V1 to V2
• Persisted Model Discovery Cache
• Upgrade Guide
• Community configuration examples

• OpenCode with plugin support
• At least one local or remote OpenAI-compatible provider
• A provider model-list endpoint returning an OpenAI-compatible response

For local plugin development, run npm run compile and reference the generated directory with file:///absolute/path/to/opencode-models-discovery/dist. OpenCode v2 expects a directory rather than a direct JavaScript entry file.

Contributions are welcome. Please feel free to submit a pull request. Community provider examples should be added under docs/config_example/ on the community/config-examples branch.

MIT

This project is not built by the OpenCode team and is not affiliated with OpenCode. It is also not affiliated with, endorsed by, or sponsored by models.dev. The optional models.dev metadata source is used only when explicitly configured.