---
title: "Connect OpenCode to XiuRouter"
description: "Save credentials through connect and add an explicit custom provider and model without overwriting other providers."
image: "https://docs.xiu.ai/og.png"
---

> XiuAI documentation index
> Full documentation index: https://docs.xiu.ai/en/llms.txt
> Check the index for current pages before reading.

# Connect OpenCode to XiuRouter

Save credentials through `/connect`, then add `xiurouter` in `opencode.json`. Existing users do not need to reinstall OpenCode. Retain other providers for rollback.

## Choose a setup method

- First setup: save the key, then add the provider and model.
- Existing setup: update the matching credential and merge only `provider.xiurouter`.
- Chat-assisted setup: OpenCode can merge credential-free JSON; you still save the key, reload, and create a new task.

## Before you start

OpenCode must start normally. Create a dedicated XiuRouter key and copy an exact model ID from the current catalog.

## Save the key

1. Run `/connect` in OpenCode.
2. Choose `Other`.
3. Enter provider ID `xiurouter`.
4. Paste the XiuRouter key.

Update the existing entry if it already exists. Do not place the key in `opencode.json`.

## Add the provider

Merge this into the project or active OpenCode `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"xiurouter": {
  "npm": "@ai-sdk/openai-compatible",
  "name": "XiuRouter",
  "options": {
    "baseURL": "https://router-api.xiu.ai/v1"
  },
  "models": {
    "YOUR_MODEL_ID": {
      "name": "YOUR_MODEL_ID"
    }
  }
}
  }
}
```

`@ai-sdk/openai-compatible` selects Chat Completions. A custom provider has no Models.dev catalog, so list the model ID explicitly under `models`. Preserve other providers.

An agent with configuration access can merge this JSON. Save the key through `/connect`, reload OpenCode, and start a new task afterward.

## Ask an agent to help

After saving the key yourself, send:

> Preserve all providers in `opencode.json`. Add only `provider.xiurouter` with `@ai-sdk/openai-compatible`, Base URL `https://router-api.xiu.ai/v1`, and model `YOUR_MODEL_ID`. Do not read or write the API key. Show the diff.

## Verify

1. Run `/models`.
2. Select `xiurouter/YOUR_MODEL_ID`.
3. Start a small read-only task.
4. Confirm the key, model, `/v1/chat/completions`, and successful result in XiuRouter's request inspection view.

Then test file reads, tools, and editing. Do not assign identical capability settings to every model.

## Troubleshoot

| Symptom | Next step |
| --- | --- |
| XiuRouter absent from `/models` | Use the same `xiurouter` ID in `/connect` and `opencode.json` |
| `401` | Update the key with `/connect`, not in project configuration |
| Incompatible request format | Use `@ai-sdk/openai-compatible`, not the dedicated OpenAI provider |
| Model unavailable | Copy the exact catalog ID and check key restrictions |

## Roll back

Use `/models` to restore the old model. Confirm a new task uses it before deleting `provider.xiurouter` and its credentials.

## Sources and review date

Reviewed on 2026-08-31. This translation preserves that date. Basic setup requires a complete reply and matching successful request record.

Source: https://docs.xiu.ai/en/router/integrations/opencode/index.mdx