OpenCode

Compatibility first

Standalone gateway only for agent workflows. OpenCode uses tools to inspect and change projects. Prepaid ZRouter accounts reject tool requests, including requests authenticated with customer BYOK.

Prepare a standalone deployment, an enabled tool-capable model, and a dedicated managed gateway key.

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_MANAGED_GATEWAY_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://STANDALONE_GATEWAY_HOST/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 is unavailable for full agent workflows on the current prepaid deployment. Use the shared troubleshooting guide for common errors.