--- title: "AgentRouter Setup Guide" version: 3.8.40 lastUpdated: 2026-06-28 --- # AgentRouter Setup Guide [AgentRouter](https://agentrouter.org) is an Anthropic-compatible relay that resells Claude and other models, often at lower prices than the direct Anthropic API. It is designed as a drop-in `ANTHROPIC_BASE_URL` replacement for the official Claude Code client, so it only accepts traffic that matches the Claude Code wire image (specific User-Agent, `anthropic-beta` flags, Stainless SDK headers, etc.). ## Quick start — use the native `agentrouter` provider (recommended) For most users, **no special setup is required**. OmniRoute ships a built-in `agentrouter` provider with the full Claude Code wire image already baked in (see `open-sse/config/providerRegistry.ts` → `agentrouter`). To use it: 1. Open **Dashboard → Providers → Add Provider**. 2. Select **AgentRouter** from the list. 3. Paste your `sk-...` API key and save. That's it — no environment variables, no custom provider type. Built-in models include `claude-opus-4-6`, `claude-haiku-4-5-20251001`, `glm-5.1`, and `deepseek-v3.2`. The rest of this guide covers the **advanced path**: using the `anthropic-compatible-cc-*` provider type. Use that when you need more control over the wire image — for example, when connecting to other AgentRouter-style relays that are not yet in the native provider registry, or when overriding the base URL, chat path, or header set. --- ## Advanced: connecting via the Claude Code compatible provider type OmniRoute also supports AgentRouter (and similar relays) through the **Claude Code compatible** provider type (`anthropic-compatible-cc-*`), which speaks the Anthropic Messages API with the correct wire image. A generic `openai-compatible-chat` provider pointing at `https://agentrouter.org` will **not** work — the upstream WAF rejects requests that do not look like Claude Code. --- ## Prerequisites - An AgentRouter account and API key. New signups get free credits via the affiliate link in the project [README](../README.md). - OmniRoute running with the `ENABLE_CC_COMPATIBLE_PROVIDER` feature flag enabled (see below). ## 1. Enable the CC-compatible provider type The Claude Code compatible provider type is gated behind a feature flag because it sends traffic that closely mirrors the official Claude Code client. Enable it by setting an environment variable before starting OmniRoute: ```bash ENABLE_CC_COMPATIBLE_PROVIDER=true ``` Docker example: ```bash docker run -d --name omniroute \ --restart unless-stopped \ -p 20128:20128 \ -v omniroute-data:/app/data \ -e ENABLE_CC_COMPATIBLE_PROVIDER=true \ diegosouzapw/omniroute:latest ``` After restarting, the dashboard exposes an **Add Claude Code Compatible** option in addition to the existing OpenAI-compatible and Anthropic-compatible flows. ## 2. Create the provider in the dashboard 1. Open **Dashboard → Providers → Add Provider**. 2. Choose **Add Claude Code Compatible** (only visible when the flag above is set). 3. Fill in the fields: | Field | Value | | --------- | -------------------------------------------------------------- | | Name | `AgentRouter` (or any label) | | Prefix | `agentrouter` (friendly alias shown in logs and the dashboard) | | Base URL | `https://agentrouter.org` | | Chat path | `/v1/messages?beta=true` (default — leave as-is) | > The canonical model identifier still uses the full provider node ID > (`anthropic-compatible-cc-{uuid}/{model}`). The **Prefix** is just a display > alias resolved by `src/lib/usage/callLogs.ts` for friendlier log output. 4. (Optional) Paste your API key in the **Validate** field and click **Check** to confirm connectivity before saving. 5. Click **Add**. Once created, open the provider and add a **Connection** with your AgentRouter API key (`sk-...`). The connection's `test_status` should turn `active`. ## 3. Use it through a combo or directly Reference the model using your provider's prefix as the namespace: ```bash curl -X POST http://localhost:20128/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "agentrouter/claude-opus-4-6", "messages": [{"role": "user", "content": "hello"}], "max_tokens": 100 }' ``` The canonical model ID `anthropic-compatible-cc-{uuid}/claude-opus-4-6` also works and is what shows up in the database and combo configuration. Or add it to a combo for routing, fallback, and quota management like any other provider. --- ## Wire image details For reference, the cc-compatible bridge sends the following on each upstream request (see `open-sse/services/claudeCodeCompatible.ts`): | Header | Value | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `Authorization` | `Bearer ` | | `User-Agent` | `claude-cli/2.1.195 (external, sdk-cli)` | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24` | | Per-connection redact-thinking beta toggle | Adds `redact-thinking-2026-02-12` for upstreams that specifically require redacted thinking streams | | Per-connection summarized thinking toggle | Adds `display: "summarized"` to CC Compatible thinking requests that did not already set a display mode | | `anthropic-dangerous-direct-browser-access` | `true` | | `x-app` | `cli` | | `X-Stainless-*` | Various Stainless SDK headers (lang, package version, OS, arch, etc.) | This is what allows requests to pass the upstream WAF / client whitelist. --- ## Troubleshooting **`{"error":{"message":"unauthorized client detected, ..."}}`** — Your request did not match the Claude Code wire image. This happens when the provider is configured as `openai-compatible-chat` instead of `anthropic-compatible-cc`, or when the `ENABLE_CC_COMPATIBLE_PROVIDER=true` flag was not set at startup. **`{"error":{"message":"无效的令牌","type":"new_api_error"}}` (HTTP 401)** — "Invalid token". The wire image is correct but the API key is rejected. Generate a new key in the AgentRouter dashboard and update the connection. **`{"error":{"code":"content-blocked","type":"agent_router_api_error"}}` (HTTP 400)** — AgentRouter's moderation hook rejected the request content, or the key's plan does not permit the requested model. Try a different prompt or model; contact AgentRouter support if a benign prompt is consistently blocked. **`[400]: content-blocked` only on specific models** — Most AgentRouter plans only allow a subset of models (e.g. `claude-opus-4-6`). Other model IDs return `unauthorized_client_error` even though the key is valid. Check which models your plan covers in the AgentRouter dashboard. **`Invalid JSON response from provider (reset after Ns)` from the omniroute logs** — The upstream returned a non-JSON body (typically an HTML error page from the WAF). This usually means the request never reached the AgentRouter backend — recheck that the provider ID starts with `anthropic-compatible-cc-` (note the trailing dash — see `CLAUDE_CODE_COMPATIBLE_PREFIX` in `open-sse/services/claudeCodeCompatible.ts`) and the feature flag is enabled. --- ## See also - [`docs/providers/CLAUDE_WEB.md`](./CLAUDE_WEB.md) — Claude Web provider integration notes - [`docs/reference/FREE_TIERS.md`](../reference/FREE_TIERS.md) — Free-tier provider catalog - [`open-sse/services/claudeCodeCompatible.ts`](../../open-sse/services/claudeCodeCompatible.ts) — Wire image implementation