---
title: "Connect OpenClaw to XiuRouter"
description: "Merge the XiuRouter provider, default model, and model allowlist while keeping credentials in the startup environment."
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 OpenClaw to XiuRouter

Merge XiuRouter into `~/.openclaw/openclaw.json`. Configure the provider, default model, and `agents.defaults.models` allowlist together.

## Choose a setup method

- First setup: set the startup process's key, then merge the provider, default model, and allowlist.
- Existing setup: retain other providers and update only `xiurouter` and the default model.
- Chat-assisted setup: an agent with file access can merge credential-free JSON. You still supply the environment, restart, and create a new task.

## Before you start

OpenClaw must already read its configuration. Create a dedicated XiuRouter key and copy an exact model ID from the catalog.

## Set the key

In the environment that starts OpenClaw:

```bash
export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"
```

Do not put the real key in shared configuration. If a service manager starts OpenClaw, set the variable in that process's secure environment rather than an unrelated terminal.

## Merge the configuration

Replace `YOUR_MODEL_ID` with the exact ID:

```json
{
  "models": {
"providers": {
  "xiurouter": {
    "baseUrl": "https://router-api.xiu.ai/v1",
    "apiKey": "${XIUROUTER_API_KEY}",
    "api": "openai-completions",
    "models": [
      {
        "id": "YOUR_MODEL_ID",
        "name": "YOUR_MODEL_ID"
      }
    ]
  }
}
  },
  "agents": {
"defaults": {
  "model": {
    "primary": "xiurouter/YOUR_MODEL_ID"
  },
  "models": {
    "xiurouter/YOUR_MODEL_ID": {
      "alias": "XiuRouter"
    }
  }
}
  }
}
```

Merge into the existing file without overwriting other providers or agent settings. Keep `api` as `openai-completions`. OpenClaw rejects a model added to the provider but omitted from the allowlist.

An agent with configuration access may merge this JSON. Keep the real key in the startup environment, then restart and create a new task.

## Ask an agent to help

After configuring the environment, send this to an agent with access:

> Preserve all providers and agent settings in `~/.openclaw/openclaw.json`. Add `models.providers.xiurouter` with Base URL `https://router-api.xiu.ai/v1`, protocol `openai-completions`, key reference `${XIUROUTER_API_KEY}`, and model `YOUR_MODEL_ID`. Set `xiurouter/YOUR_MODEL_ID` as the primary model and add it to `agents.defaults.models`. Do not read or write the real API key. Show the diff.

## Verify

Restart OpenClaw and run a small read-only task using `xiurouter/YOUR_MODEL_ID`. Check the matching model, endpoint, and successful request in XiuRouter.

Tools, images, context, and output limits vary by model. Do not add unverified capability metadata after testing only a text reply.

## Troubleshoot

| Symptom | Next step |
| --- | --- |
| Provider missing | Use `openclaw config` to locate the active configuration and check JSON nesting |
| `401` | Confirm the startup process reads `XIUROUTER_API_KEY` |
| Model not allowed | Ensure the allowlist contains exactly the same `xiurouter/YOUR_MODEL_ID` as the default |
| Text works but tools fail | Use a verified tool model or restore the original provider |

## Roll back

Restore `agents.defaults.model.primary` first. After a new task uses the old route, remove `models.providers.xiurouter` and revoke the test key.

## 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/openclaw/index.mdx