opencode-provider-litellm

OpenCode plugin for any LiteLLM proxy — auto-discovers models, MCP tools, and auth. Zero config, zero hand-maintained model lists.

Quick start

# 1. Set your LiteLLM proxy URL and API key
export LITELLM_URL="https://your-litellm-proxy.example.com"
export LITELLM_KEY="sk-..."

# 2. Install the plugin
opencode plugin opencode-provider-litellm

# 3. Restart OpenCode

All models and MCP tools from your LiteLLM proxy appear in OpenCode automatically.

Configuration

Environment variables

Environment variables take precedence over all other configuration. Use them to keep secrets out of checked-in files.

| Variable | Required | Description | |----------|----------|-------------| | LITELLM_URL | Yes | Your LiteLLM proxy base URL | | LITELLM_KEY | Yes* | API key for the proxy | | LITELLM_PROVIDER_ID | No | Provider name in OpenCode (default: LiteLLM) | | LITELLM_GCLOUD_TOKEN_AUTH | No | Set to 1 to use Google ADC for auth — makes LITELLM_KEY optional | | GOOGLE_APPLICATION_CREDENTIALS | No | Path to a Google ADC JSON file (used when LITELLM_GCLOUD_TOKEN_AUTH=1) |

*LITELLM_KEY is optional when LITELLM_GCLOUD_TOKEN_AUTH=1.

Plugin options

All env vars have an equivalent in the plugin options block in opencode.json. Env vars take precedence — use options for defaults that can be overridden per environment.

{
  "plugin": [
    ["opencode-provider-litellm", {
      "url": "https://your-litellm-proxy.example.com",  // LITELLM_URL
      "apiKey": "sk-...",                                // LITELLM_KEY
      "providerName": "MyLiteLLM",                       // LITELLM_PROVIDER_ID
      "gcloudTokenAuth": true                            // LITELLM_GCLOUD_TOKEN_AUTH=1
      // apiKey can be omitted when gcloudTokenAuth is true
    }]
  ]
}

Google Vertex AI (gcloud token auth)

When your LiteLLM proxy is backed by Google Vertex AI, you can skip LITELLM_KEY and let the plugin automatically fetch a Google OAuth token:

# 1. Authenticate with gcloud (creates an ADC JSON file)
gcloud auth application-default login

# 2. Set env vars (LITELLM_KEY is optional)
export LITELLM_URL="https://your-litellm-proxy.example.com"
export LITELLM_GCLOUD_TOKEN_AUTH=1

# 3. Install and restart OpenCode
opencode plugin opencode-provider-litellm

The plugin reads your Application Default Credentials JSON file and exchanges the refresh token for an access token. Tokens are cached for 50 minutes and used for both model discovery at startup and every LLM request.

ADC file locations searched (in order):

1. GOOGLE_APPLICATION_CREDENTIALS env var (all platforms)
2. ~/.config/gcloud/application_default_credentials.json (Linux/macOS)
3. %APPDATA%/gcloud/application_default_credentials.json (Windows)

Note: Only authorized_user credentials (from gcloud auth application-default login) are supported. Service account keys are not yet supported.

/connect flow

You can also authenticate interactively via the OpenCode TUI:

1. Run /connect
2. Select LiteLLM
3. Paste your API key

The key is stored in OpenCode's auth store.

Features

Model discovery

Queries LiteLLM on startup and injects all models with rich metadata into OpenCode:

• /health — model list with internal UUIDs
• /model/info?litellm_model_id={uuid} — costs, context limits, vision, tool calling, reasoning, etc.

Custom model_info updates via /model/update are respected — no hardcoded fallbacks.

MCP tools

Discovers tools registered on LiteLLM's MCP servers at startup and exposes them as native OpenCode tools. Each tool keeps its original description and parameter schema.

Skills

Skills registered in LiteLLM's Skills Gateway are made available to OpenCode via the proxy-sidecar, which serves skills in OpenCode's native format. Add the sidecar URL to your config:

{
  "skills": {
    "urls": ["https://your-litellm-proxy.example.com/opencode/skills"]
  }
}

Skills appear in OpenCode's /skills menu and are loaded natively by the agent.

How it works

The plugin uses these OpenCode hooks:

| Hook | Purpose | |------|---------| | config | Discovers models from LiteLLM and injects them into OpenCode | | auth | Provides a /connect entry point for pasting an API key | | tool | Exposes discovered MCP tools as native OpenCode tools | | chat.headers | Injects Authorization: Bearer <token> when gcloud token auth is enabled |

Troubleshooting

| Problem | Solution | |---------|----------| | "Plugin config error" | Set LITELLM_URL and LITELLM_KEY (or LITELLM_GCLOUD_TOKEN_AUTH=1) | | "Access denied" (403) | Verify the API key has access to the LiteLLM proxy | | "No models discovered" | Check the proxy is reachable and /health responds | | No models with gcloud auth | Verify gcloud auth application-default login has been run and the ADC file exists | | Skills not showing | Verify the proxy-sidecar is running and the skills URL is in opencode.json |

Development

npm install
npm run typecheck
npm run test
npm run build