For custom OpenAI-compatible providers, you define the provider in opencode.json so OpenCode and this plugin know the provider identity, package, and baseURL.
However, you do not need to hardcode apiKey in opencode.json when the provider credential is managed through OpenCode's native /connect command.
The plugin provides auth-backed model discovery and runtime execution across both OpenCode v2 and OpenCode v1, utilizing the native credential architecture appropriate for each host generation.
OpenCode v2 features a first-class Integration subsystem (ctx.integration) and an event-driven lifecycle. The V2 adapter seamlessly links provider model discovery and runtime LLM execution with OpenCode v2's /connect workflows.
{
"$schema": "https://opencode.ai/config.json",
"plugins": [
"[email protected]"
],
"providers": {
"deepseek-custom": {
"name": "DeepSeek Custom",
"package": "@opencode/ai/providers/openai-compatible",
"settings": {
"baseURL": "https://api.deepseek.com",
"modelsDiscovery": {
"enabled": true,
"endpoint": "/models"
}
}
}
}
}Notice that settings.apiKey is completely omitted.
- Run
/connectin the OpenCode v2 TUI. - Select your provider (
DeepSeek Custom/deepseek-custom). - Enter your API key.
- Model discovery triggers immediately, populating available models in your session without requiring a restart.
- Selecting a discovered model and sending a prompt authenticates successfully.
-
Native Integration Registration & Deduplication:
- The plugin registers an API-key authentication method for every configured provider via
ctx.integration.transform. - The integration ID strictly aligns with the provider ID (
provider.id), preventing duplicate entries from appearing in the/connectmenu. - An optional
settings.integrationIDcan override the integration target if you want to share credentials across multiple provider definitions.
- The plugin registers an API-key authentication method for every configured provider via
-
Real-time Event Reactivity:
- The plugin subscribes to host lifecycle events:
credential.updated,credential.switched,integration.updated, andconfig.updated. - When you connect, update, or disconnect credentials in
/connect, the plugin immediately triggers an inventory refresh and re-evaluates provider authorization without requiring a process restart.
- The plugin subscribes to host lifecycle events:
-
Dual-Layer Provider Authentication Binding:
- When OpenCode v2's host runner executes a chat completion for a discovered model, it requires upstream credentials.
- The plugin's provider controller (
src/v2/catalog.ts) bindsdraft.integrationIDon the editor and injects memory-onlyAuthorization: Bearer <key>headers intodraft.headers. - This ensures downstream provider packages (such as
@opencode/ai/providers/openai-compatible) always transmit the required authorization headers.
-
Credential Revocation & Cleanup:
- When credentials are deleted or disconnected in
/connect, the event stream fires and the resolver observes the missing credential. - The controller explicitly cleans up and deletes
draft.headers.authorizationin runtime memory, preventing revoked credentials from remaining active.
- When credentials are deleted or disconnected in
-
Credential Resolution Precedence (V2):
- Explicit
providers.<id>.settings.apiKey(highest priority). - Active Integration credential resolved via
ctx.integration.connection.activeandresolvematchingsettings.integrationID(if set) orprovider.id. - Unauthenticated (for local engines such as LM Studio, Ollama, or vLLM).
- Explicit
OpenCode v1 does not have the V2 plugin integration API. Instead, the V1 adapter integrates with OpenCode's host-managed auth store and XDG files.
{
"$schema": "https://opencode.ai/config.json",
"plugin": [
"[email protected]"
],
"provider": {
"test_provider": {
"npm": "@ai-sdk/openai-compatible",
"name": "Test Provider",
"options": {
"baseURL": "http://127.0.0.1:4000/v1",
"modelsDiscovery": {
"enabled": true
}
}
}
}
}Then run /connect, select the provider ID, and save the API key there.
provider.<name>.options.apiKey(explicit setting).- OpenCode resolved provider key, when available during plugin startup.
- Host auth store (
auth.json) for same-idtype: "api"credentials.
- OpenCode's provider resolution API can time out inside the V1
confighook, so the plugin includes a fallback for/connectAPI-key credentials. - The fallback first respects
OPENCODE_AUTH_CONTENT, then reads a host-specific auth store location derived fromxdg-basedir. - When
OPENCODE=1is present, the plugin reads~/.local/share/opencode/auth.json. - When
MIMOCODE=1is present, the plugin reads~/.local/share/mimocode/auth.json. - When neither host marker is present, the plugin defaults to
~/.local/share/opencode/auth.json.
Regardless of host generation (V1 or V2):
- No Config Tampering: The plugin never writes recovered API keys or secrets back into
opencode.json. - No Cache Leakage: Resolved secrets are never saved to V1 XDG cache files or V2
ctx.storagecache records. Cache stores strictly retain metadata, raw model IDs, and enrichments. - No Diagnostic Leakage: Raw credentials and Authorization headers are masked and redacted from agent tools (
models_discovery_status), RPC outputs, and logging.