---
title: "OpenCode integration"
description: "Settings for using OpenCode with MiniRouter."
canonical_url: "https://minirouter.sh/docs/integrations/opencode"
markdown_url: "https://minirouter.sh/docs/integrations/opencode.md"
last_updated: "2026-09-26"
---

# OpenCode

Run the open-source terminal agent on any model in the MiniRouter catalog.

[Get a key](https://minirouter.sh/key)

[OpenCode](https://opencode.ai) is an open-source coding agent for the terminal. Register MiniRouter as an OpenAI-compatible provider to run it on any tool-capable model in the [catalog](https://minirouter.sh/models), a [preset](https://minirouter.sh/docs/presets) or a [router](https://minirouter.sh/docs/auto-router), with one balance and per-key [spend limits](https://minirouter.sh/docs/rate-limits).

> **Note:** OpenCode model IDs are `provider/model`, so every MiniRouter ID gains a `minirouter/` prefix: `minirouter/zai/glm-5.3-flash`.

## Quick start

### 1. Install OpenCode

**macOS / Linux**

```sh
curl -fsSL https://opencode.ai/install | bash
```

**npm**

```sh
npm install -g opencode-ai
```

**Homebrew**

```sh
brew install anomalyco/tap/opencode
```

### 2. Export your key

[Create a key](https://minirouter.sh/key), then export it in the shell that launches OpenCode.

**macOS / Linux**

```sh
export MINIROUTER_KEY=mr-live-YOUR-KEY-HERE
```

**Windows**

```powershell
setx MINIROUTER_KEY mr-live-YOUR-KEY-HERE
```

> **Tip:** Give OpenCode its own key, so its spend shows separately in [Usage](https://minirouter.sh/dashboard/usage) and a limit stops only OpenCode.

### 3. Add the provider

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

```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" }
      }
    }
  }
}
```

### 4. Pick a model

```sh
opencode
```

Run `/models`, choose a MiniRouter model and send a prompt. Then open [Activity](https://minirouter.sh/dashboard/activity). The request lists its model, tokens and exact cost.

## Choose models

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

```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" }
      }
    }
  }
}
```

| Key | Sets |
| --- | --- |
| `model` | The default model. |
| `small_model` | Titles and other light tasks. |
| `provider.minirouter.models` | What `/models` lists. |

- `minirouter/auto:code` picks a model with reliable tool calling. See [Auto router](https://minirouter.sh/docs/auto-router).
- `minirouter/auto:cheap` picks the cheapest model that still answers well.
- `@preset/your-slug` runs your saved [preset](https://minirouter.sh/docs/presets). Edit it in [Presets](https://minirouter.sh/dashboard/presets).

Run `opencode models minirouter` to print the list OpenCode loaded.

## Global and project config

- **~/.config/opencode/opencode.json**: The MiniRouter provider block.
- **opencode.json**: `model` 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](https://minirouter.sh/docs/guides/code-review) for a pull request workflow.

```sh
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` | Approves permissions without asking. |

> **Warning:** The job must export `MINIROUTER_KEY`. The config reads it at startup.

## Keep spend in check

- [Own key](https://minirouter.sh/dashboard/keys): One key per person or pipeline.
- [Spend cap](https://minirouter.sh/docs/rate-limits): Daily or monthly limit on that key.
- [Activity](https://minirouter.sh/dashboard/activity): Every request and its cost.

Restrict models or filter content with [Guardrails](https://minirouter.sh/docs/guardrails).

## Recommended models

| Model | Why |
| --- | --- |
| [`zai/glm-5.3-flash`](https://minirouter.sh/models/zai/glm-5.3-flash) | Best current balance of coding ability, agentic performance, context and cost. |
| [`openai/gpt-5.6-sol`](https://minirouter.sh/models/openai/gpt-5.6-sol) | Higher-intelligence option when task quality matters more than spend. |
| [`spacexai/grok-4.6`](https://minirouter.sh/models/spacexai/grok-4.6) | Strong agentic alternative with a 500K-token window. |
| [`google/gemini-3.8-flash`](https://minirouter.sh/models/google/gemini-3.8-flash) | Multimodal coding alternative with a 1M-token window. |

Browse every model in the [catalog](https://minirouter.sh/models).

## 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`](https://minirouter.sh/docs/errors#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`](https://minirouter.sh/docs/errors#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`](https://minirouter.sh/docs/errors#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](https://minirouter.sh/docs/errors).

## Next steps

- [Presets](https://minirouter.sh/docs/presets): Save a model and its settings under one name.
- [Guardrails](https://minirouter.sh/docs/guardrails): Budgets and model lists per key.
- [Auto router](https://minirouter.sh/docs/auto-router): Let MiniRouter pick the model.