Connect OpenClaw to XiuRouter

Merge the XiuRouter provider, default model, and model allowlist while keeping credentials in the startup environment.

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:

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:

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