---
title: "Connect Claude Code to XiuRouter"
description: "Route Claude Code CLI, the VS Code extension, or Claude desktop Code through the XiuRouter Anthropic Messages gateway."
image: "https://docs.xiu.ai/og.png"
---

> XiuAI 文档索引
> 完整文档索引：https://docs.xiu.ai/llms.txt
> 阅读前先通过索引确认当前可用页面。

# Connect Claude Code to XiuRouter

Claude Code can send Anthropic Messages requests through XiuRouter. Configure the API root without `/v1`, enable gateway model discovery, and verify a real short task before using the connection on a production repository.

> **Test the full task**
>
> XiuRouter does not expose a dedicated `/v1/messages/count_tokens` route. Claude Code documents token counting as optional and can fall back through Messages, but a successful text request is not enough: the Claude Code task itself must finish.

## Before you start

- `claude --version` prints a version for CLI use.
- You have a dedicated XiuRouter API key.
- The current XiuRouter catalogue contains at least one Claude model.
- You can test in a non-critical project first.

## Claude Code CLI

Set the connection in the terminal that will start Claude Code:

```bash
export ANTHROPIC_BASE_URL="https://router-api.xiu.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_XIUROUTER_API_KEY"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
```

The base URL has no `/v1` suffix. Claude Code appends `/v1/messages`. `ANTHROPIC_AUTH_TOKEN` sends a Bearer token, which XiuRouter accepts on the Messages route.

Before starting Claude Code, isolate key or network problems with a direct request:

```bash
curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
"model": "YOUR_MODEL_ID",
"max_tokens": 32,
"messages": [
  {
    "role": "user",
    "content": "Reply only with: connected"
  }
]
  }'
```

Replace `YOUR_MODEL_ID` with an exact current ID. A successful response contains a Messages `content` value.

Run `claude`, use `/model` to select a model labeled **From gateway**, then run `/status`. Confirm the Anthropic base URL and auth token lines before completing a short task.

## VS Code extension

Open **Preferences: Open User Settings (JSON)** and merge:

```json
{
  "claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://router-api.xiu.ai" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "YOUR_XIUROUTER_API_KEY" },
{ "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" }
  ]
}
```

Use user settings, not workspace settings, so the key cannot be committed with the project. Run **Developer: Reload Window**, then verify `/status` and a short task.

## Claude desktop Code

Enable Developer Mode, then open **Developer → Configure Third-Party Inference**:

```text
Inference provider: Gateway
Gateway base URL: https://router-api.xiu.ai
Gateway API key: YOUR_XIUROUTER_API_KEY
Credential kind: Static API key
Gateway auth scheme: Bearer
```

Quit and reopen the application. Gateway mode runs local Code sessions; it does not add cloud environments, SSH, or Remote Control.

## Common failures

| Symptom | Action |
| --- | --- |
| `401` or invalid token | Use `ANTHROPIC_AUTH_TOKEN`; confirm the XiuRouter key is active |
| A warning lists two credential sources | Run `/logout` to use the gateway credential, or unset the gateway variables to keep the saved login |
| XiuRouter models are missing from `/model` | Set `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` and restart |
| The path becomes `/v1/v1/messages` | Remove `/v1` from `ANTHROPIC_BASE_URL` |
| A `400` names experimental fields | Set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` and retry |
| Logs show `count_tokens` `404` | Confirm Claude Code falls back and completes `/v1/messages`; do not rotate the key or add funds solely for this optional endpoint |
| HTTP `200` has an empty or malformed body | Check for a proxy returning an HTML error page and rerun the direct `curl` request |

## Roll back

- CLI: unset the three gateway variables and restart Claude Code.
- VS Code: restore the previous `claudeCode.environmentVariables` and reload the window.
- Desktop: restore or disable the Third-Party Inference connection and restart the app.

Run `/status` after rollback and confirm the previous connection is active.

## Sources and review date

This page was checked against the current Claude Code gateway connection and protocol references and the XiuRouter Messages integration on August 22, 2026. No real key was used to run a billable Claude Code task during this review.

源文件：https://docs.xiu.ai/en/router/integrations/claude-code/index.mdx