OpenCode providers and custom models

To add an OpenCode custom provider, define a provider block in opencode.json with npm: "@ai-sdk/openai-compatible", a baseURL, and model IDs. Built-in providers (Anthropic, OpenAI, Zen, OpenRouter) use the same provider / models / options shape.

Configure models globally, set per-model options (including reasoning effort), and override per agent.

Built-in vs custom providers

Auth: Providers docs  — env vars, opencode.json keys, or /connect in the TUI for OpenCode Zen.

How to verify OpenCode is using your provider and model

Project opencode.json overrides global ~/.config/opencode/opencode.json for team standards (Config precedence ).

OpenCode Zen via /connect

For managed routing without juggling vendor keys, run /connect in the TUI, select opencode, and sign in at opencode.ai/auth . Zen bills separately from direct BYOK — still metered per token.

small_model for hidden agents

Title, summary, and compaction agents run on a cheaper route when you set small_model:

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

OpenCode uses small_model for lightweight background calls (Config: models ). Pair with Agents routing.

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 and caching

Per-model options pass provider-specific parameters. Reasoning configuration depends on provider shape — see change reasoning effort in OpenCode for OpenAI reasoningEffort vs Anthropic thinking.budgetTokens and stable vs v2 schema paths.

{
  "provider": {
    "anthropic": {
      "models": {
        "claude-sonnet-4-5-20250929": {
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 8000
            }
          }
        }
      }
    },
    "openai": {
      "models": {
        "gpt-5": {
          "options": {
            "reasoningEffort": "low"
          }
        }
      }
    }
  }
}

Prefix / prompt caching is provider-side. Enable on supported providers:

{
  "provider": {
    "anthropic": {
      "options": {
        "setCacheKey": true
      }
    }
  }
}

OpenCode passes setCacheKey to providers that support prefix caching. OpenRouter caching: OpenRouter caching guide.

Assign models to agents

Global default + per-agent overrides — change reasoning for one agent without affecting others:

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

Use provider/model IDs from opencode models or docs. Agent options override global model options for that agent only.

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

Reconcile billing

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

Related

• OpenCode hub
• Change reasoning effort in OpenCode — reasoningEffort, budgetTokens, variants
• Context — limit.context and compaction
• OpenRouter
• Local inference
• OpenCode: Providers 
• OpenCode: Models