OmniRoute/docs/AGENTROUTER.md

AgentRouter Setup Guide

AgentRouter 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.
• 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:

ENABLE_CC_COMPATIBLE_PROVIDER=true

Docker example:

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:

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 <api-key>
User-Agent	claude-cli/2.1.137 (external, sdk-cli)
anthropic-version	2023-06-01
anthropic-beta	claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24
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.md — Other provider integration notes
• docs/reference/FREE_TIERS.md — Free-tier provider catalog
• open-sse/services/claudeCodeCompatible.ts — Wire image implementation