Working with OpenCode

Connect OpenCode to Nodul Router with a plugin that leaves only the models of your key.

OpenCode is a coding agent. The nodul.code.plugin plugin for OpenCode 2.2+ makes Nodul Router the only LLM provider:

the model list comes from GET /api/v1/models called with your key (see Models of your key): if the key is limited to some models, OpenCode shows only those;
the list has only models with the Tools capability: the OpenCode agent needs them on every step;
other LLM providers are hidden; web search integrations (Exa, Firecrawl, Parallel, Tavily, TinyFish) stay;
the default model is ru-2/deepseek-v4.1-flash; if your key cannot use it, the first available model is picked;
the list refreshes on start, when the key changes and every 10 minutes.

Install

Create an API key in a Router space (see Quickstart).
Install OpenCode Desktop.
Install the plugin. On macOS:
```
/Applications/OpenCode.app/Contents/Resources/opencode-cli plugin add 'git+https://github.com/nodul-app/nodul.code.plugin.git'
```
If the opencode CLI is on your PATH, this is shorter: opencode plugin add 'git+https://github.com/nodul-app/nodul.code.plugin.git'.

Restart the background service and OpenCode:

/Applications/OpenCode.app/Contents/Resources/opencode-cli service restart

Open Settings → Providers → Nodul Router and paste your Router key (sk-nr-…).

Instead of entering the key in the UI, you can set the NODUL_ROUTER_API_KEY environment variable.

Update

OpenCode checks for a new plugin version once a day. To install it:

/Applications/OpenCode.app/Contents/Resources/opencode-cli plugin update

Settings

If you need to, set plugin options in ~/.config/opencode/opencode.json:

{
  "plugins": [
    {
      "package": "git+https://github.com/nodul-app/nodul.code.plugin.git",
      "options": { "defaultModel": "deepseek/deepseek-v4.1-flash" }
    }
  ]
}

Option	Default	What it does
`defaultModel`	`ru-2/deepseek-v4.1-flash`	Default model id
`baseURL`	`https://router.nodul.ru/api/v1`	Router API address

Good to know

Prices. The router charges in PnP (1 PnP = 100 ₽, see Pricing and billing), and OpenCode shows these numbers with a $ sign. See the exact spend in the cabinet logs.
Budget. The agent sends long prompts: set a budget on the key.
The first seconds after the service starts. Other providers may flash by while the plugin loads.
Your own provider or model in opencode.json. These settings apply after the plugin and override it. To see only Nodul Router, do not describe your own nodul provider or any other provider in the config.

If you set up Nodul by hand before

Remove the provider.nodul block from ~/.config/opencode/opencode.json, and also model, small_model and enabled_providers if you added them. Then unset the background service variables if you set them:

/Applications/OpenCode.app/Contents/Resources/opencode-cli service unset env OPENCODE_MODELS_PATH
/Applications/OpenCode.app/Contents/Resources/opencode-cli service unset env OPENCODE_DISABLE_FREE_MODELS

Troubleshooting

Symptom	What to do
Nodul Router asks you to sign in again	The router answered `401`: the key is wrong, disabled or expired. Enter a new key.
No models	Check that the key is entered and that the cabinet allows it at least one model with the Tools capability.
Other providers are visible	Check `opencode.json`: it must not have its own `provider`. Restart the service (`service restart`).
`402` on a request	The payer is low on funds or the key budget is spent.

Other agents (Cursor, Cline, Roo Code, Kilo Code, Continue) connect as an OpenAI-compatible provider: see IDE agents.