INTEGRATION GUIDE

OpenCode

Client-specific limits

Define a custom OpenAI-compatible ZRouter provider in OpenCode: the base URL, your account API key, model names, and a quick check that requests go through.

On this page

Compatibility first

Client-executed function tools are supported with account keys. Use inline text tool results and explicit history. Full OpenCode sessions still need client-specific validation; media, hosted tools, and opaque state remain unsupported.

For the supported subset, use an enabled tool-capable model and a dedicated account API key. The example below connects to your ZRouter account at https://zrouter.si/v1.

Add the provider

Set ZROUTER_API_KEY in the environment where OpenCode runs. Merge this into your OpenCode configuration. Replace both occurrences of PROVIDER_INSTANCE/MODEL_ID with the same gateway model ID:

export ZROUTER_API_KEY="YOUR_ZROUTER_KEY"
{
  "$schema": "https://opencode.ai/config.json",
  "model": "zrouter/PROVIDER_INSTANCE/MODEL_ID",
  "provider": {
    "zrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ZRouter",
      "options": {
        "baseURL": "https://zrouter.si/v1",
        "apiKey": "{env:ZROUTER_API_KEY}"
      },
      "models": {
        "PROVIDER_INSTANCE/MODEL_ID": { "name": "ZRouter coding model" }
      }
    }
  }
}

This adapter uses Chat Completions. OpenCode also documents @ai-sdk/openai for Responses models; choose the adapter that matches the model and gateway behavior you have tested. See OpenCode's custom provider documentation.

Verify

Launch opencode, open /models, and select the ZRouter model. First send a short prompt, then try a small task that reads a file. Review logs for model, streaming, and tool errors. A connection test does not validate every agent feature.

Troubleshooting

Check that the provider ID is zrouter, the model map key is the exact gateway model ID, and the environment key reaches the process. Avoid claiming image or tool support in model metadata unless the actual provider supports it. Set context and output limits from the selected model's real limits.

Customer BYOK supports the same client-tool subset when the client sends X-ZRouter-BYOK: true. Use the shared troubleshooting guide for common errors.

Vendor configuration reviewed September 30, 2026. Model and client capabilities vary. Check the linked official sources when upgrading.