Guides

OpenCode

Connect OpenCode to a tool-capable MiniRouter model, with one API key and per-key spend limits.

OpenCode is an open-source coding agent for the terminal. Register MiniRouter as an OpenAI-compatible provider, then choose a model that supports streaming and tools from the catalog. Use Model Finder to compare task benchmarks and estimated workload cost. Model and provider capabilities can differ.

1. Install the documented version

Terminal with Node.js and npm installed
npm install -g opencode-ai@1.18.21
opencode --version

The version command should print 1.18.21. Streamed replies, tool execution and cancellation were checked on macOS against a local MiniRouter gateway with synthetic provider responses. This does not qualify every model, platform or OpenCode release.

2. Export your key

Create a key, then export it in the shell that launches OpenCode.

~/.zshrc or ~/.bashrc
export MINIROUTER_KEY=mr-live-YOUR-KEY-HERE

3. Add the provider

Add MiniRouter to your global config. {env:MINIROUTER_KEY} keeps the key out of the file.

~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "minirouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "minirouter",
      "options": {
        "baseURL": "https://api.minirouter.sh/v1",
        "apiKey": "{env:MINIROUTER_KEY}"
      },
      "models": {
        "zai/glm-5.3-flash": { "name": "GLM 5.3 Flash" },
        "openai/gpt-5.6-sol": { "name": "GPT 5.6 Sol" },
        "spacexai/grok-4.6": { "name": "Grok 4.6" },
        "google/gemini-3.8-flash": { "name": "Gemini 3.8 Flash" }
      }
    }
  }
}

Keep /v1 at the end of baseURL. Add the exact model IDs you want to use; the provider block does not import the whole catalog automatically.

4. Pick a model

Terminal
opencode

Run /models, choose a MiniRouter model and send a prompt. Then open Request logs. The request lists its model, tokens and exact cost.

Check the first reply

Confirm that OpenCode answers your prompt or completes the requested tool action. A generated session title alone does not mean the main request succeeded.

  • If a model is missing, add its exact catalog ID to provider.minirouter.models, then restart OpenCode. Prefix it with minirouter/ when selecting it.
  • If the gateway rejects streaming or tool use, choose a model and provider route that supports both. Adding a model to the config does not add those capabilities.
  • For endpoint, key or credit errors, use the troubleshooting section below and inspect Request logs.

Choose models

/models lists only the models in your provider block. Add routers and presets there too.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "minirouter/zai/glm-5.3-flash",
  "small_model": "minirouter/minirouter/auto:cheap",
  "provider": {
    "minirouter": {
      "models": {
        "minirouter/auto:code": { "name": "Auto code" },
        "minirouter/auto:cheap": { "name": "Auto cheap" },
        "@preset/your-slug": { "name": "My preset" }
      }
    }
  }
}
KeySets
modelThe default model.
small_modelTitles and other light tasks.
provider.minirouter.modelsWhat /models lists.
  • minirouter/auto:code picks a model with reliable tool calling. See Auto router.
  • minirouter/auto:cheap picks the cheapest model that still answers well.
  • @preset/your-slug runs your saved preset. Edit it in Presets.

Run opencode models minirouter to print the list OpenCode loaded.

Global and project config

  • ~/.config/opencode/opencode.jsonThe MiniRouter provider block.
  • opencode.jsonmodel for this repository. Safe to commit.

OpenCode merges both files. Project keys win where they overlap.

Run headless

opencode run runs one prompt without the TUI. Use it in scripts and CI, or see Automatic code review for a pull request workflow.

Terminal
opencode run -m minirouter/zai/glm-5.3-flash \
  --format json "Run the tests and fix failures"
FlagDoes
-mModel, as provider/model.
--format jsonPrints raw JSON events.
--autoAutomatically approves permissions that are not explicitly denied. Use only when you intend to grant that access.

Keep spend in check

Restrict models or filter content with Guardrails.

Troubleshooting

404, HTML, or a parse error on every request

Almost always the base URL. Use https://api.minirouter.sh/v1 — the bare host without /v1 also works, but never append /chat/completions to the base URL field; the client adds that path itself.

Error: 400 invalid_request.

401 on every request

Wrong or rotated key. Keys start with mr-live-; after a rotation the old key keeps working for 24 hours, then dies.

Error: 401 invalid_api_key.

402 before any tokens arrive

Balance below the estimated cost of the request. Top up (from $0.50 with direct Solana payments) — and watch the x-minirouter-balance-usd header, the low-balance signal every response carries.

Error: 402 insufficient_credits.

Provider missing from /models

OpenCode merges project and global config; a JSON syntax error makes the whole provider block vanish silently. Validate the file, then restart OpenCode.

Every error code, with its fix: Errors.

Next steps