From 8bd125ed2f3df4b79cbb456578a9af897482adb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lenine=20J=C3=BAnior?= Date: Wed, 20 May 2026 00:17:27 -0400 Subject: [PATCH] docs: add AgentRouter setup guide (#2422) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Integrated into release/v3.8.0 — AgentRouter setup guide docs. --- docs/AGENTROUTER.md | 149 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/AGENTROUTER.md diff --git a/docs/AGENTROUTER.md b/docs/AGENTROUTER.md new file mode 100644 index 0000000000..2333bc0883 --- /dev/null +++ b/docs/AGENTROUTER.md @@ -0,0 +1,149 @@ +# 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.). + +OmniRoute supports AgentRouter 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.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`](./PROVIDERS.md) — Other 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