OpenCode providers and custom models

OpenCode routes inference through providers — Anthropic, OpenAI, OpenCode Zen, OpenRouter, or your own OpenAI-compatible endpoint. There is no IDE subscription pool; you pay upstream rates (plus any gateway fee).

This page covers opencode custom provider, thinking options, and limit.context overrides.

Hub: Tokenminning in OpenCode.

Provider options

Provider style	Typical use	Metering
Direct (Anthropic, OpenAI)	Single-vendor keys	Provider dashboard
OpenCode Zen	Managed routing	Zen billing
OpenRouter	One key, many models	OpenRouter + upstream
Custom OpenAI-compatible	Local vLLM, corporate gateway	Your GPU or gateway bill

Auth: Providers docs — env vars, opencode.json keys, or CLI login.

Custom provider example


{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Local vLLM",
      "options": {
        "baseURL": "http://localhost:8000/v1",
        "apiKey": "local"
      },
      "models": {
        "llama-3.1-8b": {
          "name": "meta-llama/Llama-3.1-8B-Instruct",
          "limit": {
            "context": 8192,
            "output": 2048
          }
        }
      }
    }
  },
  "model": "local/llama-3.1-8b"
}

Set limit.context below the catalog maximum when you want earlier compaction and lower cost — user overrides win over model snapshots.

Model options (reasoning, caching)

Per-model options pass provider-specific parameters:


{
  "provider": {
    "anthropic": {
      "models": {
        "claude-sonnet-4-5": {
          "options": {
            "reasoningEffort": "low"
          }
        }
      }
    }
  }
}

Thinking budgets and effort levels: Reasoning effort.

Prefix / prompt caching is provider-side — configure on the model or gateway, not inside OpenCode’s IDE layer. OpenRouter caching: OpenRouter guide.

Assign models to agents

Global default + per-agent overrides:


{
  "model": "anthropic/claude-sonnet-4-5",
  "agent": {
    "plan": { "model": "openrouter/anthropic/claude-haiku-4-20250514" },
    "build": { "model": "anthropic/claude-sonnet-4-5" }
  }
}

Use provider/model IDs from opencode models or docs.

BYOK guardrails

Set spending caps in each provider console — OpenCode does not enforce budgets
Rotate API keys on the same schedule as CI secrets
Separate dev keys from production keys in opencode.json vs global config

Global config (~/.config/opencode/opencode.json) vs project opencode.json — project wins for team standards. See Config precedence .

Reconcile billing

opencode stats tracks local sessions; provider dashboards are billing truth. Reconcile weekly, especially with multiple providers or subagents.