How to add a custom provider in opencode

What you need before you start

opencode is configured through a JSON file, so the work happens in your editor rather than in a settings screen.

• A QuickRouter account with an active plan and an API key from the console.
• The base URL https://api.quickrouter.homes/v1 - opencode expects the OpenAI-style path.
• opencode installed and run at least once, so it has created its config directory.
• Write access to opencode.json in the project root or in the global config directory.

Register the provider

Add the provider under the provider key. The npm field tells opencode which SDK to load, and options carries the endpoint and credential.

1. 01

   Open opencode.json

   Create the file in the project root if it does not exist, or edit the global config to make the provider available in every project.

   {
     "provider": {
       "quickrouter": {
         "npm": "@ai-sdk/openai-compatible",
         "name": "QuickRouter",
         "options": {
           "baseURL": "https://api.quickrouter.homes/v1",
           "apiKey": "sk-qr-your-key"
         },
         "models": {
           "gpt-5": { "name": "GPT-5" },
           "claude-sonnet-4-5": { "name": "Claude Sonnet 4.5" },
           "deepseek-v3-2": { "name": "DeepSeek V3.2" }
         }
       }
     }
   }

2. 02

   Reference the provider in an agent

   A model id is written as provider/model, so the gateway entry is selected explicitly rather than by guessing a default.

   {
     "agent": {
       "build": { "model": "quickrouter/gpt-5" }
     }
   }

3. 03

   Confirm the route

   Start opencode and run a short prompt, then check the console usage view for the matching request.

Errors you are most likely to hit

Because opencode validates the config at load time, a mistake in the JSON shows up immediately rather than as a network error later.

Which models should opencode use?

Split roles rather than picking one model for everything: a strong planner for the main agent and a cheaper model for search and summarisation steps.