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
npm install -g opencode-ai@1.18.21
opencode --versionThe 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.
export MINIROUTER_KEY=mr-live-YOUR-KEY-HERE$env: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.
{
"$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
opencodeRun /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 withminirouter/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.
{
"$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" }
}
}
}
}| Key | Sets |
|---|---|
| model | The default model. |
| small_ | Titles and other light tasks. |
| provider.minirouter.models | What /models lists. |
minirouter/auto:codepicks a model with reliable tool calling. See Auto router.minirouter/auto:cheappicks the cheapest model that still answers well.@preset/your-slugruns 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.json
modelfor 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.
opencode run -m minirouter/zai/glm-5.3-flash \
--format json "Run the tests and fix failures"| Flag | Does |
|---|---|
| -m | Model, as provider/model. |
| --format json | Prints raw JSON events. |
| --auto | Automatically 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.
Recommended modelsBrowse every model in the catalog.
| Model | Why |
|---|---|
zai/glm-5.3-flash | Best current balance of coding ability, agentic performance, context and cost. |
openai/gpt-5.6-sol | Higher-intelligence option when task quality matters more than spend. |
spacexai/grok-4.6 | Strong agentic alternative with a 500K-token window. |
google/gemini-3.8-flash | Multimodal coding alternative with a 1M-token window. |
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.