Connect OpenCode to 9Router

Add 9Router as an OpenAI-compatible provider in OpenCode, then select a model advertised by your router. OpenCode the coding client and an OpenCode-branded upstream provider are separate roles. You can route the client through 9Router without choosing that upstream service.

That distinction matters when diagnosing a 429. A client can be configured correctly while the selected provider rejects the request because of its own usage policy or quota.

Establish a working endpoint

Follow the installation guide first. Check that the dashboard and local API answer, then connect one provider. Copy an exact model ID from your own instance instead of taking a changing free-model name from a blog post.

Check where OpenCode runs. If the client is on your host and the router is inside Docker, the published host port can be appropriate. If the client is in a different container, its own localhost points at that container, not at the router.

The reviewed 9Router writer updates ~/.config/opencode/opencode.json. Make a backup of the OpenCode configuration you actually use. Preserve other providers and agent settings. A project configuration can affect the effective setup, so inspect both project and user settings when the client seems to ignore a change.

Add the provider

The 9Router dashboard includes an OpenCode setup path in its CLI tools area. The reviewed writer uses @ai-sdk/openai-compatible, places the endpoint in options.baseURL, and adds selected model IDs under the provider’s models map.

The following example shows the relevant structure. Merge it into your configuration rather than replacing unrelated settings:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "9router": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "9Router",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "{env:NINE_ROUTER_KEY}"
      },
      "models": {
        "YOUR_EXACT_MODEL_ID": {
          "name": "My routed model"
        }
      }
    }
  },
  "model": "9router/YOUR_EXACT_MODEL_ID"
}

Set NINE_ROUTER_KEY in the environment that starts OpenCode, using your router key. Replace YOUR_EXACT_MODEL_ID in both places with the same exact ID. The friendly name is a display label; it does not change the API model ID.

The 9router/ prefix in the top-level model value selects the configured OpenCode provider. The remaining part names the model sent to the router. If that model ID already contains a provider prefix, retain it. Do not remove a segment just because the resulting string contains more than one slash.

OpenCode supports environment substitution in configuration. If you instead apply a dashboard-generated file containing a literal key, treat that file as sensitive and keep it out of public repositories.

Inspect what Apply changes

The upstream settings writer merges provider options and selected models, updates the active model, and can add an explorer subagent model. Review the generated configuration if you already use custom agents.

Applying settings on the router’s machine does not automatically edit files on a different client machine. In a container or remote deployment, copy the appropriate configuration to the client yourself and supply credentials locally.

Do not advertise image or tool capability solely because a generated configuration lists it. The provider and selected model must support the request. Start with text, then test the features your actual workflow needs.

Select the model and verify

Restart OpenCode after changing the configuration. Use its model picker to select the routed model, or confirm that the configured default is active.

Send a short prompt in a scratch project. Inspect the router’s request history for the same request, the selected model, and the response status. A visible model in the picker is not a completed routing test.

If a short response works, test one harmless tool interaction in that scratch project. For example, let the client read a small file whose contents you know. Keep approvals enabled and compare the returned information with the file. Test images or large contexts separately if you need them.

Why does OpenCode report a free-usage limit?

Upstream issue #5107, opened on 22 October 2026, reports a FreeUsageLimitError while using an OpenCode route. The report establishes that users encounter this response; commenters’ explanations do not establish a universal cause or a reliable fix.

Read the error body and identify which service returned it. Check the provider account, documented limits, selected model, and retry guidance. A router cannot create additional entitlement at a provider. Do not treat changing identities or rotating proxies as a dependable configuration fix.

You can select another provider that you are authorized to use, wait for a documented reset, or choose an appropriate paid option directly with the provider. If you add a fallback, test it and make its cost implications explicit.

When the model does not appear

Check the provider key, the models map, and the default model string together. Confirm that the configuration is valid JSON or JSONC for the file you are using. Check whether a project-level setting overrides your user-level choice.

If the model appears but requests fail, move to the troubleshooting guide. If it works, keep that one route as a baseline before building a fallback combo. Restore your backup when you want to return to the previous setup.

For a model-specific context error, the DeepSeek guide explains why a published context window may differ from a serving endpoint’s request limit.