# OpenCode Setup: Custom OpenAI Provider

> 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.

## 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:

```bash
export ZROUTER_API_KEY="YOUR_ZROUTER_KEY"
```

```json
{
  "$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](https://opencode.ai/docs/providers/).

## 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](/docs/integrations/troubleshooting) for common errors.